Control Events

AddLocal

This event notifies the installer that a feature or all features will run locally. For the Argument field it can use the identifier of a feature or the string "ALL".

AddSource

This event notifies the installer that a feature or all features will run from source. For the Argument field it can use the identifier of a feature or the string "ALL".

CheckExistingTargetPath

This event notifies the installer to check if it can write in the selected path. If it cannot write in the path (for example it doesn't have enough privileges), the event blocks further control events associated with the control. For the Argument field it can use the name of the property which contains the path. If the property is indirect its name should be enclosed in square brackets (for example [PROPERTY].

CheckTargetPath

This event notifies the installer to check if the selected path is valid. If the path is not valid the event blocks further control events associated with the control. For the Argument field it can use the name of the property which contains the path. If the property is indirect its name should be enclosed in square brackets (for example [PROPERTY].

DirectoryListNew

This event notifies a DirectoryList control (like the one in "BrowseDlg") that a new folder must be created. It creates the new folder and selects the folder's name field for editing (the default name is "New Folder"). This event does not use an argument.

DirectoryListOpen

This event selects and highlights a directory in the DirectoryList control (like the one in "BrowseDlg") that the user has chosen to open. This event does not use an argument.

DirectoryListUp

This event notifies the DirectoryList control (like the one in "BrowseDlg") that the user wants to select the present directory's parent. This event does not use an argument.

DoAction

This event notifies the installer to execute a custom action. For the Argument field it can use the name of the custom action to be executed.

EnableRollback

This event can be used to turn on or turn off the installer's rollback capabilities. For the Argument field it can use one of these values:

• False - turns off the installer's rollback capabilities
• True - turns on the installer's rollback capabilities.

EndDialog

This event notifies the installer to remove a modal dialog. In all cases the installer removes the current dialog. For the Argument field it can use one of these values:

• Exit - The wizard sequence is closed and the control returns to the installer with the UserExit value ("ERROR_INSTALL_USEREXIT" or "1602"). This argument cannot be used in a dialog that is a child of another dialog.
• Retry - The wizard sequence is closed and the control returns to the installer with the Suspend value ("ERROR_INSTALL_SUSPEND" or "1604"). This argument cannot be used in a dialog that is a child of another dialog.
• Ignore - The wizard sequence is closed and the control returns to the installer with the Finished value. This argument cannot be used in a dialog that is a child of another dialog.
• Return - The control returns to the parent of the present dialog box or if there is no parent, the control returns to the installer with the Success value ("ERROR_SUCCESS" or "0").

NewDialog

This event notifies the installer to transition the current dialog to another dialog. The installer removes the current dialog and creates the new one with the name indicated in the argument. For the Argument field it can use the name of the dialog you want to show.

SpawnDialog

This event notifies the installer to create a child of a modal dialog while keeping the current dialog running. For the Argument field it can use the name of the dialog you want to show.

SpawnWaitDialog

This event shows the dialog specified in the Argument field if its condition is FALSE. The dialog is displayed as long as the event's condition remains FALSE and is removed as soon as the condition becomes TRUE.

ReinstallMode

This event allows the author to specify the validation mode or modes during a reinstall. For the Argument field it can use a combination of these values:

• p - reinstall only if the file is missing
• o - reinstall if the file is missing or is an older version
• e - reinstall if the file is missing or is an equal or older version
• d - reinstall if the file is missing or a different version is present
• c - verify the checksum values, and reinstall the file if they are missing or corrupt
• a - force all files to be reinstalled, regardless of checksum or version
• u - rewrite all required registry entries from the Registry page that go to HKEY_CURRENT_USER or HKEY_USERS
• m - rewrite all required registry entries from the Registry page that go to HKEY_LOCAL_MACHINE or HKEY_CLASSES_ROOT
• s - reinstall all shortcuts and re-cache all icons overwriting any existing shortcuts and icons
• v - run from the source package and re-cache the local package (this option should not be used during the first time install)

Reinstall

This event allows the author to initiate a reinstall of some or all features. For the Argument field it can use the identifier of a feature or the string "ALL".

Remove

This event notifies the installer that a feature or all features will be removed. For the Argument field it can use the identifier of a feature or the string "ALL".

Reset

This event resets all the controls' property values to dialog's creation default values. This event does not use an argument.

SelectionBrowse

This event is used by a SelectionTree control (like the one on "CustomizeDlg") to spawn a Browse dialog, making it possible to modify the highlighted item's path. Any controls that publish a SelectionBrowse event become disabled if the selected feature is already installed, not configurable or not selected for local installation.

SetInstallLevel

This event changes the installation level to the value specified by the argument. For the Argument field it can use a number which represents the new install level.

SetProperty

This event sets an installer property to the specified value. Its syntax is different compared to other control events, instead of the event name it uses the property in square brackets: [property_name]. For the Argument field it can use a formatted value or {} for a null value.

Here are some examples for this control event:

[MY_PROPERTY]          My Value                AI_INSTALL
[MY_PROPERTY]          [OTHER_PROPERTY]        AI_INSTALL
[MY_PROPERTY]          {}                      AI_INSTALL

SetTargetPath

This event notifies the installer to check and set the selected path. If the path is not valid or the installer doesn't have write access for it, all control events associated with the control are blocked.

ValidateProductID

This event sets the ProductID property to the full Product ID. If the validation is unsuccessful, this event shows an error message and a modal dialog which allows the user to set the Product ID.

RmShutdownAndRestart

This event notifies Windows Installer to use the Restart Manager to shutdown all applications that have files in use and to restart them at the end of the installation. It has no effect if:

• the operating system running the installation is not Windows Vista or above
• interactions with the Restart Manager have been disabled by the "MSIRESTARTMANAGERCONTROL" property or the "DisableAutomaticApplicationShutdown" policy
• currently there isn't an open Restart Manager session
• any call from Windows Installer to the Restart Manager returns a failure

ActionData

This event is used to publish data on the latest action. A Static Text control which subscribes to it can show the data to the user.

ActionText

This event is used to publish the present action's name. A Static Text control which subscribes to it can show the data to the user.

IgnoreChange

This event is published by the DirectoryList control (like the one in "BrowseDlg") when the selected folder is changed from one directory to another in the control.

ScriptInProgress

This event is used to display an informational string while the installation's execution script is being compiled. A Static Text control which subscribes to it can show the informational string to the user.

SelectionAction

This event is used to publish a string describing the highlighted item in a SelectionTree control (like the one in "CustomizeDlg"). It can affect only the controls located on the same dialog box as the SelectionTree control. A Static Text control which subscribes to it can show the string to the user.

SelectionDescription

This event is used to publish a string which represents the feature's description in a SelectionTree control (like the one in "CustomizeDlg"). It can affect only the controls located on the same dialog box as the SelectionTree control. The description text is the one set in the Feature Properties page. A Static Text control which subscribes to it can show the string to the user.

SelectionNoItems

This event is used to delete obsolete item description text or to disable buttons that have become useless for a SelectionTree control (like the one in "CustomizeDlg"). It can affect only the controls located on the same dialog box as the SelectionTree control.

SelectionIcon

This event will display the icon associated with the current selection in a special SelectionTree control (like the one in "CustomizeDlg"). The handle to this icon is published by the SelectionTree control. It can affect only the controls located on the same dialog box as the SelectionTree control.

SelectionPath

This event is used to publish the path for the highlighted item. It can affect only the controls located on the same dialog box as the SelectionTree control. A Static Text control which subscribes to it can show the path to the user.

SelectionPathOn

This event is used to publish a Boolean value indicating whether there is a selection path associated with the currently selected feature. It can affect only the controls located on the same dialog box as the SelectionTree control and it is not used during maintenance. A Static Text control which subscribes to it can show the selection path's caption to the user.

SelectionSize

This event is used to publish the highlighted item's size. If it is a parent item, then the number of children selected is also published. It can affect only the controls located on the same dialog box as the SelectionTree control. A Static Text control which subscribes to it can show the size to the user.

SetProgress

This event is used to publish information on the installation's progress. A progress bar or billboard control can subscribe to it in order to receive information about the installation progress.

AiGlobalProgress

This event is used to display information on the installation's overall progress. A progress bar can subscribe to it in order to receive information about the overall installation progress. This event requires the Enhanced User Interface.

TimeRemaining

This event is used to publish the approximate time remaining, in seconds, for the current progress sequence. A Static Text control which subscribes to it can show the remaining time to the user.