Event Handler
An Event Handler is an action sequence that is executed in response to a user interface event, for example the user clicking on a PushButton or Hyperlink control, a change of selection, a new dialog box, or a few other events.
Event handlers are typically used for user interface-related actions, for example data validation or opening a secondary browse dialog box. InstallMate's event handlers are not used to transfer control to another dialog box in the main user interface sequence; that is done by a separate action sequence. Furthermore, in most cases you do not need to define event handlers for standard dialog buttons such as OK, Next, or Back; they are handled automatically if you assign the appropriate standard control identifiers to these buttons.
Here is how event handlers and standard control identifiers interact:
- If an event handler is defined for a particular control, no default handling is performed;
- If no event handler is defined for a control, default handling according to its control identifier is performed.
To create an event handler, right-click on the dialog box or control of interest, choose New Event Handler..., and select the desired event source and event from the Select Dialog Event dialog box. The new event handler will appear on the Event handlers tab of the Dialogs project page; underneath it is a second pane where you can add the event handler's actual actions.
Attributes
The following attributes and options are available.
| Attribute | Description |
|---|---|
| Event name | Displays the name for the event that the handler responds to. Click ... (browse) to open the Select Dialog Event dialog box, which allows you to select a different event source or event. The event source and event name are shown as Source:Event if the source is a control, or as .:Event if the source id the dialog box itself. |
| Comment | Enter a short description of the event handler's purpose. This is for your own documentation only; the installer does not use this field. |
Available events
The available events depend on the control type that fires them, as shown in the following table.
| Event | Control type | Description |
|---|---|---|
| OnClicked | CheckBox, PushButton, RadioButton, StaticText controls | Issued when the user clicks the button or hyperlink. It is typically used to perform one or more actions that show additional dialogs, or to control which dialog box will be shown next in the installation sequence (next or previous). Note: For StaticText controls, this event is only generated if the control's Type is set to Hyperlink. Note: If a control does not have an explicit event handler, it will perform a default action based on its Control ID attribute when clicked. For example, if a button with the IDNEXT control ID has no explicit event handler, it will cause the current dialog to be closed and the next action in its action sequence to be performed. Therefore, you do not have to add event handlers for controls that use one of the standard control identifiers, unless you want that control to perform a non-default action. |
| OnHideWindow | All windows | Issued when the dialog or control is hidden (not destroyed). This event is rarely used. |
| OnInitDialog | Dialog boxes | Issued just before a dialog is shown for the first time. It is typically used to perform additional initialization of the dialog or its controls. |
| OnSelectionChanged | ComboBox, ListBox, OptionTree controls | Issued after the user selected a new item in a combo box, list box, or option tree control. It is typically used to show or hide related items. Note: You can often accomplish a similar effect more easily by defining a control condition for the affected controls and use the combo box's or list box's symbol in the condition. This will enable or disable the control instead of showing or hiding it. |
| OnShowWindow | All windows | Issued when the dialog or control is shown after having been hidden. This event is rarely used. |
| OnStateChanged | CheckBox, OptionTree, RadioButton controls | Issued after the user changed the on/off state of the checkbox, any option tree item, or the radio button control. It is typically used to show or hide, or enable/disable related items. Note: For RadioButton controls, this event only fires when the button in question is selected, not when it is unselected. Note: You can often accomplish a similar effect more easily by defining a control condition for the affected controls and use the checkbox's or radio button's symbol in the condition. This will enable or disable the control instead of showing or hiding it. |
| OnTextChanged | ComboBox, EditText controls | Issued when the text in an text edit control changes, whether because the user typed some text, or because it was programmatically changed. Note: For ComboBox controls, this event is only generated if the Combo style is set to Dropdown. |