source: trunk/Documentation/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/ch07s02.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: 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.