Menu
▾
▴
[Nscldaq-cvscommits] SF.net SVN: nscldaq:[2595] trunk/nextgen
|
From: <ro...@us...> - 2011-11-18 20:47:59
|
Revision: 2595
http://nscldaq.svn.sourceforge.net/nscldaq/?rev=2595&view=rev
Author: ron-fox
Date: 2011-11-18 20:47:52 +0000 (Fri, 18 Nov 2011)
Log Message:
-----------
Add complete docs for the readout GUI.
Modified Paths:
--------------
trunk/nextgen/ChangeLog
trunk/nextgen/daq/readoutgui/readoutgui.xml
Modified: trunk/nextgen/ChangeLog
===================================================================
--- trunk/nextgen/ChangeLog 2011-11-17 14:44:00 UTC (rev 2594)
+++ trunk/nextgen/ChangeLog 2011-11-18 20:47:52 UTC (rev 2595)
@@ -143,6 +143,8 @@
reference docs (1compatibility).
- Add compatibility docs to the ring migration tutorial.
-November 16, 2011 10.0-022
+November 16-18, 2011 10.0-022
- Explicitly use ssh not rsh in the rsh package of
ReadoutShell.
+ - Add complete docs for the readout GUI.
+
Modified: trunk/nextgen/daq/readoutgui/readoutgui.xml
===================================================================
--- trunk/nextgen/daq/readoutgui/readoutgui.xml 2011-11-17 14:44:00 UTC (rev 2594)
+++ trunk/nextgen/daq/readoutgui/readoutgui.xml 2011-11-18 20:47:52 UTC (rev 2595)
@@ -567,7 +567,9 @@
<refsynopsisdiv>
<cmdsynopsis>
- <command>
+ <command>
+$DAQROOT/bin/ReadoutShell <optional><option>-host</option>=<replaceable>readout-host</replaceable></optional>
+<optional><option>-path</option>=<replaceable>readout-program-path</replaceable></optional>
</command>
</cmdsynopsis>
@@ -575,6 +577,25 @@
<refsect1>
<title>DESCRIPTION</title>
<para>
+ Starts the readout GUI. All of the options on the command line are optional.
+ If they are omitted, the program first attempts to fetch them from the
+ configuration (see the section Configuration files and environment variables
+ below for more information about configuration). If the required information
+ cannot be retrieved from the configuration, dialogs will be launched to prompt
+ for the host and readout path.
+ </para>
+ <para>
+ The NSCL Data acquisition system uses a specific file directory
+ tree to associate event data and any other data that may be
+ germane to the run. The ReadoutGUI on startup creates this
+ directory structure and enforces it during its operation.
+ </para>
+ <para>
+ The ReadouGui on startup attempts to launch the readout program
+ specified on the command line, in the configuration or via
+ prompts to the user on the host system specified in the same
+ way. It reports unexpected Readout program exits via a dialog
+ box to the user.
</para>
</refsect1>
<refsect1>
@@ -583,12 +604,1228 @@
</title>
<variablelist>
<varlistentry>
- <term></term>
- <listitem><para></para></listitem>
+ <term><option>-host</option>=<replaceable>readout-host</replaceable></term>
+ <listitem>
+ <para>
+ Specifies that
+ <parameter>readout-host</parameter> is the name of the computer
+ on which the Readout program should be run. hostname
+ is also used as the data source to which the readout
+ gui connects other pieces of the system it controls,
+ most importantly, the eventlog event data logging
+ program.
+ </para>
+ </listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>-path</option>=<replaceable>readout-program-path</replaceable></term>
+ <listitem>
+ <para>
+ Specifies
+ <parameter>readout-program-path</parameter> as the
+ readout program that should be run. The path must
+ be absolute as you cannot make any assumptions about
+ the working directory in which it is resolved.
+ This is an important point that is sometimes missed:
+ </para>
+ <para>
+ Suppose your current working directory is ~/readout
+ and the Readout program is stored in
+ <filename>~/software/readout/Readout</filename>.
+ Specifying the readout program as
+ <filename>../software/readout/Readout</filename>
+ will not work as expected.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect1>
+ <refsect1>
+ <title>FILES</title>
+ <para>
+ Several files are read written to maintain both the
+ static configuration (not changing from run to run) and the
+ last known dynamic configuration (changing from run to run).
+ Every effort is made to preserve state so that if you start
+ the Readout GUI again after it has exited normally or abnomrally,
+ it will return to the state it was when it exited.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><filename>~/stagearea/.readoutconfig</filename></term>
+ <listitem>
+ <para>
+ Contains state data for both static and dynamic
+ state. This is rewritten as dynamic stat is modified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>.daqconfig</filename></term>
+ <listitem>
+ <para>
+ This file is loaded both from the home directory ansd
+ from your current working directory. It allows
+ you to finely tune the startup static state of the
+ readout gui. See CONFIGURATION below for more
+ information about what can be put in this file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><filename>ReadoutCallouts.tcl</filename></term>
+ <listitem>
+ <para>
+ This file is loaded from the home directory,
+ the experiment view's <filename>current</filename>
+ directory and the current working directory.
+ See EXTENSION hooks below for more information
+ about what this file can contain.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>CONFIGURATION</title>
+ <para>
+ The ReadoutGUI has many configuration parameters, although
+ normally the default values are suitable for your use.
+ The program gets configuration from a combination of
+ configuration files, environment variables and default values.
+ See FILES above for the set of configuration files.
+ </para>
+ <para>
+ The section below describes the configuration parameters,
+ where appropriate the corresponding environment variables and
+ the precedence.
+ </para>
+ <segmentedlist>
+ <segtitle>Configuration Parameter</segtitle>
+ <segtitle>Environment Variable</segtitle>
+ <segtitle>Precedence</segtitle>
+ <segtitle>Description</segtitle>
+ <seglistitem>
+ <seg>SourceHost</seg>
+ <seg>DAQHOST</seg>
+ <seg>Command line, Environment variable, config files.</seg>
+ <seg>Provides the host in which the readout software is run.
+ This also determines the URL that will be generated to
+ describe to the clients Readout GUI runs where data
+ comes from.
+ </seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>ReadoutPath</seg>
+ <seg>RDOFILE</seg>
+ <seg>Command line, Environment variable, config files.</seg>
+ <seg>Absolute path to the Readout program.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>StageArea</seg>
+ <seg>EVENTS</seg>
+ <seg>Environment, Config File</seg>
+ <seg>The root directory of the event data. This normally
+ defaults to <filename>~/stagearea</filename>.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Experiment</seg>
+ <seg>EXPDIR</seg>
+ <seg>Environment, config</seg>
+ <seg>The root of the directory where the run data are stored.
+ This defaults to <filename>~/experiment which,</filename>
+ if it does not initially exist is linked symbolically to
+ <filename>$StageArea/experiment</filename>
+ </seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>RunTitle</seg>
+ <seg>EXPTITLE</seg>
+ <seg>Config File, Environment</seg>
+ <seg>Title of the run. This is normally only useful
+ to provide an initial title as it is overidden by any
+ changes the user makes in the GUI.
+ </seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>RunNumber</seg>
+ <seg>N/A</seg>
+ <seg>Gui, Config file</seg>
+ <seg>The run number of the current run if the run is active,
+ or the next run if the run is idle.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>ScalerCount</seg>
+ <seg>SCALERS</seg>
+ <seg>GUI, Configuration file, Environment</seg>
+ <seg>Value set to the Readout's <varname>scalers</varname>
+ variable prior to starting run initialization. This can be,
+ but need not be, used by the Readout program to determine how
+ many scaler channels are expected. Whether and how it is used
+ is entirely up tot he application developer(s).
+ </seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>ScalerInterval</seg>
+ <seg>SCALERINTERVAL</seg>
+ <seg>Gui, Config file, Environment</seg>
+ <seg>Determines the value set in the Readout program's
+ <varname>frequency</varname> variable prior to run initiaization.
+ This can be but need not be used to set the period of the
+ scaler readout trigger. Whether and how it is used
+ is entirely up to the application developer(s).
+ </seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Recording</seg>
+ <seg>N/A</seg>
+ <seg>GUI, Config file</seg>
+ <seg>If the run is active,this non zero when event data
+ are being recorded. When the run is not active, this
+ variable reflects whether or not the next run will record
+ event data.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>Timed</seg>
+ <seg> N/A</seg>
+ <seg>Gui, Config file</seg>
+ <seg>Reflects whether or not this run (or the next run if
+ idle) will be a timed run</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg>TimedLength</seg>
+ <seg>N/A</seg>
+ <seg>Gui, Config file</seg>
+ <seg>If the configuration/state parameter <varname>Timed</varname>
+ is true, this variable is the number of seconds for which a
+ timed run should take data.</seg>
+ </seglistitem>
+ </segmentedlist>
+ </refsect1>
+ <refsect1>
+ <title>EXTENSION HOOKS</title>
+ <para>
+ The Readout GUI can be extended by user supplied scripts.
+ How to provide an extension script is described in
+ FILES under the description of <filename>ReadoutCallouts.tcl</filename>.
+ This section describes the callbacks ReadoutGUI makes to any
+ extension that defines them and the API available to those
+ scripts (see Programmatic Inteface below).
+ </para>
+ <para>
+ In addition to executing arbitrary Tcl code at the global level
+ when it is loaded, <filename>ReadoutCallouts.tcl</filename> can
+ provide <command>proc</command>s that are called at well defined
+ points in the execution of the Readout GUI.
+ </para>
+ <para>
+ The callbacks the set of <filename>ReadoutCallouts</filename> can
+ provide are:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><command>OnStart</command></term>
+ <listitem>
+ <para>
+ Called when the readout program is started up.
+ At the time this is called, the Readout program
+ may not be sufficiently initialized to accept
+ commands. if your script feeds commands you might
+ want to insert a short delay prior to doing this.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>OnBegin</command></term>
+ <listitem>
+ <para>
+ This proc is called just after the run has been
+ started. It is passed the run number of the run
+ that has just started. By the time <command>OnBegin</command>
+ is called, the Event Logging program (if recording
+ is enabled) is ready to run. The Readout program has
+ not yet, however, been told to start the run.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>OnEnd</command></term>
+ <listitem>
+ <para>
+ Called just after a run has ended. The Readout program
+ has been asked to end however it is not known yet
+ that the readout program has actually sent its end
+ of run buffer to the event distribution system.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>OnPause</command></term>
+ <listitem>
+ <para>
+ Called when a data taking run is being paused. This
+ is called at an analagous time to the OnEnd call.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>OnResume</command></term>
+ <listitem>
+ <para>
+ Called when a data taking run is being resumed.
+ This is called at an analgous time to the OnBegin
+ function.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect2>
+ <title>Programmatic Interface</title>
+ <para>
+ Readout GUI extension scripts can also interact with well
+ defined interfaces to the Readout GUI.
+ This section describes those interfaces.
+ </para>
+ <para>
+ The Readout GUI is segmented into several packages. Each
+ package is implemented as a Tcl package and you should use
+ <command>package require</command> to ensure the package is
+ loaded prior to invoking <command>proc</command>s from the
+ package.
+ </para>
+ <variablelist>
+ <para>
+ The Readout GUI package your script can use are:
+ </para>
+ <varlistentry>
+ <term>ReadoutState</term>
+ <listitem>
+ <para>
+ Provides the ability to manipulate and inquire
+ about the state of the system.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ReadoutControl</term>
+ <listitem>
+ <para>
+ Provides the ability to control the readout
+ program.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ReadoutGui</term>
+ <listitem>
+ <para>
+ Provides the ability to do things that the
+ GUI elements can cause to happen.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>ReadougGUIPanel</term>
+ <listitem>
+ <para>
+ Provides access to the gui elements of the
+ user interface itself. Note the first
+ <literal>g</literal> in this package name
+ is <emphasis>not</emphasis> a typo.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <refsect3>
+ <title>Programmatic interface</title>
+ <subtitle>ReadoutState package</subtitle>
+ <para>
+ The ReadoutState package manipulates and gets access
+ to various state values of the Readout GUI. These commands
+ are located in the <literal>ReadoutState</literal> namespace.
+ If you don't want to qualify calls with
+ <literal>ReadoutState::</literal>, you can
+ <command>namespace import ReadoutState::*</command>.
+ The descriptions below assume this has been done.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><command>setTitle</command> <replaceable>newTitle</replaceable></term>
+ <listitem>
+ <para>
+ Sets the title string for the next run. Unlike
+ the GUI, which does not allow title string
+ changes until the run is halted, the software
+ can change this string at any time and the new
+ value will be reflected in the GUI. The Readout
+ program, however, only receives a new title
+ string just prior to the start of a run, and
+ prior to the call to <command>OnBegin</command>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>setRun</command> <replaceable>runNumber</replaceable></term>
+ <listitem>
+ <para>
+ Sets the run number for the next run that
+ Readout will start. See setTitle for for
+ what this means and when the Readout
+ program will actually see this setting.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>getRun</command></term>
+ <listitem>
+ <para>
+ Returns the run number
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>incRun</command></term>
+ <listitem>
+ <para>
+ Increments the run number held by the GUI.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>setScalerCount</command> <replaceable>scalers</replaceable></term>
+ <listitem>
+ <para>
+ Sets the number of scalers the user wants
+ read out. This is updated in the readout
+ program at the start of the next run. It is
+ possible for the readout software to
+ override this value programmtically. It is
+ intended for scaler readout software that
+ knows how to use this value to adjust the
+ set of scalers that are actually being read.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>getScalerCount</command></term>
+ <listitem>
+ <para>
+ Returns the proposed number of scalers
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>setScalerPeriod</command> <replaceable>timInSeconds</replaceable></term>
+ <listitem>
+ <para>
+ Sets the number of seconds between timed
+ scaler readout in seconds. Note that it
+ is up to the application code to select
+ a timed trigger and to modify the time interval
+ based on this value at the beginning of each
+ run. The value will be pushed into the
+ main interpreter's <varname>frequency</varname>
+ variable.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>getScalerPeriod</command></term>
+ <listitem>
+ <para>
+ Returns the number of seconds between
+ periodic scaler readouts.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>getRecording</command></term>
+ <listitem>
+ <para>
+ Returns true if event recording is enabled.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>enableRecording</command></term>
+ <listitem>
+ <para>
+ Enables event recording. As with all of
+ these parameters, event recording determines
+ what happens at the start of the next run.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>disableRecording</command></term>
+ <listitem>
+ <para>
+ Disable event recording.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>isTimedRun</command></term>
+ <listitem>
+ <para>
+ Returns a true boolean value if the Timed
+ run checkbox is enabled.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>TimedRun</command></term>
+ <listitem>
+ <para>
+ Enables the next run to be a timed run.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>notTimedRun</command></term>
+ <listitem>
+ <para>
+ Says that the next run will not be a timed
+ run.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>timedLength</command></term>
+ <listitem>
+ <para>
+ Returns the length of a timed run. The
+ length is returned as the number of seconds
+ the run would last.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>setTimedLength</command> <replaceable>seconds</replaceable></term>
+ <listitem>
+ <para>
+ Sets the length of the timed run in seconds.
+ You must also enabled timed running in
+ order for this to mean anything.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect3>
+ <refsect3>
+ <title>Programmatic interface</title>
+ <subtitle>ReadoutControl package</subtitle>
+ <para>
+ This package allows you to set and inquire the
+ known state of the Readout program. You can us it
+ to send arbitrary messages to the readout program
+ or to perform specific state transitions of the run.
+ </para>
+ <para>
+ Where you force a state change in the Readout program
+ that the GUI normally forces (e.g. starting a run), it
+ is important that you use the higher level functions to
+ do that so that the GUI remains consistent with the state
+ of the Readout. If, for example, you start a run by
+ sending the begin command directly to the Readout program,
+ the run control buttons will not reflect that the run can
+ be halted. Use of e.g.
+ <command>ReadoutControl::Begin</command> maintains
+ the state correspondence.
+ </para>
+ <para>
+ All of the procs described in this section are
+ in the <literal>ReadoutControl</literal> namespace.
+ If you don't want to prefix each command with
+ <literal>::ReadoutControl::</literal> you should
+ import the namespace using
+ <command>namespace import ::ReadoutControl::*</command>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><command>getReadoutState</command></term>
+ <listitem>
+ <para>
+ Returns the known state of the readout program.
+ This can be any of the following textual values:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>NotLoaded</literal></term>
+ <listitem>
+ <para>
+ The Readout program is not running.
+ Either it was never started, or it
+ failed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>NotRunning</literal></term>
+ <listitem>
+ <para>
+ The Readout program is present, but
+ the run is in the halted state.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>Paused</literal></term>
+ <listitem>
+ <para>
+ The readout program has an active
+ run that is currently paused.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>Active</literal></term>
+ <listitem>
+ <para>
+ The readout program has an active
+ run and is taking data.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>isExecuting</command></term>
+ <listitem>
+ <para>
+ Returns a
+ <literal>true</literal>
+ boolean value if the Readout
+ program is executing. That is if
+ <command>ReadoutControl::getReadoutState</command>
+ would not return
+ <literal>NotLoaded</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>SendCommand</command> <replaceable>string</replaceable></term>
+ <listitem>
+ <para>
+ Sends a literalcommand to the readout program.
+ In the case of the SBS Readout skeleton
+ you might use this in e.g.
+ <command>OnStart</command>
+ to force the readout program to source some
+ configuration script.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>SetReadoutProgram</command> <replaceable>host path</replaceable></term>
+ <listitem>
+ <para>
+ Determines which readout program will be run
+ next, and on which system. host specifies the
+ target processor, and path should be the full
+ absolute path to the program. If you have a
+ relative path you can use the Tcl
+ <command>file normalize</command>
+ command to turn it into an absolute path.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>ExitReadoutProgram</command></term>
+ <listitem>
+ <para>
+ Forces the readout program to exit. T
+ his is done as follows:
+ <orderedlist>
+ <listitem><para>The
+ <command>end</command>
+ command is sent to the program.
+ </para></listitem>
+ <listitem><para>The
+ <command>exit</command>
+ command is sent to the program.
+ </para></listitem>
+ <listitem><para>The pipe open to the
+ readout program is closed.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>StartReadoutProgram</command></term>
+ <listitem>
+ <para>
+ Starts the readout program using the current
+ target host and path. If the readout program
+ is running it is stopped. This means that to
+ programmatically change readout programs you
+ can do something like this:
+ <informalexample>
+ <programlisting>
+package require ReadoutControl
+set newProgram ~/daq/Readout/Readout
+set host spdaq22
+ReadoutControl::SetReadoutProgram $host [file normalize $newProgram]
+ReadoutControl::StartReadoutProgram
+ </programlisting>
+ </informalexample>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>SetRun</command> <replaceable>runNumber</replaceable></term>
+ <listitem>
+ <para>
+ Sends a command to the readout program to
+ set the run number to number. You should
+ normally use the functions in the package
+ ReadoutState to do this, in order to maintain
+ synchronization between the GUI and the
+ Readout program state.
+ </para>
+ <para>
+ If the ReadoutGui believes the readout
+ program is in the
+ <literal>NotRunning</literal> state, an
+ error will be thrown.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>SetTitle</command> <replaceable>newTitleString</replaceable></term>
+ <listitem>
+ <para>
+ Sends a message to the readout program to
+ change its title. You should normally use
+ the functions in the package ReadoutState to
+ do this, in order to maintain synchronization
+ between the GUI and the Readout program state.
+ </para>
+ <para>
+ If the ReadoutGui believes the readout
+ program is not in the
+ <literal>NotRunning</literal>
+ state, an error will be thrown.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>Begin</command></term>
+ <listitem>
+ <para>
+ Sends a message to the readout software to
+ start a run. You should normally use the
+ functions in the package ReadoutState to do
+ this, in order to maintain synchronization
+ between the GUI and the Readout program state.
+ </para>
+ <para>
+ If the ReadoutGui believes the readout
+ program is not in the
+ <literal>NotRunning</literal>
+ state, an error will be thrown.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>End</command></term>
+ <listitem>
+ <para>
+ Sends a message to the readout software
+ ending any active run. You should normally
+ use the functions in the package ReadoutState
+ to do this, in order to maintain synchronization
+ between the GUI and the Readout program state.
+ </para>
+ <para>
+ If the ReadoutGui believes the readout
+ program is in the
+ <literal>NotRunning</literal>
+ state, an error will be thrown.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>Pause</command></term>
+ <listitem>
+ <para>
+ Pauses any active run. You should normally
+ use the functions in the package ReadoutState
+ to do this, in order to maintain synchronization
+ between the GUI and the Readout program state.
+ </para>
+ <para>
+ If the ReadoutGui believes the readout
+ program is not in the
+ <literal>Active</literal> state, an error will be thrown.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>Resume</command></term>
+ <listitem>
+ <para>
+ Sends a message to the readout software to
+ resume a paused run. You should normally use
+ the functions in the package ReadoutState to
+ do this, in order to maintain synchronization
+ between the GUI and the Readout program state.
+ </para>
+ <para>
+ If the ReadoutGui believes the readout
+ program is not in the <literal>Paused</literal>
+ state, an error will be thrown.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect3>
+ <refsect3>
+ <title>Programmatic interface</title>
+ <subtitle>ReadoutGUI package</subtitle>
+ <para>
+ This package provides access to the functions that
+ the graphical user interface itself calls in response
+ to button pushes. Often using these methods is the
+ safest way to do something as gthen you are duplicating the
+ action of the GUI elements.
+ </para>
+ <para>
+ All procs described here are in the
+ <literal>ReadoutGui::</literal> namespace. If you don't
+ want to have to precede each function name with
+ <literal>::ReadoutGUI</literal>, use
+ <command>namespace import ::ReadoutGui::*</command>
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><command>Start</command></term>
+ <listitem>
+ <para>
+ Simulates the
+ <guimenu>File</guimenu>→<guisubmenu>Start</guisubmenu>
+ menu selection. The Readout program selected
+ is started on the target host without any
+ attempt to stop any existing Readout.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>Restart</command></term>
+ <listitem>
+ <para>
+ Simulates the
+ <guimenu>File</guimenu>→
+ <guisubmenu>Restart</guisubmenu>
+ menu choice. This attempts to stop an
+ existing Readout program before starting a
+ new instance of the selected Readout program
+ in the target host.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>Begin</command></term>
+ <listitem>
+ <para>
+ Simulates a press of the Begin button. This
+ attempts to start a run. Note that
+ programmatically, there are no protections
+ at this level against beginning a run that
+ is already running. You should inquire the
+ state of the system prior to attempting to
+ start a run. For example:
+ </para>
+ <informalexample>
+ <programlisting>
+
+if {[ReadoutControl::getReadoutState] eq "NotRunning"} {
+ ReadoutGui::Begin
+} else {
+ # Here recover from the fact that the run
+ # Cannot be started at this point in time.
+}
+ </programlisting>
+ </informalexample>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>Pause</command></term>
+ <listitem>
+ <para>
+ Simulates a press of the
+ <guibutton>Pause</guibutton> button.
+ as for <command>Begin</command> the state
+ should be checked to ensure it is
+ <literal>Active</literal> before invoking this.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>Resume</command></term>
+ <listitem>
+ <para>
+ Simulates a click of the
+ <guibutton>Resume</guibutton> button.
+ Call <command>getState</command> to ensure
+ the state is <literal>Paused</literal>
+ before invoking this.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>End</command></term>
+ <listitem>
+ <para>
+ Simulates a click of the
+ <guibutton>End</guibutton> button. As before,
+ ensure this is legal by comparing the return value of
+ <command>getState</command> to either
+ <literal>Paused</literal> or
+ <literal>Active</literal>> (paused runs can
+ be ended without resumption.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect3>
+ <refsect3>
+ <title>Programmatic interface</title>
+ <subtitle>Controllling the GUI</subtitle>
+ <para>
+ The <literal>ReadougGUIPanel</literal> package
+ provides access to the graphical user interfaces
+ that make up the readout gui. YOu can use this to
+ modify the state of existing widgets as well as to
+ add new widges of your own to the GUI.
+ </para>
+ <para>
+ All functions in this section are in the
+ namespace <literal>ReadougGUIPanel</literal>.
+ To avoid needing to qualify each reference you can:
+ <command>namespace import ::ReadougGUIPanel::*</command>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><command>addUserMenu</command> <replaceable>ident label</replaceable></term>
+ <listitem>
+ <para>
+ Allows you to add a user menu to the menubar
+ of the GUI. The
+ <replaceable>ident</replaceable> parameter is used as
+ the last element of the menu widget path.
+ <replaceable>label</replaceable> is the
+ text string that will label the element.
+ </para>
+ <para>
+ The actual full widget path of the menu
+ created is returned. You can use this path
+ to modify the menu configuration or to add
+ elements to the menu.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>addUserFrame</command> <replaceable>ident</replaceable></term>
+ <listitem>
+ <para>
+ Adds a frame to the bottom of the panel
+ (you can add as many user frames as you want).
+ By frame we mean a Tk frame widget.
+ <replaceable>ident</replaceable>
+ is the last element of the frame's widget
+ path. The full path will be returned.
+ </para>
+ <para>
+ At this time, the frame will span the width
+ of the Readout GUI toplevel widget. Once
+ you have created this frame you can stock
+ it with whatever widgets you want. The
+ example below is a bit silly.
+ </para>
+ <informalexample>
+ <programlisting>
+
+set frame [ReadougGUIPanel::addUserFrame myframe]
+button $frame.beep -text Beep -command {puts beep}
+button $frame.bop -text Bop -command {puts bop}
+button $frame.beebop -text BeeBop -command {puts "Now that's rockin'"}
+grid $frame.beep $frame.bop
+grid $frame.beebop
+ </programlisting>
+ </informalexample>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>getHost</command></term>
+ <listitem>
+ <para>
+ Returns the host in which the readout program will be, or is running
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>getPath</command></term>
+ <listitem>
+ <para>
+ Returns the path to the readout program that
+ will be, or is running in the target host.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>setTitle</command> <replaceable>newTitle</replaceable></term>
+ <listitem>
+ <para>
+ Sets the title string in the ReadoutGUI widget to
+ <replaceable>newTitle</replaceable>.
+ If a run is started via the GUI,
+ <replaceable>newTitle</replaceable>
+ will be the title of that run.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>getTitle</command></term>
+ <listitem>
+ <para>
+ Returns the contents of the title widget in
+ the GUI. Unless manually, or programmatically
+ modified, this is the title of the next or
+ current run.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>getRunNumber</command></term>
+ <listitem>
+ <para>
+ Returns the contents of the run number widget.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>setRun</command> <replaceable>newRunNumber</replaceable></term>
+ <listitem>
+ <para>
+ Sets the run number widget contents to
+ <replaceable>newRunNumber</replaceable>
+ this will be the run number for the next run.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>incrRun</command></term>
+ <listitem>
+ <para>
+ Increments the run number (adds one to it).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>setHost</command> <replaceable>hostname</replaceable></term>
+ <listitem>
+ <para>
+ Sets the target host for the readout program to
+ <replaceable>hostname</replaceable>.
+ The next time the readout program is started,
+ it will be run in
+ <replaceable>hostname</replaceable>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>setPath</command> <replaceable>path</replaceable></term>
+ <listitem>
+ <para>
+ Sets a new readout program to
+ <replaceable>path</replaceable>.
+ ...
[truncated message content] |