ui -- ReadoutGUI graphical user interface elements.


package require ui


This package provides all of the graphical user interface elements that are part of the standard ReadoutGUI. It is possible for a custom control interface to be written using some, all or none of these elements.

This package can also be used to access elements of the ReadoutGUI from within extensions to the standard ReadoutShell. The package consists of a rather large set of component megawidgets and singleton implementations of those megawidgets. The remainder of this section will briefly describe the purpose of each of those megawidgets. Subsequent sections will provide more detailed reference information about each megawidget.


Provides the menu bar for the application. This can be used as a genric menu bar handling class for your own applications distinct from the ReadoutShell as well.


Provides a megawidget that identifies runs. This contains an entry/display of a title string and an entry for a run number. The run number entry is constrained to hold positive integers.


Provides a megawidget that contains the controls for a run. These are buttons intended to drive the RunStateMachine. Buttons that can appear include a Start button, a Begin/End button a Pause/Resume button that can be disabled and a Record checkbutton.

The widget is linked to the run state machine singleton so that button presses create the appropriate state transitions. An associated callout bundle allows the widget to track state machine transitions that it does not initiate.


This is a non graphical element that implements a simple stopwatch. The stop watch can be started, stopped and reset. Furthermore, alarms can be added which invoke application specific commands when they are reached.

This is used to implement timed runs, and to maintain the elapsed run time, but also can be used in your own application whenever you need this functionality.


Works with an embedded stopwatch object to provide elapsed run display. The stopwatch is fully exposed allowing application specific code to be invoked when a specific elapsed run time is reached (this is how timed runs work).

A callout bundle is provided so that the timer starts, stops and resets at the appropriate times.


Provides a GUI element that prompts for timed run information. This consists of elements that allow users to specify the length of a timed run, as well as a checkbox that allows users to enable/disabled timed runs.

An associated callout bundle hooks the singleton instance to the Run state machine and the elapsed run time implementing the semantics of timed runs.


Provides a scrollable text widget and methods to output data into that widget. The widget also supports formatted log entries that are very configurable. A singleton and associated callout bundle supports logging basic state transitions.

An associated OutputWindowSettings provides a dialog that allows several settings of the output window singleton to be modified. Note that this is a bit specialized, while the output widow itself is not.


Provides a support for a vertically stacked set of widgets and convenience functions for these to be simple labels. These are intended to provide status information about components of the system.


This object manages a menu. Once created it can be turned into a menu bar for a toplevel by using it's path as the -menu option of that toplevel. The delegation of all unknown options and methods to the underying menu makes this indistinguishable from a menu created via menu. Convenience methods have been added to make simple things simpler.


addMenu label-text

Adds a new submenu (cascade objet and associated menu) to the menu. The menubutton that triggers the submenu will be labeled label-text.

lookupMenu label-text

Returns the menu widget associated with a sub-menu created via addMenu. label-text is the label that was passed in to addMenu when the submenu was created.

This relies on an internal data structure that maintains the correspondence between sub-menu labels and their menu widget paths. Therefore this method can only be used to look up submenus created with addMenu


Returns the list of menu labels created via addMenu.

addSeparator label-text

Adds a separator to the end of the menu whose label is label-text.

addCommand menu-label command-label command

Adds a command item to the menu identified by menu-label. The command item's label will be command-label. When clicked the command will be run.

addMenuItem menu-label itemtype args

Adds an arbitrary menu item to menu-label The type of the item is itemtype. The allowed values for itemtype are the menu item types defined in The man page for the menu command.

The args parameter is pasted on the back end of the menu add command and normally consists of a list of option value pairs (you can use the Tcl list command to build it). The valid options for each menu type are also described in the The man page for the menu command.


This megawidget consists of two entries and associated labels. The entries provide mechanisms for users to supply a run number and a title string. The run number entry is validated so that it must be a positive integer.


The megawidget supports the standard configure and cget methods. These operate on the following set of options:

-haverun boolean-value

If false, the run number label and entry widgets are unmanaged. This can be done if no data sources support run numbers.

-havetitle boolean-value

If false, the title entry and label are unmanaged. This can be done if no data sources support run titles.

-state normal | disabled | readonly

Specifies the state that will be applied to all entry widgets. This is normally used to make the entries read-only when the run is Active or Paused.

-title title-string

Sets/gets the value of the title string.

-run run-number

Sets/gets the value of the run number.


This is a megawidget that contains the controls needed to drive the run state machine through its state transitions. See RunStateMachine for information about the run state machine.

Associated with this widget is a singleton implementation and a callout bundle that hooks the widget into the run state machine singleton so that it can maintain a state that is consistent with the state of the run even in the face of state transitions it does not initiate.


The megawidget understands the standard configure and cget methods for configuring and querying options. The set of options understood by the RunControl widget are:

-pauseable boolean

Set this to boolean true if the system as a whole can support paused runs. False if not. If the value of this option is false, the Pause button removed from the megawidget making it impossible for the user to initiate a transition to Paused.

-recording boolean

If true the recording checkbutton is on indicating the run is either now being recorded (if in one of the active states), or the next run will be recorded if the run is not in an active state.

Active states are Active and Paused.


In the context of the standard ReadoutShell/ReadoutGUI, the run control megawidget is attached to the run state machine so that it can always reflect the state of the system. This is done by providing a singleton implementation of the widget and registering a callout bundle with the state machine singleton that manipulates the widget's appearance:

set rctl ::RunControlSingleton::getInstance ?path ?args??

The first time ::RunControlSingleton::getInstance is called it must be given a widget path and optionally addtional configuration parmaeters args. When initially called, the singleton is created and the callout bundle registered.

All calls return the widget path of the singleton. Thus, if you know the singleton has already been created the code fragment below will turn on the recording checkbutton:

[::RunControlSingleton::getInstance] configure -recording 1


The StopWatch class provides a timekeeper that can stop, start, be reset and have alarms fire and specific elapsed times. An alarm is a script that is associated with an elapsedtime via the addAlarm method.

StopWatch is not a megawidget, but does require applications that normally run in an event loop as it uses the after command to schedule clock ticks. Constructing an object creates an object command ensemble which provides access to the object methods. The constructor returns the name of the command.

You can either specify the command explicitly:

StopWatch myStopwatch;     # Command named myStopwatch
myStopwatch some-method...

or you can ask the constructor to allocated a unique command name using the special object name %AUTO%:

set myStopwatch [StopWatch %AUTO%];
$myStopWatch some-method ...


Stop watch objects have the following methods:


Starts the stop watch. When the event loop is active, every .25 seconds, a tick will be declared. The elapsed time is maintained in milliseconds. via that counter. If the application does not often enter the event loop, clearly the stopwatch will run slow.

Note that start does not clear the timer.


Stops the stopwatch. If the stopwatch is already halted, an error is thrown.


Sets the elapsed time to 0 milliseconds. It is legal to do this while the stopwatch is running. Note that this does not remove alarm scripts.

addAlarm when script

Schedules a script to be run when the elapsed time is when seconds. Note that when must be a positive integer. If the elapsed time in integer seconds is already past when, the script won't run.

removeAlarm when script

Removes the matching script from the set of scheduled scripts. It is an error to remove a script that has not been registered.


Returns true if the stopwatch is running.


Returns the elapsed time in milliseconds.


Makes use of a StopWatch to provide a visual elapsed time megawidget. This is normally used by the ReadoutGUI to provide a visual indication of the elapsed active time within a data taking run. The stopwatch methods are exposed so that given one of these widgets anything that can be done to a stopwatch can be done to it.

Within the context of the ReadoutGUI, a singleton object is available which hooks a callout bundle to the state machine singleton to ensure that the timer starts, stops and resets at the appropriate time.

Application code can get access to this singleton by

set elapsedTime [::ElapsedTime::getInstance]

This is typically done when application code wants to perform an action at a specific elapsed run time (alamr). For example, timed runs are implemented by setting an alarm for the desired length of the run. The alarm proc simply forces a state transition to Halted.


TimedRunControls is a megawidget that allows user to specify timed run durations and to enable/disable timed runs. A singleton is implemented which hooks itself into both the State machine singleton (via a callback bundle) and the Elapsed time singelton (via alarms) when a timed run is begin.


The TimedRunControls megawidget provides the standard configure and cget methods that operate on the following options:

-state disabled | normal | readonly

Controls the appearance and ability of the user to interact with the controls. normal provides a 'normal' ui appearance and allows users to interact with the widget, changing values. readonly provides a normal appearance but the user cannot change the values of the widget. disabled ghosts the controls and prevents user interaction.

-timed boolean

If true the timed run checkbox is checked if false it is not checked.

-days integer, -hours integer [0-23], -minutes integer [0-59] , -seconds integer [0-52]

Specifies the desired active duration of the run when a timed run is performed.


The ReadoutGUI/ReadoutShell manages access to the timed run instance it uses via the singleton pattern. If your extensions to ReadoutShell need access to the duration they can access the singleton via ::TimedRun::getInstance.

The code fragment below turns on timed runs and sets the duration to 2hours:

[::TimedRun::getInstance] configure -timed true \
    -days 0 -hours 2 -minutes 0 -seconds 0


The OutputWindow megawidget is a megawidget that is based on a Tk text widget coupled to vertical and horizontal scroll bars. As the name implies, while the text widget can be used for input and output, the OutputWindow is intended only for output.

The ReadoutGUI/ReadoutShell uses an OutputWindow to report output from data sources as well as to inform the user of various events (e.g state transitions). The text widget is a very complex entity. The OutputWindow has a much simpler programmatic interface.

Before providing the reference information, it is worth pointing out that the OutputWindow as support for log like messages. A log message is a message that has a severity. Log messages are automatically output with timestamps. It is possible to instruct the OutputWindow to render differnet severities using different renditions. It is also possible to suppress the display of some message severities. The log capabilitie is used extensively by the ReadoutGUI/ReadoutShell. It is also possible to make the OutputWindow record all output to a log file for later review and analysis.

The OutputWindow megawidget has a singleton associated with the instance that is used by the ReadoutGUI. There is also a state machine singleton callout bundle that is used to log state transition messages.


OutputWindow instances support the usual configure and cget operations to interact with configuration options. The configuration options supported are:

-foreground color-spec

Specifies the default text color. The color-spec can be a color name recognized by Tk or it can be an #rrggbb color value. This option is actually delegated directly to the underlying text widget without interpretation.

background color-spec

Specifies the background color of the OutputText text widget. This is passed without interpretation to the text widget.

-width characters-wide, -height lines-tall

Specifies the width and height of the text widget in characters. These options are passed without interpretation to the text widget.

-history lines

The number of lines of historical data that are kept in the scrolling buffer. If the number of output lines exceeds lines, the oldest lines are removed from the history until the number of lines remaining is at most lines.

The default value for this is 1000. Note that log files do not have a line limit other than the amount of disk space available.

-logclasses list-of-severities

Determines the set of legal logging classes (severities) that are accepted by the log message (see METHODS below). This, in addition to the value of -showclass (see below) determine how log messages are handled by the output widget.

-monitorcmd script

Provides a script that is invoked whenever output is added to the window. The ouptut is appended quoted into a single word at the end of the script.

-showlog dict-of-option-lists

Determines for each log class value in the -logclasses option what is done with messages submitted with that log class. Note that changes to this value affect the display of old log messages with the exception of suppressed classes which will only display new entries.

The form of the value for this option is a dict with keys that are log classes defined in the -logclasses option value. The values are lists of tag options as defined TAGS section of the Tcl/Tk text widget manpage . These options are applied to log entries with these classes.

If a log class is omitted fromthe dict it will not be displayed. One use for this is to provide a debug log class for debugging information which can be suppressed by omitting it from the -showlog dict.


This section describes the public methods for the OutputWindow widget.

puts ?-nonewline? message

Outputs message to the OutputWindow displaying it using the current values of the -foreground and -background options to determine the text's rendition.

If the optional -nonewline is provided, the text is not output with a trailing newline. This can be used to build up a one-line message in several puts calls.

log class message

Creates and outputs a log message. class determines the rendition of the message via the values of the -showlog option. It is an error for class to be a value not in the logclasses option value.

The messge is output preceded by a timestamp and class name.


Clears the contents of the window.


Returns the textual contents of the window. Note that no hints are provided to enable the caller to determine the rendition of the text.

open filename

Opens the file filename as an output log file. From this point on all output (log and puts) to the OutputWindow will be recorded in that file.

The file is opened for append. If there was a previously open log file it is closed first. See close below.


Closes any open log file.


The application level singleton is implemented via the ::Output::getInstance method. This proc is declared as follows:

proc Output::getInstance { {win {}} args} {

The win parameter is required only on the first call and is the window path to be used for the object. Similarly any trailing parameters to the first invocation contain configuration option/value pairs. Creation register the run state machine callout bundle that maintains the foreground/background appearance of the window as runs start and stop.

The proc returns the widget path.