Chapter 5. Using Tcl/Tk
Contents
1. 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 star The starID global variable is set by the TclScript star set S starID numInputs This evaluates to the number of inputs that are connected to the star set S starID numOutputs This evaluates to the number of outputs that are connected to the star set starID tcl_file This evaluates to the name of the file containing the Tcl script associated with the star set starID fullName This evaluates to the full name of the star which is of the form universe galaxy galaxy star 5 3 Tcl utilities that are available to the programmer A number of Tcl global variables and procedures that will be useful to the Tcl programmer have been incorporated into Ptolemy Any of these can be used in any Tcl script associated with an instance of the TclScript star For example in example 1 on page 5 2 the global variable ptkControlPanel specifies the control panel that is used to run the system Below is a list of the useful global variables that have been set by the graphical interface pigi when the Tcl script is sourced or when the goTcl_ starID procedure is invoked S ptkControlPanel A string giving the name of the control panel window associ ated with a given2. run This variable is set by pigi U C Berkeley Department of EECS The Almagest 5 7 SptkControlPanel high The uppermost panel in the control panel that is intended for user defined entries SptkControlPanel middle The middle panel in the control panel that is intended for user defined entries SptkControlPanel low The lowest panel in the control panel that is intended for user defined entries In addition to these global variables a number of procedures have been supplied Using these procedures can ensure a consistent look and feel across a variety of Ptolemy applications The complete set of procedures can be found in PTOLEMY 1ib tcl We list a few of the more useful ones here Note also that the entire set of commands defined in the Tcl based textual interpreter for Ptolemy ptc1 are also available So for example the command curuniverse will return the name of the current universe See the ptcl chapter in the User s Manual ptkExpandEnvVar Procedure to expand a string that begins with an environment variable reference For example ptkExpandEnvVar SPTOLEMY src will return something like usr users ptolemy src Arguments path the string to expand ptkImportantMessage Procedure to pop up a message window and grab the focus The process is suspended until the message is dismissed Arguments win window name to use for the message text text to display in the pop up win dow ptkMake
3. star Example 1 Consider the following simple schematic in the SDF domain Tel n TclScript ShowValues The TkShowValues Star is in the standard SDF star library It displays whatever input values are supplied in a subpanel of the control panel for the system Suppose we spec ify the following Tcl script for the Tcl Script star set s SptkControlPanel middle button_S starID if winfo exists Ss button Ss text PUSH ME pack append SptkControlPanel middle s top bind s lt ButtonPress 1 gt setOutputs_SstarID 1 0 bind s lt ButtonRelease 1 gt setOutputs_SstarID 0 0 setOutputs_SstarID 0 0 unset s This script creates a pushbutton in the control panel When the button is depressed the star outputs the value 1 0 When the button is released the star outputs value 0 0 The resulting control panel is shown below A Bun tel script deme Control panel for tel_script_demo when to stop r Denug GO lt Return PAUSE Space STOF Escapes FUSH ME inpats to the ThShow Wales star 0 0 OPSHrss While the system is running depressing the button labeled PUSH ME will cause the value displayed at the bottom to change from 0 0 to 1 0 Releasing the button will change the value back to 0 0 The lines in the Tcl script are explained below U C Berkeley Department of EECS The Almagest 5 3 set s SptkControlPanel middle button_S starID Thi
4. Button Procedure to make a pushbutton in a window A callback proce dure must be defined by the programmer It will be called whenever the user pushes the button and takes no arguments Arguments win name of window to contain the button name name to use for the button itself desc description to be put into the display callback name of callback procedure to register changes ptkMakeEntry Procedure to make a text entry box in a window A callback procedure must be defined by the programmer It will be called whenever the user changes the value in the entry box and types Ptolemy Last updated 10 17 97 5 8 ptkMakeMeter ptkSetMeter ptkMakeScale U C Berkeley Using Tcl Tk lt Return gt Its single argument will be the new value of the entry Arguments win name of window to contain the entry box name name to use for the entry box itself desc description to be put into the display default the initial value of the entry callback name of callback procedure to reg ister changes Procedure to make a bar type meter in a window Arguments win name of window to contain the entry box name name to use for the entry box itself desc description to be put into the display low the value of the low end of the scale high the value of the high end of the scale Procedure to set the value of a bar type meter created with ptkMakeMeter Arguments win name of window to contain the entry box name name to use for the e
5. The Almagest 5 1 Chapter 5 Using Tcl Tk Authors Edward A Lee Other Contributors Brian L Evans Wei Jen Huang Alan Kamas Kennard White 5 1 Introduction Tcl is an interpreted tool command language designed by John Ousterhout while at UC Berkeley Tk is an associated X window toolkit Both have been integrated into Ptolemy Parts of the graphical user interface and all of the textual interpreter pt cl are designed using them Several of the stars in the standard star library also use Tcl Tk This chapter explains how to use the most basic of these stars TclScript as well how to design such stars from scratch It is possible to define very sophisticated totally customized user interfaces using this mechanism In this chapter we assume the reader is familiar with the Tcl language Documentation is provided along with the Ptolemy distribution in the SPTOLEMY tcltk itcl man direc tory in Unix man page format HTML format documentation is available from the other src tar file in SPTOLEMY src tcltk Up to date documentation and software releases are available by on the SunScript web page at http www sunscript com There is also a newsgroup called comp lang tcl This news group accumulates a list of frequently asked questions about Tcl which is available http www teraform com 7Elvirden tcl faq The principal use of Tcl Tk in Ptolemy is to customize the user interface Stars can be created that interact with the us
6. e star by the following statement included in the constructor tcl_file clearAttributes A_SETTABLE Thus the user sees only the parameters that are defined in the derived star This is a key part of customizing the star A second issue is that of communicating the new parameter values to the Tcl script For example the Tcl script will need to know the value of the abel parameter in order to cre ate the label for the display The TclScript star automatically makes all the parameters of any derived star available as array entries in the global array whose name is given by the glo bal variable starID To read the value of the label parameter in the Tcl script use the expression set starID label The confusing syntax is required to ensure that Tcl uses the value of starID as the name of the array The string label is just the index into the array The set command in Tcl when given only one argument returns the value of the vari able whose name is given by the argument Some programmers may prefer an alternative way to refer to parameters that is slightly more readable The Tcl statement upvar 0 SstarID params allows subsequent statement to refer to parameters simply as Sparam param_name The upvar command with argument 0 declares the local variable params equivalent to the glo bal variable whose name is given by the value of starID Many more examples can be found in PTOLEMY src domain
7. er in specialized ways by creating customized displays or by soliciting graphical inputs 5 2 Writing Tcl Tk scripts for the TclScript star Several of the domains in Ptolemy have a star called TclScript This star provides the quickest and easiest path to a customized user interface The icon can take any number of forms including the following Wy i y mat gt TclScript TelScript TelScript TelScript TelScript FLIN l Ve Tel Tel Tel Tel TelScript TelScript TelScript TelScript gt gt gt gt Tol TaL Tel 7 Ta All of these icons refer to the same star but each has been customized for a particular number of input and output ports You should select the one you need on the basis of the number of Y Ptolemy Last updated 10 17 97 5 2 Using Tcl Tk input and output ports required The left most icon has an unspecified number of inputs and outputs as indicated by the double arrows at its input and output ports The TclScript star has one parameter settable state tcl_file A string giving 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 star every time it runs We begin with two examples that illustrate most of the key techniques needed to use this
8. g Tcl script can be used with the TclScript star in the sys tem configuration given in example on page 5 2 ptkMakeMeter SptkControlPanel high meter_SstarlI meter tracking scale 0 100 proc scale_update_S starID new_value otkSetMeter SptkControlPanel high meter _SstarID Snew_value D SptkControlPanel high scale_S starID value configure text Snew_value ptkMakeScale SptkControlPanel high scale_SstarlI my scale 50 scale_update_SstarID ptkMakeButton SptkControlPanel middle button_S s my button button_update proc button_update ptkImportantMessage msg ptkMakeEntry SptkControlPanel low entry_SstarID my entry 10 entry_update_SstarID proc entry_update_SstarID new_value setOutputs_SstarID Snew_value It will create the rather ugly control panel shown below Control panal for tel script demo When to stop oom F Debug SO Return PAUSE Seaces STOP Escape meter tracking scale my attom my entry Se DISATSS The commands are explained individually below Ptolemy ptkMakeMeter SptkControlPanel high meter_ starI D tarID Hello D Last updated 10 17 97 5 10 Using Tcl Tk meter tracking scale 0 100 This creates a meter display with the label meter tracking scale in the upper part of the control panel with range from 0 to 100 proc scale_update_SstarID new_value otkSetMete
9. le 2 Consider the following schematic in the SDF domain A Ramp Suppose we specify the following Tcl script for the TclScript star TclScript oral ane pode proc goTcl_SstarID starID set inputVals grabInputs_SstarID set xin lindex SinputVals 0 set yin lindex SinputVals 1 setOutputs_SstarID expr xint yin U C Berkeley Department of EECS The Almagest 5 5 Unlike the previous example this script does not define any code that runs when the script is sourced during the setup phase of execution of the star Instead it simply defines a procedure with a name unique to the instance of the star This procedure reads two input values adds them and writes the result to the output Although this would be a very costly way to accomplish addition in Ptolemy this example nonethe less illustrates an important point If a Tcl script sourced by a TclScript star defines a procedure called goTcl_ starlID then that procedure will be invoked every time the star fires The single argument passed to the procedure when it is called is the starID In this example the procedure uses grabInputs_ starID defined by the TclScript star to read the inputs The current input values are returned by this procedure as a list so the Tcl command 1 index is used to index into the list The final line adds the two inputs and sends the result to the output A
10. ntry box itself value the new value to display in the meter Procedure to make a sliding scale All scales in the control panel range from O to 100 A callback procedure must be defined by the programmer It will be called whenever the user moves the control on the scale Its single argument will be the new position of the control between 0 and 100 Arguments win name of window to contain the scale name name to use for the scale itself desc description to be put into the display position initial integer position between 0 and 100 callback name of callback procedure to register changes Note A widget is created with name win name value that should be used by the programmer to display the current value of the slider Thus the callback procedure should contain a command like Department of EECS The Almagest 5 9 Swin Sname value configure text S new_value to display the new value after the slider has been moved This is not performed automatically because the fixed range from 0 to 100 may be correct from the user s perspective So for exam ple if you divide the scale value by 100 before displaying it then to the user it will appear as if the scale ranges from 0 0 to 1 0 It is also possible to control the position of the slider from Tcl overriding the user actions using a command like Swin name scale set Sposition where position is an integer valued variable in to 100 the range of 0 Example 3 The followin
11. r SptkControlPanel high meter _SstarID Snew_value SptkControlPanel high scale_SstarID value configure text S new_value This defines the callback function to be used for the slider scale shown below the meter The callback function sets the meter and updates the numeric display to the left of the slider Notice that the body of the procedure is enclosed in quotation marks rather than the usual braces This ensures that the variables ptkControlPanel and starID will be evaluated at the time the procedure is defined rather than at the time it is invoked To make sure that new_value is not evaluated until the procedure is invoked we use a preceding backslash as in new_value We could have alterna tively passed the ptkControlPanel and starID values as arguments ptkMakeScale SptkControlPanel high scale_S starID my_scale 50 scale_update_S starID This makes the slider itself and sets its initial value to 50 half of full scale ptkMakeButton SptkControlPanel middle button_SstarID my button button_update This makes a button labeled my button proc button_update ptkImportantMessage msg Hello This defines the callback function connected with the button This callback function opens a new window with the message Hello and grabs the focus The user must dismiss the new window before continuing ptkMakeEntry SptkControlPanel low entry_SstarID my entry 10 entry_update_S
12. s defines a Tcl variable s whose value is the name of the window to be used for the button The first part of the name ptkControlPanel is a global variable giv ing the name of the control panel window itself This global variable has been set by pigi and can be used by any Tcl script The second part middle specifies that the button should appear in the subwindow named middle of the control panel The control panel by default has empty subwindows named high middle and low The last part button_ starID gives a unique name to the button itself The Tcl variable st arID has been set by the TclScript star to a name that is guaranteed to be unique for each instance of the star Using a unique name for the button permits multiple instances of the star in a schematic to create separate buttons in the control window without conflict if winfo exists s This conditionally checks to see whether or not the button already exists If for exam ple the system is being run a second time then there is no need to create the button a second time In fact an attempt to do so will generate an error message If the button does not already exist then it is created by the following lines button s text PUSH ME pack append S ptkControlPanel middle s top The first of these defines the button and the second packs it into the control panel see the Tk documentation The following Tcl statement binds a partic
13. s sdf tcltk stars Ptolemy Last updated 10 17 97 5 12 Using Tcl Tk 5 5 Selecting colors Since X window installations do not necessarily use consistent color names a particu lar color database has been installed in Ptolemy The available colors can be found in the file SPTOLEMY 1lib tcl ptkColor tcl To access this color database use the Tcl function ptkColor name which returns a color defined in terms of RGB components This color can be used anyplace that Tk expects a color If the given name is not in the color database the color returned is black 5 6 Writing Tcl stars for the DE domain In the discrete event DE domain stars are fired in chronological order according to the time stamps of the new data that has arrived at their input ports The Tcl interface class TclStarIfc which was originally written with the SDF domain in mind works well for some types of DE stars Specifically any star with an input in the DE domain can use this class effectively Consequently a basic Tcl Tk star TclScript has been written for the DE domain The TclScript star can have any number of input or output portholes As of this writing it will not work if it is instantiated with no inputs The problem is that with no inputs there will be no events to trigger a firing of the star This will be corrected in the future U C Berkeley Department of EECS
14. s shown in the previous example if the Tcl script defines the optional Tcl procedure goTcl_ starID then that procedure will be invoked every time the star fires It takes one argument the starID and returns nothing This procedure therefore allows for synchro nous communication between the Ptolemy simulation and the Tcl code it is synchronized to the firing of the star If no goTcl_ starl D procedure is defined then communication is asynchronous Tcl commands are invoked at arbitrary times as specified when the script is read For asynchronous operation typically X events are bound to Tcl Tk commands that read or write data to the star The inputs to the star can be of any type The print method of the particle is used to construct a string passed to Tcl Although chronous reads of the star inputs are also allo it is not illustrated in the above examples asyn wed Below is a summary of the Tcl procedures used when executing a Tcl Script star grabInputs_SstarID A procedure that returns the current values of the inputs of the star corresponding to the given starID This procedure is defined by the TclScript star if and only if the instance of the star has at least one input port setOutputs_SstarID A procedure that takes one argument for each output of the TclScript star The value becomes the new output value for the star This procedure is defined by the TclScript
15. star if and only if the instance of the star has at least one output port goTcl_ starID If this procedure is defined in the Tcl script associated with an instance of the TclScript star then it will be invoked every time the star fires wrapupTcl_SstarID If this procedure is defined in the Tcl script associated with an instance of the Ptolemy TclScript star then it will be invoked every Last updated 10 17 97 5 6 Using Tcl Tk time the wrapup method of the star is invoked In other words it will be invoked when a simulation stops destructorTcl_SstarID If this procedure is defined in the Tcl script associated with an instance of the TclScript star then it will be invoked when the destructor for the star is invoked This can be used to destroy windows or to unset variables that will no longer be needed In addition to the starID global variable the TclScript star 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 starIDa 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 con nected to the star The value of the expression set starID numInputs is an inte ger giving the number of inputs The Tcl command set when
16. starID This makes the entry box with initial value 10 proc entry_update_SstarID new_value setOutputs_SstarID Snew_value This defines the callback function associated with the entry box Again notice that the procedure body is enclosed quotation marks U C Berkeley Department of EECS The Almagest 5 11 5 4 Creating new stars derived from the TclScript star A large number of useful stars can be derived from the TclScript star The TkShowValues Star used in example 1 on page 5 2 is such a star That star takes inputs of any type and displays their value in a window that is optionally located in the control panel It has three parameters settable states label A string valued parameter giving a label to identify the display put_in_control_panel A Boolean valued parameter that specifies whether the display should be put in the control panel or in its own window wait_between_outputs A Boolean valued parameter that specifies whether the execu tion of the system should pause each time a new value is dis played If it does then a mouse click in the display restarts the system Conspicuously absent is the fcl_file parameter of the TclScript star from which this is derived The file is hard wired into the definition of the star by the following C statement included in the setup method tcl_file SPTOLEMY src domains sdf tcltk stars tkShowValues tcl The parameter is then hidden from the user of th
17. the case when more than one TclScript star sources the same Tcl script These unique names are constructed using a unique string defined by the star prior to sourcing the script That string is made available to the Tcl script in the form of a glo bal Tcl variable st ar ID The procedure used by the Tcl script to set output values is called setOutputs_ starID This procedure takes as many arguments as there are output ports The argument list should contain a floating point value for each output of the star In the above example Tcl code is executed when the Tcl script is sourced This occurs during the setup phase of the execution of the star After the setup phase no Tcl code will be executed unless the user pushes the PUSH ME button The command bind s lt ButtonPress 1 gt setOutputs_S starID 1 0 defines a Tcl command to be executed asynchronously Notice that the command is enclosed in quotation marks not braces Tcl aficionados will recognize that this is necessary to ensure that the starID variable is evaluated when the command binding occurs when the script is sourced rather than when the command is executed There is no guarantee that the variable will be set when the command is executed In the above example no Tcl code is executed when the star fires The following example shows how to define Tcl code to be executed each time the star fires and also how to read the inputs of the star from Tcl Examp
18. ular command to a mouse action thus defining the response when the button is pushed bind s lt ButtonPress 1 gt setOutputs_S starID 1 0 When button number 1 of the mouse is pressed the Tcl interpreter invokes a proce dure named setOutputs_S starID with a single argument 1 0 passed as a string This procedure has been defined by the TclScript star It sets the value s of the out puts of the star In this case there is only one output so there is only one argument The next statement defines the action when the button is released bind s lt ButtonRelease 1 gt setOutputs_SstarID 0 0 The next statement initializes the output of the star to value 0 0 setOutputs_SstarID 0 0 The last command unsets the variable s since it is no longer needed Ptolemy Last updated 10 17 97 5 4 Using Tcl Tk unset s As illustrated in the previous example a number of procedures and global variables will have been defined for use by the Tcl script by the time it is sourced These enable the script to mod ify the control panel define unique window names and set initial output values for the star Much of the complexity in the above example is due to the need to use unique names for each star instance that sources this script In the above example the Tcl procedure for setting the output values has a name unique to this star Moreover the name of the button in the control panel has to be unique to handle
Download Pdf Manuals
Related Search