Onetastic Macro Documentation > Functions > Dialog Box Functions > DialogBox_SetEventHandler

DialogBox_SetEventHandler

Sets an event handler for a dialog box.

Syntax

void DialogBox_SetEventHandler(
	DialogBox dialogBox, 
	String functionName)

Parameters

DialogBox dialogBox

The dialog box to set the event handler for.

String functionName

Name of the user defined function to set as an event handler for the dialog.

Remarks

An event handler is a user defined function that gets called when the dialog is first created and then each time when value of one of the controls in the dialog box changes (e.g. user types into a text box, checks a check box, or chooses an option from a dropdown box etc.) or user clicks a custom button. Event handlers are not required to be set for a dialog box but can be used for more control on what controls are visible or enabled under specific conditions. The signature of an event handler is as follows:

The first parameter is the dialog box that the event is coming from. The second parameter is the name of the control which the event is originating from. When the event handler is called the first time when the dialog is created, control name will be empty. In the subsequent calls, in case of a value change this will be the name of the corresponding color picker, combo box, date/time picker, drop down, font picker, radio group or text box. In case of a button click, this will be the name of the button.

Handling of button clicks in a dialog

Closing a dialog via X button on the top right ends macro execution and the event handler will not be called.

If there are no custom buttons added to a dialog box, it will display the default "OK" button. In this case, if user clicks on the "OK" button:

• The dialog is closed
• DialogBox_Show returns "ok"
• The event handler is not called even if one is set

If there are custom buttons added to a dialog box (via DialogBox_AddButton), and the user clicks on one of the buttons, the handling of the dialog depends on whether an event handler is set or not:

• If no event handler is set, when a button is clicked:
  • The dialog is closed
  • DialogBox_Show returns the name of the button clicked
• If an event handler is set, when a button is clicked:
  • The event handler is called and expected to return a bool value
  • If the event handler returns true
    • The dialog is closed
    • DialogBox_Show returns the name of the button clicked
  • If the event handler returns false
    • The dialog is not closed and user can continue to interact with the dialog