source: trunk/Documentation/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/ch02s08.html @ 902

Last change on this file since 902 was 901, checked in by garnier, 16 years ago

Add Geant4 Documentation at 8.12.2008
File size: 18.3 KB
Line 
1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.8.  How to Set Up an Interactive Session</title><link rel="stylesheet" href="../xml/XSLCustomizationLayer/G4HTMLStylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.71.1"><link rel="start" href="index.html" title="Geant4 User's Guide for Application Developers"><link rel="up" href="ch02.html" title="Chapter 2.  Getting Started with Geant4 - Running a Simple Example"><link rel="prev" href="ch02s07.html" title="2.7.  How to Make an Executable Program"><link rel="next" href="ch02s09.html" title="2.9.  How to Execute a Program"><script language="JavaScript">
2function remote_win(fName)
3{
4   var url = "AllResources/Detector/geometry.src/" + fName;
5   RemoteWin=window.open(url,"","resizable=no,toolbar=0,location=0,directories=0,status=0,menubar=0,scrollbars=0,copyhistory=0,width=520,height=520")
6   RemoteWin.creator=self
7}
8</script></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2.8. 
9How to Set Up an Interactive Session
10</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s07.html"><img src="AllResources/IconsGIF/prev.gif" alt="Prev"></a> </td><th width="60%" align="center">Chapter 2. 
11Getting Started with Geant4 - Running a Simple Example
12</th><td width="20%" align="right"> <a accesskey="n" href="ch02s09.html"><img src="AllResources/IconsGIF/next.gif" alt="Next"></a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sect.HowToSetUpInter"></a>2.8. 
13How to Set Up an Interactive Session
14</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.HowToSetUpInter.Intro"></a>2.8.1. 
15Introduction
16</h3></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect.HowToSetUpInter.Intro.RolesIntercoms"></a>2.8.1.1. 
17Roles of the "intercoms" category
18</h4></div></div></div><p>
19The "intercoms" category
20provides an expandable command interpreter. It is the key mechanism
21of Geant4 to realize user interactions of all categories without
22being annoyed by the dependencies among categories. The direct use
23of Geant4 classes in a C++ program offers a first ground level of
24interactivity, i.e., the batch session. As seen in the
25examples/novice/N01, Geant4 commands and macros are to be
26hard-coded in the program.
27</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect.HowToSetUpInter.Intro.UserInterfaces"></a>2.8.1.2. 
28User Interfaces to steer the simulation
29</h4></div></div></div><p>
30To avoid too much programming, the
31"intercoms" category provides the abstract class <span class="emphasis"><em>G4UIsession</em></span>
32that captures interactive commands . The concrete implementation of
33the user interface and Graphical User Interfaces (GUI) is left to
34the interfaces category. This interfacing strategy opens an
35important door towards various user interface tools and allows
36Geant4 to utilize the state-of-the-art GUI tools such as Motif and
37Java, etc..The richness of the collaboration has permitted for
38different groups to offer various user interfaces to the Geant4
39command system. Currently available are the following;
40
41</p><div class="orderedlist"><ol type="1" compact><li><p>
42  Character terminal (dumb terminal and tcsh(bash)-like terminal),
43  the default user interface of Geant4,
44  </p></li><li><p>
45  Xm, Xaw, Win32, variations of the upper terminal by using a
46  Motif, Athena or Windows widget to retrieve commands, and
47  </p></li><li><p>
48  GAG, a fully Graphical User Interface and its extension
49  GainServer of the client/server type.
50  </p></li></ol></div><p>
51</p><p>
52Full implementation of the character
53terminals (1 and 2) is included in the standard Geant4 distribution
54in the <code class="literal">source/interfaces/basic</code> directory. As for GAG
55with rich GUI functionalities, its front-end classes are included
56in the Geant4 distribution in the source/interfaces/GAG directory.
57The corresponding GUI package is available either from the author's
58Web pages (see URL below) or in the distributed package under the
59<code class="literal">environments/MOMO</code> directory.
60</p><p>
61GAG, GainServer's client GUI Gain:
62<a href="http://erpc1.naruto-u.ac.jp/~geant4" target="_top">
63http://erpc1.naruto-u.ac.jp/~geant4
64</a>
65</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.HowToSetUpInter.DescInter"></a>2.8.2. 
66A Short Description of Available Interface Classes
67</h3></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect.HowToSetUpInter.DescInter.G4UI"></a>2.8.2.1. 
68<span class="emphasis"><em>G4UIterminal</em></span> and <span class="emphasis"><em>G4UItcsh</em></span> classes
69</h4></div></div></div><p>
70These interfaces open a session on the character terminal.
71<span class="emphasis"><em>G4UIterminal</em></span> runs on all platform supported by Geant4,
72including <span class="emphasis"><em>cygwin</em></span> on Windows,
73while <span class="emphasis"><em>G4UItcsh</em></span> runs on Solaris and Linux. G4UItcsh
74supports user-friendly key bindings a-la-tcsh (or bash);
75
76</p><div class="variablelist"><dl><dt><span class="term">^A</span></dt><dd>
77    move cursor to the top
78    </dd><dt><span class="term">^B</span></dt><dd>
79    backward cursor ([LEFT] cursor)
80    </dd><dt><span class="term">^C (except Windows terminal)</span></dt><dd>
81    abort a run (<span class="emphasis"><em>soft abort</em></span>) during event processing.
82    A program will be terminated while accepting a user command.
83    </dd><dt><span class="term">^D</span></dt><dd>
84    delete/exit/show matched list
85    </dd><dt><span class="term">^E</span></dt><dd>
86    move cursor to the end
87    </dd><dt><span class="term">^F</span></dt><dd>
88    forward cursor ([RIGHT] cursor)
89    </dd><dt><span class="term">^K</span></dt><dd>
90    clear after the cursor
91    </dd><dt><span class="term">^N</span></dt><dd>
92    next command ([DOWN] cursor)
93    </dd><dt><span class="term">^P</span></dt><dd>
94    previous command ([UP] cursor)
95    </dd><dt><span class="term">TAB</span></dt><dd>
96    command completion
97    </dd><dt><span class="term">DEL</span></dt><dd>
98    backspace
99    </dd><dt><span class="term">BS</span></dt><dd>
100    backspace
101    </dd></dl></div><p>
102</p><p>
103In addition, the following string substitutions are supported;
104
105</p><div class="variablelist"><dl><dt><span class="term">%s</span></dt><dd>
106    current application status
107    </dd><dt><span class="term">%/</span></dt><dd>
108    current working directory
109    </dd><dt><span class="term">%h</span></dt><dd>
110    history number
111    </dd></dl></div><p>
112</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect.HowToSetUpInter.DescInter.G4UIXm"></a>2.8.2.2. 
113<span class="emphasis"><em>G4UIXm</em></span>, <span class="emphasis"><em>G4UIXaw</em></span> and
114<span class="emphasis"><em>G4UIWin32</em></span> classes
115</h4></div></div></div><p>
116These interfaces are versions of <span class="emphasis"><em>G4UIterminal</em></span> 
117implemented over libraries Motif, Athena and WIN32 respectively.
118<span class="emphasis"><em>G4UIXm</em></span> uses the Motif XmCommand widget,
119<span class="emphasis"><em>G4UIXaw</em></span> the Athena dialog
120widget, and <span class="emphasis"><em>G4UIWin32</em></span> the Windows "edit" component to do the
121command capturing. These interfaces are useful if working in
122conjunction with visualization drivers that use the Xt library or
123the WIN32 one.
124</p><p>
125A command box is at disposal for entering or recalling Geant4 commands.
126Command completion by typing &amp;ldquo;TAB&amp;rdquo; key is
127available on the command line. The shellcommands "exit, cont,
128help, ls, cd..." are also supported. A menu bar could be customized
129through the <span class="emphasis"><em>AddMenu</em></span> and
130<span class="emphasis"><em>AddButton</em></span> method. Ex:
131
132</p><div class="variablelist"><dl><dt><span class="term">/gui/addMenu</span></dt><dd>
133    test Test
134    </dd><dt><span class="term">/gui/addButton</span></dt><dd>
135    test Init /run/initialize
136    </dd><dt><span class="term">/gui/addButton</span></dt><dd>
137    test "Set gun" "/control/execute gun.g4m"
138    </dd><dt><span class="term">/gui/addButton</span></dt><dd>
139    test "Run one event" "/run/beamOn 1"
140    </dd></dl></div><p>
141</p><p>
142<span class="emphasis"><em>G4UIXm</em></span> runs on Unix/Linux with Motif. <span class="emphasis"><em>G4UIXaw</em></span>,
143less user friendly, runs on Unix with Athena widgets.
144<span class="emphasis"><em>G4UIWin32</em></span> runs on Windows.
145</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sect.HowToSetUpInter.DescInter.G4UIGAG"></a>2.8.2.3. 
146<span class="emphasis"><em>G4UIGAG</em></span> and <span class="emphasis"><em>G4UIGainServer</em></span> classes
147</h4></div></div></div><p>
148They are the front-end classes of Geant4 which interface with their
149respective graphical user interfaces, GAG (Geant4 Adaptive GUI) and Gain
150(Geant4 adaptive interface for network). While GAG must run on the same
151system (Windows or Unixen) as a Geant4 application, Gain can run on a
152remote system (Windows, Linux, etc.) to which JVM (Java Virtual
153Machine) is installed. A Geant4 application is invoked on a Unix
154(Linux) system and behaves as a network server. It opens a port,
155waiting the connection from the Gain. Gain is capable to connect to
156multiple Geant4 "servers" on Unixen systems at different
157institutes.
158</p><p>
159Client GUI, GAG and Gain have almost similar look-and-feel. So,
160GAG's functionalities are briefly introduced here. Please refer to
161the above URL for details and to download the client GUIs.
162</p><p>
163GAG is a Graphical User Interface tool with which user
164can set parameters and execute commands. It is adaptive, since GAG
165reflects the internal states of Geant4 that is a state machine. GAG
166is based on the server-client model; GAG is the server, while
167Geant4 executables are clients. Hence, GAG does nothing by itself
168and it must invoke an executable simulation program. Geant4's
169front-end class <span class="emphasis"><em>G4UIGAG</em></span> must be instantiated to
170communicate with GAG. This runs on Linux and Windows 2000.
171GAG is written in Java and
172its Jar (Java Archive) file is available from the above URL. See
173the same pages to know how to install and run Java programs.
174</p><p>
175GAG has following functions.
176
177</p><div class="variablelist"><dl><dt><span class="term">GAG Menu:</span></dt><dd>
178    The menus are to choose and run a GEANT4 executable file, to kill or exit
179    a GEANT4 process and to exit GAG. Upon the normal exit or an
180    unexpected death of the Geant4 process, GAG window are
181    automatically reset to accept another GEANT4 executable.   
182    </dd><dt><span class="term">GEANT4 Command tree:</span></dt><dd>
183    Upon the establishment of the pipe with the GEANT4 process, GAG displays
184    the command menu tree whose look and feel is quite similar to
185    Windows' file browser. Disabled commands are shown opaque. GAG
186    doesn &amp;rsquo;t display commands that are just below the root of
187    the command hierarchy. Direct type-in field is available for such
188    input. Guidance of command categories and commands are displayed
189    upon focusing. GAG has a command history function. User can
190    re-execute a command with old parameters, edit the history, or save
191    the history to create a macro file.
192    </dd><dt><span class="term">Command Parameter panel:</span></dt><dd>
193    GAG's parameter panel is the user-friendliest part. It displays parameter
194    name, its guidance, its type(s) (integer, double, Boolean or string),
195    omittable, default value(s), expression(s) of its range and candidate list(s)
196    (for example, of units). Range check is done by intercoms and
197    the error message from it is shown in the pop-up dialog box. When a
198    parameter component has a candidate list, a list box is
199    automatically displayed . When a file is requested by a command,
200    the file chooser is available.
201    </dd><dt><span class="term">Logging:</span></dt><dd>
202    Log can be redirected to the terminal (xterm or cygwin
203    window) from which GAG is invoked. It can be interrupted as will,
204    in the middle of long session of execution. Log can be saved to a
205    file independent of the above redirection . GAG displays warning or
206    error messages from GEANT4 in a pop-up warning widget.
207    </dd></dl></div><p>
208</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.HowToSetUpInter.BuildLib"></a>2.8.3. 
209Building the Interface Libraries
210</h3></div></div></div><p>
211The libraries that don't depend on external packages are made by default.
212They include <span class="emphasis"><em>G4UIterminal</em></span>, <span class="emphasis"><em>G4UItcsh</em></span>
213and <span class="emphasis"><em>G4UIGAG</em></span> in libraries <span class="emphasis"><em>libG4UIbasic.a/so</em></span> and
214<span class="emphasis"><em>libG4UIGAG.a/so</em></span>. <span class="emphasis"><em>G4UIGainServer.o</em></span> is packed in
215the <span class="emphasis"><em>libG4UIGAG</em></span>.
216</p><p>
217To make the libraries of <span class="emphasis"><em>G4UIXm</em></span>, <span class="emphasis"><em>G4UIXaw</em></span> and
218<span class="emphasis"><em>G4UIWin32</em></span> , respective environment variables
219<span class="bold"><strong>G4UI_BUILD_XM_SESSION</strong></span>,
220<span class="bold"><strong>G4UI_BUILD_XAW_SESSION</strong></span> or
221<span class="bold"><strong>G4UI_BUILD_WIN32_SESSION</strong></span> must be set
222explicitly.
223</p><p>
224However, if the environment variable <span class="bold"><strong>G4UI_NONE</strong></span> is
225set, no interface libraries are built at all.
226</p><p>
227Build scheme of the user interface libraries is
228specified in "$G4INSTALL/config/G4UI_BUILD.gmk" makefile and the
229dependencies on the external packages are specified in
230"$G4INSTALL/config/interactivity.gmk".
231</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.HowToSetUpInter.HowToUseInter"></a>2.8.4. 
232How to Use the Interface
233</h3></div></div></div><p>
234To use a given interface
235(<code class="literal">G4UIxxx</code> where <code class="literal">xxx = terminal,Xm, Xaw, Win32,
236GAG, GainServer</code>) in a user's program, he has the following
237lines in his main program;
238
239</p><div class="informalexample"><pre class="programlisting">
240// to include the class definition in his main program:
241   #include "G4Uixxx.hh"
242// to instantiate a session of his choice and start the session
243   G4UIsession* session = new G4UIxxx;
244   session-&gt;SessionStart();
245// the line next to the "SessionStart" is usually to finish the session
246   delete session;
247</pre></div><p>
248</p><p>
249For a tcsh session, the second line must be :
250
251</p><div class="informalexample"><pre class="programlisting">
252   G4UIsession* session = new G4UIterminal(new G4UItcsh);
253</pre></div><p>
254</p><p>
255See the examples in "examples/novice/N0x" in which the terminal session
256is used.
257</p><p>
258If the user wants to deactivate the default signal handler (soft abort)
259raised by "Ctr-C", the false flag can be set in the second argument
260of the <span class="emphasis"><em>G4UIterminal</em></span> constructor like;
261
262</p><div class="informalexample"><pre class="programlisting">
263   G4UIsession* session = new G4UIterminal(new G4UItcsh, false).
264</pre></div><p>
265</p><p>
266Again, environment variable selects a given interface. But for your
267convenience, some of them are set defaults.
268
269</p><div class="itemizedlist"><ul type="disc" compact><li><p>
270   <span class="emphasis"><em>G4UIterminal</em></span>, <span class="emphasis"><em>G4UItcsh</em></span>,
271   <span class="emphasis"><em>G4UIGAG</em></span> and <span class="emphasis"><em>G4UIGainServer</em></span> 
272   can be used without any environment
273   variables. Sessions not needing external packages or libraries are
274   always built (see "G4UI_BUILD.gmk") and linked, so the user can
275   instantiate one of these sessions without rebuilding the libraries
276   and without setting any environment variables. For backwards
277   compatibility with user code, as typified by geant4/examples main
278   programs, the C-pre-processor variables corresponding to the
279   original environment variables for the above three (i.e.,
280   <span class="bold"><strong>G4UI_USE_TERMINAL</strong></span>,
281   <span class="bold"><strong>G4UI_USE_TCSH</strong></span> and
282   <span class="bold"><strong>G4UI_USE_GAG</strong></span> ) are set. However,
283   if he/she sets no environment variables, then the C-pre-processor variable
284   <span class="bold"><strong>G4UI_USE_TERMINAL</strong></span> is set by default,
285   although there is no need to use it.
286   </p></li><li><p>
287   The environment variable <span class="bold"><strong>G4UI_USE_XM</strong></span>,
288   <span class="bold"><strong>G4UI_USE_XAW</strong></span> or
289   <span class="bold"><strong>G4UI_USE_WIN32</strong></span> must be set to use the
290   respective interface. The file "$G4INSTALL/config/interactivity.gmk"
291   resolves their dependencies on external packages.
292   </p></li><li><p>
293   If the environment variable <span class="bold"><strong>G4UI_NONE</strong></span> is
294   set, no externa ibraries are selected. Also, for your convenience, if any
295   <span class="bold"><strong>G4UI_USE_XXX</strong></span> environment variable is set,
296   then the corresponding C-pre-processor flag is also set. However, if the
297   environment variable <span class="bold"><strong>G4UI_NONE</strong></span> is set,
298   no C-pre-processor flags are set.
299   </p></li></ul></div><p>
300</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s07.html"><img src="AllResources/IconsGIF/prev.gif" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html"><img src="AllResources/IconsGIF/up.gif" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ch02s09.html"><img src="AllResources/IconsGIF/next.gif" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">2.7. 
301How to Make an Executable Program
302 </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="AllResources/IconsGIF/home.gif" alt="Home"></a></td><td width="40%" align="right" valign="top"> 2.9. 
303How to Execute a Program
304</td></tr></table></div></body></html>
Note: See TracBrowser for help on using the repository browser.