创建脚本集合（脚本库）#
第一步，您需要创建一个包含各个命令的脚本集合。您可以定义每个命令，使其调用指定的 Tcl 或 Python 脚本中的特定程序。
随后，各个命令将直接在 VisualApplets GUI 中以图形化方式可用，您可以通过鼠标点击或拖放来启动它们。这样，您就可以将您的 Tcl 或 Python 程序用作库元素。调用时，这些命令将在 Scripting Console 中执行。如果您打开 Scripting Console，您可以看到命令是如何执行的。
在 Script Collection 窗格中，您可以查看 VisualApplets 安装中已有哪些脚本集合可用，以及每个集合中包含哪些命令。
要打开 Script Collection 窗格，请打开 Window 菜单，选择 Dock Windows，然后选择 Scripting Collection：
Script 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）
- 可选：命令范围（参见下文的 Adding a Command to a Script Collection）
- 可选：其他信息，例如版本号、描述等。
- 可选：代表该命令的 GUI 图标（参见下文的 Adding a Command to a Script Collection）。如果您未提供图标文件，GUI 中将使用默认图标。
描述正好一个脚本集合的所有列出信息都存储在一个 XML 文件中。
您可以定义多个脚本集合。
GUI 的底层机制是什么？#
在后台，系统会在您为集合定义 XML 文件指定的目录中创建一个新的 XML 文件（参见 Required Settings）：
文件名与您在 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 的命令，您可以定义 command scope。在命令范围中，您可以将命令限制为特定的设计元素（例如模块或链路），以便该命令仅适用于这些元素。
要求#
文件要求#
脚本集合由以下文件组成：
- 用于定义脚本集合的 XML 文件。该 XML 文件包含集合本身的定义以及集合中包含的命令的定义。
- 包含实际脚本的 Tcl 或 Python 文件。这些文件必须满足以下要求：
- 它们是 Tcl 或 Python 脚本。
- 这些文件仅包含过程。它们不包含加载脚本文件时执行的任何命令。
- 为避免命名冲突，对于命令 CMD_NAME，请遵循以下命名规范：
- Command_CMD_NAME
- 将 .tcl 或 .py 文件存储在与集合文件（*.xml）相同的目录或其子目录中。
- 可选：用于 VA GUI 上的单个合集或命令图标的 PNG 图标文件。PNG 文件需要满足以下要求：
- 它们必须包含正方形图像。
- 最小分辨率为 16 x 16。
- 将图标文件存储在与集合文件（*.xml）相同的目录或其子目录中。如果您未提供图标文件，则会在 GUI 中使用默认图标来表示该命令。
信息
工作脚本合集所需的所有文件均为纯文本文件。这使您可以将脚本合集定义存储在版本控制系统中。
必需的设置#
您可以在 VisualApplets 中指定脚本合集定义文件（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 创建的每个 Script Collection，都会在指定目录中写入一个 XML 文件。如果您向该目录中添加新的集合描述 XML 文件或编辑存储在那里的现有 XML 文件，您可以使更改在 VisualApplets GUI 中可见。若要在不重启 VisualApplets 的情况下显示更改，请在 Script Collection 窗格中右键单击，然后选择 Rescan Script Collection Directory。
通过 GUI 创建脚本集合#
您可以完全通过 GUI 定义脚本合集，而无需接触底层 XML 文件。XML 文件会在后台创建和更新。一旦您定义了合集及包含的命令，该合集就会显示在 VisualApplets GUI 中。
创建新的脚本集合#
若要通过图形用户界面创建新的脚本合集：
- 右键单击 Script Collection 窗格。
-
从上下文菜单中选择 Create New Script Collection。
将打开一个对话框。
-
输入新 Script Collection 的名称，并点击 OK 确认。
新集合将显示在 Script Collection 窗格中：
将命令添加到脚本集合#
若要通过 GUI 将命令添加到脚本合集中：
- 右键单击脚本合集的名称。
-
从上下文菜单中选择 Create Element。
将打开一个对话框，用于描述您要添加的命令。以红色突出显示的字段为必填项：
-
Command Name（必填）：为您的命令指定一个名称。
- Version：您可以为您的命令提供版本信息。
- Description：该描述将作为工具提示信息显示。请输入命令将调用的过程的描述。
- Icon File：如果您希望在 Script Collection 窗格或工具栏中显示特定的命令图标，可以在此处提供图标文件的路径。您可以设置绝对路径，或者设置相对于集合文件（*.xml）的相对路径。（详见 File Requirements）。如果不选择图标文件，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：您必须且只能选择一个 module 才能启动此命令。
- Link：您必须且只能选择一个 link 才能启动此命令。
- CommentBox：您必须且只能选择一个 comment box 才能启动此命令。
- SimModule：您必须且只能选择一个 simulation module 才能启动此命令。
- SingleSelect：您必须且只能选择一个设计元素才能启动此命令。选择哪种元素（module、link 等）并不重要。
- MultiSelect：您必须选择两个或更多设计元素才能启动此命令。选择哪些元素（module、link 等）并不重要。
您可以组合这些选项：例如，如果您组合了选项 Module 和 Link，则只要您选择且仅选择一个 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 collections 的文件夹路径。
-
右键点击 Script Collection 窗格并选择 Rescan Script Collection Directory。
此时，GUI 会在 Script Collection 窗格中显示示例 script collections：
-
您现在可以试用 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：您必须且只能选择一个 module 才能启动此命令。
- Link：您必须且只能选择一个 link 才能启动此命令。
- CommentBox：您必须且只能选择一个 comment box 才能启动此命令。
- SimModule：您必须且只能选择一个 simulation module 才能启动此命令。
- SingleSelect：您必须且只能选择一个设计元素才能启动此命令。选择哪种元素（module、link 等）并不重要。
- MultiSelect：您必须选择两个或更多设计元素才能启动此命令。选择哪些元素（module、link 等）并不重要。
您可以组合这些选项：例如，如果您组合了选项 Module 和 Link，则只要您选择且仅选择一个 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 创建的每个脚本系统，都会在您在设置 → 系统设置 → 路径下指定的目录中写入一个 XML 文件。如果您向该目录添加新的描述集合的 XML 文件或编辑存放在那里的现有 XML 文件，您可以使您的更改在 VisualApplets GUI 中可见。若要显示更改而无需重新启动 VisualApplets，请在脚本集合窗格中单击鼠标右键，然后选择重新扫描脚本集合目录。