2.8 How to specify a user interface

Geant4 User's Guide
For Application Developers
Getting Started with Geant4

2.8 How to Set Up an Interactive Session

2.8.1 Introduction

Roles of the "intercoms" category

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.

User Interfaces to steer the simulation

To avoid too much programming, the "intercoms" category provides the abstract class G4UIsession 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;

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

Full implementation of the character terminals (1 and 2) is included in the standard Geant4 distribution in the source/interfaces/basic 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 environments/MOMO directory.


`GAG, GainServer's client GUI Gain`	http://erpc1.naruto-u.ac.jp/~geant4

2.8.2 A Short Description of Available Interface Classes

1. G4UIterminal and G4UItcsh classes

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

^A move cursor to the top

^B backward cursor ([LEFT] cursor)

^D delete/exit/show matched list

^E move cursor to the end

^F forward cursor ([RIGHT] cursor)

^K clear after the cursor

^N next command ([DOWN] cursor)

^P previous command ([UP] cursor)

TAB command completion

DEL backspace

BS backspace

In addition, the following string substitutions are supported;

%s current application status

%/ current working directory

%h history number

**2. G4UIXm, G4UIXaw, G4UIQt and G4UIWin32 classes**

These interfaces are versions of G4UIterminal implemented over libraries Motif, Athena and WIN32 respectively. G4UIXm uses the Motif XmCommand widget, G4UIXaw the Athena dialog widget, G4UIQt the Qt toolkit and G4UIWin32 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.

A command box is at disposal for entering or recalling Geant4 commands. Command completion by typing “TAB” 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 AddMenu and AddButton method.

Ex:

/gui/addMenu test Test

/gui/addButton test Init /run/initialize

/gui/addButton test "Set gun" "/control/execute gun.g4m"

/gui/addButton test "Run one event" "/run/beamOn 1"

G4UIXm runs on Unix/Linux with Motif. G4UIXaw, less user friendly, runs on Unix with Athena widgets. G4UIQt run everywhere and G4UIWin32 runs on Windows.

**3. G4UIGAG and G4UIGainServer classes**

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.

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.

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 G4UIGAG 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.

GAG has following functions.

GAG Menu: 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.
GEANT4 Command tree: 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’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.
Command Parameter panel: 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.
Logging: 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.

2.8.3 Building the Interface Libraries

The libraries that don't depend on external packages are made by default. They include G4UIterminal, G4UItcsh and G4UIGAG in libraries libG4UIbasic.a/so and libG4UIGAG.a/so. G4UIGainServer.o is packed in the libG4UIGAG.
To make the libraries of G4UIXm, G4UIXaw, G4UIQt and G4UIWin32 , respective environment variables G4UI_BUILD_XM_SESSION , G4UI_BUILD_XAW_SESSION, G4UI_BUILD_QT_SESSION or G4UI_BUILD_WIN32_SESSION must be set explicitly.

However, if the environment variable G4UI_NONE is set, no interface libraries are built at all.

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".

2.8.4 How to Use the Interface

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

// 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->SessionStart();
/ /the line next to the "SessionStart" is usually to finish the session
delete session;

For a tcsh session, the second line must be :

G4UIsession* session = new G4UIterminal(new G4UItcsh);

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

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

G4UIterminal, G4UItcsh, G4UIGAG and G4UIGainServer 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., G4UI_USE_TERMINAL, G4UI_USE_TCSH and G4UI_USE_GAG ) are set. However, if he/she sets no environment variables, then the C-pre-processor variable G4UI_USE_TERMINAL is set by default, although there is no need to use it.
The environment variable G4UI_USE_XM, G4UI_USE_XAW, G4UI_USE_QT or G4UI_USE_WIN32 must be set to use the respective interface. The file "$G4INSTALL/config/interactivity.gmk" resolves their dependencies on external packages.
If the environment variable G4UI_NONE is set, no externa ibraries are selected. Also, for your convenience, if any G4UI_USE_XXX environment variable is set, then the corresponding C-pre-processor flag is also set. However, if the environment variable G4UI_NONE is set, no C-pre-processor flags are set.

About the authors