Top Up Prev Next Bottom Contents Index Search

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:

$ptkControlPanel A string giving the name of the control panel window associated with a given run. This variable is set by pigi.
$ptkControlPanel.high
The uppermost panel in the control panel that is intended for user-defined entries.
$ptkControlPanel.middle
The middle panel in the control panel that is intended for user-defined entries.
$ptkControlPanel.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/lib/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, ptcl, 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 $PTOLEMY/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 window
ptkMakeButton Procedure to make a pushbutton in a window. A callback procedure 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 <Return>. 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 register changes
ptkMakeMeter 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
ptkSetMeter 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 entry box itself
value the new value to display in
the meter
ptkMakeScale Procedure to make a sliding scale. All scales in the control panel range from 0 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:
$win.$name.value configure -text $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 example, 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
$win.$name.scale set $position
where position is an integer-valued variable in the range of 0 to 100.
Example 3: The following Tcl script can be used with the TclScript star in the system configuration given in example 1 on page 5-2:

ptkMakeMeter $ptkControlPanel.high meter_$starID \
"meter tracking scale" 0 100
proc scale_update_$starID {new_value} \
"ptkSetMeter $ptkControlPanel.high \
meter_$starID \$new_value
$ptkControlPanel.high.scale_$starID.value \
configure -text \$new_value"
ptkMakeScale $ptkControlPanel.high scale_$starID \
"my scale" 50 scale_update_$starID
ptkMakeButton $ptkControlPanel.middle button_$starID \
"my button" button_update
proc button_update {} {ptkImportantMessage .msg "Hello"}
ptkMakeEntry $ptkControlPanel.low entry_$starID \
"my entry" 10 entry_update_$starID
proc entry_update_$starID {new_value} \
"setOutputs_$starID \$new_value"
It will create the rather ugly control panel shown below:

The commands are explained individually below.


ptkMakeMeter $ptkControlPanel.high meter_$starID \
"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_$starID {new_value} \
"ptkSetMeter $ptkControlPanel.high \
meter_$starID \$new_value
$ptkControlPanel.high.scale_$starID.value \
configure -text \$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 alternatively passed the ptkControlPanel and starID values as arguments.


ptkMakeScale $ptkControlPanel.high scale_$starID \
my_scale 50 scale_update_$starID
This makes the slider itself, and sets its initial value to 50, half of full scale.


ptkMakeButton $ptkControlPanel.middle button_$starID \
"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 $ptkControlPanel.low entry_$starID \
"my entry" 10 entry_update_$starID
This makes the entry box with initial value "10".

proc entry_update_$starID {new_value} \
"setOutputs_$starID \$new_value"

This defines the callback function associated with the entry box. Again notice that the procedure body is enclosed quotation marks.



Top Up Prev Next Bottom Contents Index Search

Copyright © 1990-1997, University of California. All rights reserved.