外部工具支持脚本
外部工具支持(External Tool Support,ETS)包让模型开发者能够借助 ETS 脚本增强 GUI 程序的用户界面与行为。
ETS 脚本使开发者能够控制 GUI 程序用户界面的两个基本方面:
- 脚本可以指定向 GUI 程序的菜单中添加菜单项,这些菜单项称为操作。开发者随后在脚本中定义每个自定义菜单项被选中时所执行的 ETS 操作。
- 脚本可以通过动作定义(action definition)指定:当用户单击对象属性对话框中的自定义按钮时执行相应的 ETS 操作。
此外,ETS 脚本还可以定义自定义调色板和自定义菜单的内容(本章后面会加以说明)。ETS 脚本共有六种类型:编辑器配置、操作列表、菜单定义、调色板定义、动作定义和程序执行。
操作定义
Riverbed 程序和编辑器的标准操作与自定义操作都在一种特殊的 ETS 脚本文件中定义,这种文件称为操作列表文件。操作列表文件的名称通常采用 std_<editor>_operations.ets 或 std_<editor>_<menu>_operations.ets 的形式。可以为一个编辑器指定任意数量的自定义操作。
例如,为 Network Editor 添加的自定义操作可以写入名为 std_network_network_operations.ets 的操作列表文件,也可以写入一个新的、由开发者定义的文件。操作列表文件要生效,必须在编辑器配置文件中该编辑器的条目里被引用。
操作列表文件
操作列表文件声明在编辑器中出现的系列菜单、子菜单和操作。一个操作条目可以引用某个内置函数,也可以引用某个 ETS 文件。当引用内置函数时,guidance string 字段是可选的。icon、shortcut 和 separator 字段始终是可选的。每个条目中的字段可以按任意顺序出现。必须在编辑器配置文件中出现对操作列表文件的引用,菜单项才会显示。
例如,图 7 中的 Scenarios 菜单可以由图 8 中的示例操作列表文件定义。
图 7:示例菜单

图 8:示例操作列表文件
File format: operation list
start_operation
title: "Scenarios"
position: 3
end_operation
#########################################
start_operation
operation: exec_builtin new_scenario
menu string: "New Scenario"
menu header: "Scenarios"
position: 100
separator: before
end_operation
start_operation
operation: exec_builtin duplicate_scenario
menu string: "Duplicate Scenario"
menu header: "Scenarios”
position: 110
end_operation
start_operation
operation: exec_builtin manage_scenarios
menu string: "Manage Scenarios"
menu header: "Scenarios”
position: 120
end_operation
start_operation
submenu: "Scenarios:Scenario"
menu string: "Switch To"
menu header: "Scenarios"
position: 130
end_operation
#########################################
start_operation
submenu: "Scenarios:Components"
menu string: "Scenario Components"
menu header: "Scenarios"
position: 200
separator: before
end_operation
start_operation
operation: exec_builtin import
menu string: "Import..."
menu header: "Scenarios:Components"
position: 100
separator: before
end_operation
start_operation
operation: exec_builtin export
menu string: "Export..."
menu header: "Scenarios:Components"
position: 110
end_operation
start_operation
submenu: "Scenarios:Aliases"
menu string: "Node Aliases"
menu header: "Scenarios"
position: 300
end_operation
start_operation
operation: exec_builtin import_aliases_from_text
menu string: "Import From Text File..."
menu header: "Scenarios:Aliases”
position: 300
end_operation
start_operation
operation: exec_builtin export_aliases_to_text
menu string: "Export To Text File..."
menu header: "Scenarios:Aliases”
position: 310
end_operation
start_operation
operation: exec_builtin import_alias_sets
menu string: "Import Change Sets..."
menu header: "Scenarios:Aliases"
position: 320
separator: before
end_operation
start_operation
operation: exec_builtin export_alias_set
menu string: "Export Change Sets..."
menu header: "Scenarios:Aliases"
position: 330
end_operation
操作列表文件结构
操作列表文件具有如下结构:
- 第一行指明该 ETS 脚本是一个操作列表文件。
- 第一行之后是菜单、子菜单和操作条目定义块。每个定义以“
start_operation”一行开始,以“end_operation”一行结束。在这两行之间,以<attribute name>: <attribute value>的形式给出描述该菜单、子菜单或操作的属性。 - 菜单由两个属性描述,这两个属性可以在菜单定义块中以任意顺序出现。
- title。该属性表明此条目用于一个菜单。title 的取值必须加引号,它将出现在编辑器的菜单栏中。
- position。该属性指定菜单在菜单栏中的位置,从左到右计数。你可以在取值后加上“R”来从右向左指定位置;例如,“2R”表示从右数第二个条目。
- 子菜单由四个属性描述,这四个属性可以在子菜单定义块中以任意顺序出现。
- submenu。该属性表明此条目用于一个子菜单。该属性的取值必须加引号,在指定子菜单条目时会用到它。
- menu string。该属性指定菜单项的名称。取值必须加引号。
- menu header。该属性指定该子菜单的父菜单。取值必须加引号,并且应当与父菜单的 title 或 submenu 属性取值一致。
- position。该设置指定子菜单在父菜单中的位置,从上到下计数。该取值与父菜单中所有其他子菜单和操作的位置设置一起,决定父菜单中各条目的排列顺序。
- 操作由若干属性描述,这些属性可以在操作条目定义块中以任意顺序出现。
- operation。该属性表明此条目用于一个操作。它指定选中该条目时应发生什么。该属性的取值必须是表 4 中列出的操作之一。
- menu string。该属性指定菜单中显示的名称。取值必须加引号。
- menu header。该属性指定该操作的父菜单。取值必须加引号,并且应当与父菜单的 title 或 submenu 属性取值一致。
- position。该属性指定操作在父菜单中的位置,从上到下计数。该取值与父菜单中所有其他子菜单和操作的 position 属性一起,决定父菜单中各条目的排列顺序。
- shortcut。该属性指定用于调用该操作的按键组合。取值必须加引号。快捷键可以是键盘上任意有效的按键组合,例如“ctrl+a”、“alt+k”、“F5”、“shift+F9”或“ctrl+shift+c”。
- separator。该属性指定菜单中位于操作之前或之后的一条分隔线。如果取值为“yes”或“after”,则在操作名称之后出现一条分隔线。如果取值为“before”,则在操作名称之前出现一条分隔线。
- toggle。该属性启用一个对勾标记,每次选中该操作时,操作名称前的对勾标记都会在开启与关闭之间切换。取值可以是“no”、“yes”或“exclusive”。
- icon。该属性指定要在编辑器按钮栏中显示的图标图形的名称。这可以是标准图标数据库中的图标,也可以是开发者创建的自定义图标。如果不包含该属性,该操作只会出现在 menu header 属性所指定的菜单中。
- guidance string。该属性定义当光标位于菜单中的操作名称上、或位于按钮栏中对应按钮上时,弹出的工具提示中所显示的文本。如果该按钮对应一个内置函数,则该属性是可选的。
- 如果“#”字符是 ETS 脚本某行的第一个字符,则该行的其余部分被视为注释而被忽略。
表 4:操作参数
| 操作 | 用途 |
|---|---|
exec_builtin <builtin_function_name> |
执行软件内置的某个函数。可用的函数列于表 5 内置函数。 |
go_file <ets_config_file> |
执行一个包含 ETS 代码的文件,该代码定义了一个对话框(内部执行脚本)。注:这是一种旧格式;新的对话框应使用对话框编辑器创建,并通过“load_dialog”操作调用。 |
exec_file <ets_program_name> |
执行一个包含 ETS 代码的文件,该代码不使用对话框。 |
load_dialog <dialog_name> |
执行一个包含 ETS 代码的文件,其中带有从资源文件获得的对话框。对话框资源文件可以用对话框编辑器创建(如第 3 章“Dialog Box Resource File Editor”第 65 页所述)。 |
exec_function <library_name> <symbol_name> |
从 ETS 库(.ets.so 或 .ets.dll 文件)或 Python 文件中调用指定函数(不带参数,也没有返回值)。 |
exec_browser <url> |
启动 Web 浏览器并访问指定 URL。<url> 必须是有效的非空 URL 格式,否则该操作不会出现在菜单中。 |
exec_pdf <help_card_name> |
启动 Acrobat Reader 并显示指定的 PDF 帮助卡文件。<help_card_name> 不应包含目录或扩展名。 |
你可以通过下面的过程为编辑器添加操作。
过程 9:添加一个可选操作
-
在系统提示符下,进入
<reldir>/sys/configs目录。 -
使用文本编辑器打开你要添加可选操作的操作列表文件。ODK 应用程序使用的操作列表文件都列在编辑器配置文件(
<product>.ets,其中<product>是被定制的分析软件产品,例如modeler、itguru、spguru或netbiz)中。 -
在文件中添加以下几行。可选操作将出现在指定的菜单中,其位置由 position 属性指定,或者按它在文件中出现的顺序排列。
start_operation operation: exec_builtin <builtin_function_name> menu string: "<name of menu item>" menu header: <menu name> end_operation -
保存对文件的更改,关闭文本编辑器,然后启动应用程序。该可选操作将出现在指定的编辑器中。
作为示例,假设某位模型开发者想为 Network Editor 添加三个动作。如果该开发者不想把这些新操作直接加入 std_network_network_operations.ets 文件,可以创建一个新的操作列表文件(本例中称为 network_extra_operations.ets)。
第一个动作称为“Administration Network”,它会显示一个参数对话框。用户需要能够在执行程序之前修改参数,以便基于“administration database”创建一个网络模型。
下一个动作是“Executive Network”,它执行程序以基于“executive database”创建网络模型。程序执行期间应用程序会等待。程序结束后,会打开一个文本编辑区,供用户记录注释。
第三个动作是“Engineering Network”,它执行程序以基于工程数据库创建网络模型。该程序在后台执行。
这位模型开发者还不确定应当如何呈现这些动作,因此将通过创建三个 Network 菜单项来做试验,每一项演示一种不同的方式。第一个操作将显示一个调色板,其中把三个动作以图标形式呈现。第二个操作将显示一个菜单,其中把三个动作以菜单项形式呈现。第三个操作将直接执行第三个动作“Engineering Network”。
在图 9 中,操作列表 ETS 脚本定义了三个自定义操作。这段代码可以存放在名为 network_extra_operations.ets 的文件中。
图 9:操作定义文件示例
File format: operation list
# sample operation entry definition blocks follow
start_operation
menu string: "Custom Database Palette"
menu header: "Network"
guidance string: "Obtain custom database derived network"
operation: load_dialog custom_palette
end_operation
start_operation
menu string: "Custom Database Menu"
menu header: "Network"
guidance string: "Obtain custom database derived network"
operation: exec_file custom_menu
end_operation
start_operation
menu string: "Execute Custom Database"
menu header: "Network"
operation: exec_file custom_trans_engineer
guidance string: "Load Engineering Net"
end_operation
当把上述示例的文件目录包含在用户的偏好文件中,并且把 network_extra_operations.ets 添加到编辑器配置文件中的某个编辑器条目之后,所列的菜单项就会出现在相应编辑器的 Network 菜单中。
内置函数
下表列出内置函数。说明列中给出的要么是函数的菜单名称(即 menu string 属性的取值),要么是对该函数的(小写)说明。
表 5:内置函数
| 菜单字符串或说明 | 内置函数名 |
|---|---|
| Add Image… | add_bkg |
| Add Image Map… | add_map |
| annotation: create ellipse(批注:创建椭圆) | create_annot_ellipse |
| annotation: create line(批注:创建直线) | create_annot_line |
| annotation: create rectangle(批注:创建矩形) | create_annot_rect |
| annotation: create text(批注:创建文本) | create_annot_text |
| Background(背景) | background |
| Clear Model(清除模型) | clear_model |
| Close | close_projectquit |
| Collapse Selected Subnets(折叠所选子网) | collapse_subnets |
| Components: Export… | export |
| Components: Import | import |
| Copy | copy |
| Cut | cut |
| Declare External Object Files(声明外部对象文件) | declare_ext_files |
| Delete Models… | delete_models |
| Delete Projects… | delete_projects |
| Device Creator | m3dc_gen_palette |
| Duplicate Scenario… | duplicate_scenario |
| duplicate selected objects(复制所选对象) | duplicate |
| Edit/View Comment Log | open_comment_log |
| ETS Scripting | network_ets_scripting |
| Exit | exit |
| Expand Selected Subnets(展开所选子网) | expand_subnets |
| Export to Visio | visio_export |
| Find Node… | find_node |
| From XML File… | import_xml_topology |
| generate EMA C code for all scenarios of the project(为项目的全部场景生成 EMA C 代码) | gen_full_ema_code |
| Go To Parent Subnet(转到父子网) | previous_subnet |
| Hide All(全部隐藏) | vc_hide_all |
| License Management | flm_tool |
| Manage Scenarios… | manage_scenarios |
| Map Edit Mode | edit_bkg |
| Model Documentation(模型文档) | view_pdf_doc |
| New… | new_model |
| New Network… | new_network |
| New Scenario | new_scenario |
| Open… | open_model |
| Open Annotation Palette(打开批注调色板) | open_annot_palette |
| Open Edit Pad(打开编辑区) | open_edit_pad |
| Open Network… | load |
| Open Object Palette(打开对象调色板) | open_palette |
| Page Setup… | page_setup |
| Paste | paste |
| Paths(路径) | path |
| Preferences | admin_tool |
| Print… | printprint_preview |
| Print All Subnets… | all_subnets_print_preview |
| Print Text Report(打印文本报告) | print_report |
| Rapid Configuration(快速配置) | rapid_config |
| Redraw(重画) | redraw |
| Refresh Model Directories(刷新模型目录) | rehash_dirs |
| Save | save |
| Save As... | save_project_as |
| Select Objects… | select_logical |
| Set Border Map… | load_map |
| Set Grid Properties… | set_grid_props |
| Show All(全部显示) | vc_show_all |
| Show Annotations in Subnet(显示子网中的批注) | hide_annots |
| Show Maps in Subnet(显示子网中的地图) | hide_map_bkg |
| Show Network Browser(显示网络浏览器) | net_object_browsernt_network_browser_show |
| Startup Wizard(启动向导) | startup_wizard |
| To Bitmap… | image_capture |
| To HTML… | export_to_html |
| To Rectangle(缩放到矩形) | zoom |
| To Selection(缩放到所选) | zoom_selected |
| To Spreadsheet… | net_summary_report |
| To Window(缩放到窗口) | zoom_full |
| To XML… | xml_export |
| Traffic Browser(流量浏览器) | net_object_browser_traffic |
| Undo | undo |
| Unzoom(取消缩放) | unzoom |
| Verify Links… | check_links |
| zoom to all objects in subnet(缩放到子网中的所有对象) | zoom_to_all |
动态更新操作状态
操作(菜单、菜单项或工具按钮)的外观在 GUI 中可能需要随应用程序的状态而变化。例如,某个操作可能:
- 部分时间处于禁用状态(禁用的操作以变暗的方式显示)。
- 名称前带有对勾标记,表示处于活动状态。
- 在不同时刻改变名称(例如,某个菜单项可能在“Show windows”和“Hide windows”之间切换)。
你可以通过提供一个命令查询过程,并在 ETS 脚本文件中把它与某个操作关联,来控制这些外观变化。共有五个属性支持命令查询。
- query id。该属性指定一个字符串,它会被传给查询过程,用以标识受影响的该操作。
- query procs library。该属性指定包含查询过程的文件的名称。
- query enabled state proc。该属性指定用于确定该操作启用状态的过程名称。该过程的原型见 EtsT_Command_Query_Enabled_State_Proc 第 586 页。
- query checkmark state proc。该属性指定用于确定该操作对勾标记状态的过程名称。该过程的原型见 EtsT_Command_Query_Checkmark_State_Proc 第 587 页。(必须把该操作的“toggle”属性设置为“yes”或“exclusive”,才能显示对勾标记。)
- query title proc。该属性指定用于确定该操作所显示名称的过程名称。该过程的原型见 EtsT_Command_Query_Title_Proc 第 588 页。
图 10 给出了一个操作定义示例。该示例中的查询属性指定了一个过程,用于控制何时在“Map Edit Mode”菜单项前显示对勾标记。
图 10:使用操作查询的操作定义示例
start_operation
operation: exec_builtin edit_bkg
menu string: "Map Edit Mode"
menu header: "View:Background"
toggle: yes
query library: my_query_procs
query id: map_edit_operation
query checkmark state proc: map_edit_checkmark_state_get
position: 130
end_operation