Writing Tcl/Tk scripts for the TclScript primitive

Several of the domains in MLDesigner have a primitive called TclScript. This primitive provides the quickest and easiest path to a customized user interface.

The TclScript primitive has an unspecified number of inputs and outputs as indicated by the double arrows at its input and output ports. The TclScript primitive has two settable parameters.

`tcl_file`	Defines a string that contains the full path name of a file containing a Tcl script. The Tcl script file specifies initialization commands, for example to open new windows on the screen, and may optionally define a procedure to be invoked by the primitive every time it runs.
`put_in_control_panel`	If set to `YES` the control panel window is created. You can refer to it with the global tcl variable `$ptkControlPanel`.

We begin with two examples that illustrate most of the key techniques needed to use this primitive.

Example 1

This example demonstrates the use of the TclScript primitive for creating customized GUI elements using Tcl files.

Example 2

This example demonstrates how to invoke a procedure every time a primitive fires.

Tcl procedures provided by the TclScript primitive

Below is a summary of the Tcl procedures used when executing a TclScript primitive:

`grapInputs_$starID`	A procedure that returns the current values of the inputs of the primitive corresponding to the given `starID`. This procedure is defined by the TclScript primitive if and only if the instance of the primitive has at least one input port.
`setOutputs_$starID`	A procedure that takes one argument for each output of the TclScript primitive. The value becomes the new output value for the primitive. This procedure is defined by the TclScript primitive if and only if the instance of the primitive has at least one output port.
`goTcl_$starID`	If this procedure is defined in the Tcl script associated with an instance of the TclScript primitive, then it will be invoked every time the primitive fires.
`wrapupTcl_$starID`	If this procedure is defined in the Tcl script associated with an instance of the TclScript primitive, then it will be invoked every time the wrapup method of the primitive is invoked. In other words, it will be invoked when a simulation stops.
`destructorTcl_$starID`	If this procedure is defined in the Tcl script associated with an instance of the TclScript primitive, then it will be invoked when the destructor for the primitive is invoked. This can be used to destroy windows or to unset variables that are no longer needed.

In addition to the starID global variable, the TclScript primitive makes other information available to the Tcl script. The mechanism used is to define an array with a name equal to the value of the starID variable. Tcl arrays are indexed by strings. Thus, not only is starID a global variable, but so is $starID. The value of the former is a unique string, while the value of the latter is an array. One of the entries in this array gives the number of inputs that are connected to the primitive. The value of the expression [set $starID(numInputs)] is an integer giving the number of inputs. The Tcl command set, when given only one argument, returns the value of the variable whose name is given by that argument. The array entries are summarized below.

`$starID`	This evaluates to a string that is different for every instance of the TclScript primitive. The `starID` global variable is set by the TclScript primitive.
`[set $starID(numInputs)]`	This evaluates to the number of inputs that are connected to the primitive.
`[set $starID(numOutputs)]`	This evaluates to the number of outputs that are connected to the primitive.
`[set $starID(tcl_file)]`	This evaluates to the name of the file containing the Tcl script associated with the primitive.
`[set $starID(fullName)]`	This evaluates to the full name of the primitive (which is of the form `system.module.module.primitive`).