Data Type: Script Module ()

Description:

is scriptable via its built-in Tcl interface (see The Script Module module allows the user or a custom solution provider to create scripts that fit seamlessly into the user interface, and define their own user interface components.

A script object is an object showing up in the Project View similar to an Ortho Slice or a Local Axes module. It can have ports, like sliders or buttons. The ports are defined by Tcl code and the reaction to a change of the ports is also implemented in Tcl. The Tcl code consists of a portion for initialization and a Tcl procedure that is called whenever the script has to react to changes of input parameters, the compute procedure.

Any script can be turned into a script object by putting a special header line into the script. Write an script (using your favorite text editor) and put a special header for script objects in the first line:

  # -Script-Object 

  $this script show
  echo "Hello world, a script is called."

Load this file into . A blue icon appears. Each time you click on the Restart button, the script will be read and executed and the above message appears in the console window.

During the execution of a script object, the global variable $this always contains the name of the currently active script object. This allows the user to easily access object-specific commands, the so-called methods. Declaring a method is very similar to declaring an ordinary Tcl procedure:

  $this proc name args body

Just like the Tcl command proc, you can declare a method by using $this proc. Methods can be executed by calling $this name args. The syntax is completely analogous to global Tcl procedures (see The special point about a method is that inside the method the $this variable is set appropriately. Example:

  # -Script-Object 

  $this proc sayHello {} {
     echo "module $this is greeting you"
  }

If you load this script object, nothing will happen visibly. However, if your script object is called MyScript.scro, you can type

  MyScript.scro sayHello

in the console window, and you will get a personalized greeting line as the result.

There are several methods with a special meaning:

• $this proc constructor {} {...} defines a method that is called when the script object is created. This is used for creating user interface elements and initializing the object.
• $this proc destructor {} {...} defines a method that is executed when the object is deleted or restarted. Used for cleaning up or terminating communications.
• $this proc compute {} {...} defines a method that is called whenever a user interface component of the script object is changed by the user. See examples below.
• $this proc savePreparation {<datadir> <savingFlags>} {...} defines a method that is called before a session is stored in a project file. So some clean up can be done here.

Here is an example that uses the constructor and compute methods in order to define a simple user interface and to query the current state of that user interface:

  # -Script-Object 

  $this proc constructor {} {
    $this newPortIntSlider myValue
    $this myValue setLabel "Value:"
  }

  $this proc compute {} {
    set val [$this myValue getValue]
    echo "The value is $val"
  }

In the example, the constructor creates a new port, an integer slider which will appear in the user interface. The port has the internal name myValue and its visible label is set to Value. Whenever the user modifies the value of the slider, the compute method is called, and outputs the current port value.

In addition to defining methods, a script object also allows the user to define member variables. Analogous to Tcl variables, a member variable is a placeholder for a certain value, but a member is local to each script object. If you have two script objects A and B, both can have a member variable x, and the values of these two variables is kept separately. In order to define and query member variables, use the commands $this setVar and $this getVar (see below).

You can save projects containing script objects. When loading the saved project into , the following things will happen:

• the script object is created
• the saved value of all member variables is restored
• the constructor method is called
• the compute method is called
• the value of all ports is restored
• the compute method is called again

Connections:

Data [optional]
Can be connected to any data object. Can be used by the script.

Ports:

Script

This port is available for any script object. The Restart button deletes all dynamically created ports, sets the isFirstCall flag to 1 and calls the script. The text field indicates the location of the script file.

Commands:

newPort3DPointList <name> <number-of-points>
Creates a new 3D point list port.

newPortButtonList <name> <number-of-buttons>
Creates a new button list port.

newPortButtonMenu <name> <number-of-buttons> <number-of-options>
Creates a new button menu port.

newPortColormap <name>
Creates a new colormap port.

newPortColorList <name> <number-of-colors>
Creates a new color list port.

newPortDirectory <name>
Creates a new directory port.

newPortDoIt <name>
Creates a new DoIt port.

newPortFilename <name>
Creates a new filename port.

newPortFloatSlider <name>
Creates a new float slider port.

newPortFloatTextN <name> <number-of-fields>
Creates a new float text port.

newPortFontSelection <name>
Creates a new font selection port.

newPortGeneric <name>
Creates a new generic port.

newPortInfo <name>
Creates a new info port.

newPortIntSlider <name>
Creates a new integer slider port.

newPortIntTextN <name> <number-of-fields>
Creates a new integer text port.

newPortMultiMenu <name> <num-options-1> [<num-options-2> [<num-options-3>]
Creates a new multi menu port.

newPortMultiOptions <name> <num-options-1> [<display-type>] [<is-tri-state>]
Creates a new multi options port. display-type is 0 for List View and 1 for Combo Box. is-tri-state is 0 if no tri-state mode and 1 if tri state mode supported for options.

newPortRadioBox <name> <number-of-toggles>
Creates a new radio box port.

newPortRangeSlider <name>
Creates a new range slider port.

newPortSeparator <name>
Creates a new separator port.

newPortTabBar <name> <number-of-tabs>
Creates a new tab bar port.

newPortText <name>
Creates a new text port.

newPortTextEdit <name>
Creates a new multi-line text edit port.

newPortTime <name>
Creates a new time port.

newPortToggleList <name> <number-of-toggles>
Creates a new toggle list port.

newPortConnection <name> <type-name>
Creates a new connection port. The type name specifies what type of objects can be connected to the port. The type name of an existing object can be obtained using the Tcl command getTypeId.

deletePort <name-of-port>
Deletes a port which has been created using one of the newPort commands.

proc name args body
Define a Tcl member procedure (see above). The syntax is analogous to the global Tcl proc command. This command is not specific to the Script Module, but it is available in all objects.

setVar <variable> <value>
Variables stored in this way keep their values between successive calls of the compute procedure. Ordinary Tcl variables get lost. This command is not specific to the Script Module, but it is available in all objects.

setVarSerialize <variable> 0|1
Variables created with setVar are usually serialized when storing a session in a project file. This behavior can be disabled for variables whose values are only meaningful within one session.

getVar <variable>
Returns the value of a variable set using setVar. This command is not specific to the Script Module, but it is available in all objects.

testBreak
This commands checks if the stop button has been pressed. If so the execution of the script is automatically terminated. Use this command inside long animation loops or similar constructs.

In addition to the script object extensions, each script object inherits a number of methods from the general object type.