source: trunk/documents/UserDoc/UsersGuides/ForApplicationDeveloper/html/Control/userInterfaceCommand.html @ 1208

Last change on this file since 1208 was 1208, checked in by garnier, 15 years ago

CVS update
File size: 26.6 KB
Line 
1<HTML>
2<TITLE>
3</TITLE>
4<!-- Changed by: Katsuya Amako, 21-Sep-1998 -->
5<!-- Changed by: Katsuya Dosanjh, 15-Jul-2000 -->
6<!-- Changed by: Dennis Wright, 29-Nov-2001 -->
7<!-- Changed by: Jacek Generowicz, 13-Mar-2002 -->
8<!-- Proof read by: Joe Chuma,   2-Jul-1999 -->
9
10<BODY>
11<TABLE WIDTH="100%"><TR>
12<TD>
13
14
15<A HREF="index.html">
16<IMG SRC="../../../../resources/html/IconsGIF/Contents.gif" ALT="Contents"></A>
17<A HREF="commands.html">
18<IMG SRC="../../../../resources/html/IconsGIF/Previous.gif" ALT="Previous"></A>
19<A>
20<IMG SRC="../../../../resources/html/IconsGIF/NextGR.gif" ALT="Next"></A>
21</TD>
22<TD ALIGN="Right">
23<FONT SIZE="-1" COLOR="#238E23">
24<B>Geant4 User's Guide</B>
25<BR>
26<B>For Application Developers</B>
27<BR>
28<B>Communication and Control</B>
29</FONT>
30</TD>
31</TR></TABLE>
32<BR><BR>
33
34<P ALIGN="Center">
35<FONT SIZE="+3" COLOR="#238E23">
36<B>7.2 User Interface - Defining New Commands</B>
37</FONT>
38<BR><BR>
39
40<HR ALIGN="Center" SIZE="7%">
41<p>
42
43<a name="7.2.1">
44<H2>7.2.1 <i>G4UImessenger</i></H2></a>
45
46 <i>G4UImessenger</i> is a base class which represents a messenger
47 that delivers command(s) to the destination class object.
48 Your concrete messenger should have the following
49 functionalities.
50 <ul>
51  <li>Construct your command(s) in the constructor of your messenger.
52  <li>Destruct your command(s) in the destructor of your messenger.
53 </ul>
54 These requirements mean that your messenger should
55 keep all pointers to your command objects as its data members.
56<p>
57 You can use <i>G4UIcommand</i> derived classes
58 for the most frequent types of command. These derived classes have their
59 own conversion methods according to their types, and they make implementation of
60 the <tt>SetNewValue()</tt> and <tt>GetCurrentValue()</tt> methods of your messenger
61 much easier and simpler.
62<p>
63 For complicated commands which take various parameters,
64 you can use the <i>G4UIcommand</i> base class, and construct <i>G4UIparameter</i>
65 objects by yourself. You don't need to delete <i>G4UIparameter</i>
66 object(s).
67<p>
68 In the <tt>SetNewValue()</tt> and <tt>GetCurrentValue()</tt> methods of your messenger,
69 you can compare the <i>G4UIcommand</i> pointer given in the argument of these
70 methods with the pointer of your command, because your messenger keeps
71 the pointers to the commands. Thus, you don't need to compare by
72 command name. Please remember, in the cases where you use <i>G4UIcommand</i>
73 derived classes, you should store the pointers
74 with the types of these derived classes so that you can use methods
75 defined in the derived classes according to their types without casting.
76<p>
77 <i>G4UImanager/G4UIcommand/G4UIparameter</i> have
78 very powerful type and range checking routines. You are strongly
79 recommended to set the range of your parameters. For the case of a
80 numerical value (<tt>int</tt> or <tt>double</tt>), the range can be given by a <i>G4String</i>
81 using C++ notation, e.g., <tt>"X &gt; 0 &amp;&amp; X &lt; 10"</tt>.
82 For the case of a string type parameter, you can set a
83 candidate list. Please refer to the detailed
84 descriptions below.
85<p>
86 <tt>GetCurrentValue()</tt> will be invoked after the user's application of
87 the corresponding command, and before the <tt>SetNewValue()</tt> invocation.
88 This <tt>GetCurrentValue()</tt> method will be invoked only if
89 <ul>
90  <li>at least one parameter of the command has a range
91  <li>at least one parameter of the command has a candidate list
92  <li>at least the value of one parameter is omitted and this parameter
93      is defined as omittable and <tt>currentValueAsDefault</tt>
94 </ul>
95 For the first two cases, you can re-set the range or the candidate
96 list if you need to do so, but these ``re-set'' parameters are needed only for
97 the case where the range or the candidate list varies dynamically.
98<p>
99 A command can be ``state sensitive'', i.e., the command can
100 be accepted only for a certain <i>G4ApplicationState</i>(s). For
101 example, the <tt>/run/beamOn</tt> command should not be accepted when
102 Geant4 is processing another event (``G4State_EventProc'' state). You can
103 set the states available for the command with the
104 <tt>AvailableForStates()</tt> method.
105<p>
106
107<HR>
108<a name="7.2.2">
109<H2>7.2.2 <i>G4UIcommand</i> and its derived classes</H2></a>
110
111 <dl>
112  <dt>Methods available for all derived classes<p>
113  <dd>These are methods defined in the <i>G4UIcommand</i> base class which should be
114      used from the derived classes.<p>
115      <ul>
116       <li><tt>void SetGuidance(char*)</tt><p>
117           Define a guidance line. You can invoke this method as many times
118           as you need to give enough amount of guidance. Please note that
119           the first line will be used as a title head of the command guidance.<p>
120       <li><tt>void availableForStates(G4ApplicationState s1,...)</tt><p>
121           If your command is valid only for certain states of the Geant4 kernel,
122           specify these states by this method. Currently available states are
123           <tt>G4State_PreInit, G4State_Init, G4State_Idle, G4State_GeomClosed,</tt>
124           and <tt>G4State_EventProc</tt>. Refer to the section 3.4.2 for meaning of
125           each state. Please note that
126           the <tt>Pause</tt> state had been removed from <i>G4ApplicationState</i>.<p>
127       <li><tt>void SetRange(char* range)</tt><p>
128           Define a range of the parameter(s). Use C++ notation, e.g.,
129           <tt>"x &gt; 0 &amp;&amp; x &lt; 10"</tt>, with variable name(s) defined by the
130           <tt>SetParameterName()</tt> method. For the case of a <i>G4ThreeVector</i>, you
131           can set the relation between parameters, e.g., <tt>"x &gt; y"</tt>.
132     </ul>
133  <p>
134  <dt><i>G4UIdirectory</i><p>
135  <dd>This is a <i>G4UIcommand</i> derived class for defining a directory.<p>
136      <ul>
137       <li><tt>G4UIdirectory(char* directoryPath)</tt><p>
138           Constructor. Argument is the (full-path) directory, which
139           must begin and terminate with `<tt>/</tt>'.
140      </ul>
141  <p>
142  <dt><i>G4UIcmdWithoutParameter</i><p>
143  <dd>This is a <i>G4UIcommand</i> derived class for a command which takes no parameter.<p>
144      <ul>
145       <li><tt>G4UIcmdWithoutParameter(char* commandPath,G4UImessenger* theMessenger)</tt><p>
146           Constructor. Arguments are the (full-path) command name
147           and the pointer to your messenger.
148      </ul>
149  <p>
150  <dt><i>G4UIcmdWithABool</i><p>
151  <dd>This is a <i>G4UIcommand</i> derived class which takes one boolean type parameter.<p>
152      <ul>
153       <li><tt>G4UIcmdWithABool(char* commandpath,G4UImanager* theMessenger)</tt><p>
154           Constructor. Arguments are the (full-path) command name
155           and the pointer to your messenger.<p>
156       <li><tt>void SetParameterName(char* paramName,G4bool omittable)</tt><p>
157           Define the name of the boolean parameter and set the omittable flag.
158           If omittable is true, you should define the default value using the
159           next method.<p>
160       <li><tt>void SetDefaultValue(G4bool defVal)</tt><p>
161           Define the default value of the boolean parameter.<p>
162       <li><tt>G4bool GetNewBoolValue(G4String paramString)</tt><p>
163           Convert <i>G4String</i> parameter value given by the <tt>SetNewValue()</tt>
164           method of your messenger into boolean.<p>
165       <li><tt>G4String convertToString(G4bool currVal)</tt><p>
166           Convert the current boolean value to <i>G4String</i> which should
167           be returned by the <tt>GetCurrentValue()</tt> method of your messenger.
168      </ul>
169  <p>
170  <dt><i>G4UIcmdWithAnInteger</i><p>
171  <dd>This is a <i>G4UIcommand</i> derived class which takes one integer type parameter.<p>
172      <ul>
173       <li><tt>G4UIcmdWithAnInteger(char* commandpath,G4UImanager* theMessenger)</tt><p>
174           Constructor. Arguments are the (full-path) command name
175           and the pointer to your messenger.<p>
176       <li><tt>void SetParameterName(char* paramName,G4bool omittable)</tt><p>
177           Define the name of the integer parameter and set the omittable flag.
178           If omittable is true, you should define the default value using the
179           next method.<p>
180       <li><tt>void SetDefaultValue(G4int defVal)</tt><p>
181           Define the default value of the integer parameter.<p>
182       <li><tt>G4int GetNewIntValue(G4String paramString)</tt><p>
183           Convert <i>G4String</i> parameter value given by the <tt>SetNewValue()</tt>
184           method of your messenger into integer.<p>
185       <li><tt>G4String convertToString(G4int currVal)</tt><p>
186           Convert the current integer value to <i>G4String</i>, which should
187           be returned by the <tt>GetCurrentValue()</tt> method of your messenger.
188      </ul>
189  <p>
190  <dt><i>G4UIcmdWithADouble</i><p>
191  <dd>This is a <i>G4UIcommand</i> derived class which takes one double type parameter.<p>
192      <ul>
193       <li><tt>G4UIcmdWithADouble(char* commandpath,G4UImanager* theMessenger)</tt><p>
194           Constructor. Arguments are the (full-path) command name
195           and the pointer to your messenger.<p>
196       <li><tt>void SetParameterName(char* paramName,G4bool omittable)</tt><p>
197           Define the name of the double parameter and set the omittable flag.
198           If omittable is true, you should define the default value using the
199           next method.<p>
200       <li><tt>void SetDefaultValue(G4double defVal)</tt><p>
201           Define the default value of the double parameter.<p>
202       <li><tt>G4double GetNewDoubleValue(G4String paramString)</tt><p>
203           Convert <i>G4String</i> parameter value given by the <tt>SetNewValue()</tt>
204           method of your messenger into double.<p>
205       <li><tt>G4String convertToString(G4double currVal)</tt><p>
206           Convert the current double value to <i>G4String</i> which should
207           be returned by the <tt>GetCurrentValue()</tt> method of your messenger.
208      </ul>
209  <p>
210  <dt><i>G4UIcmdWithAString</i><p>
211  <dd>This is a <i>G4UIcommand</i> derived class which takes one string type parameter.<p>
212      <ul>
213       <li><tt>G4UIcmdWithAString(char* commandpath,G4UImanager* theMessenger)</tt><p>
214           Constructor. Arguments are the (full-path) command name
215           and the pointer to your messenger.<p>
216       <li><tt>void SetParameterName(char* paramName,G4bool omittable)</tt><p>
217           Define the name of the string parameter and set the omittable flag.
218           If omittable is true, you should define the default value using the
219           next method.<p>
220       <li><tt>void SetDefaultValue(char* defVal)</tt><p>
221           Define the default value of the string parameter.<p>
222       <li><tt>void SetCandidates(char* candidateList)</tt><p>
223           Define a candidate list which can be taken by the parameter.
224           Each candidate listed in this list should be separated by a single
225           space. If this candidate list is given, a string given by the user
226           but which is not listed in this list will be rejected.
227      </ul>
228  <p>
229  <dt><i>G4UIcmdWith3Vector</i><p>
230  <dd>This is a <i>G4UIcommand</i> derived class which takes one three vector parameter.<p>
231      <ul>
232       <li><tt>G4UIcmdWith3Vector(char* commandpath,G4UImanager* theMessenger)</tt><p>
233           Constructor. Arguments are the (full-path) command name
234           and the pointer to your messenger.<p>
235       <li><tt>void SetParameterName</tt><br>
236           &nbsp;&nbsp;<tt>(char* paramNamX,char* paramNamY,char* paramNamZ,G4bool omittable)</tt><p>
237           Define the names of each component of the three vector and set
238           the omittable flag. If omittable is true, you should define the default
239           value using the next method.<p>
240       <li><tt>void SetDefaultValue(G4ThreeVector defVal)</tt><p>
241           Define the default value of the three vector.<p>
242       <li><tt>G4ThreeVector GetNew3VectorValue(G4String paramString)</tt><p>
243           Convert the <i>G4String</i> parameter value given by the <tt>SetNewValue()</tt>
244           method of your messenger into a <i>G4ThreeVector</i>.<p>
245       <li><tt>G4String convertToString(G4ThreeVector currVal)</tt><p>
246           Convert the current three vector to <i>G4String</i>, which should
247           be returned by the <tt>GetCurrentValue()</tt> method of your messenger.
248      </ul>
249  <p>
250  <dt><i>G4UIcmdWithADoubleAndUnit</i><p>
251  <dd>This is a <i>G4UIcommand</i> derived class which takes one double type parameter
252      and its unit.<p>
253      <ul>
254       <li><tt>G4UIcmdWithADoubleAndUnit(char* commandpath,G4UImanager* theMessenger)</tt><p>
255           Constructor. Arguments are the (full-path) command name
256           and the pointer to your messenger.<p>
257       <li><tt>void SetParameterName(char* paramName,G4bool omittable)</tt><p>
258           Define the name of the double parameter and set the omittable flag.
259           If omittable is true, you should define the default value using the
260           next method.<p>
261       <li><tt>void SetDefaultValue(G4double defVal)</tt><p>
262           Define the default value of the double parameter.<p>
263       <li><tt>void SetUnitCategory(char* unitCategory)</tt><p>
264           Define acceptable unit category.<p>
265       <li><tt>void SetDefaultUnit(char* defUnit)</tt><p>
266           Define the default unit. Please use this method and the <tt>SetUnitCategory()</tt>
267           method alternatively.<p>
268       <li><tt>G4double GetNewDoubleValue(G4String paramString)</tt><p>
269           Convert <i>G4String</i> parameter value given by the <tt>SetNewValue()</tt>
270           method of your messenger into double. Please note
271           that the return value has already been multiplied
272           by the value of the given unit.<p>
273       <li><tt>G4double GetNewDoubleRawValue(G4String paramString)</tt><p>
274           Convert <i>G4String</i> parameter value given by the <tt>SetNewValue()</tt>
275           method of your messenger into double but without multiplying
276           the value of the given unit.<p>
277       <li><tt>G4double GetNewUnitValue(G4String paramString)</tt><p>
278           Convert <i>G4String</i> unit value given by the <tt>SetNewValue()</tt>
279           method of your messenger into double.<p>
280       <li><tt>G4String convertToString(G4bool currVal,char* unitName)</tt><p>
281           Convert the current double value to a <i>G4String</i>, which should
282           be returned by the <tt>GetCurrentValue()</tt> method of your messenger.
283           The double value will be divided by the value of the given unit
284           and converted to a string. Given unit will be added to the string.
285      </ul>
286  <p>
287  <dt><i>G4UIcmdWith3VectorAndUnit</i><p>
288  <dd>This is a <i>G4UIcommand</i> derived class which takes one three vector parameter
289      and its unit.<p>
290      <ul>
291       <li><tt>G4UIcmdWith3VectorAndUnit(char* commandpath,G4UImanager* theMessenger)</tt><p>
292           Constructor. Arguments are the (full-path) command name
293           and the pointer to your messenger.<p>
294       <li><tt>void SetParameterName</tt><br>
295           &nbsp;&nbsp;<tt>(char* paramNamX,char* paramNamY,char* paramNamZ,G4bool omittable)</tt><p>
296           Define the names of each component of the three vector and set
297           the omittable flag. If omittable is true, you should define the default
298           value using the next method.<p>
299       <li><tt>void SetDefaultValue(G4ThreeVector defVal)</tt><p>
300           Define the default value of the three vector.<p>
301       <li><tt>void SetUnitCategory(char* unitCategory)</tt><p>
302           Define acceptable unit category.<p>
303       <li><tt>void SetDefaultUnit(char* defUnit)</tt><p>
304           Define the default unit. Please use this method and the <tt>SetUnitCategory()</tt>
305           method alternatively.<p>
306       <li><tt>G4ThreeVector GetNew3VectorValue(G4String paramString)</tt><p>
307           Convert a <i>G4String</i> parameter value given by the <tt>SetNewValue()</tt>
308           method of your messenger into a <i>G4ThreeVector</i>.
309           Please note that the return value has already been multiplied
310           by the value of the given unit.<p>
311       <li><tt>G4ThreeVector GetNew3VectorRawValue(G4String paramString)</tt><p>
312           Convert a <i>G4String</i> parameter value given by the <tt>SetNewValue()</tt>
313           method of your messenger into three vector, but without multiplying
314           the value of the given unit.<p>
315       <li><tt>G4double GetNewUnitValue(G4String paramString)</tt><p>
316           Convert a <i>G4String</i> unit value given by the <tt>SetNewValue()</tt>
317           method of your messenger into a double.<p>
318       <li><tt>G4String convertToString(G4ThreeVector currVal,char* unitName)</tt><p>
319           Convert the current three vector to a <i>G4String</i> which should
320           be returned by the <tt>GetCurrentValue()</tt> method of your messenger.
321           The three vector value will be divided by the value of the given unit
322           and converted to a string. Given unit will be added to the string.
323      </ul>
324  <p>
325  <dt>Additional comments on the <tt>SetParameterName()</tt> method<p>
326  <dd>You can add one additional argument of <tt>G4bool</tt> type for every
327      <tt>SetParameterName()</tt> method mentioned above. This additional argument
328      is named <tt>currentAsDefaultFlag</tt> and the
329      default value of this argument is <tt>false</tt>. If you assign this extra
330      argument as <tt>true</tt>, the default value of the parameter will be
331      overriden by the current value of the target class.
332 </dl>
333
334<p>
335
336<HR>
337<a name="7.2.3">
338<H2>7.2.3 An example messenger</H2></a>
339
340 This example is of <i>G4ParticleGunMessenger</i>, which is made by
341 inheriting <i>G4UIcommand</i>.
342<p>
343
344<center>
345<table border=2 cellpadding=10>
346<tr>
347<td>
348<pre>
349#ifndef G4ParticleGunMessenger_h
350#define G4ParticleGunMessenger_h 1
351
352class G4ParticleGun;
353class G4ParticleTable;
354class G4UIcommand;
355class G4UIdirectory;
356class G4UIcmdWithoutParameter;
357class G4UIcmdWithAString;
358class G4UIcmdWithADoubleAndUnit;
359class G4UIcmdWith3Vector;
360class G4UIcmdWith3VectorAndUnit;
361
362#include "G4UImessenger.hh"
363#include "globals.hh"
364
365class G4ParticleGunMessenger: public G4UImessenger
366{
367  public:
368    G4ParticleGunMessenger(G4ParticleGun * fPtclGun);
369    ~G4ParticleGunMessenger();
370   
371  public:
372    void SetNewValue(G4UIcommand * command,G4String newValues);
373    G4String GetCurrentValue(G4UIcommand * command);
374
375  private:
376    G4ParticleGun * fParticleGun;
377    G4ParticleTable * particleTable;
378   
379  private: //commands
380    G4UIdirectory *             gunDirectory;
381    G4UIcmdWithoutParameter *   listCmd;
382    G4UIcmdWithAString *        particleCmd;
383    G4UIcmdWith3Vector *        directionCmd;
384    G4UIcmdWithADoubleAndUnit * energyCmd;
385    G4UIcmdWith3VectorAndUnit * positionCmd;
386    G4UIcmdWithADoubleAndUnit * timeCmd;
387   
388};
389
390#endif </pre>
391</td>
392</tr>
393<tr>
394<td align=center>
395 Source listing 7.2.1<BR>
396 An example of <tt>G4ParticleGunMessenger.hh</tt>.
397</td>
398</tr>
399</table></center>
400<p>
401
402<center>
403<table border=2 cellpadding=10>
404<tr>
405<td>
406<pre>
407#include "G4ParticleGunMessenger.hh"
408#include "G4ParticleGun.hh"
409#include "G4Geantino.hh"
410#include "G4ThreeVector.hh"
411#include "G4ParticleTable.hh"
412#include "G4UIdirectory.hh"
413#include "G4UIcmdWithoutParameter.hh"
414#include "G4UIcmdWithAString.hh"
415#include "G4UIcmdWithADoubleAndUnit.hh"
416#include "G4UIcmdWith3Vector.hh"
417#include "G4UIcmdWith3VectorAndUnit.hh"
418#include &lt;iostream.h&gt;
419
420G4ParticleGunMessenger::G4ParticleGunMessenger(G4ParticleGun * fPtclGun)
421:fParticleGun(fPtclGun)
422{
423  particleTable = G4ParticleTable::GetParticleTable();
424
425  gunDirectory = new G4UIdirectory("/gun/");
426  gunDirectory-&gt;SetGuidance("Particle Gun control commands.");
427
428  listCmd = new G4UIcmdWithoutParameter("/gun/list",this);
429  listCmd-&gt;SetGuidance("List available particles.");
430  listCmd-&gt;SetGuidance(" Invoke G4ParticleTable.");
431
432  particleCmd = new G4UIcmdWithAString("/gun/particle",this);
433  particleCmd-&gt;SetGuidance("Set particle to be generated.");
434  particleCmd-&gt;SetGuidance(" (geantino is default)");
435  particleCmd-&gt;SetParameterName("particleName",true);
436  particleCmd-&gt;SetDefaultValue("geantino");
437  G4String candidateList;
438  G4int nPtcl = particleTable-&gt;entries();
439  for(G4int i=0;i&lt;nPtcl;i++)
440  {
441    candidateList += particleTable-&gt;GetParticleName(i);
442    candidateList += " ";
443  }
444  particleCmd-&gt;SetCandidates(candidateList);
445
446  directionCmd = new G4UIcmdWith3Vector("/gun/direction",this);
447  directionCmd-&gt;SetGuidance("Set momentum direction.");
448  directionCmd-&gt;SetGuidance("Direction needs not to be a unit vector.");
449  directionCmd-&gt;SetParameterName("Px","Py","Pz",true,true);
450  directionCmd-&gt;SetRange("Px != 0 || Py != 0 || Pz != 0");
451 
452  energyCmd = new G4UIcmdWithADoubleAndUnit("/gun/energy",this);
453  energyCmd-&gt;SetGuidance("Set kinetic energy.");
454  energyCmd-&gt;SetParameterName("Energy",true,true);
455  energyCmd-&gt;SetDefaultUnit("GeV");
456  energyCmd-&gt;SetUnitCandidates("eV keV MeV GeV TeV");
457
458  positionCmd = new G4UIcmdWith3VectorAndUnit("/gun/position",this);
459  positionCmd-&gt;SetGuidance("Set starting position of the particle.");
460  positionCmd-&gt;SetParameterName("X","Y","Z",true,true);
461  positionCmd-&gt;SetDefaultUnit("cm");
462  positionCmd-&gt;SetUnitCandidates("micron mm cm m km");
463
464  timeCmd = new G4UIcmdWithADoubleAndUnit("/gun/time",this);
465  timeCmd-&gt;SetGuidance("Set initial time of the particle.");
466  timeCmd-&gt;SetParameterName("t0",true,true);
467  timeCmd-&gt;SetDefaultUnit("ns");
468  timeCmd-&gt;SetUnitCandidates("ns ms s");
469 
470  // Set initial value to G4ParticleGun
471  fParticleGun-&gt;SetParticleDefinition( G4Geantino::Geantino() );
472  fParticleGun-&gt;SetParticleMomentumDirection( G4ThreeVector(1.0,0.0,0.0) );
473  fParticleGun-&gt;SetParticleEnergy( 1.0*GeV );
474  fParticleGun-&gt;SetParticlePosition(G4ThreeVector(0.0*cm, 0.0*cm, 0.0*cm));
475  fParticleGun-&gt;SetParticleTime( 0.0*ns );
476}
477
478G4ParticleGunMessenger::~G4ParticleGunMessenger()
479{
480  delete listCmd;
481  delete particleCmd;
482  delete directionCmd;
483  delete energyCmd;
484  delete positionCmd;
485  delete timeCmd;
486  delete gunDirectory;
487}
488
489void G4ParticleGunMessenger::SetNewValue(
490  G4UIcommand * command,G4String newValues)
491{
492  if( command==listCmd )
493  { particleTable-&gt;dumpTable(); }
494  else if( command==particleCmd )
495  {
496    G4ParticleDefinition* pd = particleTable-&gt;findParticle(newValues);
497    if(pd != NULL)
498    { fParticleGun-&gt;SetParticleDefinition( pd ); }
499  }
500  else if( command==directionCmd )
501  { fParticleGun-&gt;SetParticleMomentumDirection(directionCmd-&gt;
502     GetNew3VectorValue(newValues)); }
503  else if( command==energyCmd )
504  { fParticleGun-&gt;SetParticleEnergy(energyCmd-&gt;
505     GetNewDoubleValue(newValues)); }
506  else if( command==positionCmd )
507  { fParticleGun-&gt;SetParticlePosition(
508     directionCmd-&gt;GetNew3VectorValue(newValues)); }
509  else if( command==timeCmd )
510  { fParticleGun-&gt;SetParticleTime(timeCmd-&gt;
511     GetNewDoubleValue(newValues)); }
512}
513
514G4String G4ParticleGunMessenger::GetCurrentValue(G4UIcommand * command)
515{
516  G4String cv;
517 
518  if( command==directionCmd )
519  { cv = directionCmd-&gt;ConvertToString(
520     fParticleGun-&gt;GetParticleMomentumDirection()); }
521  else if( command==energyCmd )
522  { cv = energyCmd-&gt;ConvertToString(
523     fParticleGun-&gt;GetParticleEnergy(),"GeV"); }
524  else if( command==positionCmd )
525  { cv = positionCmd-&gt;ConvertToString(
526     fParticleGun-&gt;GetParticlePosition(),"cm"); }
527  else if( command==timeCmd )
528  { cv = timeCmd-&gt;ConvertToString(
529     fParticleGun-&gt;GetParticleTime(),"ns"); }
530  else if( command==particleCmd )
531  { // update candidate list
532    G4String candidateList;
533    G4int nPtcl = particleTable-&gt;entries();
534    for(G4int i=0;i&lt;nPtcl;i++)
535    {
536      candidateList += particleTable-&gt;GetParticleName(i);
537      candidateList += " ";
538    }
539    particleCmd-&gt;SetCandidates(candidateList);
540  }
541  return cv;
542}</pre>
543</td>
544</tr>
545<tr>
546<td align=center>
547 Source listing 7.2.2<BR>
548 An example of <tt>G4ParticleGunMessenger.cc</tt>.
549</td>
550</tr>
551</table></center>
552<p>
553
554<HR>
555<a name="7.2.4">
556<H2>7.2.4 How to control the output of <i>G4cout/G4cerr</i></H2></a>
557
558 Instead of <i>cout</i> and <i>cerr</i>, Geant4 uses <i>G4cout</i> and
559 <i>G4cerr</i>.  Output streams from <i>G4cout/G4cerr</i> are handled by
560 <i>G4UImanager</i> which allows the application programmer to control the
561 flow of the stream.  Output strings may therefore be displayed on another
562 window or stored in a file.  This is accomplished as follows:
563<p>
564 <ol>
565 <li>Derive a class from <i>G4UIsession</i> and implement the two methods:
566 <pre>
567      G4int ReceiveG4cout(G4String coutString);
568      G4int ReceiveG4cerr(G4String cerrString);
569 </pre>
570     These methods receive the string stream of <i>G4cout</i> and
571     <i>G4cerr</i>, respectively.  The string can be handled to meet
572     specific requirements.  The following sample code shows how to
573     make a log file of the output stream:
574 <pre>
575        ostream logFile;
576        logFile.open("MyLogFile");
577        G4int MySession::ReceiveG4cout(G4String coutString)
578        {
579          logFile << coutString << flush;
580          return 0;
581        }
582 </pre>
583 <p>
584 <li>Set the destination of <i>G4cout/G4cerr</i> using
585     <tt>G4UImanager::SetCoutDestination(session)</tt>.
586     <p>
587     Typically this method is invoked from the constructor of
588     <i>G4UIsession</i> and its derived classes, such as <i>G4UIGAG/G4UIteminal</i>.
589     This method sets the destination of <i>G4cout/G4cerr</i> to the session. 
590     For example, when the following code appears in the constructor of
591     <i>G4UIterminal</i>, the method <tt>SetCoutDestination(this)</tt> tells <i>UImanager</i>
592     that this instance of <i>G4UIterminal</i> receives the stream generated
593     by <i>G4cout</i>.
594 <pre>
595
596        G4UIterminal::G4UIterminal()
597        {
598          UI = G4UImanager::GetUIpointer();
599          UI->SetCoutDestination(this);
600          //  ...
601        }
602   
603 </pre>
604     Similarly, <tt>UI->SetCoutDestination(NULL)</tt> must be added
605     to the destructor of the class.
606 <p>
607 <li>Write or modify the main program.  To modify <tt>exampleN01</tt> to
608     produce a log file, derive a class as described in step 1 above, and
609     add the following lines to the main program:
610 <pre>
611        #include "MySession.hh"
612        main()
613        {
614          // get the pointer to the User Interface manager
615          G4UImanager* UI = G4UImanager::GetUIpointer();
616          // construct a session which receives G4cout/G4cerr
617          MySession * LoggedSession = new MySession;
618          UI->SetCoutDestination(LoggedSession);
619          // session->SessionStart(); // not required in this case
620          // .... do simulation here ...
621
622          delete LoggedSession;
623          return 0;
624        }
625 </pre>
626 </ol>
627
628 <table>
629 <tr>
630 <td valign=top>Note:
631 <td><i>G4cout/G4cerr</i> should not be used in the constructor of a class if
632     the instance of the class is intended to be used as <tt>static</tt>.
633     This restriction comes from the language specification of C++.
634     See the documents below for details.
635 </table>
636<p>
637  M.A.Ellis, B.Stroustrup.  ``Annotated C++ Reference Manual'', Section 3.4<br>
638  P.J.Plauger, ``The Draft Standard C++ Library''
639<p>
640
641<BR><BR>
642<HR>
643<A HREF="../../../../Authors/html/subjectsToAuthors.html">
644<I>About the authors</A></I>
645</BODY>
646</HTML>
647
Note: See TracBrowser for help on using the repository browser.