Creating Script Collections (Script Libraries)

To allow you to use the procedures in your Tcl scripts most conveniently directly from the VisualApplets GUI, VisualApplets offers the Script Collection feature.

In a first step, you create script collections (libraries) that contain individual commands. Each command you define to call a specific procedure in a specified Tcl script.

Afterwards, the individual commands are graphically available directly on the VisualApplets GUI and can be started via mouse click or Drag & Drop. This way, you can make use of your Tcl procedures as library elements. When called, the commands are executed in the TCL console. If you open the TCL Console, you can see how the command is carried out.

In the pane Script Collection, you see which script collections are already available in your VisualApplets installation and which commands are contained in each collection:

You can define a script collection either

• in a graphical way, using the VisualApplets GUI, or
• creating/editing an XML file that defines the script collection.

Info

Storing all collection information in XML files allows you to use version control systems not only for the individual Tcl scripts, but also for the structure and content definitions of your script collections.

Structure of a Script Collection

Each script collection contains a number of commands (elements of the script collection).

This is reflected in the display on the GUI:

Each command points to one specific Tcl procedure within a specific Tcl script. When a command is carried out, the TCL procedure it points to is called.

To define a script collection, you have to define:

• The name of the collection
• The commands contained in the collection
• Optionally: Some further information like version number, description, etc.
• Optionally: A GUI icon representing the script collection.
• For each individual command:
  • Command name
  • Tcl file it points to
  • Tcl procedure within this file it points to
  • Arguments that need to be passed to the Tcl procedure (the values required will be prompted at starting a command from the GUI)
  • Command mode (see Command Options below)
  • Optionally: Command scope (see Command Options below)
  • Optionally: Some further information like version number, description, etc.
  • Optionally: A GUI icon representing the command (see Command Options below). If you don't provide an icon file, a default icon will be used for representation in the GUI. All listed information (describing exactly one script collection) is stored in one XML file.

You can define multiple script collections.

Command Options

Command Start

When defining a command, you need to define which way the command can be started on the GUI. You have two options:

• Trigger mode: The command is started via click on a GUI button. The GUI button is available in the Script Collection pane of the VisualApplets GUI. It looks like this:
• Drag & Drop mode: The command is carried out only after a Drag & Drop from the Script Collection pane into the design window of VisualApplets. The Drag & Drop mode is represented in the Script Collection pane by a hand symbol:

Command Scope

For commands set to trigger mode, you can define the command scope. The command scope defines if design elements need to be selected for being modified by the Tcl procedure, and if yes, which elements this are. (You may, for example, have defined a Tcl procedure that alters the parameters of one or multiple links in a design, or a procedure that is to be carried out exactly on one module, etc.)

The following options are available:

• Module: Exactly one design element must be selected. This element must be a module.
• Link: Exactly one design element must be selected. This element must be a link.
• CommentBox: Exactly one design element must be selected. This element must be a comment box.
• SimModule: Exactly one design element must be selected. This element must be a simulation module.
• SingleSelect: Exactly one design element must be selected. Which kind of element is selected (module, link, …) is not relevant.
• MultiSelect: Two ore more design elements must be selected. Which kinds of elements are selected (module, link, …) is not relevant.

These options can be combined: If you, for example, combine the options Module and Link, the command will be carried out if the user on the GUI selects either exactly one module OR exactly one link. Combining SingleSelect and MultiSelect allows starting the command if one ore more design elements are selected.

If a GUI user tries to carry out a command without selecting the design elements defined as command scope, an according message is displayed, for example:

Toolbar Buttons for Commands

For commands set to trigger mode, you can arrange that a command button is added to the tool bar of the VisualApplets program window. A click on the command button in the tool bar will have the same effect as a click on the command button in the Script Collection pane.

Requirements

File Requirements

A script collection is made up of the following files:

• XML file that defines a script collection. The XML file contains the definition of the collection itself and the definitions of the commands contained in the collection.
• Tcl files that contain the actual scripts. These files need to meet the following requirements:
  • They are Tcl scrips.
  • The files contain only procedures. They do not contain any commands that are carried out at loading the script file.
  • To avoid naming conflicts, for a command CMD_NAME you you should stick to the following naming conventions:
    • Command_CMD_NAME
  • Store the Tcl files in the same directory as the collection file (*.xml) or in a subdirectory of it.
• Nonmandatory: PNG icon files for individual collection or command icons on the VA GUI. The PNG files need to meet the following requirements:
  • They need to contain a square image.
  • The minimum resolution is 16 x 16.
  • Store the icon files in the same directory as the collection file (*.xml) or in a subdirectory of it. If you don't provide an icon file, a default icon will be used for representation in the GUI.

Info

All files required for a working script collection are plain text files. This allows you to store your script collection definitions in version control systems.

Required Settings

You need to specify the location of the script collection definition files (XML files) in Visual Applets. All collection-defining XML files need to be stored in the same directory.

To set the path to your script collection directory:

1. From menu Settings, select System Settings.
2. Select tab Paths.
3. 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.

Info

For each script collection you define via GUI, an according XML file is written into the specified directory. If you add new collection-describing XML files to the directory or edit existing XML files stored there, your changes will be visible on the VisualApplets GUI. To display your changes without re-starting VisualApplets, right-click into the Script Collection pane, and select Rescan Script Collection Directory.

Creating Script Collection via GUI

You can define script collections completely via GUI, without touching the underlying XML files. The XML files are created and updated in the background. As soon as you have defined a collection and the contained commands, the collection is displayed on the VisualApplets GUI.

Creating a New Collection

To create a new script collection via graphical user interface:

1. Right-click in the Script Collection pane.

2. From the context menu, select Create New Script Collection.

   

   A dialog opens.

3. Enter a name for the new collection and confirm with OK.

   

   The new collection is displayed in the Script Collection pane:

   

What Happens Beneath the GUI?

In the background, a new XML file is created in the directory you specified for your collection-defining XML files (see Required Settings):

The file name is the same as the collection name you have given the collection in the GUI. The file contains all information on the collection that is currently defined:

As you have not specified any commands to be part of the collection, the "elements" section is still empty.

Info

For creating new collections, you can either use the GUI or create XML files from scratch. The results are absolutely the same. The GUI always displays the information defined in the XML files.

Adding a Command to a Collection

To add commands to a collection via graphical user interface:

1. Right-click on the name of the script collection.

2. From the context menu, select Create Element.

   

   A dialog opens for describing the command you want to add. The fields highlighted in red are mandatory:

   

3. Command Name (mandatory): Give a name to your command.

4. Version: Version information for command.
5. Description: The description will be visible as tooltip information. Enter a description of the procedure the command will call.
6. Icon File: Provide the path to an icon file if you want a specific command icon to be displayed in the Script Collection pane or in the toolbar. Define the path relative to the collection file (*.xml). (See File Requirements for details). If you don't provide an icon file, a default icon will be used for representation in the GUI.

7. Script File: Provide the path to and the name of the script that contains the procedure you want to be started via the command. Define the path relative to the collection file (*.xml). Alternatively, instead of defining a script file that contains the procedure the command is to call, you can enter a Tcl procedure directly into the command. The Tcl procedure defined directly in the command will be executed each time you call the command. If you prefer this option, leave field Script File empty and provide the whole Tcl procedure the command stands for under Command Call in field Template.

   

8. Command Options: Define how you want the command to be started on the VisualApplets GUI. A command can be started either via click on an according button (trigger mode), or by drag & drop into the design window (Drag & Drop mode). If you use trigger mode, you can add an additional button for the command in the tool bar of the program window and define under which conditions the command is carried out (scope).

   

   1. Trigger mode: To create a button that starts the command as soon as you click it, clear the Drag & Drop field. The command will be displayed in the Script Collection pane with the Run button:

      

      On the GUI, a simple click on the Run button starts executing the command.

   2. Drag & Drop mode: Select the Drag & Drop checkbox if you want to start execution via drag & drop operation on the GUI. In this case, a hand icon is displayed in column Action:

      

   3. Toolbar option (only trigger mode): To make the command available in the toolbar of VisualApplets: Check the Add to Toolbar option; this is only possible if you clear the Drag & Drop checkbox. On the GUI, a new tool bar is created for the collection and the command icon is displayed:

      

      Clicking at the command icon in the tool bar has the same effect as clicking the Run button. The text you entered under Description is visible as tooltip information on the GUI:

      

9. Define Command Scope (only trigger mode): If you need to define for which elements in the design the command (i.e., the underlying Tcl procedure) is to be carried out, check the Define Command Scope box. This element is only available if Drag & Drop is disabled.

   

   The elements you define here need to be selected in the design before starting the command from the GUI. If they are not selected at starting the command, the user will get an according prompt.

   Multiple selection is allowed.

   You have the following options:

   • Module: Exactly one design element must be selected. This element must be a module.
   • Link: Exactly one design element must be selected. This element must be a link.
   • CommentBox: Exactly one design element must be selected. This element must be a comment box.
   • SimModule: Exactly one design element must be selected. This element must be a simulation module.
   • SingleSelect: Exactly one design element must be selected. Which kind of element is selected (module, link, …) is not relevant.
   • MultiSelect: Two ore more design elements must be selected. Which kinds of elements are selected (module, link, …) is not relevant.

   These options can be combined: If you, for example, combine the options Module and Link, the command will be carried out if the user on the GUI selects either exactly one module OR exactly one link. Combining SingleSelect and MultiSelect allows starting the command if one ore more design elements are selected.

   The scope of a command (i.e., the scope of the Tcl procedure) is displayed in the Script Collection pane on the VA GUI:

   

10. Command Call: Define here how the command is called.

    

    1. Template: Enter here the template for the command call. Typically, it starts with the name of the Tcl procedure, followed by a list of parameters. The parameters are given as place holders, wrapped in %. For each place holder you define the according parameter in the list below. Follow the syntax of Tcl commands. Alternatively, you can enter here a complete Tcl console command line if you left field Script File above empty.
    2. Parameters: Define here the parameters used in the template. The order of the parameters listed here is of no consequence. Just ensure that the parameter names match the place holder names of the template. To add a new parameter to the command definition, click the plus button.
       1. Name: Provide a name for each parameter. Use the name you used for the argument that carries the value at command call.
       2. Type: Define the data type of the parameter. You can define parameters of type string, integer, or double.
       3. Mode: Define if your parameter contains a fix value or a variable, or a drop position. dropX and dropY provide the position where the mouse pointer was released during drop. Note that dropX and dropY are only available in Drag & Drop mode. If you define the parameter as variable, you will be asked at starting the command to enter a value for the parameter.
       4. Default: Enter here a default value.
       5. Min/Max: Enter here the value range for the parameter.
       6. Inc: Enter here the step size within the value range.

Example:

Creating Script Collection via XML

You can define script collections completely in XML, without using the VisualApplets GUI.

For each script collection, you need to create one XML file.

As soon as you have defined a collection and the contained commands in the XML file, the collection is displayed on the VisualApplets GUI. (Prerequisite: You have specified the location of the XML files in the System Settings of VisualApplets, see Required Settings).

XML Syntax

All information regarding structure and content of a script collection is defined in one XML file. You can provide multiple XML files, each defining one script collection. If an XML file defining a script collection is located in the directory you specify in VisualApplets under menu Settings -> System Settings -> Paths -> Script Collection, the script collection is displayed in the VisualApplets GUI in the Script Collection pane.

Example

Three Script Collections TclExamples, LayoutAssist, and DesignTools are defined in their respective XML files.

XML files in the directory:

Directory for storing script collections as specified under Settings -> System Settings -> Paths:

Script collections as displayed in the GUI of VisualApplets:

Info

Make sure you use the same name for the XML file as you specify as collection name in the XML file in tag <ScriptCollection>.

Example:

   File name:
   myCollection.xml

   Collection name within XML file:
   <ScriptCollection name ="myCollection" formatVersion="1.0">.

Syntax

The syntax of the XML file is the following:

The format is defined the in accordance to the following convention:

• Optional, individual elements are enclosed in square brackets [ ].
• Syntax elements that are allowed to be non-existent, to be there once or to be there multiple times, are enclosed in curly brackets { }.
• Syntax (..|..) indicates that one of the provided elements can be stated.
• Parameter values are stated in italic capital letters.

Annotations to Tags <Scope> and <Toolbar>

<Scope/>:

Optional tag, allowed only when you set Command mode to Trigger. You can define multiple times to specify multiple scopes. The tag is not allowed when Command mode is set to DragAndDrop.

Use the tag if you want to define for which design elements the command (i.e., the underlying Tcl procedure) is to be carried out.

The elements you define here need to be selected in the design before starting the command from the GUI. If they are not selected at starting the command, the user will get an according prompt.

Multiple selection is allowed.

You have the following options:

• Module: Exactly one design element must be selected. This element must be a module.
• Link: Exactly one design element must be selected. This element must be a link.
• CommentBox: Exactly one design element must be selected. This element must be a comment box.
• SimModule: Exactly one design element must be selected. This element must be a simulation module.
• SingleSelect: Exactly one design element must be selected. Which kind of element is selected (module, link, …) is not relevant.
• MultiSelect: Two ore more design elements must be selected. Which kinds of elements are selected (module, link, …) is not relevant.

These options can be combined: If you, for example, combine the options Module and Link, the command will be carried out if the user on the GUI selects either exactly one module OR exactly one link. Combining SingleSelect and MultiSelect allows starting the command if one ore more design elements are selected.

<Toolbar\>:

Optional tag, allowed only when you set Command mode to Trigger. If you include the tag, the commando is added to the toolbar of the collection. The tag is not allowed when Command mode is set to DragAndDrop.

Parameters

The parameters given above (in italic capital letters) you need to fill with the following content:

• COL_NAME: Name of collection
• COL_PNG_FILE_PATH: Path to icon file for collection (PNG format, for details see File Requirements). You need to specify the path relative to the XML file.
• COL_TOOLTIP_TEXT: Text displayed as tooltip information on the collection.
• CMD_NAME: Name of command.
• CMD_TOOLTIP_TEXT: Text displayed as tooltip information on the command.
• CMD_VERSION: Command version in format MAJOR.MINOR (for example, 1.0)
• TCL_FILE_PATH: Path to the Tcl script that contains the procedure you want to be called by the command. Specify the path relative to the XML file.
• CMD_PNG_FILE_PATH: Icon file for the command (PNG format, for details see File Requirements). Specify the path relative to the XML file.
• CMD_CALL: Name of procedure within the Tcl script (or whole Tcl procedure) that is to be called by the command
• CMD_PARAM: Parameter names (arguments) to be substituted by actual values at command call. Only specify parameter names that are defined in the following tags.
• PAR_NAME: Parameter name
• PAR_RANGE_FROM: Start of value range (only for data types int or double)
• PAR_RANGE_TO: End of value range (only for data types int or double)
• PAR_RANGE_INC: Step size within the value range (only for data types int or double)
• PAR_VALUE: Default value for parameter

Info

To display your changes without restarting VisualApplets, right-click into the Script Collection pane and select Rescan Script Collection Directory.

Example

XML Examples

You have a set of XML file examples (together with the referenced Tcl and PNG files) available in your VisualApplets installation.

You find them in the following directory:

<YourVisualAppletsInstallationDirectory\>/Examples/AdvancedVAFunctions/Script Collection

If you want to make the examples there visible in the GUI of your VisualApplets installation:

1. Adapt the location of/the path settings to the examples files:

   • Copy the files you find in the examples directory <YourVisualAppletsInstallationDirectory\>/Examples/AdvancedVAFunctions/Script Collection into the default directory for script collections: <YourVisualAppletsInstallationDirectory\>/ScriptCollection, or
   • In Visual Applets, select from menu Settings -> System Settings the tab Paths and under Script Collection, set the path to <YourVisualAppletsInstallationDirectory\>/Examples/AdvancedVAFunctions/Script Collection:

   

2. In VisualApplets, right-click in the Script Collection pane, and from the context menu, select Rescan Script Collection Directory.

   

   The GUI now displays the example script collections:

   

3. Play around with the GUI options and the content of the XML files to see the impact of your actions.