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] |