基本 API
图形用户界面(GUI)
对话框与控件
大多数 GUI 函数用于以编程方式操作对话框及对话框内的控件。通常用于这些目的的一些函数是 GUI 包中 Ets_Dbox, Ets_Ctl 和 Ets_Tree_Element 子包中的函数。有关这些子包以及本节所述函数的详细信息,参见第 6 章“GUI Package”(第 243 页)。
对话框本身在 Dialog Box Editor (op_etsed) 中创建,该编辑器在第 3 章“Dialog Box Resource File Editor”(第 65 页)中有说明。本节重点介绍从对话框调用的处理程序函数。
将回调与 GUI 控件关联
在 Dialog Box Editor 中创建对话框时,你为每个控件指定处理程序函数。当用户对控件或对话框执行某些操作时,这些处理程序函数会被调用。此外,对话框本身有一个默认处理程序函数,它会被调用两次:一次是在对话框创建时,另一次是在对话框销毁时。
被调用函数的效果取决于控件的性质和你的意图。例如,当单击 OK 按钮时,该按钮的处理程序函数通常从对话框中的控件读取值,将这些值设置到内部数据结构中,然后调用 Ets_Dbox_Destroy() 关闭对话框。
对话框中的所有函数必须驻留在同一个共享对象库中。该库在 Dialog Box Editor 的 ETS Library 对话框属性中指定(有关该编辑器的详细信息,参见第 3 章“Dialog Box Resource File Editor”(第 65 页))。你通常会将应用使用的所有函数存储在一个库中。
不同的控件有不同类型的处理程序函数。
表格控件
表格控件用于管理在对话框中以行和列(表格)形式显示的数据。表格通常用作某种数据结构的接口,该数据结构通过 Ets_Dbox_State_Set() 与对话框状态信息相关联。表格控件支持以下处理程序:
- ETS Display Proc,当表格单元格需要重绘时调用。有关原型,参见第 605 页的
EtsT_Table_Display_Proc。 - ETS Tooltip Proc,当工具提示需要重绘时调用。有关原型,参见第 605 页的
EtsT_Table_Display_Proc。 - ETS Decoration Proc,当表格单元格需要重绘时调用。有关原型,参见第 603 页的
EtsT_Table_Decoration_Proc。 - ETS Store Proc,当用户为表格单元格设置值时调用(例如,在从键盘输入值或从弹出菜单选择值之后)。有关原型,参见第 606 页的
EtsT_Table_Save_Proc。 - ETS Double Click Proc(参见第 602 页的
EtsT_Table_Click_Proc) - ETS Left Click Proc(参见第 602 页的
EtsT_Table_Click_Proc)
使用这些处理程序来控制用户与表格的交互方式。例如,你可以控制:
- 哪些字段可编辑——通过在单击处理程序中调用(或不调用)
Ets_Ctl_Table_Cell_Edit()。 - 通过显示处理程序控制任意表格单元格中显示的内容。
- 通过存储处理程序控制用户的输入和输出。
树视图控件
树视图具有:
- 一个 init 函数,在树视图首次显示时调用(有关原型,参见第 614 页的
EtsT_Tree_Init_Proc) - 一个展开处理程序,在用户展开树视图时调用(参见第 613 页的
EtsT_Tree_Expand_Proc) - 一个工具提示处理程序,当光标停留在已展开的树视图元素上的时间超过“tooltip_delay“偏好设置所指定的时长时调用(参见第 617 页的
EtsT_Tree_Tooltip_Proc) - 一个左键单击处理程序,当用户在树视图中的控件上左键单击时调用(参见第 615 页的
EtsT_Tree_Left_Proc) - 一个右键单击处理程序,当用户在树视图中的控件上右键单击时调用(参见第 616 页的
EtsT_Tree_Right_Proc)
其他控件
所有其他控件都使用默认处理程序函数(参见“Using the Default Event-Handler Prototype“(第 42 页))。当以下任一事件发生时,该函数以等于 EtsC_Message_Control 的 message 参数被调用:
- 单击该控件
- 输入一个值
其他常用的 GUI 函数有:
Ets_An子包函数,用于创建分析面板(图形)(参见第 248 页的“Analysis Panel Sub-Package“)Ets_Dbox子包函数,用于在较高层次上操作对话框(参见第 375 页的“Dialog Box Sub-Package“)Ets_File_Chooser子包函数,用于打开文件选择器(参见第 422 页的“File Chooser Sub-Package“)Ets_Msg子包函数,用于显示警告和错误消息(参见第 459 页的“Message Sub-Package“)Ets_Progress_Bar子包函数,用于在屏幕上显示进度条(参见第 513 页的“Progress Bar Sub-Package“)Ets_Tool子包函数,用于打开和关闭编辑器(参见第 533 页的“Tool Sub-Package“)
处理程序原型
本节给出常用处理程序的原型。
按钮处理程序
void
ets_button_handler (EtsT_Dbox* dbox_ptr, EtsT_Message message,
EtsT_Submessage submessage, char* control_name, void* state_ptr);
对话框默认处理程序
void
ets_dbox_default_handler (EtsT_Dbox* dbox_ptr, EtsT_Message message,
EtsT_Submessage submessage, char* dbox_name, void* state_ptr);
树视图 init 处理程序
void
ets_treeview_init_handler (EtsT_Dbox* dbox_ptr, const char* treeview_name_ptr);
树视图展开处理程序
void
ets_treeview_expand_handler (EtsT_Dbox* dbox_ptr,
const char* treeview_name_ptr, EtsT_Tree_Element* clicked_tree_element_ptr);
树视图左键单击处理程序
void
ets_treeview_left_click_handler (EtsT_Dbox* dbox_ptr,
const char* treeview_name_ptr, EtsT_Tree_Element* clicked_tree_element_ptr);
树视图右键单击处理程序
void
ets_treeview_right_click_handler (EtsT_Dbox* dbox_ptr,
const char* treeview_name_ptr, EtsT_Tree_Element* clicked_tree_element_ptr);
工作区与对象单击处理程序
你可以在自定义应用中为特定事件定义自定义单击处理程序。例如,你可以定义一个当用户单击工作区中的对象时调用的单击处理程序函数。你可能希望根据被单击对象的类型提供不同的功能,因此该函数的一个参数将是对象类型。
创建这个自定义单击处理程序后,你将通过调用 Ets_Nt_Click_Callback_Register() 并把函数名作为参数来注册它。Ets_Nt_Click_Callback_Register() 通常在初始化函数(ets_startup 或加载回调)中调用。
其他可用的处理程序有:
Ets_Nt_Menu_Define_Callback_Register()。注册一个每次将要显示右键单击菜单时调用的回调函数。Ets_Nt_Menu_Select_Callback_Register()。注册一个每次选中菜单条目时调用的回调函数。Ets_Nt_Object_Install_Callback_Register()。注册一个每次用户向网络添加对象时调用的回调函数。Ets_Tool_Close_Check_Callback_Register()。注册一个当用户试图关闭当前工具窗口时由你的应用调用的函数。该函数询问工具是否已准备好关闭(基本上是检查是否已全部保存)。Ets_Tool_Close_Callback_Register()。注册一个由你的应用调用以实现关闭当前工具窗口的函数。该函数可以在继续之前与用户交互(例如询问“Save”、“Don’t Save”或“Cancel”)。
所有这些处理程序都应在初始化函数中注册。