ControlEvent Overview

ControlEvents are analogous to Microsoft Windows messages in Win32-based applications. However, rather than creating a callback function to receive Windows messages and sending Windows messages with the SendMessage function, the user interface (UI) installer and controls publish ControlEvents. Other controls and the installer can be specified to subscribe to particular ControlEvents that will then change attributes of the subscribing control. To add working controls to dialog boxes, the author of the UI specifies the publication of ControlEvents in the ControlEvent table and subscribes controls to ControlEvents in the EventMapping table.

The installer will publish the following events to subscribing controls listed in the EventMapping table. A ProgressBar control or Billboard control typically subscribes to SetProgress, the rest are subscribed to by Text controls.

ActionData ControlEvent

ActionText ControlEvent

SetProgress ControlEvent

TimeRemaining ControlEvent

ScriptInProgress ControlEvent

The following events are published by the control when the item selection is moved in a SelectionTree control or DirectoryList Control. Subscribing controls must be located on the same dialog box and listed in the EventMapping table.

IgnoreChange ControlEvent

SelectionDescription ControlEvent

SelectionSize ControlEvent

SelectionPath ControlEvent

SelectionAction ControlEvent

SelectionNoItems ControlEvent

The following ControlEvents can be published at the discretion of a user by interacting with a PushButton control or CheckBox control on a dialog box. The Checkbox control can only publish the AddLocal, AddSource, Remove, DoAction, and SetProperty events. With Windows Installer versions that shipped with Windows Server 2003 and later, the SelectionTree control can publish the DoAction, ControlEvent and SetProperty ControlEvents. The author of the UI should list the ControlEvent in the ControlEvent table. The UI handler of the installer is the subscriber to these events.

AddLocal ControlEvent

AddSource ControlEvent

CheckExistingTargetPath ControlEvent

CheckTargetPath ControlEvent

DoAction ControlEvent

EnableRollback ControlEvent

EndDialog ControlEvent

NewDialog ControlEvent

Reinstall ControlEvent

ReinstallMode ControlEvent

Remove ControlEvent

Reset ControlEvent

SetInstallLevel ControlEvent

SetProperty ControlEvent

SetTargetPath ControlEvent

SpawnDialog ControlEvent

SpawnWaitDialog ControlEvent

ValidateProductID ControlEvent

A PushButton control can publish the following events to a subscribing SelectionTree control or DirectoryList control located in the same dialog box. The PushButton Control should be listed in the ControlEvent table and the subscribing controls should be listed in the EventMapping table.

SelectionBrowse ControlEvent

DirectoryListUp ControlEvent

DirectoryListNew ControlEvent

DirectoryListOpen ControlEvent

Control events generally require that the UI be run at the full UI level. Most ControlEvents will not work with a reduced UI or basic UI because these levels only display modeless dialog boxes. The ActionText, AddSource, SetProgress, TimeRemaining, and ScriptInProgress events are exceptions and will work in reduced or basic UI. For more information about UI levels, see User Interface Levels.

You can run custom actions by publishing a ControlEvent from a PushButton control or Checkbox control. Add a record to the ControlEvent table with the names of the dialog and the control publishing the ControlEvent. This control should publish a DoAction ControlEvent notifying the installer to run the custom action. On Windows XP or earlier systems, you cannot run a custom action by publishing a ControlEvent from a SelectionTree control.

For a more information about particular ControlEvents, see the list of standard ControlEvents in User Interface Reference.