Pascal Scripting: Event Functions

The Pascal script can contain several event functions which are called at appropriate times.

Setup event functions

Setup supports following event functions:

function InitializeSetup(): Boolean;

Called during Setup's initialization. Return False to abort Setup, True otherwise.

procedure InitializeWizard();

Use this event function to make changes to the wizard or wizard pages at startup. You can't use the InitializeSetup event function for this since at the time it is triggered, the wizard form does not yet exist.

procedure DeinitializeSetup();

Called just before Setup terminates. Note that this function is called even if the user exits Setup before anything is installed.

procedure CurStepChanged(CurStep: TSetupStep);

You can use this event function to perform your own pre-install and post-install tasks.

Called with CurStep=ssInstall just before the actual installation starts, with CurStep=ssPostInstall just after the actual installation finishes, and with CurStep=ssDone just before Setup terminates after a successful install.

procedure CurInstallProgressChanged(CurProgress, MaxProgress: Integer);

You can use this event function to monitor progress while Setup is extracting files, creating shortcuts, creating INI entries, and creating registry entries.

function NextButtonClick(CurPageID: Integer): Boolean;

Called when the user clicks the Next button. If you return True, the wizard will move to the next page; if you return False, it will remain on the current page (specified by CurPageID).

Note that this function is called on silent installs as well, even though there is no Next button that the user can click. Setup instead simulates "clicks" on the Next button. On a silent install, if your NextButtonClick function returns False prior to installation starting, Setup will exit automatically.

function BackButtonClick(CurPageID: Integer): Boolean;

Called when the user clicks the Back button. If you return True, the wizard will move to the previous page; if you return False, it will remain on the current page (specified by CurPageID).

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

Called when the user clicks the Cancel button or clicks the window's Close button. The Cancel parameter specifies whether normal cancel processing should occur; it defaults to True. The Confirm parameter specifies whether an "Exit Setup?" message box should be displayed; it usually defaults to True. If Cancel is set to False, then the value of Confirm is ignored.

function ShouldSkipPage(PageID: Integer): Boolean;

The wizard calls this event function to determine whether or not a particular page (specified by PageID) should be shown at all. If you return True, the page will be skipped; if you return False, the page may be shown.

Note: This event function isn't called for the wpPreparing, and wpInstalling pages, nor for pages that Setup has already determined should be skipped (for example, wpSelectComponents in an install containing no components).

procedure CurPageChanged(CurPageID: Integer);

Called after a new wizard page (specified by CurPageID) is shown.

function CheckPassword(Password: String): Boolean;

If Setup finds the CheckPassword event function in the Pascal script, it automatically displays the Password page and calls CheckPassword to check passwords. Return True to accept the password and False to reject it.

To avoid storing the actual password inside the compiled [Code] section which is stored inside Setup, you should use comparisons by hash only: calculate the SHA-1 hash of your salted password yourself and then compare that to GetSHA1OfString(Password). This way the actual value of the password remains protected.

Note: If Setup is run with a /PASSWORD= command line parameter, your CheckPassword function will be called before any other event function is called, including InitializeSetup.

function NeedRestart(): Boolean;

Return True to instruct Setup to prompt the user to restart the system at the end of a successful installation, False otherwise.

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

If Setup finds the UpdateReadyMemo event function in the Pascal script, it is called automatically when the Ready to Install wizard page becomes the active page. It should return the text to be displayed in the settings memo on the Ready to Install wizard page as a single string with lines separated by the NewLine parameter. Parameter Space contains a string with spaces. Setup uses this string to indent settings. The other parameters contain the (possibly empty) strings that Setup would have used as the setting sections. The MemoDirInfo parameter for example contains the string for the Selected Directory section.

procedure RegisterPreviousData(PreviousDataKey: Integer);

To store user settings entered on custom wizard pages, place a RegisterPreviousData event function in the Pascal script and call SetPreviousData(PreviousDataKey, ...) inside it, once per setting.

function CheckSerial(Serial: String): Boolean;

If Setup finds the CheckSerial event function in the Pascal script, a serial number field will automatically appear on the User Info wizard page (which must be enabled using UserInfoPage=yes in your [Setup] section!). Return True to accept the serial number and False to reject it. When using serial numbers, it's important to keep in mind that since no encryption is used and the source code to Inno Setup is freely available, it would not be too difficult for an experienced individual to remove the serial number protection from an installation. Use this only as a convenience to the end user and double check the entered serial number (stored in the {userinfoserial} constant) in your application.

function GetCustomSetupExitCode: Integer;

Return a non zero number to instruct Setup to return a custom exit code. This function is only called if Setup was successfully run to completion and the exit code would have been 0. Also see Setup Exit Codes.

function PrepareToInstall(var NeedsRestart: Boolean): String;

You can use this event function to detect and install missing prerequisites and/or to shutdown any application which is about to be updated.

Return a non empty string to instruct Setup to stop at the Preparing to Install wizard page, showing the returned string as the error message. Set NeedsRestart to True (and return a non empty string) if a restart is needed. If Setup is stopped this way, it will exit with a dedicated exit code as described in Setup Exit Codes. Any custom exit code set by the /RESTARTEXITCODE= command line parameter will not be used in this case.

This function is called before Setup checks for files being in-use if CloseApplications is set to yes.

This function is only called if Setup didn't already determine it can't continue because one or more files specified in the [Files] and [InstallDelete] sections were queued (by some other installation) to be replaced or deleted on the next restart.

procedure RegisterExtraCloseApplicationsResources;

To register extra files which Setup should check for being in-use if CloseApplications is set to yes, place a RegisterExtraCloseApplicationsResources event function in the Pascal script and call RegisterExtraCloseApplicationsResource inside it, once per file.

Uninstall event functions

Uninstall supports following event functions:

function InitializeUninstall(): Boolean;

Return False to abort Uninstall, True otherwise.

procedure InitializeUninstallProgressForm();

Use this event function to make changes to the progress form at startup. You can't use the InitializeUninstall event function for this since at the time it is triggered, the progress form does not yet exist.

procedure DeinitializeUninstall();

procedure CurUninstallStepChanged(CurUninstallStep: TUninstallStep);

function UninstallNeedRestart(): Boolean;

Return True to instruct Uninstall to prompt the user to restart the system at the end of a successful uninstallation, False otherwise.

Constants

Here's the list of constants used by these functions:

• TSetupStep values
  ssInstall, ssPostInstall, ssDone
• TUninstallStep values
  usAppMutexCheck, usUninstall, usPostUninstall, usDone
• PageID values for predefined wizard pages
  wpWelcome, wpLicense, wpPassword, wpInfoBefore, wpUserInfo, wpSelectDir, wpSelectComponents, wpSelectProgramGroup, wpSelectTasks, wpReady, wpPreparing, wpInstalling, wpInfoAfter, wpFinished

Event Attributes

Normally a script can contain only one implementation per event function. Using event attributes it is possible to have multiple implementations of the same event function in your script. This is especially useful in included scripts implementing an event function to avoid conflicts with the main script.

Here is an example of a script which contains three implementations of the InitializeWizard event function.

[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;

The following rules apply:

• The implementations will be called in order of their definition except that any main implementation (=the implementation without an event attribute) will be called last.
• Event attributes may be used for all event functions. If the event function has a return value then lazy evaluation is performed:
• InitializeSetup, BackButtonClick, NextButtonClick, InitializeUninstall: All implementations must return True for the event function to be treated as returning True and an implementation returning False stops the calls to the other implementations.
• CheckPassword, CheckSerial, ShouldSkipPage, NeedRestart: All implementations must return False for the event function to be treated as returning False and an implementation returning True stops the calls to the other implementations.
• UpdateReadyMemo, PrepareToInstall: All implementations must return an empty string for the event function to be treated as returning an empty string and an implementation returning a non empty string stops the calls to the other implementations.
• GetCustomSetupExitCode: All implementations must return zero for the event function to be treated as returning zero and an implementation returning a non zero number stops the calls to the other implementations.
• Event attributes may only be used on procedures or functions which do not already have the name of an event function.
• If the event function uses var parameters then the value will be passed on from implementation to implementation.
• To call an implementation with an event attribute yourself from [Code] you should use the normal name of the function, just as if the implementation had no event attribute.