外部工具支持脚本

外部工具支持(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:添加一个可选操作

  1. 在系统提示符下,进入 <reldir>/sys/configs 目录。

  2. 使用文本编辑器打开你要添加可选操作的操作列表文件。ODK 应用程序使用的操作列表文件都列在编辑器配置文件(<product>.ets,其中 <product> 是被定制的分析软件产品,例如 modeler、itguru、spguru 或 netbiz)中。

  3. 在文件中添加以下几行。可选操作将出现在指定的菜单中,其位置由 position 属性指定,或者按它在文件中出现的顺序排列。

    start_operation
    	operation:					exec_builtin <builtin_function_name>
    	menu string:					"<name of menu item>"
    	menu header:					<menu name>
    end_operation
    
  4. 保存对文件的更改,关闭文本编辑器,然后启动应用程序。该可选操作将出现在指定的编辑器中。

作为示例,假设某位模型开发者想为 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_project
quit
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… print
print_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_browser
nt_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

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · 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