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

Last change on this file since 901 was 901, checked in by garnier, 17 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.