建立腳本集合（腳本庫）#
首先，您需建立一個包含個別指令的腳本集合。您需為每個指令進行定義，使其呼叫指定 Tcl 或 Python 腳本中的特定程序。
之後，各項指令會直接以圖形化方式顯示於VisualApplets 的GUI中，您可以透過滑鼠點擊或拖放來執行它們。如此一來，您便能將 Tcl 或 Python 程序作為函式庫元件加以利用。當呼叫這些指令時，它們會在「腳本控制台」中執行。若您開啟「腳本控制台」，即可觀察指令的執行過程。
在「腳本集合」窗格中，您可以查看當前VisualApplets 安裝中已有的腳本集合，以及每個集合所包含的指令。
要開啟「腳本集合」窗格，請開啟「視窗」選單，選擇「停靠」Windows，然後選擇「腳本集合」：
「Scrip Collection」窗格會出現在「VisualApplets 」主視窗的右側：
您可以透過以下方式定義腳本集合：
資訊
VisualApplets 支援以 Python 和 Tcl 編寫的腳本集合。當使用 Python 腳本集合元素時，腳本主控台會自動切換至 Python；若主控台已設定為 Tcl，則會切換回 Tcl。Python 腳本集合會在「Python 版本設定」對話方塊中選為「目前版本」的 Python 環境中執行。詳細資訊請參閱「管理 Python 版本」。
資訊
將所有集合資訊儲存於 `XML ` 檔案中，不僅能讓您對個別腳本使用版本控制系統，還能對腳本集合的結構與內容定義進行版本控制。
劇本集的結構#
每個腳本集合都包含若干個指令（即腳本集合的元素）。
這點在圖形使用者介面（GUI）中有所體現：
每個指令都指向特定腳本中的某個特定程序。當執行某個指令時，該指令所指向的程序便會被呼叫。
要定義一個腳本集合，您必須定義：
- 該系列的名稱
- 該集合中所包含的指令
- （可選）：其他相關資訊，例如版本號、說明等。
- 可選：代表腳本集合的 GUI 圖示。
- 針對每條個別指令：
- 指令名稱
- 該指令所指向的 Tcl 或 Python 檔案
- 該指令所指向的此檔案中的 Tcl 或 Python 程序
- 必須傳遞給 Tcl 或 Python 程序的參數（從 GUI 執行命令時，系統會提示所需的值）
- 指令模式（請參閱下文「將指令新增至腳本集合」）
- （可選）：命令作用域（請參閱下文「將命令新增至腳本集合」）
- （可選）：其他資訊，例如版本號、說明等。
- 可選：代表該指令的 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 ` 檔案中定義的資訊。
指令選項#
在定義指令時，您可以指定該指令是否可透過按鈕啟動 
（即觸發模式）或透過拖放操作，GUI 中會以手形圖示標示此功能 
. 您也可以在工具列上為您的指令新增一個按鈕。
對於設定為觸發模式的指令，您可以定義該指令的適用範圍。在指令的適用範圍內，您可以將指令限制在特定的設計元件（例如模組或連結）上，使該指令僅適用於這些元件。
Requirements#
檔案要求#
一個腳本集合包含以下檔案：
- 一個定義腳本集合的 `XML ` 檔案。`XML ` 檔案包含該集合本身的定義，以及集合中所含指令的定義。
- 包含實際腳本的 Tcl 或 Python 檔案。這些檔案必須符合以下要求：
- 它們是 Tcl 或 Python 腳本。
- 這些檔案僅包含程序。其中並未包含任何在載入腳本檔案時會執行的指令。
- 為避免名稱衝突，對於某個指令 CMD_NAME, 請遵循以下命名規範：
- Command_CMD_NAME
- 請將.tcl或.py檔案儲存於彙整檔案 (*.xml) 所在的同一個目錄中，或其子目錄內。
- 可選：用於 VA 圖形使用者介面中個別集合或指令圖示的 PNG 圖示檔案。這些 PNG 檔案須符合以下要求：
- 這些圖片必須包含一張正方形圖片。
- 最低解析度為 16 x 16。
- 請將圖示檔案儲存於集合檔案 (*.xml) 所在的目錄中，或其子目錄內。若未提供圖示檔案，系統將使用預設圖示來呈現 GUI 中的指令圖示。
資訊
一個可運作的腳本集合所需的所有檔案皆為純文字檔案。這使您能夠將腳本集合的定義儲存於版本控制系統中。
必填設定#
您可以在 Visual Applets 中指定腳本集合定義檔案（XML 檔案）的位置。由於您只能為集合腳本檔案定義一個儲存位置，因此 Basler 建議將所有用於定義集合的XML 檔案儲存於同一個目錄中。
要設定腳本集合目錄的路徑：
- 從「設定」選單中，選擇「系統設定」。
- 選取「路徑」索引標籤。
- 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 ，請在「腳本集合」窗格中按右鍵，然後選取「重新掃描腳本集合目錄」。
透過圖形化使用者介面建立腳本集合#
您可以完全透過圖形化使用者介面 (GUI) 來定義腳本集合，無需直接修改底層的 `XML ` 檔案。系統會在後台自動建立並更新 `XML ` 檔案。只要您定義好集合及其所包含的指令，該集合便會顯示在 `VisualApplets ` GUI 中。
建立新的腳本集合#
若要透過圖形使用者介面建立新的腳本集合：
- 在「腳本集合」窗格上按右鍵。
-
從快顯選單中，選擇「建立新腳本集合」。
會開啟一個對話方塊。
-
為新的腳本集合輸入名稱，然後按「確定」確認。
新收藏集會顯示在「腳本收藏集」窗格中：
將命令新增至腳本集合#
若要透過圖形化使用者介面 (GUI) 將指令新增至腳本集合：
- 在腳本集合的名稱上按右鍵。
-
從快顯選單中，選擇「建立元素」。
此時會開啟一個對話方塊，供您描述要新增的指令。以紅色標示的欄位為必填欄位：
-
指令名稱（必填）：為您的指令命名。
- 版本：您可以提供指令的版本資訊。
- 說明：此說明將以工具提示資訊的形式顯示。請輸入該指令將呼叫之程序的說明。
- 圖示檔案：若要讓特定指令的圖示顯示在「腳本集合」窗格或工具列中，您可在此處指定圖示檔案的路徑。您可以設定絕對路徑，或相對於集合檔案 (*.xml) 的相對路徑。（詳情請參閱「檔案要求」）。若未選取圖示檔案，GUI 中將使用預設圖示來代表您的新指令。
-
腳本檔案：請提供包含您希望透過該指令啟動之程序的腳本路徑及名稱。您可以定義相對於集合檔案（.xml）的相對路徑。此外，您也可以不定義包含該指令要呼叫之程序的腳本檔案，而是直接在指令中輸入 Tcl 或 Python 程序。 直接在命令中定義的 Tcl 或 Python 程序，將在每次呼叫該命令時執行。若您偏好此選項，請將「腳本檔案」欄位留空，並在「範本」欄位的「命令呼叫」中提供該命令所代表的完整 Tcl 或 Python 程序。
若您未選取定義為命令範圍的設計元素，便嘗試執行命令，系統將顯示「範圍無效」訊息：
-
指令選項：定義您希望在「VisualApplets 」圖形使用者介面（GUI）上如何啟動該指令。指令可透過點擊按鈕（觸發模式）或拖放至設計視窗（拖放模式）來啟動。若使用觸發模式，您可在程式視窗的工具列中為該指令新增一個按鈕，並定義在何種條件下執行該指令（範圍）。
-
觸發模式：若要建立一個一點擊即會執行該指令的按鈕，請清空「拖放」欄位。該指令將會顯示在「腳本集合」窗格中，並附有「執行」按鈕：
要開始執行該指令，請按一下「執行」按鈕。
-
工具列選項（僅限觸發模式）：若要讓該指令出現在「VisualApplets 」的工具列中：請勾選「新增至工具列」選項；此操作僅在您取消勾選「拖放」核取方塊時才可執行。在圖形使用者介面上，系統會為該集合建立一個新的工具列，並顯示該指令的圖示：
點擊工具列中的指令圖示，效果與點擊「執行」按鈕相同。此時，您在「說明」欄位中輸入的文字會以工具提示的形式顯示在工具列上：
-
拖放模式：若要透過在 GUI 上執行拖放操作來啟動執行，請勾選「拖放」核取方塊。此時，「動作」欄位中會顯示一個手形圖示：
-
-
定義指令範圍（僅在觸發模式下可用）：若要將指令的範圍限制在設計中的特定設計元件上，請選取「定義指令範圍」核取方塊。此選項僅在「拖放」功能已停用時才會顯示。
可用的選項如下：
- 模組：您必須精確選取一個模組，才能執行此指令。
- 連結：您必須精確選取一個連結才能執行此命令。
- 留言框：您必須精確選取一個留言框，才能執行此指令。
- SimModule：您必須精確選取一個模擬模組，才能執行此指令。
- SingleSelect：您必須精確選取一個設計元素才能執行此指令。選取何種元素（模組、連結等）並不重要。
- 多重選取：您必須選取兩個或更多設計元素才能執行此指令。選取何種類型的元素（模組、連結等）並不重要。
您可以將這些選項組合使用：例如，若將「模組」與「連結」這兩項選項組合，只要選取「恰好一個模組」或「恰好一個連結」，該指令就會執行。若將「單一選取」與「多重選取」組合，只要選取一個或多個設計元素，即可執行該指令。
指令的作用域（即 Tcl 程序的作用域）會顯示在 VA GUI 的「腳本集合」窗格中：
若您未選取定義為命令範圍的設計元素，便嘗試執行命令，系統將顯示「範圍無效」訊息：
-
指令呼叫：請在此處定義指令的呼叫方式。
- 範本：請在此處輸入命令呼叫的範本。通常，範本以 Tcl 或 Python 程序的名稱開頭，後接參數清單。參數以 % 包圍，作為佔位符。請針對每個佔位符，在下方清單中定義對應的參數。請遵循 Tcl 或 Python 命令的語法。此外，若您將上方的「腳本檔案」欄位留空，亦可在此處直接輸入完整的 Tcl 或 Python 控制台命令列。
- Parameters: 請在此處定義範本中使用的參數。此處列出的參數順序無關緊要。只需確保參數名稱與範本中的佔位符名稱相符即可。若要向指令定義中新增參數，請按一下
「+」按鈕。- 名稱：請為每個參數指定名稱。請使用您在呼叫指令時，用於傳遞該值的參數名稱。
- 類型：定義參數的資料類型。您可以定義字串、整數或雙精度數值的參數。
- 模式：請指定您的參數是包含固定值、變數，還是下放位置。
dropX進行明確的生命週期管理即呼叫dropY提供滑鼠指標在拖放過程中被釋放的位置。請注意，dropX進行明確的生命週期管理即呼叫dropY僅在「拖放」模式下可用。若將該參數定義為變數，系統會在執行命令時提示您輸入該參數的數值。 - 預設值：請在此處輸入預設值。
- 最小值/最大值：請在此處輸入該參數的數值範圍。
- Inc：請在此處輸入值範圍內的步長。
範例：
透過...建立腳本集合XML#
您可以在XML 中完全定義腳本集合，無需使用VisualApplets 的圖形化使用者介面。
針對每個腳本集合，請建立一個名為「XML 」的檔案。
只要您在 `XML ` 檔案中定義了集合及其所包含的指令，該集合便會顯示於 `VisualApplets ` 圖形化使用者介面中。先決條件：您必須已在 `VisualApplets` 的「系統設定」中指定 `XML ` 檔案的位置，詳見「必要設定」。
有關腳本集合結構與內容的所有資訊，均定義於每個腳本集合對應的單一XML 檔案中。您可以提供多個XML 檔案，每個檔案皆定義一個腳本集合。若定義腳本集合的XML 檔案位於您於「設定」→「系統設定」→「路徑」→「腳本集合」中的「VisualApplets 」選項所指定的目錄內，該腳本集合便會顯示於VisualApplets 圖形化使用者介面（GUI）的「腳本集合」窗格中。
範例#
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）中顯示範例腳本集合：
-
請在「設定」→「系統設定」→「路徑」中，指定儲存範例腳本集合的資料夾路徑。
-
在「腳本集合」窗格中按右鍵，然後選取「重新掃描腳本集合目錄」。
GUI 現已在「腳本集合」窗格中顯示範例腳本集合：
-
現在您可以試著調整 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.
可用的選項如下：
- 模組：您必須精確選取一個模組，才能執行此指令。
- 連結：您必須精確選取一個連結才能執行此命令。
- 留言框：您必須精確選取一個留言框，才能執行此指令。
- SimModule：您必須精確選取一個模擬模組，才能執行此指令。
- SingleSelect：您必須精確選取一個設計元素才能執行此指令。選取何種元素（模組、連結等）並不重要。
- 多重選取：您必須選取兩個或更多設計元素才能執行此指令。選取何種類型的元素（模組、連結等）並不重要。
您可以將這些選項組合使用：例如，若將「模組」與「連結」這兩項選項組合，只要選取「恰好一個模組」或「恰好一個連結」，該指令就會執行。若將「單一選取」與「多重選取」組合，只要選取一個或多個設計元素，即可執行該指令。
若您未選取定義為命令範圍的設計元素，便嘗試執行命令，系統將顯示「範圍無效」訊息：
<Toolbar>:
可選標籤，僅在您設定時才允許使用 Command mode 至 Trigger. 若您加入該標籤，該指令便會新增至該集合的工具列中。當 Command mode 已設定為 DragAndDrop.
Parameters#
您必須將以下數值填入上圖中以斜體標示的參數欄位中：
- 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：在呼叫命令時會被實際值取代的參數名稱（引數）。僅指定以下所定義的參數名稱
標籤。 - 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 ，請在「腳本集合」窗格中按右鍵，然後選取「重新掃描腳本集合目錄」。