创建脚本集合（脚本库）#
第一步是创建一个包含各个命令的脚本集合。您可以定义每个命令以调用指定 Tcl 或 Python 脚本中的特定程序。
随后，各个命令将直接以图形化方式在 VisualApplets GUI 中可用，您可以通过鼠标点击或拖放来启动它们。通过这种方式，您可以将 Tcl 或 Python 程序用作库元素。调用时，这些命令将在 Scripting Console 中执行。如果打开 Scripting Console，您可以查看命令的执行过程。
在 Script Collection 窗格中，您可以查看 VisualApplets 安装中已有的脚本集合以及每个集合包含的命令。
要打开 Script Collection 窗格，请打开 Window 菜单，选择 Dock Windows，然后选择 Scripting Collection：
Scrip Collection 窗格将在 VisualApplets 主窗口右侧打开：
您可以通过以下方式定义脚本集合：
信息
VisualApplets 支持用 Python 和 Tcl 编写的脚本的脚本集合。使用 Python 脚本集合元素时，Scripting Console 会自动切换到 Python，而在控制台设置为 Tcl 时又会切回 Tcl。Python 脚本集合在 Python Version Settings 对话框中选为 Active Version 的 Python 环境中运行。有关详细信息，请参阅 Managing Python Versions。
信息
将所有集合信息存储在 XML 文件中，使您不仅可以将版本控制系统用于单个脚本，还可以用于脚本集合的结构和内容定义。
脚本集合的结构#
每个脚本集合包含多个命令（脚本集合的元素）。
这体现在 GUI 中：
每个命令指向特定脚本中的一个特定过程。执行命令时，将调用它所指向的过程。
要定义脚本集合，您必须定义：
- 集合的名称
- 集合中包含的命令
- 可选：一些其他信息，例如版本号、描述等。
- 可选：代表脚本集合的 GUI 图标。
- 对于每个单独的命令：
- 命令名称
- 命令指向的 Tcl 或 Python 文件
- 命令指向的此文件中的 Tcl 或 Python 过程
- 必须传递给 Tcl 或 Python 过程的参数（从 GUI 启动命令时会提示所需的值）
- 命令模式（参见下文的Adding a Command to a Script Collection）
- 可选：命令范围（参见下文的向脚本集合添加命令）
- 可选：其他信息，例如版本号、描述等。
- 可选：代表该命令的 GUI 图标（参见下文的向脚本集合添加命令）。如果未提供图标文件，GUI 中将使用默认图标。
准确描述一个脚本集合的所有列出信息都存储在一个 XML 文件中。
您可以定义多个脚本集合。
GUI 背后发生了什么？#
在后台，您指定的用于存放集合定义 XML 文件的目录中将创建一个新的 XML 文件（参见必需设置）：
文件名与您在 GUI 中定义的脚本集合名称相同。该 XML 文件包含有关当前定义的集合的所有信息：
As you haven't specified any commands for your script collection yet, the <Elements> element is still empty.
信息
要创建新的脚本集合，您可以使用 GUI，也可以从头开始创建 XML 文件。结果是相同的。GUI 始终显示 XML 文件中定义的信息。
命令选项#
在定义命令时，您可以指定该命令是通过按钮启动 
（即 Trigger Mode）还是通过拖放启动，GUI 中会通过手形图标来指示这一点 
。您还可以在工具栏中为命令添加一个按钮。
对于设置为 Trigger Mode 的命令，您可以定义命令范围。在命令范围中，您可以将命令限制为特定的设计元素（例如模块或链路），以便该命令仅适用于这些元素。
要求#
文件要求#
脚本集合由以下文件组成：
- 定义脚本集合的 XML 文件。该 XML 文件包含集合本身的定义以及集合中包含的命令的定义。
- 包含实际脚本的 Tcl 或 Python 文件。这些文件必须满足以下要求：
- 它们是 Tcl 或 Python 脚本。
- 这些文件仅包含过程。它们不包含在加载脚本文件时执行的任何命令。
- 为避免命名冲突，对于命令 CMD_NAME，请遵循以下命名规范：
- Command_CMD_NAME
- 将 .tcl 或 .py 文件存储在与集合文件（*.xml）相同的目录或其子目录中。
- 可选：用于 VA GUI 上的单个集合或命令图标的 PNG 图标文件。PNG 文件需要满足以下要求：
- 它们必须包含正方形图像。
- 最小分辨率为 16 x 16。
- 将图标文件存储在与集合文件（*.xml）相同的目录或其子目录中。如果未提供图标文件，则在 GUI 中使用默认图标来表示该命令。
信息
正常工作所需的脚本集合的所有文件都是纯文本文件。这允许您将脚本集合定义存储在版本控制系统中。
必需设置#
您可以在 Visual Applets 中指定脚本集合定义文件（XML 文件）的位置。由于您只能为集合脚本文件定义一个存储位置，Basler 建议将所有集合定义 XML 文件存储在同一目录中。
要设置脚本集合目录的路径：
- 从 Settings 菜单中选择 System Settings。
- 选择 Paths 选项卡。
- Under Script Collection, specify the path to the directory where you store the collection-defining XML files you want to use. The default setting is <VA installation directory>/ScriptCollection:
对于通过 GUI 创建的每个脚本集合，都会在指定的目录中写入一个 XML 文件。如果您向该目录添加了新的集合描述 XML 文件或编辑了存储在那里的现有 XML 文件，则可以在 VisualApplets GUI 中显示这些更改。若要显示更改而无需重新启动 VisualApplets，请在 Script Collection 窗格中单击鼠标右键，然后选择 Rescan Script Collection Directory。
通过 GUI 创建脚本集合#
您可以通过图形用户界面完全定义脚本集合，而无需修改底层代码。 XML 文件。 XML 文件在后台创建和更新。一旦您定义了集合及其包含的命令，该集合就会显示在屏幕上。 VisualApplets 图形用户界面。
创建新脚本集合#
通过图形用户界面创建新的脚本集合：
- 右键单击 Script Collection 窗格。
-
从上下文菜单中选择 Create New Script Collection。
对话框打开。
-
输入新脚本集合的名称并点击 OK 确认。
新集合将显示在 Script Collection 窗格中：
向脚本集合添加命令#
通过图形用户界面向脚本集合添加命令：
- 右键单击脚本集合的名称。
-
从上下文菜单中选择 Create Element。
此时会弹出一个对话框，用于描述您要添加的命令。红色高亮显示的字段为必填项：
-
Command Name（必填）：为您的命令指定一个名称。
- Version：您可以为您的命令提供版本信息。
- Description：该描述将作为工具提示信息显示。请输入命令将调用的过程的描述。
- Icon File：如果您希望在 Script Collection 窗格或工具栏中显示特定的命令图标，可以在此处提供图标文件的路径。您可以设置绝对路径，也可以设置相对于集合文件（*.xml）的路径。（详情请参见文件要求）。如果您不选择图标文件，GUI 将使用默认图标来表示您的新命令。
-
Script File：提供包含您希望通过该命令启动的过程的脚本路径和名称。您可以定义相对于集合文件的路径（.xml）。或者，您也可以不定义包含该命令要调用的过程的脚本文件，而是直接在命令中输入 Tcl 或 Python 过程。直接在命令中定义的 Tcl 或 Python 过程将在您每次调用该命令时执行。如果您倾向于此选项，请将 Script File 字段留空，并在 Command Call 下的 Template 字段中提供命令所代表的整个 Tcl 或 Python 过程。
如果您尝试执行未选择定义为命令作用域的设计元素的命令，将弹出 Invalid Scope 消息：
-
Command Options：定义您希望如何在 VisualApplets GUI 上启动命令。可以通过点击按钮启动命令（Trigger Mode），也可以通过拖放到设计窗口中启动命令（Drag & Drop 模式）。如果您使用 Trigger Mode，您可以在程序窗口的工具栏中为该命令添加一个额外的按钮，并定义执行该命令的条件（作用域）。
-
Trigger Mode：要创建一个点击即可启动命令的按钮，请清除 Drag & Drop 字段。该命令将连同 Run 按钮一起显示在 Script Collection 窗格中：
要开始执行命令，请点击 Run 按钮。
-
工具栏选项（仅限 Trigger Mode）：要使命令在 VisualApplets 的工具栏中可用：勾选 Add to Toolbar 选项；只有在清除 Drag & Drop 复选框时，此操作才可行。在 GUI 上，将为该集合创建一个新工具栏并显示命令图标：
点击工具栏中的命令图标与点击 Run 按钮具有相同效果。您在 Description 下输入文本将作为工具提示显示在工具栏中：
-
Drag & Drop 模式：如果您希望通过 GUI 上的拖放操作来启动执行，请勾选 Drag & Drop 复选框。在这种情况下，Action 列中将显示一个手形图标：
-
-
Define Command Scope（仅在 Trigger Mode 下可用）：如果您希望将命令限制在设计中的特定设计元素内，请勾选 Define Command Scope 复选框。此选项仅在禁用 Drag & Drop 时可用。
可以使用如下选项：
- Module：您必须选择且仅选择一个模块来启动此命令。
- Link：您必须选择且仅选择一个链路来启动此命令。
- CommentBox：您必须选择且仅选择一个注释框来启动此命令。
- SimModule：您必须选择且仅选择一个仿真模块来启动此命令。
- SingleSelect：您必须选择且仅选择一个设计元素来启动此命令。您选择哪种元素（模块、链路等）并不重要。
- MultiSelect：您必须选择两个或更多设计元素来启动此命令。您选择哪种元素（模块、链路等）并不重要。
您可以组合使用这些选项：例如，如果您组合使用 Module 和 Link 选项，只要您选择正好一个模块或者正好一个链路，就会执行该命令。组合使用 SingleSelect 和 MultiSelect 允许在选择了一个或多个设计元素时启动命令。
命令的作用域（即 Tcl 过程的作用域）显示在 VisualApplets GUI 的 Script Collection 窗格中：
如果您尝试执行未选择定义为命令作用域的设计元素的命令，将弹出 Invalid Scope 消息：
-
Command Call：在此定义命令的调用方式。
- Template：在此输入命令调用的模板。通常，它以 Tcl 或 Python 过程的名称开始，后跟参数列表。这些参数作为用 % 包裹的占位符给出。对于每个占位符，您可以在下方的列表中定义相应的参数。请遵循 Tcl 或 Python 命令的语法。或者，如果您将上面的 Script File 字段留空，也可以在此处输入完整的 Tcl 或 Python 控制台命令行。
- 参数：在此定义模板中使用的参数。此处列出的参数顺序无关紧要。只需确保参数名称与模板的占位符名称匹配即可。要将新参数添加到命令定义中，请点击
加号按钮。- Name：为每个参数提供一个名称。使用在命令调用时承载该值的参数所用的名称。
- Type：定义参数的数据类型。您可以定义 string、integer 或 double 类型的参数。
- Mode：定义您的参数包含固定值、变量还是放置位置。
dropX和dropY提供在拖放过程中释放鼠标指针时的位置。请注意，dropX和dropY仅在 Drag & Drop 模式下可用。如果您将参数定义为变量，系统将在启动命令时要求您输入该参数的值。 - Default：在此处输入默认值。
- Min/Max：在此处输入参数的值范围。
- Inc：在此处输入值范围内的步长。
示例：
通过 XML 创建脚本集合#
您可以完全在 XML 中定义脚本集合，而无需使用 VisualApplets GUI。
为每个脚本集合创建一个 XML 文件。
一旦您在 XML 文件中定义了一个 collection 及其包含的命令，该 collection 就会显示在 VisualApplets GUI 中。前提条件：您已在 VisualApplets 的 System Settings 中指定了 XML 文件的位置，请参见 Required Settings。
关于 script collection 的结构和内容的所有信息都定义在每个 script collection 的一个 XML 文件中。您可以提供多个 XML 文件，每个文件定义一个 script collection。如果定义 script collection 的 XML 文件位于您在 VisualApplets 的菜单 Settings -> System Settings -> Paths -> Script Collection 下指定的目录中，则该 script collection 将显示在 VisualApplets GUI 的 Script Collection 窗格中。
示例#
VisualApplets provides the three example script collections DesignTools, LayoutAssist, and TclExamples. You find them as .xml file as well as as .tcl file in the directory <VA installation directory>/Examples/AdvancedVAFunctions/Script Collection.
要在 VisualApplets 的 GUI 中显示示例脚本集合：
-
在 Settings -> System Settings -> Paths 中定义存储示例 script collection 的文件夹路径。
-
在 Script Collection 窗格中右键点击，然后选择 Rescan Script Collection Directory。
此时，GUI 会在 Script Collection 窗格中显示示例 script collection：
-
您现在可以试用 GUI 选项和 XML 文件的内容，以查看您的操作产生的影响。
示例 DesignTools.xml 的外观如下：
句法#
XML 文件的语法如下：
信息
Make sure you use the same name for the XML file name as in tag <ScriptCollection> of the XML file.
示例：
文件名：
myCollection.xml
XML 文件中的集合名称：
<ScriptCollection name ="myCollection" formatVersion="1.0">.
格式遵循以下约定进行定义：
- 可选，各个元素包含在方括号 [ ] 中。
- 允许不存在、出现一次或多次的语法元素包含在花括号 { } 中。
- 语法 (..|..) 表示可以指定所提供的元素之一。
- 参数值以斜体大写字母表示。
The Tags <Scope> and <Toolbar>#
<Scope>:
Use the tag <Scope>, if you want to limit the command to a specific design element in the design.
这是一个可选标签，仅当您将命令模式设置为 Trigger. You can define <Scope> multiple times to specify multiple scopes. The tag isn't allowed when Command mode 参数 DragAndDrop.
可以使用如下选项：
- Module：您必须选择且仅选择一个模块来启动此命令。
- Link：您必须选择且仅选择一个链路来启动此命令。
- CommentBox：您必须选择且仅选择一个注释框来启动此命令。
- SimModule：您必须选择且仅选择一个仿真模块来启动此命令。
- SingleSelect：您必须选择且仅选择一个设计元素来启动此命令。您选择哪种元素（模块、链路等）并不重要。
- MultiSelect：您必须选择两个或更多设计元素来启动此命令。您选择哪种元素（模块、链路等）并不重要。
您可以组合使用这些选项：例如，如果您组合使用 Module 和 Link 选项，只要您选择正好一个模块或者正好一个链路，就会执行该命令。组合使用 SingleSelect 和 MultiSelect 允许在选择了一个或多个设计元素时启动命令。
如果您尝试执行未选择定义为命令作用域的设计元素的命令，将弹出 Invalid Scope 消息：
<Toolbar>:
可选标签，仅当您设置 Command mode 变为 Trigger时允许使用。如果包含该标签，则该命令将添加到集合的工具栏中。当出现以下情况时，该标签不允许使用： Command mode 参数 DragAndDrop.
参数#
您必须将以下值写入上图中以斜体显示的参数：
- COL_NAME：脚本集合的名称。
- COL_PNG_FILE_PATH：脚本集的图标文件路径（PNG 格式，详见文件要求）。请指定相对于 XML 文件的路径。
- COL_TOOLTIP_TEXT：显示为描述脚本集合的工具提示的文本。
- CMD_NAME：命令名称。
- CMD_TOOLTIP_TEXT：显示为描述命令的工具提示的文本。
- CMD_VERSION：以 MAJOR.MINOR 格式表示的命令版本（例如 1.0）
- TCL_FILE_PATH：包含在执行命令时要调用的过程的 Tcl 脚本的路径。指定相对于 XML 文件的路径。
- CMD_PNG_FILE_PATH：命令的图标文件（PNG 格式，详见文件要求）。请指定相对于 XML 文件的路径。
- CMD_CALL：Tcl 脚本中由命令调用的过程的名称（或整个 Tcl 过程）。
- CMD_PARAM：在命令调用时由实际值替换的参数名称（实参）。仅指定在以下内容中定义的参数名称
tags。 - PAR_NAME：参数名称。
- PAR_RANGE_FROM：值范围的起点（仅适用于 int 或 double 数据类型）。
- PAR_RANGE_TO：值范围的终点（仅适用于 int 或 double 数据类型）。
- PAR_RANGE_INC：值范围内的步长（仅适用于 int 或 double 数据类型）。
- PAR_VALUE：参数的默认值。
将脚本集合加载到 GUI 中#
对于通过 GUI 创建的每个脚本集，都会在您在设置 (Settings) → 系统设置 (System Settings) → 路径 (Path) 下指定的目录中写入一个 XML 文件。如果您将新的描述脚本集的 XML 文件添加到该目录，或编辑其中存储的现有 XML 文件，您可以使您的更改在 VisualApplets GUI 中可见。要显示您的更改而无需重新启动 VisualApplets，请右键单击脚本集 (Script Collection) 窗格，然后选择重新扫描脚本集目录 (Rescan Script Collection Directory)。