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.
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.
SelectionDescription 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.
CheckExistingTargetPath 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.
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.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for