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 button, a button a button that can be disabled and a 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
-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.
Adds a new submenu (cascade objet and associated menu)
to the menu. The menubutton that triggers the
submenu will be labeled
Returns the menu widget associated with a sub-menu
label-text is the label
that was passed in to
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
Returns the list of menu labels created via
Adds a separator to the end of the menu
whose label is
menu-label command-label command
Adds a command item to the menu identified by
command item's label will be
When clicked the
menu-label itemtype args
Adds an arbitrary menu item to
The type of the item is
The allowed values for
are the menu item types defined in
The man page for the menu
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
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:
If false, the run number label and entry widgets are unmanaged. This can be done if no data sources support run numbers.
If false, the title entry and label are unmanaged. This can be done if no data sources support run titles.
-statenormal | 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.
Sets/gets the value of the title string.
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
cget methods for configuring and
querying options. The set of options understood by
RunControl widget are:
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, thebutton removed from the megawidget making it impossible for the user to initiate a transition to Paused.
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:
The first time
is called it must be given a widget
optionally addtional configuration parmaeters
When initially called, the singleton is created and the callout bundle
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:
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
StopWatch is not a megawidget, but does
require applications that normally run in an event loop as it
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:
or you can ask the constructor to allocated a unique command name using the special object name %AUTO%:
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.
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.
script to be run when the elapsed time
when must be a positive integer.
If the elapsed time in integer seconds is already
when, the script won't run.
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
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.
provides the standard
cget methods that
operate on the following options:
-statedisabled | 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.
If true the timed run checkbox is checked if false it is not checked.
-minutesinteger [0-59] ,
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
The code fragment below turns on timed runs and sets the duration to 2hours:
OutputWindow megawidget is a megawidget
that is based on a Tk
widget coupled to vertical and horizontal scroll bars. As
the name implies, while the text widget
can be used for input and output, the
is intended only for output.
The ReadoutGUI/ReadoutShell uses an
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
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
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.
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
OutputWindow instances support
cget operations to interact with
configuration options. The configuration options supported
Specifies the default text color. The
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
Specifies the background color of the
widget. This is passed without interpretation to
the text widget.
Specifies the width and height of the text widget in characters. These options are passed without interpretation to the text widget.
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.
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
(see below) determine how log messages are handled
by the output widget.
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.
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
-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
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
This section describes the public methods for the
message to the
OutputWindow displaying it
using the current values of
-background options to determine
the text's rendition.
If the optional
provided, the text is not output with
a trailing newline. This can be used to
build up a one-line message in several
Creates and outputs a log
the rendition of the message via
the values of the
option. It is an error for
to be a value not in 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.
Opens the file
an output log file. From this point on all
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.
Closes any open log file.
The application level singleton is implemented via the
This proc is declared as follows:
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.