Creating the Event Handler Functions
You must create a high-level default event handler that is called when the dialog box is about to be displayed. You can also create a control-specific event handler that becomes active when the control (pop-up, button, check box, radio button, or icon) is clicked.
The high-level handler must process any of the messages sent from the application. The control-specific handler must process only EtsC_Message_Control messages. If either event handler fails to process a message, the application may crash. For more information about handlers, see "Handler Prototypes" on page 34 and Model Handlers.
Using the Default Event-Handler Prototype
The prototype is as follows:
DLLEXPORT void
test_event_proc (EtsT_Dbox *dbox_ptr, EtsT_Message message,
EtsT_Submessage submessage, char *control, void *data)
This event handler has the data type EtsT_Event_Proc.
The following table lists each of the arguments. In some cases, the submessage, control, and data arguments are not used, depending on the value of the message argument.
Table 5: Prototype Arguments
| Argument | Description |
|---|---|
dbox_ptr |
A marker, required when communicating with ETS. Identifies the dialog box that is invoking the event handler. |
message |
Event to be handled. |
submessage |
Event-specific information. |
control |
Pointer to a string representing the ID of the control (if any) that caused this event. |
data |
Pointer to additional event-specific data. |
The EtsT_Message data type represents the possible messages your event handler can receive from the application. The four defined values are listed in the following table.
Table 6: EtsT_Message Messages
| Message | Description |
|---|---|
EtsC_Message_Open |
The dialog box is being opened; allows initialization. - submessage: unused - control: unused - data: unused |
EtsC_Message_Close |
The dialog box is being closed; allows cleanup. - submessage: unused - control: unused - data: unused |
EtsC_Message_Control |
A control has been acted upon by the user. Allows responding to user actions on dialog box buttons. - submessage: EtsC_Submessage_Click. Delivered to control-specific event handler if one was specified, or to the high-level handler otherwise.- control: text string of name of control - data: unused |
EtsC_Message_Ping |
A ping message was sent by another dialog box. - submessage: unused - control: unused - data: a pointer sent along with the ping by the “pinger”. This is the value specified in the data argument of EtsC_Command_Ping. |
We recommend that your event handler function “case out” the four values, as shown in Figure 11. Note that the EtsC_Message_Control case, unlike the others, must handle submessages (the EtsT_Submessage data type). The case statements are in bold for readability.
Figure 11: Sample Event Handler Source Code
DLLEXPORT void
test_event_proc (EtsT_Dbox *dbox_ptr, EtsT_Message message,
EtsT_Submessage submessage, char *control, void *data)
{
. . .
FIN (test_event_proc (dbox_ptr, message, submessage, control, data));
switch (message)
{
case EtsC_Message_Open:
/* Try to obtain information about all nodes/links in the network */
/* editor at the time that this dialog box is opened. */
. . .
break;
case EtsC_Message_Ping:
/* got a ping from a sibling or child. */
. . .
break;
case EtsC_Message_Close:
. . .
break;
case EtsC_Message_Control:
switch (submessage)
{
case EtsC_Submessage_Click:
. . .
break;
}
break;
}
FOUT;
}
Handling Events
The source code you write can use the ETS GUI functions to implement the functionality you desire. See “GUI Package“ on page 243.