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_Proc on page 605.
  • ETS Tooltip Proc, called when a tooltip needs to be redrawn. For the prototype, seeEtsT_Table_Display_Proc on page 605.
  • ETS Decoration Proc, called when a table cell needs to be redrawn.For the prototype, see EtsT_Table_Decoration_Proc on 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_Proc on page 606.
  • ETS Double Click Proc (see EtsT_Table_Click_Proc on page 602)
  • ETS Left Click Proc (see EtsT_Table_Click_Proc on 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_Proc on page 614)
  • an expand handler, called when the user expands a treeview (see EtsT_Tree_Expand_Proc on 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_Proc on page 617)
  • a left-click handler, called when the user left-clicks on a control in the treeview (see EtsT_Tree_Left_Proc on page 615)
  • a right-click handler, called when the user right-clicks on a control in the treeview (see EtsT_Tree_Right_Proc on 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_An sub-package functions, for creating analysis panels (graphs) (see “Analysis Panel Sub-Package“ on page 248)
  • Ets_Dbox sub-package functions, for manipulating dialog boxes at a high level (see “Dialog Box Sub-Package“ on page 375)
  • Ets_File_Chooser sub-package functions, for opening a file chooser (see “File Chooser Sub-Package“ on page 422)
  • Ets_Msg sub-package functions, for displaying warning and error messages (see “Message Sub-Package“ on page 459)
  • Ets_Progress_Bar sub-package functions, for showing a progress bar on the screen (see “Progress Bar Sub-Package“ on page 513)
  • Ets_Tool sub-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.

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com