Basic API
Graphical User Interface (GUI)
Dialog Boxes and Controls
Most GUI functions are used to programmatically manipulate dialog boxes and the controls within those dialog boxes. Some functions typically used for these purposes are the functions in the Ets_Dbox, Ets_Ctl, and Ets_Tree_Element sub-packages of the GUI package. See Chapter 6 “GUI Package” on page 243 for details on these sub-packages and the functions described in this section.
The dialog box itself is created in the Dialog Box Editor (op_etsed), described in Chapter 3 “Dialog Box Resource File Editor” on page 65. This section focuses on the handler functions that are called from a dialog box.
Associating Callbacks with GUI Controls
When creating a dialog box in the Dialog Box Editor, you specify handler functions for each control. These handler functions are called when the user performs some action on a control or the dialog box. In addition, the dialog box itself has a default handler function that is called twice: once when the dialog box is created and again when it is destroyed.
The effect of the called function depends on the nature of the control and your intent. For example, when an OK button is clicked, the button's handler function typically reads values from controls in the dialog box, sets those values in internal data structures, then calls Ets_Dbox_Destroy() to close the dialog box.
The functions in a dialog box must all reside in the same shared object library. This library is specified in the ETS Library dialog attribute in the Dialog Box Editor (see Chapter 3 “Dialog Box Resource File Editor” on page 65 for details on this editor). You will usually store all functions used by your application in one library.
Different controls have different types of handler functions.
Table Control
Table controls are used to manage data displayed as rows and columns (a table) in a dialog box. A table typically is used as an interface to a data structure of some kind, which is associated with the dialog box state information using Ets_Dbox_State_Set(). Table controls support the following handlers:
- ETS Display Proc, called when a table cell needs to be redrawn. For the prototype, see
EtsT_Table_Display_Procon page 605. - ETS Tooltip Proc, called when a tooltip needs to be redrawn. For the prototype, see
EtsT_Table_Display_Procon page 605. - ETS Decoration Proc, called when a table cell needs to be redrawn.For the prototype, see
EtsT_Table_Decoration_Procon page 603 - ETS Store Proc, called when the user sets a value for a table cell (for example, after a value is entered from the keyboard or selected from a pop-up menu). For the prototype, see
EtsT_Table_Save_Procon page 606. - ETS Double Click Proc (see
EtsT_Table_Click_Procon page 602) - ETS Left Click Proc (see
EtsT_Table_Click_Procon page 602)
Use these handlers to control how the user interacts with the table. For example, you can control:
- Which fields are editable by calling (or not calling)
Ets_Ctl_Table_Cell_Edit()in a click handler. - What is displayed in any table cell with the display handler.
- User input and output with the store handler.
Treeview Control
A treeview has:
- an init function, called when the treeview is first displayed (for prototype, see
EtsT_Tree_Init_Procon page 614) - an expand handler, called when the user expands a treeview (see
EtsT_Tree_Expand_Procon page 613) - a tooltip handler, called when the cursor rests on an expanded treeview element for longer than the time specified by the “tooltip_delay“ preference (see
EtsT_Tree_Tooltip_Procon page 617) - a left-click handler, called when the user left-clicks on a control in the treeview (see
EtsT_Tree_Left_Procon page 615) - a right-click handler, called when the user right-clicks on a control in the treeview (see
EtsT_Tree_Right_Procon page 616)
Other Controls
All other controls use the default handler function (see “Using the Default Event-Handler Prototype“ on page 42). This function is called with the message argument equal to EtsC_Message_Control when either of the following events occurs:
- the control is clicked
- a value is entered
Other commonly-used GUI functions are:
Ets_Ansub-package functions, for creating analysis panels (graphs) (see “Analysis Panel Sub-Package“ on page 248)Ets_Dboxsub-package functions, for manipulating dialog boxes at a high level (see “Dialog Box Sub-Package“ on page 375)Ets_File_Choosersub-package functions, for opening a file chooser (see “File Chooser Sub-Package“ on page 422)Ets_Msgsub-package functions, for displaying warning and error messages (see “Message Sub-Package“ on page 459)Ets_Progress_Barsub-package functions, for showing a progress bar on the screen (see “Progress Bar Sub-Package“ on page 513)Ets_Toolsub-package functions, for opening and closing editors (see “Tool Sub-Package“ on page 533)
Handler Prototypes
This section gives prototypes for commonly-used handlers.
button handler
void
ets_button_handler (EtsT_Dbox* dbox_ptr, EtsT_Message message,
EtsT_Submessage submessage, char* control_name, void* state_ptr);
dialog box default handler
void
ets_dbox_default_handler (EtsT_Dbox* dbox_ptr, EtsT_Message message,
EtsT_Submessage submessage, char* dbox_name, void* state_ptr);
treeview init handler
void
ets_treeview_init_handler (EtsT_Dbox* dbox_ptr, const char* treeview_name_ptr);
treeview expand handler
void
ets_treeview_expand_handler (EtsT_Dbox* dbox_ptr,
const char* treeview_name_ptr, EtsT_Tree_Element* clicked_tree_element_ptr);
treeview left-click handler
void
ets_treeview_left_click_handler (EtsT_Dbox* dbox_ptr,
const char* treeview_name_ptr, EtsT_Tree_Element* clicked_tree_element_ptr);
treeview right-click handler
void
ets_treeview_right_click_handler (EtsT_Dbox* dbox_ptr,
const char* treeview_name_ptr, EtsT_Tree_Element* clicked_tree_element_ptr);
Workspace and Object Click Handlers
You can define custom click handlers for specific events in your custom applications. For example, you can define a click handler function that is called when the user clicks an object in the workspace. You would probably want to create different functionality, depending on the type of object that is clicked on, so one argument to this function would be the object type.
After creating this custom click handler, you would register it by calling Ets_Nt_Click_Callback_Register() with the name of the function as an argument. Ets_Nt_Click_Callback_Register() is usually called in an initialization function (ets_startup or a load callback).
Other handlers available are:
Ets_Nt_Menu_Define_Callback_Register(). Registers a callback function that is called every time a right-click menu is to be displayed.Ets_Nt_Menu_Select_Callback_Register(). Registers a callback function that is called every time a menu entry is selected.Ets_Nt_Object_Install_Callback_Register(). Registers a callback function that is called every time the user adds objects to the network.Ets_Tool_Close_Check_Callback_Register(). Registers a function to be called by your application when the user tries to close the current tool window. This function queries whether the tool is ready for closing (basically, checking that everything has been saved).Ets_Tool_Close_Callback_Register(). Registers a function to be called by your application to implement closing the current tool window. This function can interact with the user (for example, asking “Save”, “Don’t Save”, or “Cancel”) before preceding.
All of these handlers should be registered in an initialization function.