[user/user-gui.tex]
\label{user-gui-chapter}
\section{GUI Guide lines}
The current \dabc\ GUI is written in Java using the DIM software as communication layer.
The standard part of the GUI described here may be extended by application specific parts.
How to add such extensions is described in the programmer's manual.
Typically they are started as prompter panels via buttons in the
main GUI menu. 

The standard part builds a set of panels (windows) according the parameters
the DIM servers offer. Only services from one single DIM name server
(node name specified as shell variable \keyw{DIM\_DNS\_NODE})
defining a name space can be processed.
See \paref{user:MbsDimconfig} for preparations.

The GUI needs no file access to the \dabc\ working directory.
However, user must have \keyw{ssh} (or \keyw{rsh}) access to
the \dabc\ (or \mbs) master node.
Currently the GUI must run under the same account as the \dabc.
In monitoring mode (no commands) the GUI may run under different account.
Master node must have remote access to all worker nodes.
The user's \keyw{ssh} settings must enable remote access without
prompts.

The layout of the GUI can be adjusted to individual needs.
It is strongly recommended to save these settings to see the same layout
after a restart of the GUI. The GUI can be restarted any time.
\dabc\ and \mbs\ systems continue without GUI.

\section{GUI Panels}
\figpng{user-gui-main-buttons}{Main toolbar buttons.}{htb}{0}{0.8}
Fig. \paref{fig:user-gui-main-buttons} shows the main menu of \dabc\ (minimal view).
The GUI as it comes up is divided in three major parts: 
one sees on top a toolbar with icon buttons. Most of these open
other windows. The dark line at the bottom shows a list of active DIM servers.
The other windows are placed in the white middle pane. The functions of the buttons and the
invoked panels is described in the next sections.
Depending on the application some buttons may be not seen, additional ones may show up.
If one does not work with \mbs\ plug-ins the control panels for \mbs\
are of cause not useful.\\
\figpng{user-gui-full-screen}{More typical full screen view.}{htb}{0}{1.0}
Fig. \paref{fig:user-gui-full-screen} shows a more typical view of a running \dabc.
In general, all panels (including the GUI itself) can be closed and reopened any time.

\lsubsection[Main DABC GUI buttons]{user:dabcButtons}{Main \dabc\ GUI buttons}
\icon{fileclose} Quit GUI. Will prompt (\keyw{RET} will quit). The \dabc\ will continue to run.
The GUI may be started anywhere again. In case you saved the layout (recommended, see \paref{user:guiSaveRestore})
and you start the GUI from the same directory it will look pretty much the same as you left it. \\
\icon{control} Test, shell script\\
\icon{savewin} Save settings: window layout, record attributes, 
command arguments, parameter selection filters.
Details see \paref{user:guiSaveRestore}. Note that the content of the control panels
must be saved by similar buttons in these panels.\\
\icon{dabcmbsicon} Open \dabc\ \mbs\ control panel, see \paref{user:controlDabcMbs}.\\
\icon{dabcicon} Open \dabc\ control panel, see \paref{user:controlDabc}.\\
\icon{mbsicon} Open \mbs\ control panel, see \paref{user:controlMbs}.\\
\icon{browser} Refresh. All parameters and commands are removed. 
Rebuild DIM service list from DIM name server.
Parameters and Commands are sorted alphabetically by name.
All panels are updated.
In normal operation there is no need to refresh manually.\\
\icon{comicon} Open command panel (\paref{user:CommandPanel}).\\
\icon{paramwin} Open parameter table (\paref{user:ParTabPanel}).\\
\icon{usericon} Open parameter selection panel (\paref{user:ParSelPanel}).\\
\icon{meterwin} Open rate meter panel (\paref{user:MonitorPanels}).\\
\icon{histowin} Open histogram panel (\paref{user:MonitorPanels}).\\
\icon{statewin} Open state panel (\paref{user:MonitorPanels}).\\
\icon{infowin} Open info panel (\paref{user:MonitorPanels}).\\
\icon{logwin} Open log panel (\paref{user:MonitorPanels}).\\
\icon{usericongreen} Eventually one might see additional icons from application panels
(this one is only an example).\\\\
The three control panels (\dabc, \mbs, combined \dabc\ and \mbs) 
are used depending on the
application to be controlled. Eventually an application provides 
additional specific control panels.

\lsubsection[DABC control panel]{user:controlDabc}{\dabc~ control panel}
The standard \dabc\ control panel is shown in \paref{fig:user-gui-pan-dabc}.
As mentioned already some applications may provide their own control panels
like the \mbs\ applications (see section \paref{user:controlMbs}).
But most of the buttons are very common.
From left to right they startup a system, configure it, start
data taking, pause data taking, stop tasks, shut down.
At the very left we see a save button, at the right a shell execution button.
\figpng{user-gui-pan-dabc}{DABC controller panel.}{htb}{0}{0.6}
Values are read from file {\tt DabcControl.xml} (default, may be saved/restored to/from other file,
see \paref{user:guiSaveRestore}).
{\small \begin{verbatim}
<?xml version="1.0" encoding="utf-8"?>
<DabcLaunch>
<DabcMaster prompt="DABC Master" value="node.xxx.de" />
<DabcName prompt="DABC Name" value="Controller:41" />
<DabcUserPath prompt="DABC user path" value="myWorkDir" />
<DabcSystemPath prompt="DABC system path" value="/dabc" />
<DabcSetup prompt="DABC setup file" value="SetupDabc.xml" />
<DabcScript prompt="DABC Script" value="ps" />
<DabcServers prompt="%Number of needed DIM servers%" value="5" />
</DabcLaunch>
\end{verbatim}
}
\bdes
\item[DabcMaster:] Node where the master controller shall be started.
Can be one of the worker nodes.
\item[DabcName:] A unique name inside \dabc\ of the system.
\item[DabcUserPath:] User working directory. The GUI does not need to have
access to the filesystem. 
\item[DabcSystemPath:] Path where the \dabc\ is installed.
\item[DabcSetup:] Setup file name.
\item[DabcScript:] Command to be executed in an ssh at the master node.
\item[DabcServers:] Number of workers and controllers. This information
is minimum for the GUI to know when all \dabc\ nodes are up. The GUI waits until
this number of DIM servers is up and running. \strong{Note} that this number 
must be consistent with the \dabc\ setup file used.
\edes
The name server name is translated from shell environment variable \keyw{DIM\_DNS\_NODE},
the user name from shell environment variable \keyw{USER}. Password can be chosen when
the first remote shell script is executed (which itself is protected by
user password). All following commands then need this password.

\subsubsection[DABC controller buttons]{\dabc\ controller buttons}
\icon{savewin} Save panel settings to the file \keyw{Control file}.
If you choose a name different from the default you must
set a shell variable to it to get the values from that file
(see \paref{user:guiSaveRestore}).\\
\icon{connprm} Startup all tasks. Executes a \dabc\ script \verba{dabcstartup.sc} via \verba{ssh} 
on the master node under user name. Then it waits until the number of DIM servers
expected are announced. A progress panel pops up during that time
(see \paref{user:guiProgress}).
When the servers are up the main GUI \keyw{Update} is triggered building
all panels from scratch according the parameters offered by the servers.\\
\icon{dabcconfig} Configure. Executes state transition command \comm{Configure}
on master node and waits for the transition.
All plug-in components are created. Then execute \keyw{Enable}.
Waits until all workers go into \keyw{Ready} state. Now the \dabc\ is ready to run.
Triggers the main GUI \keyw{Update}.\\
\icon{dabcstart} Start acquisition. Executes \comm{Start} command.
All components go into running state \keyw{Running}.\\
\icon{dabcstop} Pause acquisition. Executes \comm{Stop} command.
All components go into standby state \keyw{Ready}.\\
\icon{mbsstop} Halt acquisition. Executes \comm{Halt} command.
This closes all plug-ins. States go into \keyw{Halted}. Next must be
shut down or configure.\\
\icon{disconn} Exit all processes by \comm{EXIT} commands. After 2 seconds 
trigger the main GUI \keyw{Update}.\\
\icon{exitall} Shut down all processes on all nodes by script. This is the hard shut down.\\
\icon{controldabc} \verba{ssh} shell script execution on master node.\\

\lsubsection{user:guiProgress}{Action in progress}
\figpng{user-gui-pan-progress}{Launching progress.}{htb}{0}{0.6}
When starting up, configure or shut down the GUI has to wait
until the front-ends have completed the action.
During that time a progress window similar to the one shown
in Fig. \paref{fig:user-gui-pan-progress} pops up.
Please wait until the popup disappears.

\subsection[MBS control panel]{\mbs\ control panel}
To control and monitor a stand-alone \mbs\ system a dedicated control
panel is provided by the \mbs\ application.
This panel is described in the \mbs\ section \paref{user:controlMbs}.

\subsection[Combined DABC and MBS control panel]{Combined \dabc\ and \mbs\ control panel}
To control and monitor \mbs\ front-ends with \dabc\ event builders a dedicated control
panel is provided by the \mbs\ application.
This panel is described in the \mbs\ section \paref{user:controlDabcMbs}.

\lsubsection{user:CommandPanel}{Command panel}
The control system of \dabc\ and/or the application specific plug-ins
can define commands. These commands are encoded as DIM services
including a full description of arguments. Therefore the GUI
can build up at runtime a command tree and provide the proper forms for
each command. Commands are executed in all components of \dabc.

The \dabc\ naming convention for commands and parameters defines four main name fields
separated by slashes:
\bnum
\item DIM server name space (example: DABC)
\item Node (example: lxg0523)
\item Application (example: Controller:41)
\item Name (example: doEnable)
\enum 
Example: \comm{DABC/lxg0523/Controller:41/doEnable}.
\figpng{user-gui-pan-cmd-dabc}{Command panel.}{htb}{0}{0.9}
Fig. \paref{fig:user-gui-pan-cmd-dabc} shows
on the left side the command tree. The tree is built
from name, application, nodes. Double click (or \keyw{RETURN}) on a treenode
executes the command on all treenodes below.
A click on a command opens at the right side the argument panel.
Entering argument values and \keyw{RETURN} executes the command.
In the example shown in the figure double click on \comm{doEnable}
would execute that command on three nodes.
Double click on \comm{Eventbuilder} would execute only on two nodes. 

\lsubsection{user:ParTabPanel}{Parameter table}
\dabc\ parameters are DIM services as the commands. The naming convention is
the same. The server providing parameters can be make them (no)visible 
and (un)changable. \dabc\ defines some special parameter types
having a data structure and a specific interpretation like
a rate parameter having a value, limits, a color, and a graphic presentation.
A rate parameter is assumed to be changed and updated regularly.
The GUI displayes these special parameters in dedicated panels. 
Parameters are used in all components of \dabc.
\figpng{user-gui-pan-pardabc}{Parameter table.}{htb}{0}{0.9}
The central place for all parameters in the GUI is the
parameter table as shwon in Fig. \paref{fig:user-gui-pan-pardabc}.
The parameter table holds all parameters which are marked by the provider to be visible.
The parameter values can be changed
in the \keyw{Set value} column if no minus sign is there in which case the
provider does not grant modification.
The buttons in the \keyw{Show} column 
indicate if the parameter is shown in some graphics panel. It can be removed from or added
to this panel by the buttons.
The table can be ordered by columns (click on column header). 
The column width can be adjusted and is saved/restored by main save button
(see \paref{user:guiSaveRestore}).

\lsubsubsection{user:ParSelPanel}{Parameter selection}
\figpng{user-gui-pan-parsel}{Parameter selection panel and selected parameter list.}{htb}{0}{1.0}
To get a more selective view on the parameters one can specify
filters in the panel shown at the left side of Fig. \paref{fig:user-gui-pan-parsel}. 
Text substrings for each of the four name fields
can be specified as well as a selection of record types.
Values can be saved (see \paref{user:guiSaveRestore}).
With the check boxes the filter function for each of these can (de)activated.
The parameter list at the right window in Fig. \paref{fig:user-gui-pan-parsel}
shows only the parameters matching all filters.

If the data field is white the parameter can be changed.
This cannot be done in place because the parameter might be
updated in the mean time. Instead press \keyw{RETURN} in the field.
A prompter will pop up to enter the value.

\lsubsection{user:MonitorPanels}{Monitoring panels}
As already mentioned the \dabc\ provides definitions of
special purpose DIM parameters. These \func{Records}
can be recognized by the GUI and are handled in appropriate way.
Currently there are
\bcir
\item States
\item Rates
\item Histograms
\item Infos
\ecir

\subsubsection{States}
\figpng{user-gui-pan-statedabc}{States.}{htb}{0}{0.8}
States are records having a number for severity (0 to 4), a color,
and a brief state description (see Fig. \paref{fig:user-gui-pan-statedabc}).
Of cause the states of the \dabc\ state machine are shown as states.
Application plug-ins may use this kind of records also for other
information.

\subsubsection{Rate meters}
\figpng{user-gui-pan-rate}{Rates.}{htb}{0}{0.7}
All rate meters are displayed in the meter panel, Fig.\paref{fig:user-gui-pan-rate}. 
Meters can be removed
in the parameter table (See Fig. \paref{fig:user-gui-pan-pardabc}) 
with the \keyw{Show} buttons like the other graphical parameters.
Saving the setup, the visibility will be preserved.
\figpdf{user-gui-rate-set}{Steering menus.}{htb}{0}{0.8}

On the left side in Fig. \paref{fig:user-gui-rate-set} the \keyw{Settings}
menu is shown. It affects all items in the panel. One can \keyw{Zoom}
(toggle between large and normal view), change the number of
columns, change the display mode, toggle \keyw{Autoscale}, and set limits
(applied to all meters). 

Besides that each individual item can be
adjusted by right mouse button. The context menu is shown on the right.
All changes done individually are changing the defaults!
The global changes can be overwritten by these defaults.
All settings are saved with the setup and restored on GUI startup
(see \paref{user:guiSaveRestore}).

\subsubsection{Histograms}
Histogram panels are handled in pretty much the same way as the rate meters.
\figpng{user-gui-pan-histo}{Histograms.}{htb}{0}{1.0}
All histograms are displayed in the histogram panel, Fig.\paref{fig:user-gui-pan-histo}. 
Histograms can have arbitrary size set in \keyw{Layout} menu.

\subsubsection{Information}
\figpng{user-gui-pan-infodabc}{Info.}{htb}{0}{1.0}
Information records mainly display one line of text with a color
(see Fig. \paref{fig:user-gui-pan-infodabc}).

\subsubsection{Logging window}
\figpng{user-gui-pan-logdabc}{Logging.}{htb}{0}{1.0}
Fig. \paref{fig:user-gui-pan-logdabc} show the logging window.

\lsection{user:guiSaveRestore}{GUI save/restore setups}
There are several setups which can be stored in XML files and are retrieved
when the \gui\ is started again. The file names can be specified by
shell variables. 
\bdes
\item [\keyw{DABC\_CONTROL\_DABC}]: 
Values of \dabc\ control panel. Saved by button in panel. \\
Default \verba{DabcControl.xml}. Filename in panel itself.
\item [\keyw{DABC\_CONTROL\_MBS}]: 
Values of \mbs\ control panel. Saved by button in panel. \\
Default \verba{MbsControl.xml}. Filename in panel itself.
\item [\keyw{DABC\_RECORD\_ATTRIBUTES}]: 
Attributes of records. Saved by main save button. \\
Default \verba{Records.xml}.
\item [\keyw{DABC\_PARAMETER\_FILTER}]: 
Values of parameter filter panel. Saved by main save button. \\
Default \verba{Selection.xml}.
\item [\keyw{DABC\_GUI\_LAYOUT}]: 
Layout of frames. Saved by main save button. \\
Default \verba{Layout.xml}.
\edes
