source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/GettingStarted/graphicalUserInterface.xml @ 904

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.HowToSetUpInter">
<title>
How to Set Up an Interactive Session
</title>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToSetUpInter.Intro">
<title>
Introduction
</title>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToSetUpInter.Intro.RolesIntercoms">
<title>
Roles of the "intercoms" category
</title>

<para>
The "intercoms" category
provides an expandable command interpreter. It is the key mechanism
of Geant4 to realize user interactions of all categories without
being annoyed by the dependencies among categories. The direct use
of Geant4 classes in a C++ program offers a first ground level of
interactivity, i.e., the batch session. As seen in the
examples/novice/N01, Geant4 commands and macros are to be
hard-coded in the program.
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToSetUpInter.Intro.UserInterfaces">
<title>
User Interfaces to steer the simulation
</title>

<para>
To avoid too much programming, the
"intercoms" category provides the abstract class <emphasis>G4UIsession</emphasis>
that captures interactive commands . The concrete implementation of
the user interface and Graphical User Interfaces (GUI) is left to
the interfaces category. This interfacing strategy opens an
important door towards various user interface tools and allows
Geant4 to utilize the state-of-the-art GUI tools such as Motif and
Java, etc..The richness of the collaboration has permitted for
different groups to offer various user interfaces to the Geant4
command system. Currently available are the following;

<orderedlist spacing="compact">
  <listitem><para>
  Character terminal (dumb terminal and tcsh(bash)-like terminal), 
  the default user interface of Geant4,
  </para></listitem>
  <listitem><para>
  Xm, Xaw, Win32, variations of the upper terminal by using a
  Motif, Athena or Windows widget to retrieve commands, and
  </para></listitem>
  <listitem><para>
  GAG, a fully Graphical User Interface and its extension
  GainServer of the client/server type.
  </para></listitem>
</orderedlist>
</para>

<para>
Full implementation of the character
terminals (1 and 2) is included in the standard Geant4 distribution
in the <literal>source/interfaces/basic</literal> directory. As for GAG
with rich GUI functionalities, its front-end classes are included
in the Geant4 distribution in the source/interfaces/GAG directory.
The corresponding GUI package is available either from the author's
Web pages (see URL below) or in the distributed package under the
<literal>environments/MOMO</literal> directory.
</para>

<para>
GAG, GainServer's client GUI Gain: 
<ulink url="http://erpc1.naruto-u.ac.jp/~geant4">
http://erpc1.naruto-u.ac.jp/~geant4
</ulink>
</para>

</sect3>
</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToSetUpInter.DescInter">
<title>
A Short Description of Available Interface Classes
</title>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToSetUpInter.DescInter.G4UI">
<title>
<emphasis>G4UIterminal</emphasis> and <emphasis>G4UItcsh</emphasis> classes
</title>

<para>
These interfaces open a session on the character terminal. 
<emphasis>G4UIterminal</emphasis> runs on all platform supported by Geant4, 
including <emphasis>cygwin</emphasis> on Windows, 
while <emphasis>G4UItcsh</emphasis> runs on Solaris and Linux. G4UItcsh
supports user-friendly key bindings a-la-tcsh (or bash);

<variablelist>
  <varlistentry>
    <term>^A</term>
    <listitem>
    move cursor to the top
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>^B</term>
    <listitem>
    backward cursor ([LEFT] cursor)
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>^C (except Windows terminal)</term>
    <listitem>
    abort a run (<emphasis>soft abort</emphasis>) during event processing. 
    A program will be terminated while accepting a user command. 
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>^D</term>
    <listitem>
    delete/exit/show matched list
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>^E</term>
    <listitem>
    move cursor to the end
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>^F</term>
    <listitem>
    forward cursor ([RIGHT] cursor)
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>^K</term>
    <listitem>
    clear after the cursor
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>^N</term>
    <listitem>
    next command ([DOWN] cursor)
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>^P</term>
    <listitem>
    previous command ([UP] cursor)
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>TAB</term>
    <listitem>
    command completion
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>DEL</term>
    <listitem>
    backspace
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>BS</term>
    <listitem>
    backspace
    </listitem>
  </varlistentry>
</variablelist>
</para>

<para>
In addition, the following string substitutions are supported;

<variablelist>
  <varlistentry>
    <term>%s</term>
    <listitem>
    current application status
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>%/</term>
    <listitem>
    current working directory
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>%h</term>
    <listitem>
    history number
    </listitem>
  </varlistentry>
</variablelist>
</para>

</sect3>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToSetUpInter.DescInter.G4UIXm">
<title>
<emphasis>G4UIXm</emphasis>, <emphasis>G4UIXaw</emphasis> and 
<emphasis>G4UIWin32</emphasis> classes
</title>

<para>
These interfaces are versions of <emphasis>G4UIterminal</emphasis> 
implemented over libraries Motif, Athena and WIN32 respectively. 
<emphasis>G4UIXm</emphasis> uses the Motif XmCommand widget, 
<emphasis>G4UIXaw</emphasis> the Athena dialog
widget, and <emphasis>G4UIWin32</emphasis> the Windows "edit" component to do the
command capturing. These interfaces are useful if working in
conjunction with visualization drivers that use the Xt library or
the WIN32 one.
</para>

<para>
A command box is at disposal for entering or recalling Geant4 commands.
Command completion by typing &amp;ldquo;TAB&amp;rdquo; key is
available on the command line. The shellcommands "exit, cont,
help, ls, cd..." are also supported. A menu bar could be customized
through the <emphasis>AddMenu</emphasis> and 
<emphasis>AddButton</emphasis> method. Ex:

<variablelist>
  <varlistentry>
    <term>/gui/addMenu</term>
    <listitem>
    test Test
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>/gui/addButton</term>
    <listitem>
    test Init /run/initialize
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>/gui/addButton</term>
    <listitem>
    test "Set gun" "/control/execute gun.g4m"
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>/gui/addButton</term>
    <listitem>
    test "Run one event" "/run/beamOn 1"
    </listitem>
  </varlistentry>
</variablelist>
</para>

<para>
<emphasis>G4UIXm</emphasis> runs on Unix/Linux with Motif. <emphasis>G4UIXaw</emphasis>, 
less user friendly, runs on Unix with Athena widgets. 
<emphasis>G4UIWin32</emphasis> runs on Windows.
</para>

</sect3>


<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.HowToSetUpInter.DescInter.G4UIGAG">
<title>
<emphasis>G4UIGAG</emphasis> and <emphasis>G4UIGainServer</emphasis> classes
</title>

<para>
They are the front-end classes of Geant4 which interface with their
respective graphical user interfaces, GAG (Geant4 Adaptive GUI) and Gain
(Geant4 adaptive interface for network). While GAG must run on the same 
system (Windows or Unixen) as a Geant4 application, Gain can run on a
remote system (Windows, Linux, etc.) to which JVM (Java Virtual
Machine) is installed. A Geant4 application is invoked on a Unix
(Linux) system and behaves as a network server. It opens a port,
waiting the connection from the Gain. Gain is capable to connect to
multiple Geant4 "servers" on Unixen systems at different
institutes.
</para>

<para>
Client GUI, GAG and Gain have almost similar look-and-feel. So,
GAG's functionalities are briefly introduced here. Please refer to
the above URL for details and to download the client GUIs.
</para>

<para>
GAG is a Graphical User Interface tool with which user
can set parameters and execute commands. It is adaptive, since GAG
reflects the internal states of Geant4 that is a state machine. GAG
is based on the server-client model; GAG is the server, while
Geant4 executables are clients. Hence, GAG does nothing by itself
and it must invoke an executable simulation program. Geant4's
front-end class <emphasis>G4UIGAG</emphasis> must be instantiated to 
communicate with GAG. This runs on Linux and Windows 2000.
GAG is written in Java and
its Jar (Java Archive) file is available from the above URL. See
the same pages to know how to install and run Java programs.
</para>

<para>
GAG has following functions.

<variablelist>
  <varlistentry>
    <term>GAG Menu:</term>
    <listitem>
    The menus are to choose and run a GEANT4 executable file, to kill or exit
    a GEANT4 process and to exit GAG. Upon the normal exit or an
    unexpected death of the Geant4 process, GAG window are
    automatically reset to accept another GEANT4 executable.    
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>GEANT4 Command tree:</term>
    <listitem>
    Upon the establishment of the pipe with the GEANT4 process, GAG displays
    the command menu tree whose look and feel is quite similar to
    Windows' file browser. Disabled commands are shown opaque. GAG
    doesn &amp;rsquo;t display commands that are just below the root of
    the command hierarchy. Direct type-in field is available for such
    input. Guidance of command categories and commands are displayed
    upon focusing. GAG has a command history function. User can
    re-execute a command with old parameters, edit the history, or save
    the history to create a macro file.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Command Parameter panel:</term>
    <listitem>
    GAG's parameter panel is the user-friendliest part. It displays parameter 
    name, its guidance, its type(s) (integer, double, Boolean or string), 
    omittable, default value(s), expression(s) of its range and candidate list(s)
    (for example, of units). Range check is done by intercoms and
    the error message from it is shown in the pop-up dialog box. When a
    parameter component has a candidate list, a list box is
    automatically displayed . When a file is requested by a command,
    the file chooser is available.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Logging:</term>
    <listitem>
    Log can be redirected to the terminal (xterm or cygwin
    window) from which GAG is invoked. It can be interrupted as will,
    in the middle of long session of execution. Log can be saved to a
    file independent of the above redirection . GAG displays warning or
    error messages from GEANT4 in a pop-up warning widget.
    </listitem>
  </varlistentry>
</variablelist>
</para>

</sect3>
</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToSetUpInter.BuildLib">
<title>
Building the Interface Libraries
</title>

<para>
The libraries that don't depend on external packages are made by default. 
They include <emphasis>G4UIterminal</emphasis>, <emphasis>G4UItcsh</emphasis>
and <emphasis>G4UIGAG</emphasis> in libraries <emphasis>libG4UIbasic.a/so</emphasis> and
<emphasis>libG4UIGAG.a/so</emphasis>. <emphasis>G4UIGainServer.o</emphasis> is packed in
the <emphasis>libG4UIGAG</emphasis>.
</para>

<para>
To make the libraries of <emphasis>G4UIXm</emphasis>, <emphasis>G4UIXaw</emphasis> and
<emphasis>G4UIWin32</emphasis> , respective environment variables
<emphasis role="bold">G4UI_BUILD_XM_SESSION</emphasis>, 
<emphasis role="bold">G4UI_BUILD_XAW_SESSION</emphasis> or
<emphasis role="bold">G4UI_BUILD_WIN32_SESSION</emphasis> must be set
explicitly.
</para>

<para>
However, if the environment variable <emphasis role="bold">G4UI_NONE</emphasis> is
set, no interface libraries are built at all.
</para>

<para>
Build scheme of the user interface libraries is
specified in "$G4INSTALL/config/G4UI_BUILD.gmk" makefile and the
dependencies on the external packages are specified in
"$G4INSTALL/config/interactivity.gmk".
</para>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.HowToSetUpInter.HowToUseInter">
<title>
How to Use the Interface
</title>

<para>
To use a given interface
(<literal>G4UIxxx</literal> where <literal>xxx = terminal,Xm, Xaw, Win32,
GAG, GainServer</literal>) in a user's program, he has the following
lines in his main program;

<informalexample>
<programlisting>
// to include the class definition in his main program:
   #include "G4Uixxx.hh"
// to instantiate a session of his choice and start the session
   G4UIsession* session = new G4UIxxx;
   session-&gt;SessionStart();
// the line next to the "SessionStart" is usually to finish the session
   delete session;
</programlisting>
</informalexample>
</para>

<para>
For a tcsh session, the second line must be :

<informalexample>
<programlisting>
   G4UIsession* session = new G4UIterminal(new G4UItcsh);
</programlisting>
</informalexample>
</para>

<para>
See the examples in "examples/novice/N0x" in which the terminal session 
is used.
</para>

<para>
If the user wants to deactivate the default signal handler (soft abort)
raised by "Ctr-C", the false flag can be set in the second argument 
of the <emphasis>G4UIterminal</emphasis> constructor like;

<informalexample>
<programlisting>
   G4UIsession* session = new G4UIterminal(new G4UItcsh, false).
</programlisting>
</informalexample>
</para>

<para>
Again, environment variable selects a given interface. But for your
convenience, some of them are set defaults.

<itemizedlist spacing="compact">
   <listitem><para>
   <emphasis>G4UIterminal</emphasis>, <emphasis>G4UItcsh</emphasis>, 
   <emphasis>G4UIGAG</emphasis> and <emphasis>G4UIGainServer</emphasis> 
   can be used without any environment
   variables. Sessions not needing external packages or libraries are
   always built (see "G4UI_BUILD.gmk") and linked, so the user can
   instantiate one of these sessions without rebuilding the libraries
   and without setting any environment variables. For backwards
   compatibility with user code, as typified by geant4/examples main
   programs, the C-pre-processor variables corresponding to the
   original environment variables for the above three (i.e.,
   <emphasis role="bold">G4UI_USE_TERMINAL</emphasis>, 
   <emphasis role="bold">G4UI_USE_TCSH</emphasis> and
   <emphasis role="bold">G4UI_USE_GAG</emphasis> ) are set. However, 
   if he/she sets no environment variables, then the C-pre-processor variable
   <emphasis role="bold">G4UI_USE_TERMINAL</emphasis> is set by default, 
   although there is no need to use it.
   </para></listitem>
   <listitem><para>
   The environment variable <emphasis role="bold">G4UI_USE_XM</emphasis>, 
   <emphasis role="bold">G4UI_USE_XAW</emphasis> or
   <emphasis role="bold">G4UI_USE_WIN32</emphasis> must be set to use the 
   respective interface. The file "$G4INSTALL/config/interactivity.gmk"
   resolves their dependencies on external packages.
   </para></listitem>
   <listitem><para>
   If the environment variable <emphasis role="bold">G4UI_NONE</emphasis> is
   set, no externa ibraries are selected. Also, for your convenience, if any
   <emphasis role="bold">G4UI_USE_XXX</emphasis> environment variable is set, 
   then the corresponding C-pre-processor flag is also set. However, if the
   environment variable <emphasis role="bold">G4UI_NONE</emphasis> is set, 
   no C-pre-processor flags are set.
   </para></listitem>
</itemizedlist>
</para>

</sect2>
</sect1>