Click Handler Functions
Abstract
Use this handler to indicate how an application responds when a user clicks on an attribute name: either perform the default action for that attribute, open a dialog box, or open a pull-down menu.
Syntax
<click handler name> (attr_name, orig_object, copy_object, menu_tlptr)
| Argument | Type | Description |
|---|---|---|
attr_name |
const char* |
Name of the attribute that the user clicked |
orig_object |
EtsT_Obj_Handle |
Handle for the original attribute object |
copy_object |
EtsT_Obj_Handle |
Handle for a copy of the original attribute object |
menu_tlptr |
Prg_List* |
Pointer to a text list that contains the current symbolic values defined by the attribute, plus the “Other…” string if the attribute allows other values |
Return Type
EtsT_Obj_Dbox_Click_Options
A structure containing the following Boolean values:
EtsC_Obj_Dbox_Click_Default— indicates that the handler performed the default action for that attribute.EtsC_Obj_Dbox_Click_Show_Dbox— indicates that the handler displayed an ETS dialog box to handle user input, and may have modified the attribute.EtsC_Obj_Dbox_Click_Show_Menu— indicates that the handler displayed a pull-down menu based on the list referenced by menu_tlptr, and may have modified the attribute.
Details
A click handler determines an application’s response when a user clicks on an attribute name in the Edit Attributes dialog box. An attribute dialog can take one of three forms: it can perform the default action for that attribute, it can open a pull-down menu, or it can open a custom ETS dialog box. The return value must accurately reflect the action taken.
The application automatically passes the attr_name, orig_object, copy_object, and menu_tlptr arguments when it calls a click handler.
If a click handler opens an ETS dialog box, you should include any input-processing routines (for example, checking for invalid input) with the dialog box code inside the click handler.
If a click handler opens a pull-down menu, the application calls a new value handler when the user changes the attribute value. For this reason, any input-processing routines for a menu should go in the new value handler, not the click handler.
A pull-down menu reflects the text list referenced by menu_tlptr. You must ensure that your handler initializes this pointer to reference an appropriate list. You do not need to deallocate the list contents within this handler.
To have the application perform the default dialog for an attribute, simply have the click handler return with EtsC_Obj_Dbox_Click_Default set to PRGC_TRUE.