source: trunk/Documentation/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/ch07s02.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: 34.7 KB
Line 
1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>7.2.  User Interface - Defining New Commands</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="ch07.html" title="Chapter 7.  Communication and Control"><link rel="prev" href="ch07.html" title="Chapter 7.  Communication and Control"><link rel="next" href="ch08.html" title="Chapter 8.  Visualization"><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">7.2. 
9User Interface - Defining New Commands
10</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch07.html"><img src="AllResources/IconsGIF/prev.gif" alt="Prev"></a> </td><th width="60%" align="center">Chapter 7. 
11Communication and Control
12</th><td width="20%" align="right"> <a accesskey="n" href="ch08.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.UIDefNew"></a>7.2. 
13User Interface - Defining New Commands
14</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.UIDefNew.UIMess"></a>7.2.1. 
15G4UImessenger
16</h3></div></div></div><p>
17<span class="emphasis"><em>G4UImessenger</em></span> is a base class which represents a
18messenger that delivers command(s) to the destination class object. Your
19concrete messenger should have the following functionalities.
20
21</p><div class="itemizedlist"><ul type="disc" compact><li><p>
22 Construct your command(s) in the constructor of your messenger.
23 </p></li><li><p>
24 Destruct your command(s) in the destructor of your messenger.
25 </p></li></ul></div><p>
26</p><p>
27These requirements mean that your messenger should keep all
28pointers to your command objects as its data members.
29</p><p>
30You can use <span class="emphasis"><em>G4UIcommand</em></span> derived classes for the most
31frequent types of command. These derived classes have their own
32conversion methods according to their types, and they make
33implementation of the <code class="literal">SetNewValue()</code> and
34<code class="literal">GetCurrentValue()</code> methods of your messenger much easier
35and simpler.
36</p><p>
37For complicated commands which take various parameters, you can
38use the <span class="emphasis"><em>G4UIcommand</em></span> base class, and construct
39<span class="emphasis"><em>G4UIparameter</em></span> objects by yourself. You don't need to delete
40<span class="emphasis"><em>G4UIparameter</em></span> object(s).
41</p><p>
42In the <code class="literal">SetNewValue()</code> and <code class="literal">GetCurrentValue()</code>
43methods of your messenger, you can compare the <span class="emphasis"><em>G4UIcommand</em></span>
44pointer given in the argument of these methods with the pointer of
45your command, because your messenger keeps the pointers to the
46commands. Thus, you don't need to compare by command name. Please
47remember, in the cases where you use <span class="emphasis"><em>G4UIcommand</em></span> derived
48classes, you should store the pointers with the types of these
49derived classes so that you can use methods defined in the derived
50classes according to their types without casting.
51</p><p>
52<span class="emphasis"><em>G4UImanager/G4UIcommand/G4UIparameter</em></span> have very powerful
53type and range checking routines. You are strongly recommended to
54set the range of your parameters. For the case of a numerical value
55(<code class="literal">int</code> or <code class="literal">double</code>), the range can be given by a
56<span class="emphasis"><em>G4String</em></span> using C++ notation, e.g., <code class="literal">"X &gt; 0 &amp;&amp;
57X &lt; 10"</code>. For the case of a string type parameter, you can
58set a candidate list. Please refer to the detailed descriptions below.
59</p><p>
60<code class="literal">GetCurrentValue()</code> will be invoked after the user's
61application of the corresponding command, and before the
62<code class="literal">SetNewValue()</code> invocation. This <code class="literal">GetCurrentValue()</code>
63method will be invoked only if
64
65</p><div class="itemizedlist"><ul type="disc" compact><li><p>
66 at least one parameter of the command has a range
67 </p></li><li><p>
68 at least one parameter of the command has a candidate list
69 </p></li><li><p>
70 at least the value of one parameter is omitted and this
71 parameter is defined as omittable and
72 <code class="literal">currentValueAsDefault</code>
73 </p></li></ul></div><p>
74</p><p>
75For the first two cases, you can re-set the range or the candidate
76list if you need to do so, but these ``re-set'' parameters are
77needed only for the case where the range or the candidate list
78varies dynamically.
79</p><p>
80A command can be ``state sensitive'', i.e., the command can be
81accepted only for a certain <span class="emphasis"><em>G4ApplicationState</em></span>(s). For
82example, the <code class="literal">/run/beamOn</code> command should not be accepted
83when Geant4 is processing another event (``G4State_EventProc''
84state). You can set the states available for the command with the
85<code class="literal">AvailableForStates()</code> method.
86</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.UIDefNew.DervCls"></a>7.2.2. 
87G4UIcommand and its derived classes
88</h3></div></div></div><h5><a name="id495268"></a>
89Methods available for all derived classes
90</h5><p>
91These are methods defined in the <span class="emphasis"><em>G4UIcommand</em></span> base class
92which should be used from the derived classes.
93
94</p><div class="itemizedlist"><ul type="disc" compact><li><p>
95 <code class="literal">void SetGuidance(char*)</code>
96 </p><p>
97 Define a guidance line. You can invoke this method as many times
98 as you need to give enough amount of guidance. Please note that the
99 first line will be used as a title head of the command guidance.
100 </p><p>
101 </p></li><li><p>
102 <code class="literal">void availableForStates(G4ApplicationState s1,...)</code>
103 </p><p>
104 If your command is valid only for certain states of the Geant4
105 kernel, specify these states by this method. Currently available
106 states are <code class="literal">G4State_PreInit, G4State_Init, G4State_Idle,
107 G4State_GeomClosed,</code> and <code class="literal">G4State_EventProc</code>.
108 Refer to the section 3.4.2 for meaning of each state. Please note that
109 the <code class="literal">Pause</code> state had been removed from
110 <span class="emphasis"><em>G4ApplicationState</em></span>.
111 </p><p>
112 </p></li><li><p>
113 <code class="literal">void SetRange(char* range)</code>
114 </p><p>
115 Define a range of the parameter(s). Use C++ notation, e.g.,
116 <code class="literal">"x &gt; 0 &amp;&amp; x &lt; 10"</code>, with variable name(s)
117 defined by the <code class="literal">SetParameterName()</code> method. For the case of
118 a <span class="emphasis"><em>G4ThreeVector</em></span>, you can set the relation between
119 parameters, e.g., <code class="literal">"x &gt; y"</code>.
120 </p><p>
121 </p></li></ul></div><p>
122</p><h5><a name="id495379"></a>
123G4UIdirectory
124</h5><p>
125This is a <span class="emphasis"><em>G4UIcommand</em></span> derived class for defining a
126directory.
127
128</p><div class="itemizedlist"><ul type="disc" compact><li><p>
129 <code class="literal">G4UIdirectory(char* directoryPath)</code>
130 </p><p>
131 Constructor. Argument is the (full-path) directory, which must
132 begin and terminate with `<code class="literal">/</code>'.
133 </p><p>
134 </p></li></ul></div><p>
135</p><h5><a name="id495420"></a>
136G4UIcmdWithoutParameter
137</h5><p>
138This is a <span class="emphasis"><em>G4UIcommand</em></span> derived class for a command which
139takes no parameter.
140
141</p><div class="itemizedlist"><ul type="disc" compact><li><p>
142 <code class="literal">G4UIcmdWithoutParameter(char* commandPath,
143 G4UImessenger* theMessenger)</code>
144 </p><p>
145 Constructor. Arguments are the (full-path) command name and the
146 pointer to your messenger.
147 </p><p>
148 </p></li></ul></div><p>
149</p><h5><a name="id495457"></a>
150G4UIcmdWithABool
151</h5><p>
152This is a <span class="emphasis"><em>G4UIcommand</em></span> derived class which takes one
153boolean type parameter.
154
155</p><div class="itemizedlist"><ul type="disc" compact><li><p>
156 <code class="literal">G4UIcmdWithABool(char* commandpath,G4UImanager*
157 theMessenger)</code>
158 </p><p>
159 Constructor. Arguments are the (full-path) command name and the
160 pointer to your messenger.
161 </p><p>
162 </p></li><li><p>
163 <code class="literal">void SetParameterName(char* paramName,
164 G4bool omittable)</code>
165 </p><p>
166 Define the name of the boolean parameter and set the omittable
167 flag. If omittable is true, you should define the default value
168 using the next method.
169 </p><p>
170 </p></li><li><p>
171 <code class="literal">void SetDefaultValue(G4bool defVal)</code>
172 </p><p>
173 Define the default value of the boolean parameter.
174 </p><p>
175 </p></li><li><p>
176 <code class="literal">G4bool GetNewBoolValue(G4String paramString)</code>
177 </p><p>
178 Convert <span class="emphasis"><em>G4String</em></span> parameter value given by the
179 <code class="literal">SetNewValue()</code> method of your messenger into boolean.
180 </p><p>
181 </p></li><li><p>
182 <code class="literal">G4String convertToString(G4bool currVal)</code>
183 </p><p>
184 Convert the current boolean value to <span class="emphasis"><em>G4String</em></span>
185 whichshould be returned by the <code class="literal">GetCurrentValue()</code> method
186 of your messenger.
187 </p><p>
188 </p></li></ul></div><p>
189</p><h5><a name="id495570"></a>
190G4UIcmdWithAnInteger
191</h5><p>
192This is a <span class="emphasis"><em>G4UIcommand</em></span> derived class which takes one
193integer type parameter.
194
195</p><div class="itemizedlist"><ul type="disc" compact><li><p>
196 <code class="literal">G4UIcmdWithAnInteger(char* commandpath,
197 G4UImanager* theMessenger)</code>
198 </p><p>
199 Constructor. Arguments are the (full-path) command name and the
200 pointer to your messenger.
201 </p><p>
202 </p></li><li><p>
203 <code class="literal">void SetParameterName(char* paramName,
204 G4bool omittable)</code>
205 </p><p>
206 Define the name of the integer parameter and set the omittable
207 flag. If omittable is true, you should define the default value
208 using the next method.
209 </p><p>
210 </p></li><li><p>
211 <code class="literal">void SetDefaultValue(G4int defVal)</code>
212 </p><p>
213 Define the default value of the integer parameter.
214 </p><p>
215 </p></li><li><p>
216 <code class="literal">G4int GetNewIntValue(G4String paramString)</code>
217 </p><p>
218 Convert <span class="emphasis"><em>G4String</em></span> parameter value given by the
219 <code class="literal">SetNewValue()</code> method of your messenger into integer.
220 </p><p>
221 </p></li><li><p>
222 <code class="literal">G4String convertToString(G4int currVal)</code>
223 </p><p>
224 Convert the current integer value to <span class="emphasis"><em>G4String</em></span>, which
225 should be returned by the <code class="literal">GetCurrentValue()</code> method of your
226 messenger.
227 </p><p>
228</p></li></ul></div><p>
229</p><h5><a name="id495683"></a>
230G4UIcmdWithADouble
231</h5><p>
232This is a <span class="emphasis"><em>G4UIcommand</em></span> derived class which takes one
233double type parameter.
234
235</p><div class="itemizedlist"><ul type="disc" compact><li><p>
236 <code class="literal">G4UIcmdWithADouble(char* commandpath,
237 G4UImanager* theMessenger)</code>
238 </p><p>
239 Constructor. Arguments are the (full-path) command name and the
240 pointer to your messenger.
241 </p><p>
242 </p></li><li><p>
243 <code class="literal">void SetParameterName(char* paramName,
244 G4bool omittable)</code>
245 </p><p>
246 Define the name of the double parameter and set the omittable
247 flag. If omittable is true, you should define the default value
248 using the next method.
249 </p><p>
250 </p></li><li><p><code class="literal">void SetDefaultValue(G4double defVal)</code>
251 </p><p>
252 Define the default value of the double parameter.
253 </p><p>
254 </p></li><li><p>
255 <code class="literal">G4double GetNewDoubleValue(G4String paramString)</code>
256 </p><p>
257 Convert <span class="emphasis"><em>G4String</em></span> parameter value given by the
258 <code class="literal">SetNewValue()</code> method of your messenger into double.
259 </p><p>
260 </p></li><li><p>
261 <code class="literal">G4String convertToString(G4double currVal)</code>
262 </p><p>
263 Convert the current double value to <span class="emphasis"><em>G4String</em></span> which
264 should be returned by the <code class="literal">GetCurrentValue()</code> method of
265 your messenger.
266 </p><p>
267 </p></li></ul></div><p>
268</p><h5><a name="id495795"></a>
269G4UIcmdWithAString
270</h5><p>
271This is a <span class="emphasis"><em>G4UIcommand</em></span> derived class which takes one
272string type parameter.
273
274</p><div class="itemizedlist"><ul type="disc" compact><li><p>
275 <code class="literal">G4UIcmdWithAString(char* commandpath,
276 G4UImanager* theMessenger)</code>
277 </p><p>
278 Constructor. Arguments are the (full-path) command name and the
279 pointer to your messenger.
280 </p><p>
281 </p></li><li><p>
282 <code class="literal">void SetParameterName(char* paramName,
283 G4bool omittable)</code>
284 </p><p>
285 Define the name of the string parameter and set the omittable
286 flag. If omittable is true, you should define the default value
287 using the next method.
288 </p><p>
289 </p></li><li><p>
290 <code class="literal">void SetDefaultValue(char* defVal)</code>
291 </p><p>
292 Define the default value of the string parameter.
293 </p><p>
294 </p></li><li><p>
295 <code class="literal">void SetCandidates(char* candidateList)</code>
296 </p><p>
297 Define a candidate list which can be taken by the parameter.
298 Each candidate listed in this list should be separated by a single
299 space. If this candidate list is given, a string given by the user
300 but which is not listed in this list will be rejected.
301 </p><p>
302 </p></li></ul></div><p>
303</p><h5><a name="id495876"></a>
304G4UIcmdWith3Vector
305</h5><p>
306This is a <span class="emphasis"><em>G4UIcommand</em></span> derived class which takes one
307three vector parameter.
308
309</p><div class="itemizedlist"><ul type="disc" compact><li><p>
310 <code class="literal">G4UIcmdWith3Vector(char* commandpath,
311 G4UImanager* theMessenger)</code>
312 </p><p>
313 Constructor. Arguments are the (full-path) command name and the
314 pointer to your messenger.
315 </p><p>
316 </p></li><li><p>
317 <code class="literal">void SetParameterName(char* paramNamX, char* paramNamY,
318 char* paramNamZ, G4bool omittable)</code>
319 </p><p>
320 Define the names of each component of the three vector and set
321 the omittable flag. If omittable is true, you should define the
322 default value using the next method.
323 </p><p>
324 </p></li><li><p>
325 <code class="literal">void SetDefaultValue(G4ThreeVector defVal)</code>
326 </p><p>
327 Define the default value of the three vector.
328 </p><p>
329 </p></li><li><p>
330 <code class="literal">G4ThreeVector GetNew3VectorValue(G4String paramString)</code>
331 </p><p>
332 Convert the <span class="emphasis"><em>G4String</em></span> parameter value given by the
333 <code class="literal">SetNewValue()</code> method of your messenger into a
334 <span class="emphasis"><em>G4ThreeVector</em></span>.
335 </p><p>
336 </p></li><li><p>
337 <code class="literal">G4String convertToString(G4ThreeVector currVal)</code>
338 </p><p>
339 Convert the current three vector to <span class="emphasis"><em>G4String</em></span>, which
340 should be returned by the <code class="literal">GetCurrentValue()</code> method of
341 your messenger.
342 </p><p>
343 </p></li></ul></div><p>
344</p><h5><a name="id495993"></a>
345G4UIcmdWithADoubleAndUnit
346</h5><p>
347This is a <span class="emphasis"><em>G4UIcommand</em></span> derived class which takes one
348double type parameter and its unit.
349
350</p><div class="itemizedlist"><ul type="disc" compact><li><p>
351 <code class="literal">G4UIcmdWithADoubleAndUnit(char* commandpath,
352 G4UImanager* theMessenger)</code>
353 </p><p>
354 Constructor. Arguments are the (full-path) command name and the
355 pointer to your messenger.
356 </p><p>
357 </p></li><li><p>
358 <code class="literal">void SetParameterName(char* paramName,
359 G4bool omittable)</code>
360 </p><p>
361 Define the name of the double parameter and set the omittable
362 flag. If omittable is true, you should define the default value
363 using the next method.
364 </p><p>
365 </p></li><li><p>
366 <code class="literal">void SetDefaultValue(G4double defVal)</code>
367 </p><p>
368 Define the default value of the double parameter.
369 </p><p>
370</p><p>
371</p></li><li><p>
372 <code class="literal">void SetUnitCategory(char* unitCategory)</code>
373 </p><p>
374 Define acceptable unit category.
375 </p><p>
376 </p></li><li><p>
377 <code class="literal">void SetDefaultUnit(char* defUnit)</code>
378 </p><p>
379 Define the default unit. Please use this method and the
380 <code class="literal">SetUnitCategory()</code> method alternatively.
381 </p><p>
382 </p></li><li><p>
383 <code class="literal">G4double GetNewDoubleValue(G4String paramString)</code>
384 </p><p>
385 Convert <span class="emphasis"><em>G4String</em></span> parameter value given by the
386 <code class="literal">SetNewValue()</code> method of your messenger into double.
387 Please note that the return value has already been multiplied by the
388 value of the given unit.
389 </p><p>
390 </p></li><li><p><code class="literal">G4double GetNewDoubleRawValue(G4String paramString)</code>
391 </p><p>
392 Convert <span class="emphasis"><em>G4String</em></span> parameter value given by the
393 <code class="literal">SetNewValue()</code> method of your messenger into double but
394 without multiplying the value of the given unit.
395 </p><p>
396 </p></li><li><p><code class="literal">G4double GetNewUnitValue(G4String paramString)</code>
397 </p><p>
398 Convert <span class="emphasis"><em>G4String</em></span> unit value given by the
399 <code class="literal">SetNewValue()</code> method of your messenger into double.
400 </p><p>
401 </p></li><li><p>
402 <code class="literal">G4String convertToString(G4bool currVal,
403 char* unitName)</code>
404 </p><p>
405 Convert the current double value to a <span class="emphasis"><em>G4String</em></span>, which
406 should be returned by the <code class="literal">GetCurrentValue()</code> method of your
407 messenger. The double value will be divided by the value of the
408 given unit and converted to a string. Given unit will be added to the string.
409 </p><p>
410 </p></li></ul></div><p>
411</p><h5><a name="id496191"></a>
412G4UIcmdWith3VectorAndUnit
413</h5><p>
414This is a <span class="emphasis"><em>G4UIcommand</em></span> derived class which takes one
415three vector parameter and its unit.
416
417</p><div class="itemizedlist"><ul type="disc" compact><li><p>
418 <code class="literal">G4UIcmdWith3VectorAndUnit(char* commandpath,
419 G4UImanager* theMessenger)</code>
420 </p><p>
421 Constructor. Arguments are the (full-path) command name and the
422 pointer to your messenger.</p><p>
423 </p></li><li><p>
424 <code class="literal">void SetParameterName(char* paramNamX, char* paramNamY,
425 char* paramNamZ,G4bool omittable)</code>
426 </p><p>
427 Define the names of each component of the three vector and set
428 the omittable flag. If omittable is true, you should define the
429 default value using the next method.
430 </p><p>
431 </p></li><li><p>
432 <code class="literal">void SetDefaultValue(G4ThreeVector defVal)</code>
433 </p><p>
434 Define the default value of the three vector.
435 </p><p>
436 </p></li><li><p>
437 <code class="literal">void SetUnitCategory(char* unitCategory)</code>
438 </p><p>
439 Define acceptable unit category.
440 </p><p>
441 </p></li><li><p>
442 <code class="literal">void SetDefaultUnit(char* defUnit)</code>
443 </p><p>
444 Define the default unit. Please use this method and the
445 <code class="literal">SetUnitCategory()</code> method alternatively.
446 </p><p>
447 </p></li><li><p>
448 <code class="literal">G4ThreeVector GetNew3VectorValue(G4String paramString)</code>
449 </p><p>
450 Convert a <span class="emphasis"><em>G4String</em></span> parameter value given by the
451 <code class="literal">SetNewValue()</code> method of your messenger into a
452 <span class="emphasis"><em>G4ThreeVector</em></span>. Please note that the return value has
453 already been multiplied by the value of the given unit.
454 </p><p>
455 </p></li><li><p>
456 <code class="literal">G4ThreeVector GetNew3VectorRawValue(G4String paramString)</code>
457 </p><p>
458 Convert a <span class="emphasis"><em>G4String</em></span> parameter value given by the
459 <code class="literal">SetNewValue()</code> method of your messenger into three vector,
460 but without multiplying the value of the given unit.
461 </p><p>
462 </p></li><li><p>
463 <code class="literal">G4double GetNewUnitValue(G4String paramString)</code>
464 </p><p>
465 Convert a <span class="emphasis"><em>G4String</em></span> unit value given by the
466 <code class="literal">SetNewValue()</code> method of your messenger into a double.
467 </p><p>
468 </p></li><li><p>
469 <code class="literal">G4String convertToString(G4ThreeVector currVal,
470 char* unitName)</code>
471 </p><p>
472 Convert the current three vector to a <span class="emphasis"><em>G4String</em></span> which
473 should be returned by the <code class="literal">GetCurrentValue()</code> method of
474 your messenger. The three vector value will be divided by the value of
475 the given unit and converted to a string. Given unit will be added
476 to the string.
477 </p><p>
478 </p></li></ul></div><p>
479</p><h5><a name="id496393"></a>
480Additional comments on the <code class="literal">SetParameterName()</code> method
481</h5><p>
482You can add one additional argument of <code class="literal">G4bool</code> type for
483every <code class="literal">SetParameterName()</code> method mentioned above. This
484additional argument is named <code class="literal">currentAsDefaultFlag</code> and the
485default value of this argument is <code class="literal">false</code>. If you assign
486this extra argument as <code class="literal">true</code>, the default value of the
487parameter will be overriden by the current value of the target
488class.
489</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.UIDefNew.ExpMess"></a>7.2.3. 
490An example messenger
491</h3></div></div></div><p>
492This example is of <span class="emphasis"><em>G4ParticleGunMessenger</em></span>, which is
493made by inheriting <span class="emphasis"><em>G4UIcommand</em></span>.
494
495</p><div class="example"><a name="programlist_UIDefNew_1"></a><p class="title"><b>Example 7.1. 
496An example of <code class="literal">G4ParticleGunMessenger.hh</code>.
497</b></p><div class="example-contents"><pre class="programlisting">
498#ifndef G4ParticleGunMessenger_h
499#define G4ParticleGunMessenger_h 1
500
501class G4ParticleGun;
502class G4ParticleTable;
503class G4UIcommand;
504class G4UIdirectory;
505class G4UIcmdWithoutParameter;
506class G4UIcmdWithAString;
507class G4UIcmdWithADoubleAndUnit;
508class G4UIcmdWith3Vector;
509class G4UIcmdWith3VectorAndUnit;
510
511#include "G4UImessenger.hh"
512#include "globals.hh"
513
514class G4ParticleGunMessenger: public G4UImessenger
515{
516 public:
517 G4ParticleGunMessenger(G4ParticleGun * fPtclGun);
518 ~G4ParticleGunMessenger();
519
520 public:
521 void SetNewValue(G4UIcommand * command,G4String newValues);
522 G4String GetCurrentValue(G4UIcommand * command);
523
524 private:
525 G4ParticleGun * fParticleGun;
526 G4ParticleTable * particleTable;
527
528 private: //commands
529 G4UIdirectory * gunDirectory;
530 G4UIcmdWithoutParameter * listCmd;
531 G4UIcmdWithAString * particleCmd;
532 G4UIcmdWith3Vector * directionCmd;
533 G4UIcmdWithADoubleAndUnit * energyCmd;
534 G4UIcmdWith3VectorAndUnit * positionCmd;
535 G4UIcmdWithADoubleAndUnit * timeCmd;
536
537};
538
539#endif
540</pre></div></div><p><br class="example-break">
541</p><p>
542</p><div class="example"><a name="programlist_UIDefNew_2"></a><p class="title"><b>Example 7.2. 
543An example of <code class="literal">G4ParticleGunMessenger.cc</code>.
544</b></p><div class="example-contents"><pre class="programlisting">
545#include "G4ParticleGunMessenger.hh"
546#include "G4ParticleGun.hh"
547#include "G4Geantino.hh"
548#include "G4ThreeVector.hh"
549#include "G4ParticleTable.hh"
550#include "G4UIdirectory.hh"
551#include "G4UIcmdWithoutParameter.hh"
552#include "G4UIcmdWithAString.hh"
553#include "G4UIcmdWithADoubleAndUnit.hh"
554#include "G4UIcmdWith3Vector.hh"
555#include "G4UIcmdWith3VectorAndUnit.hh"
556#include &lt;iostream.h&gt;
557
558G4ParticleGunMessenger::G4ParticleGunMessenger(G4ParticleGun * fPtclGun)
559:fParticleGun(fPtclGun)
560{
561 particleTable = G4ParticleTable::GetParticleTable();
562
563 gunDirectory = new G4UIdirectory("/gun/");
564 gunDirectory-&gt;SetGuidance("Particle Gun control commands.");
565
566 listCmd = new G4UIcmdWithoutParameter("/gun/list",this);
567 listCmd-&gt;SetGuidance("List available particles.");
568 listCmd-&gt;SetGuidance(" Invoke G4ParticleTable.");
569
570 particleCmd = new G4UIcmdWithAString("/gun/particle",this);
571 particleCmd-&gt;SetGuidance("Set particle to be generated.");
572 particleCmd-&gt;SetGuidance(" (geantino is default)");
573 particleCmd-&gt;SetParameterName("particleName",true);
574 particleCmd-&gt;SetDefaultValue("geantino");
575 G4String candidateList;
576 G4int nPtcl = particleTable-&gt;entries();
577 for(G4int i=0;i&lt;nPtcl;i++)
578 {
579 candidateList += particleTable-&gt;GetParticleName(i);
580 candidateList += " ";
581 }
582 particleCmd-&gt;SetCandidates(candidateList);
583
584 directionCmd = new G4UIcmdWith3Vector("/gun/direction",this);
585 directionCmd-&gt;SetGuidance("Set momentum direction.");
586 directionCmd-&gt;SetGuidance("Direction needs not to be a unit vector.");
587 directionCmd-&gt;SetParameterName("Px","Py","Pz",true,true);
588 directionCmd-&gt;SetRange("Px != 0 || Py != 0 || Pz != 0");
589
590 energyCmd = new G4UIcmdWithADoubleAndUnit("/gun/energy",this);
591 energyCmd-&gt;SetGuidance("Set kinetic energy.");
592 energyCmd-&gt;SetParameterName("Energy",true,true);
593 energyCmd-&gt;SetDefaultUnit("GeV");
594 energyCmd-&gt;SetUnitCandidates("eV keV MeV GeV TeV");
595
596 positionCmd = new G4UIcmdWith3VectorAndUnit("/gun/position",this);
597 positionCmd-&gt;SetGuidance("Set starting position of the particle.");
598 positionCmd-&gt;SetParameterName("X","Y","Z",true,true);
599 positionCmd-&gt;SetDefaultUnit("cm");
600 positionCmd-&gt;SetUnitCandidates("micron mm cm m km");
601
602 timeCmd = new G4UIcmdWithADoubleAndUnit("/gun/time",this);
603 timeCmd-&gt;SetGuidance("Set initial time of the particle.");
604 timeCmd-&gt;SetParameterName("t0",true,true);
605 timeCmd-&gt;SetDefaultUnit("ns");
606 timeCmd-&gt;SetUnitCandidates("ns ms s");
607
608 // Set initial value to G4ParticleGun
609 fParticleGun-&gt;SetParticleDefinition( G4Geantino::Geantino() );
610 fParticleGun-&gt;SetParticleMomentumDirection( G4ThreeVector(1.0,0.0,0.0) );
611 fParticleGun-&gt;SetParticleEnergy( 1.0*GeV );
612 fParticleGun-&gt;SetParticlePosition(G4ThreeVector(0.0*cm, 0.0*cm, 0.0*cm));
613 fParticleGun-&gt;SetParticleTime( 0.0*ns );
614}
615</pre></div></div><p><br class="example-break">
616</p><div class="informalexample"><pre class="programlisting">
617G4ParticleGunMessenger::~G4ParticleGunMessenger()
618{
619 delete listCmd;
620 delete particleCmd;
621 delete directionCmd;
622 delete energyCmd;
623 delete positionCmd;
624 delete timeCmd;
625 delete gunDirectory;
626}
627
628void G4ParticleGunMessenger::SetNewValue(
629 G4UIcommand * command,G4String newValues)
630{
631 if( command==listCmd )
632 { particleTable-&gt;dumpTable(); }
633 else if( command==particleCmd )
634 {
635 G4ParticleDefinition* pd = particleTable-&gt;findParticle(newValues);
636 if(pd != NULL)
637 { fParticleGun-&gt;SetParticleDefinition( pd ); }
638 }
639 else if( command==directionCmd )
640 { fParticleGun-&gt;SetParticleMomentumDirection(directionCmd-&gt;
641 GetNew3VectorValue(newValues)); }
642 else if( command==energyCmd )
643 { fParticleGun-&gt;SetParticleEnergy(energyCmd-&gt;
644 GetNewDoubleValue(newValues)); }
645 else if( command==positionCmd )
646 { fParticleGun-&gt;SetParticlePosition(
647 directionCmd-&gt;GetNew3VectorValue(newValues)); }
648 else if( command==timeCmd )
649 { fParticleGun-&gt;SetParticleTime(timeCmd-&gt;
650 GetNewDoubleValue(newValues)); }
651}
652
653G4String G4ParticleGunMessenger::GetCurrentValue(G4UIcommand * command)
654{
655 G4String cv;
656
657 if( command==directionCmd )
658 { cv = directionCmd-&gt;ConvertToString(
659 fParticleGun-&gt;GetParticleMomentumDirection()); }
660 else if( command==energyCmd )
661 { cv = energyCmd-&gt;ConvertToString(
662 fParticleGun-&gt;GetParticleEnergy(),"GeV"); }
663 else if( command==positionCmd )
664 { cv = positionCmd-&gt;ConvertToString(
665 fParticleGun-&gt;GetParticlePosition(),"cm"); }
666 else if( command==timeCmd )
667 { cv = timeCmd-&gt;ConvertToString(
668 fParticleGun-&gt;GetParticleTime(),"ns"); }
669 else if( command==particleCmd )
670 { // update candidate list
671 G4String candidateList;
672 G4int nPtcl = particleTable-&gt;entries();
673 for(G4int i=0;i&lt;nPtcl;i++)
674 {
675 candidateList += particleTable-&gt;GetParticleName(i);
676 candidateList += " ";
677 }
678 particleCmd-&gt;SetCandidates(candidateList);
679 }
680 return cv;
681}
682</pre></div><p>
683</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sect.UIDefNew.HowCont"></a>7.2.4. 
684How to control the output of G4cout/G4cerr
685</h3></div></div></div><p>
686Instead of <span class="emphasis"><em>cout</em></span> and <span class="emphasis"><em>cerr</em></span>,
687Geant4 uses <span class="emphasis"><em>G4cout</em></span> and
688<span class="emphasis"><em>G4cerr</em></span>. Output streams from
689<span class="emphasis"><em>G4cout/G4cerr</em></span>
690are handled by <span class="emphasis"><em>G4UImanager</em></span> which allows the application
691programmer to control the flow of the stream. Output strings may
692therefore be displayed on another window or stored in a file. This
693is accomplished as follows:
694
695</p><div class="orderedlist"><ol type="1" compact><li><p>
696 Derive a class from <span class="emphasis"><em>G4UIsession</em></span> and implement the two
697 methods:
698
699 </p><p>
700 </p><div class="informalexample"><pre class="programlisting">
701 G4int ReceiveG4cout(G4String coutString);
702 G4int ReceiveG4cerr(G4String cerrString);
703 </pre></div><p>
704
705 These methods receive the string stream of <span class="emphasis"><em>G4cout</em></span> and
706 <span class="emphasis"><em>G4cerr</em></span>, respectively. The string can be handled to meet
707 specific requirements. The following sample code shows how to make
708 a log file of the output stream:
709
710 </p><div class="informalexample"><pre class="programlisting">
711 ostream logFile;
712 logFile.open("MyLogFile");
713 G4int MySession::ReceiveG4cout(G4String coutString)
714 {
715 logFile &lt;&lt; coutString &lt;&lt; flush;
716 return 0;
717 }
718 </pre></div><p>
719 </p><p>
720 </p></li><li><p>
721 </p><p>
722 Set the destination of <span class="emphasis"><em>G4cout/G4cerr</em></span> using
723 <code class="literal">G4UImanager::SetCoutDestination(session)</code>.
724 </p><p>
725 </p><p>
726 Typically this method is invoked from the constructor of
727 <span class="emphasis"><em>G4UIsession</em></span> and its derived classes, such as
728 <span class="emphasis"><em>G4UIGAG/G4UIteminal</em></span>. This method sets the destination of
729 <span class="emphasis"><em>G4cout/G4cerr</em></span> to the session. For example, when the
730 following code appears in the constructor of <span class="emphasis"><em>G4UIterminal</em></span>,
731 the method <code class="literal">SetCoutDestination(this)</code> tells
732 <span class="emphasis"><em>UImanager</em></span> that this instance of
733 <span class="emphasis"><em>G4UIterminal</em></span> receives the stream
734 generated by <span class="emphasis"><em>G4cout</em></span>.
735
736 </p><div class="informalexample"><pre class="programlisting">
737 G4UIterminal::G4UIterminal()
738 {
739 UI = G4UImanager::GetUIpointer();
740 UI-&gt;SetCoutDestination(this);
741 // ...
742 }
743 </pre></div><p>
744
745 Similarly, <code class="literal">UI-&gt;SetCoutDestination(NULL)</code> must be added
746 to the destructor of the class.
747 </p><p>
748 </p></li><li><p>
749 Write or modify the main program. To modify <code class="literal">exampleN01</code>
750 to produce a log file, derive a class as described in step 1 above,
751 and add the following lines to the main program:
752
753 </p><div class="informalexample"><pre class="programlisting">
754 #include "MySession.hh"
755 main()
756 {
757 // get the pointer to the User Interface manager
758 G4UImanager* UI = G4UImanager::GetUIpointer();
759 // construct a session which receives G4cout/G4cerr
760 MySession * LoggedSession = new MySession;
761 UI-&gt;SetCoutDestination(LoggedSession);
762 // session-&gt;SessionStart(); // not required in this case
763 // .... do simulation here ...
764
765 delete LoggedSession;
766 return 0;
767 }
768 </pre></div><p>
769 </p></li></ol></div><p>
770</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
771<span class="emphasis"><em>G4cout/G4cerr</em></span> should not be used in the constructor of a
772class if the instance of the class is intended to be used as
773<code class="literal">static</code>. This restriction comes from the language
774specification of C++. See the documents below for details:
775
776</p><div class="itemizedlist"><ul type="disc" compact><li><p>
777 M.A.Ellis, B.Stroustrup, ``Annotated C++ Reference Manual'', Section 3.4
778 [<span class="citation">
779 <a href="bi01.html#biblio.ellis1990">
780 Ellis1990
781 </a>
782 </span>]
783 </p></li><li><p>
784 P.J.Plauger, ``The Draft Standard C++ Library''
785 [<span class="citation">
786 <a href="bi01.html#biblio.plauger1995">
787 Plauger1995
788 </a>
789 </span>]
790 </p></li></ul></div><p>
791</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch07.html"><img src="AllResources/IconsGIF/prev.gif" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="ch07.html"><img src="AllResources/IconsGIF/up.gif" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="ch08.html"><img src="AllResources/IconsGIF/next.gif" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 7. 
792Communication and Control
793 </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"> Chapter 8. 
794Visualization
795</td></tr></table></div></body></html>
Note: See TracBrowser for help on using the repository browser.