Pascal Scripting: Функции событий

Pascal-сценарий может содержать несколько функций, которые вызываются при определённых событиях.

Функции событий программы установки

Программа установки поддерживает следующие функции событий:

function InitializeSetup(): Boolean;

Вызывается во время инициализации программы установки. В случае успеха возвращает значение True, иначе False и работа программы установки прерывается.

procedure InitializeWizard();

Вызывается при создании формы мастера установки. Эту функцию можно использовать для внесения изменений в форму или страницы мастера установки. Для этого нельзя использовать функцию InitializeSetup, поскольку на момент запуска инсталлятора форма мастера ещё не существует.

procedure DeinitializeSetup();

Вызывается перед завершением программы установки. Обратите внимание, что эта функция вызывается даже, если пользователь преждевременно завершит работу программы установки.

procedure CurStepChanged(CurStep: TSetupStep);

Вызывается на определённых этапах установки и может использоваться для выполнения собственных задач до и после процесса установки.

При CurStep=ssInstall вызов выполняется перед началом фактической установки; при CurStep=ssPostInstall — сразу по окончании фактической установки; при CurStep=ssDone — непосредственно перед завершением программы установки, если инсталляция завершилась успешно.

procedure CurInstallProgressChanged(CurProgress, MaxProgress: Integer);

Вызывается при изменении текущего прогресса установки и может использоваться для отслеживания прогресса извлечения файлов, создания ярлыков, создания записей в INI-файлах или реестре.

function NextButtonClick(CurPageID: Integer): Boolean;

Вызывается при нажатии кнопки "Далее". Если функция вернёт значение True, мастер перейдёт на следующую страницу. При значении False мастер останется на текущей странице (указанной в параметре CurPageID).

Обратите внимание, что эта функция также вызывается при тихой установке, несмотря на отсутствие кнопки "Далее", которую пользователь может нажать. Вместо этого программа установки имитирует "нажатия" на кнопку "Далее". При тихой установке, если функция NextButtonClick вернёт значение False до начала процесса установки, программа установки автоматически завершит свою работу.

function BackButtonClick(CurPageID: Integer): Boolean;

Вызывается при нажатии кнопки "Назад". Если функция вернёт значение True, мастер перейдёт на предыдущую страницу. При значении False мастер останется на текущей странице (указанной в параметре CurPageID).

procedure CancelButtonClick(CurPageID: Integer; var Cancel, Confirm: Boolean);

Вызывается при нажатии кнопки "Отмена", или "Закрыть" в заголовке окна. Параметр Cancel определяет обычную обработку команды отмены и по умолчанию имеет значение True. Параметр Confirm определяет отображение сообщения "Выйти из программы установки?" и по умолчанию равен True. Если параметр Cancel имеет значение False, значение параметра Confirm игнорируется.

function ShouldSkipPage(PageID: Integer): Boolean;

Вызывается при определении условия пропуска определённой страницы (указанной в параметре PageID). Если функция вернёт значение True, страница будет пропущена. При значении False страница может быть показана.

Примечание: эта функция не вызывается для страниц wpPreparing и wpInstalling, а также страниц, для которых программа установки уже определила, что они должны быть пропущены (например, страница wpSelectComponents, если инсталлятор не содержит компонентов).

procedure CurPageChanged(CurPageID: Integer);

Вызывается после отображения определённой страницы (указанной в параметре CurPageID).

function CheckPassword(Password: String): Boolean;

Если программа установки обнаружит в сценарии функцию CheckPassword, она автоматически отобразит страницу Пароль и выполнит вызов CheckPassword для проверки пароля. Возвращает значение True, если пароль принят, и False, если пароль отклонен.

Чтобы обезопасить свой инсталлятор, не указывайте пароль для сравнения с пользовательским вводом в открытом виде. Вместо этого используйте хеширование строк. Определите хеш действительного пароля по алгоритму SHA-1, затем укажите это значение в функции проверки, сравнивая его с введённым паролем посредством GetSHA1OfString(Password). Таким образом, фактическое значение пароля останется защищённым.

Примечание: если программа установки запущена с параметром командной строки /PASSWORD=, функция CheckPassword будет вызвана ранее других функций события, включая InitializeSetup.

function NeedRestart(): Boolean;

Вызывается при проверке условия перезагрузки ПК. Если функция возвращает значение True, то при успешном завершении установки пользователю будет предложено выполнить перезагрузку ПК, иначе False.

function UpdateReadyMemo(Space, NewLine, MemoUserInfoInfo, MemoDirInfo, MemoTypeInfo, MemoComponentsInfo, MemoGroupInfo, MemoTasksInfo: String): String;

Если программа установки обнаружит в сценарии функцию UpdateReadyMemo, она автоматически выполнит её вызов, когда страница "Всё готово к установке" станет активной. Функция должна вернуть текст, показанный в поле настроек установки на странице мастера "Всё готово к установке", в виде единственной строки, где многострочный текст разделён параметром NewLine. Параметр Space содержит строку с пробелами. Программа установки использует эту строку для создания отступа при выводе настроек. Другие параметры содержат строки (могут быть пустыми), которые программа установки использовала бы в качестве разделов настроек. Параметр MemoDirInfo, к примеру, содержит строку для раздела Папка установки.

procedure RegisterPreviousData(PreviousDataKey: Integer);

Чтобы сохранить пользовательские параметры, введённые на пользовательских страницах мастера, поместите в сценарий функцию RegisterPreviousData и выполните из неё вызов функции SetPreviousData(PreviousDataKey, ...) соответственно для каждого параметра.

function CheckSerial(Serial: String): Boolean;

Если программа установки обнаружит в сценарии функцию CheckSerial, она автоматически отобразит поле ввода серийного номера на странице "Информация о пользователе" (эта страница должна быть включена с использованием директивы UserInfoPage=yes в секции [Setup]!). Возвращает значение True, если серийный номер принят, и False, если серийный номер отклонен. При использовании серийных номеров важно помнить, что, поскольку шифрование не используется и исходный код Inno Setup находится в свободном доступе, опытному специалисту не составит особого труда снять такую защиту с программы установки. Используйте эту функцию только для удобства конечного пользователя и повторной проверки введённого серийного номера (записанного в константу {userinfoserial}) для вашего приложения.

function GetCustomSetupExitCode: Integer;

Вызывается только в том случае, если программа установки успешно завершила свою работу и код выхода был равен 0. Используйте ненулевое число, чтобы инструктировать программу установки вернуть пользовательский код выхода. См. также "Коды выхода программы установки".

function PrepareToInstall(var NeedsRestart: Boolean): String;

Эту функцию можно использовать для обнаружения и установки недостающих зависимостей и/или завершения работы любого приложения, которое должно быть обновлено.

Используйте непустую строку, чтобы инструктировать программу установки остановиться на странице мастера "Подготовка к установке" и вывести указанную строку в качестве сообщения об ошибке. Если требуется выполнить перезагрузку, установите для функции NeedsRestart значение True (и верните непустую строку). При остановке программы установки таким путём, она будет завершена с кодом выхода, описанными в разделе "Коды выхода программы установки". Любой пользовательский код выхода, заданный параметром командной строки /RESTARTEXITCODE=, в этом случае использоваться не будет.

Если директива CloseApplications имеет значение yes, эта функция вызывается перед проверкой используемых файлов.

Эта функция вызывается только в том случае, если программа установки ещё не определила, что она не может продолжить работу, поскольку один или несколько файлов, указанных в секциях [Files] и [InstallDelete], были поставлены в очередь (какой-то другой установкой) для замены или удаления при следующем перезапуске.

procedure RegisterExtraCloseApplicationsResources;

Чтобы зарегистрировать дополнительные файлы, которые программа установки должна проверить на предмет использования, когда для параметра CloseApplications задано значение yes, поместите в сценарий функцию RegisterExtraCloseApplicationsResources и выполните из неё вызов функции RegisterExtraCloseApplicationsResource, соответственно для каждого файла.

Функции событий программы удаления

Программа удаления поддерживает следующие функции событий:

function InitializeUninstall(): Boolean;

Вызывается во время инициализации программы удаления. В случае успеха возвращает значение True, иначе False и работа программы удаления прерывается.

procedure InitializeUninstallProgressForm();

Вызывается при создании формы с прогрессом удаления и может использоваться для внесения в неё изменений. Для этих целей нельзя использовать функцию InitializeUninstall, поскольку на момент запуска деинсталлятора форма с прогрессом удаления ещё не существует.

procedure DeinitializeUninstall();
procedure CurUninstallStepChanged(CurUninstallStep: TUninstallStep);
function UninstallNeedRestart(): Boolean;

Вызывается при проверке условия перезагрузки ПК. Если функция возвращает значение True, то при успешном завершении удаления пользователю будет предложено выполнить перезагрузку ПК, иначе False.

Константы

Ниже приведен перечень констант, используемых этими функциями:

Атрибуты события

Как правило, сценарий может содержать только одну реализацию для каждой функции события. Используя атрибуты события, сценарий может иметь несколько реализаций одной и той же функции события. Особенно хорошо их эффективность проявляется во включенных сценариях, реализующих функции событий, что позволяет избежать конфликтов с основным сценарием.

Ниже приведен пример сценария, который содержит три реализации функции InitializeWizard.

[Code]
procedure InitializeWizard;
begin
  Log('InitializeWizard called');
end;

<event('InitializeWizard')>
procedure InitializeWizard2;
begin
  Log('InitializeWizard2 called');
end;

<event('InitializeWizard')>
procedure InitializeWizard3;
begin
  Log('InitializeWizard3 called');
end;

При использовании атрибутов события действуют следующие правила: