Control Events

Execute custom action - 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.

Please see the Execute custom action on button push How-To for more details about using this type of control events.

Set installer property value - 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

Install one or more features locally - AddLocal

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

Install one or more features from source - AddSource

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

Reinstall one or more features - Reinstall

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

Set reinstall mode - 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)

The recommended argument is omus.

Uninstall one or more features - Remove

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

Display a specific dialog - 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.

Close the current dialog - 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").

For error dialogs the argument of this control event can be one of these values: "ErrorOk", "ErrorCancel", "ErrorAbort", "ErrorRetry", "ErrorIgnore", "ErrorYes" or "ErrorNo".

Display a specific child dialog - 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.

Display a child dialog while a condition is true - 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.

Verify and set the selected folder path - 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.

Check if a folder path has write permissions - 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].

Check if a folder path is valid - 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].

Set install level value - 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.

Reset control properties to default values - Reset

This event resets all the control property values to default for the current dialog. It does not use an argument.

Enable/disable installation rollback - 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.

Browse selected tree item - 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.

Restart processes using your installation files - 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

Create new directory in a DirectoryList control - 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.

If this control event is called again when a new folder already exists, a second new folder will not be created. In this case, calling DirectoryListNew selects the existing new folder's name for editing.

Open a directory in a DirectoryList control - 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.

If no directory has been selected in the DirectoryList control, a DirectoryListOpen event disables any other controls that publish a similar event.

Open parent directory in a DirectoryList control - 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.

If the current directory is the drive's root directory, a DirectoryListUp event disables any other controls that publish a similar event.

Validate ProductID property - 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.

Refresh the current dialog

This event refreshes all user interface controls from the current dialog.

Display action data during install - 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.

Display action text during install - 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.

Display installation summary (Enhanced UI only)

This event is used to display overall installation's actions. An multiline edit or text control on a modeless dialog subscribes to this event using the Text attribute to display the installation summary. This event requires the Enhanced User Interface.

Display installation details (Enhanced UI only)

This event is used to display detailed actions performed during installation (like which files and registry are installed). An multiline edit or text control on a modeless dialog subscribes to this event using the Text attribute to display the installation summary. This event requires the Enhanced User Interface.

Display action for the selected tree item - 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.

Display description for the selected tree item - 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.

Update control when no tree item is selected - SelectionNoItems

This event is triggered only when the selection tree control has no nodes. It 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.

Display path for the selected tree item - 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.

Determine if the selected tree item is using a path - 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.

Display size for the selected tree item - 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.

Display installation progress - 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.

Display overall installation progress (Enhanced UI only) - 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.

Display installation remaining time - 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.

Receive selection change notification for a DirectoryList control - 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.

Display installation script information - ScriptInProgress

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

A subscribed event can set one of the following attributes for the control which uses it:

• Enabled - specifies if the control is enabled or disabled
• Indirect - specifies whether the value displayed or changed by this control is referenced indirectly
• IndirectPropertyName - this attribute is the name of an indirect property associated with the control; if the Indirect attribute is set, the control displays or changes the indirect property's value
• Position - specifies the control's position on the dialog box
• PropertyName - specifies the name of the property associated with this control
• PropertyValue - specifies the value of the property associated with this control
• Text - specifies the text showed by (or in) the control
• Visible - specifies if the control is visible or hidden

These attributes are changed according to the data received from the subscribed event.