source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Control/userInterfaceCommand.xml @ 905

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Changed by: Katsuya Amako, 21-Sep-1998                -->
<!--    Changed by: Katsuya Dosanjh, 15-Jul-2000              -->
<!--    Changed by: Dennis Wright, 29-Nov-2001                -->
<!--    Changed by: Jacek Generowicz, 13-Mar-2002             -->
<!--    Proof read by: Joe Chuma,   2-Jul-1999                -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.UIDefNew">
<title>
User Interface - Defining New Commands
</title>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.UIDefNew.UIMess">
<title>
G4UImessenger
</title>

<para>
<emphasis>G4UImessenger</emphasis> is a base class which represents a 
messenger that delivers command(s) to the destination class object. Your
concrete messenger should have the following functionalities.

<itemizedlist spacing="compact">
  <listitem><para>
    Construct your command(s) in the constructor of your messenger.
  </para></listitem>
  <listitem><para>
    Destruct your command(s) in the destructor of your messenger.
  </para></listitem>
</itemizedlist>
</para>

<para>
These requirements mean that your messenger should keep all
pointers to your command objects as its data members.
</para>

<para>
You can use <emphasis>G4UIcommand</emphasis> derived classes for the most
frequent types of command. These derived classes have their own
conversion methods according to their types, and they make
implementation of the <literal>SetNewValue()</literal> and
<literal>GetCurrentValue()</literal> methods of your messenger much easier
and simpler.
</para>

<para>
For complicated commands which take various parameters, you can
use the <emphasis>G4UIcommand</emphasis> base class, and construct
<emphasis>G4UIparameter</emphasis> objects by yourself. You don't need to delete
<emphasis>G4UIparameter</emphasis> object(s).
</para>

<para>
In the <literal>SetNewValue()</literal> and <literal>GetCurrentValue()</literal>
methods of your messenger, you can compare the <emphasis>G4UIcommand</emphasis>
pointer given in the argument of these methods with the pointer of
your command, because your messenger keeps the pointers to the
commands. Thus, you don't need to compare by command name. Please
remember, in the cases where you use <emphasis>G4UIcommand</emphasis> derived
classes, you should store the pointers with the types of these
derived classes so that you can use methods defined in the derived
classes according to their types without casting.
</para>

<para>
<emphasis>G4UImanager/G4UIcommand/G4UIparameter</emphasis> have very powerful
type and range checking routines. You are strongly recommended to
set the range of your parameters. For the case of a numerical value
(<literal>int</literal> or <literal>double</literal>), the range can be given by a
<emphasis>G4String</emphasis> using C++ notation, e.g., <literal>"X &gt; 0 &amp;&amp;
X &lt; 10"</literal>. For the case of a string type parameter, you can
set a candidate list. Please refer to the detailed descriptions below.
</para>

<para>
<literal>GetCurrentValue()</literal> will be invoked after the user's
application of the corresponding command, and before the
<literal>SetNewValue()</literal> invocation. This <literal>GetCurrentValue()</literal>
method will be invoked only if

<itemizedlist spacing="compact">
  <listitem><para>
    at least one parameter of the command has a range
  </para></listitem>
  <listitem><para>
    at least one parameter of the command has a candidate list
  </para></listitem>
  <listitem><para>
    at least the value of one parameter is omitted and this
    parameter is defined as omittable and
    <literal>currentValueAsDefault</literal>
  </para></listitem>
</itemizedlist>
</para>

<para>
For the first two cases, you can re-set the range or the candidate
list if you need to do so, but these ``re-set'' parameters are
needed only for the case where the range or the candidate list
varies dynamically.
</para>

<para>
A command can be ``state sensitive'', i.e., the command can be
accepted only for a certain <emphasis>G4ApplicationState</emphasis>(s). For
example, the <literal>/run/beamOn</literal> command should not be accepted
when Geant4 is processing another event (``G4State_EventProc''
state). You can set the states available for the command with the
<literal>AvailableForStates()</literal> method.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.UIDefNew.DervCls">
<title>
G4UIcommand and its derived classes
</title>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Methods available for all derived classes
</bridgehead>

<para>
These are methods defined in the <emphasis>G4UIcommand</emphasis> base class
which should be used from the derived classes.

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>void SetGuidance(char*)</literal>
    <para>
    Define a guidance line. You can invoke this method as many times
    as you need to give enough amount of guidance. Please note that the
    first line will be used as a title head of the command guidance.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void availableForStates(G4ApplicationState s1,...)</literal>
    <para>
    If your command is valid only for certain states of the Geant4
    kernel, specify these states by this method. Currently available
    states are <literal>G4State_PreInit, G4State_Init, G4State_Idle,
    G4State_GeomClosed,</literal> and <literal>G4State_EventProc</literal>. 
    Refer to the section 3.4.2 for meaning of each state. Please note that 
    the <literal>Pause</literal> state had been removed from
    <emphasis>G4ApplicationState</emphasis>.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetRange(char* range)</literal>
    <para>
    Define a range of the parameter(s). Use C++ notation, e.g.,
    <literal>"x &gt; 0 &amp;&amp; x &lt; 10"</literal>, with variable name(s)
    defined by the <literal>SetParameterName()</literal> method. For the case of
    a <emphasis>G4ThreeVector</emphasis>, you can set the relation between
    parameters, e.g., <literal>"x &gt; y"</literal>.
    </para>
  </para></listitem>
</itemizedlist>
</para>


<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4UIdirectory
</bridgehead>

<para>
This is a <emphasis>G4UIcommand</emphasis> derived class for defining a
directory.

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>G4UIdirectory(char* directoryPath)</literal>
    <para>
    Constructor. Argument is the (full-path) directory, which must
    begin and terminate with `<literal>/</literal>'.
    </para>
  </para></listitem>
</itemizedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4UIcmdWithoutParameter
</bridgehead>

<para>
This is a <emphasis>G4UIcommand</emphasis> derived class for a command which
takes no parameter.

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>G4UIcmdWithoutParameter(char* commandPath,
    G4UImessenger* theMessenger)</literal>
    <para>
    Constructor. Arguments are the (full-path) command name and the
    pointer to your messenger.
    </para>
  </para></listitem>
</itemizedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4UIcmdWithABool
</bridgehead>

<para>
This is a <emphasis>G4UIcommand</emphasis> derived class which takes one
boolean type parameter.

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>G4UIcmdWithABool(char* commandpath,G4UImanager*
    theMessenger)</literal>
    <para>
    Constructor. Arguments are the (full-path) command name and the
    pointer to your messenger.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetParameterName(char* paramName,
    G4bool omittable)</literal>
    <para>
    Define the name of the boolean parameter and set the omittable
    flag. If omittable is true, you should define the default value
    using the next method.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetDefaultValue(G4bool defVal)</literal>
    <para>
    Define the default value of the boolean parameter.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>G4bool GetNewBoolValue(G4String paramString)</literal>
    <para>
    Convert <emphasis>G4String</emphasis> parameter value given by the
    <literal>SetNewValue()</literal> method of your messenger into boolean.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>G4String convertToString(G4bool currVal)</literal>
    <para>
    Convert the current boolean value to <emphasis>G4String</emphasis> 
    whichshould be returned by the <literal>GetCurrentValue()</literal> method 
    of your messenger.
    </para>
  </para></listitem>
</itemizedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4UIcmdWithAnInteger
</bridgehead>

<para>
This is a <emphasis>G4UIcommand</emphasis> derived class which takes one
integer type parameter.

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>G4UIcmdWithAnInteger(char* commandpath,
    G4UImanager* theMessenger)</literal>
    <para>
    Constructor. Arguments are the (full-path) command name and the
    pointer to your messenger.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetParameterName(char* paramName,
    G4bool omittable)</literal>
    <para>
    Define the name of the integer parameter and set the omittable
    flag. If omittable is true, you should define the default value
    using the next method.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetDefaultValue(G4int defVal)</literal>
    <para>
    Define the default value of the integer parameter.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>G4int GetNewIntValue(G4String paramString)</literal>
    <para>
    Convert <emphasis>G4String</emphasis> parameter value given by the
    <literal>SetNewValue()</literal> method of your messenger into integer.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>G4String convertToString(G4int currVal)</literal>
    <para>
    Convert the current integer value to <emphasis>G4String</emphasis>, which
    should be returned by the <literal>GetCurrentValue()</literal> method of your
    messenger.
    </para>
</para></listitem>
</itemizedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4UIcmdWithADouble
</bridgehead>

<para>
This is a <emphasis>G4UIcommand</emphasis> derived class which takes one
double type parameter.

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>G4UIcmdWithADouble(char* commandpath,
    G4UImanager* theMessenger)</literal>
    <para>
    Constructor. Arguments are the (full-path) command name and the
    pointer to your messenger.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetParameterName(char* paramName,
    G4bool omittable)</literal>
    <para>
    Define the name of the double parameter and set the omittable
    flag. If omittable is true, you should define the default value
    using the next method.
    </para>
  </para></listitem>
  <listitem><para><literal>void SetDefaultValue(G4double defVal)</literal>
  <para>
  Define the default value of the double parameter.
  </para>
  </para></listitem>
  <listitem><para>
    <literal>G4double GetNewDoubleValue(G4String paramString)</literal>
    <para>
    Convert <emphasis>G4String</emphasis> parameter value given by the
    <literal>SetNewValue()</literal> method of your messenger into double.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>G4String convertToString(G4double currVal)</literal>
    <para>
    Convert the current double value to <emphasis>G4String</emphasis> which
    should be returned by the <literal>GetCurrentValue()</literal> method of 
    your messenger.
    </para>
  </para></listitem>
</itemizedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4UIcmdWithAString
</bridgehead>

<para>
This is a <emphasis>G4UIcommand</emphasis> derived class which takes one
string type parameter.

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>G4UIcmdWithAString(char* commandpath,
    G4UImanager* theMessenger)</literal>
    <para>
    Constructor. Arguments are the (full-path) command name and the
    pointer to your messenger.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetParameterName(char* paramName,
    G4bool omittable)</literal>
    <para>
    Define the name of the string parameter and set the omittable
    flag. If omittable is true, you should define the default value
    using the next method.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetDefaultValue(char* defVal)</literal>
    <para>
    Define the default value of the string parameter.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetCandidates(char* candidateList)</literal>
    <para>
    Define a candidate list which can be taken by the parameter.
    Each candidate listed in this list should be separated by a single
    space. If this candidate list is given, a string given by the user
    but which is not listed in this list will be rejected.
    </para>
  </para></listitem>
</itemizedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4UIcmdWith3Vector
</bridgehead>

<para>
This is a <emphasis>G4UIcommand</emphasis> derived class which takes one
three vector parameter.

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>G4UIcmdWith3Vector(char* commandpath,
    G4UImanager* theMessenger)</literal>
    <para>
    Constructor. Arguments are the (full-path) command name and the
    pointer to your messenger.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetParameterName(char* paramNamX, char* paramNamY,
    char* paramNamZ, G4bool omittable)</literal>
    <para>
    Define the names of each component of the three vector and set
    the omittable flag. If omittable is true, you should define the
    default value using the next method.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetDefaultValue(G4ThreeVector defVal)</literal>
    <para>
    Define the default value of the three vector.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>G4ThreeVector GetNew3VectorValue(G4String paramString)</literal>
    <para>
    Convert the <emphasis>G4String</emphasis> parameter value given by the
    <literal>SetNewValue()</literal> method of your messenger into a
    <emphasis>G4ThreeVector</emphasis>.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>G4String convertToString(G4ThreeVector currVal)</literal>
    <para>
    Convert the current three vector to <emphasis>G4String</emphasis>, which
    should be returned by the <literal>GetCurrentValue()</literal> method of 
    your messenger.
    </para>
  </para></listitem>
</itemizedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4UIcmdWithADoubleAndUnit
</bridgehead>

<para>
This is a <emphasis>G4UIcommand</emphasis> derived class which takes one
double type parameter and its unit.

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>G4UIcmdWithADoubleAndUnit(char* commandpath,
    G4UImanager* theMessenger)</literal>
    <para>
    Constructor. Arguments are the (full-path) command name and the
    pointer to your messenger.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetParameterName(char* paramName,
    G4bool omittable)</literal>
    <para>
    Define the name of the double parameter and set the omittable
    flag. If omittable is true, you should define the default value
    using the next method.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetDefaultValue(G4double defVal)</literal>
    <para>
    Define the default value of the double parameter.
    </para>
</para><para>
</para></listitem>
<listitem><para>
  <literal>void SetUnitCategory(char* unitCategory)</literal>
  <para>
  Define acceptable unit category.
  </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetDefaultUnit(char* defUnit)</literal>
    <para>
    Define the default unit. Please use this method and the
    <literal>SetUnitCategory()</literal> method alternatively.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>G4double GetNewDoubleValue(G4String paramString)</literal>
    <para>
    Convert <emphasis>G4String</emphasis> parameter value given by the
    <literal>SetNewValue()</literal> method of your messenger into double. 
    Please note that the return value has already been multiplied by the 
    value of the given unit.
    </para>
  </para></listitem>
  <listitem><para><literal>G4double GetNewDoubleRawValue(G4String paramString)</literal>
  <para>
  Convert <emphasis>G4String</emphasis> parameter value given by the
  <literal>SetNewValue()</literal> method of your messenger into double but
  without multiplying the value of the given unit.
  </para>
  </para></listitem>
  <listitem><para><literal>G4double GetNewUnitValue(G4String paramString)</literal>
  <para>
  Convert <emphasis>G4String</emphasis> unit value given by the
  <literal>SetNewValue()</literal> method of your messenger into double.
  </para>
  </para></listitem>
  <listitem><para>
    <literal>G4String convertToString(G4bool currVal,
    char* unitName)</literal>
    <para>
    Convert the current double value to a <emphasis>G4String</emphasis>, which
    should be returned by the <literal>GetCurrentValue()</literal> method of your
    messenger. The double value will be divided by the value of the
    given unit and converted to a string. Given unit will be added to the string.
    </para>
  </para></listitem>
</itemizedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
G4UIcmdWith3VectorAndUnit
</bridgehead>

<para>
This is a <emphasis>G4UIcommand</emphasis> derived class which takes one
three vector parameter and its unit.

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>G4UIcmdWith3VectorAndUnit(char* commandpath,
    G4UImanager* theMessenger)</literal>
    <para>
    Constructor. Arguments are the (full-path) command name and the
    pointer to your messenger.</para>
  </para></listitem>
  <listitem><para>
    <literal>void SetParameterName(char* paramNamX, char* paramNamY,
    char* paramNamZ,G4bool omittable)</literal>
    <para>
    Define the names of each component of the three vector and set
    the omittable flag. If omittable is true, you should define the
    default value using the next method.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetDefaultValue(G4ThreeVector defVal)</literal>
    <para>
    Define the default value of the three vector.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetUnitCategory(char* unitCategory)</literal>
    <para>
    Define acceptable unit category.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>void SetDefaultUnit(char* defUnit)</literal>
    <para>
    Define the default unit. Please use this method and the
    <literal>SetUnitCategory()</literal> method alternatively.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>G4ThreeVector GetNew3VectorValue(G4String paramString)</literal>
    <para>
    Convert a <emphasis>G4String</emphasis> parameter value given by the
    <literal>SetNewValue()</literal> method of your messenger into a
    <emphasis>G4ThreeVector</emphasis>. Please note that the return value has 
    already been multiplied by the value of the given unit.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>G4ThreeVector GetNew3VectorRawValue(G4String paramString)</literal>
    <para>
    Convert a <emphasis>G4String</emphasis> parameter value given by the
    <literal>SetNewValue()</literal> method of your messenger into three vector,
    but without multiplying the value of the given unit.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>G4double GetNewUnitValue(G4String paramString)</literal>
    <para>
    Convert a <emphasis>G4String</emphasis> unit value given by the
    <literal>SetNewValue()</literal> method of your messenger into a double.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>G4String convertToString(G4ThreeVector currVal,
    char* unitName)</literal>
    <para>
    Convert the current three vector to a <emphasis>G4String</emphasis> which
    should be returned by the <literal>GetCurrentValue()</literal> method of 
    your messenger. The three vector value will be divided by the value of
    the given unit and converted to a string. Given unit will be added
    to the string.
    </para>
  </para></listitem>
</itemizedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Additional comments on the <literal>SetParameterName()</literal> method
</bridgehead>

<para>
You can add one additional argument of <literal>G4bool</literal> type for
every <literal>SetParameterName()</literal> method mentioned above. This
additional argument is named <literal>currentAsDefaultFlag</literal> and the
default value of this argument is <literal>false</literal>. If you assign
this extra argument as <literal>true</literal>, the default value of the
parameter will be overriden by the current value of the target
class.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.UIDefNew.ExpMess">
<title>
An example messenger
</title>

<para>
This example is of <emphasis>G4ParticleGunMessenger</emphasis>, which is  
made by inheriting <emphasis>G4UIcommand</emphasis>.

<example id="programlist_UIDefNew_1">
<title>
An example of <literal>G4ParticleGunMessenger.hh</literal>.
</title>

<programlisting>
#ifndef G4ParticleGunMessenger_h
#define G4ParticleGunMessenger_h 1

class G4ParticleGun;
class G4ParticleTable;
class G4UIcommand;
class G4UIdirectory;
class G4UIcmdWithoutParameter;
class G4UIcmdWithAString;
class G4UIcmdWithADoubleAndUnit;
class G4UIcmdWith3Vector;
class G4UIcmdWith3VectorAndUnit;

#include "G4UImessenger.hh"
#include "globals.hh"

class G4ParticleGunMessenger: public G4UImessenger
{
  public:
    G4ParticleGunMessenger(G4ParticleGun * fPtclGun);
    ~G4ParticleGunMessenger();
    
  public:
    void SetNewValue(G4UIcommand * command,G4String newValues);
    G4String GetCurrentValue(G4UIcommand * command);

  private:
    G4ParticleGun * fParticleGun;
    G4ParticleTable * particleTable;
    
  private: //commands
    G4UIdirectory *             gunDirectory;
    G4UIcmdWithoutParameter *   listCmd;
    G4UIcmdWithAString *        particleCmd;
    G4UIcmdWith3Vector *        directionCmd;
    G4UIcmdWithADoubleAndUnit * energyCmd;
    G4UIcmdWith3VectorAndUnit * positionCmd;
    G4UIcmdWithADoubleAndUnit * timeCmd;
    
};

#endif 
</programlisting>
</example>
</para>


<para>
<example id="programlist_UIDefNew_2">
<title>
An example of <literal>G4ParticleGunMessenger.cc</literal>.
</title>

<programlisting>
#include "G4ParticleGunMessenger.hh"
#include "G4ParticleGun.hh"
#include "G4Geantino.hh"
#include "G4ThreeVector.hh"
#include "G4ParticleTable.hh"
#include "G4UIdirectory.hh"
#include "G4UIcmdWithoutParameter.hh"
#include "G4UIcmdWithAString.hh"
#include "G4UIcmdWithADoubleAndUnit.hh"
#include "G4UIcmdWith3Vector.hh"
#include "G4UIcmdWith3VectorAndUnit.hh"
#include &lt;iostream.h&gt;

G4ParticleGunMessenger::G4ParticleGunMessenger(G4ParticleGun * fPtclGun)
:fParticleGun(fPtclGun)
{
  particleTable = G4ParticleTable::GetParticleTable();

  gunDirectory = new G4UIdirectory("/gun/");
  gunDirectory-&gt;SetGuidance("Particle Gun control commands.");

  listCmd = new G4UIcmdWithoutParameter("/gun/list",this);
  listCmd-&gt;SetGuidance("List available particles.");
  listCmd-&gt;SetGuidance(" Invoke G4ParticleTable.");

  particleCmd = new G4UIcmdWithAString("/gun/particle",this);
  particleCmd-&gt;SetGuidance("Set particle to be generated.");
  particleCmd-&gt;SetGuidance(" (geantino is default)");
  particleCmd-&gt;SetParameterName("particleName",true);
  particleCmd-&gt;SetDefaultValue("geantino");
  G4String candidateList; 
  G4int nPtcl = particleTable-&gt;entries();
  for(G4int i=0;i&lt;nPtcl;i++)
  {
    candidateList += particleTable-&gt;GetParticleName(i);
    candidateList += " ";
  }
  particleCmd-&gt;SetCandidates(candidateList);

  directionCmd = new G4UIcmdWith3Vector("/gun/direction",this);
  directionCmd-&gt;SetGuidance("Set momentum direction.");
  directionCmd-&gt;SetGuidance("Direction needs not to be a unit vector.");
  directionCmd-&gt;SetParameterName("Px","Py","Pz",true,true); 
  directionCmd-&gt;SetRange("Px != 0 || Py != 0 || Pz != 0");
  
  energyCmd = new G4UIcmdWithADoubleAndUnit("/gun/energy",this);
  energyCmd-&gt;SetGuidance("Set kinetic energy.");
  energyCmd-&gt;SetParameterName("Energy",true,true);
  energyCmd-&gt;SetDefaultUnit("GeV");
  energyCmd-&gt;SetUnitCandidates("eV keV MeV GeV TeV");

  positionCmd = new G4UIcmdWith3VectorAndUnit("/gun/position",this);
  positionCmd-&gt;SetGuidance("Set starting position of the particle.");
  positionCmd-&gt;SetParameterName("X","Y","Z",true,true);
  positionCmd-&gt;SetDefaultUnit("cm");
  positionCmd-&gt;SetUnitCandidates("micron mm cm m km");

  timeCmd = new G4UIcmdWithADoubleAndUnit("/gun/time",this);
  timeCmd-&gt;SetGuidance("Set initial time of the particle.");
  timeCmd-&gt;SetParameterName("t0",true,true);
  timeCmd-&gt;SetDefaultUnit("ns");
  timeCmd-&gt;SetUnitCandidates("ns ms s");
  
  // Set initial value to G4ParticleGun
  fParticleGun-&gt;SetParticleDefinition( G4Geantino::Geantino() );
  fParticleGun-&gt;SetParticleMomentumDirection( G4ThreeVector(1.0,0.0,0.0) );
  fParticleGun-&gt;SetParticleEnergy( 1.0*GeV );
  fParticleGun-&gt;SetParticlePosition(G4ThreeVector(0.0*cm, 0.0*cm, 0.0*cm));
  fParticleGun-&gt;SetParticleTime( 0.0*ns );
}
</programlisting>
</example>
<informalexample>
<programlisting>
G4ParticleGunMessenger::~G4ParticleGunMessenger()
{
  delete listCmd;
  delete particleCmd;
  delete directionCmd;
  delete energyCmd;
  delete positionCmd;
  delete timeCmd;
  delete gunDirectory;
}

void G4ParticleGunMessenger::SetNewValue(
  G4UIcommand * command,G4String newValues)
{
  if( command==listCmd )
  { particleTable-&gt;dumpTable(); }
  else if( command==particleCmd )
  {
    G4ParticleDefinition* pd = particleTable-&gt;findParticle(newValues);
    if(pd != NULL)
    { fParticleGun-&gt;SetParticleDefinition( pd ); }
  }
  else if( command==directionCmd )
  { fParticleGun-&gt;SetParticleMomentumDirection(directionCmd-&gt;
     GetNew3VectorValue(newValues)); }
  else if( command==energyCmd )
  { fParticleGun-&gt;SetParticleEnergy(energyCmd-&gt;
     GetNewDoubleValue(newValues)); }
  else if( command==positionCmd )
  { fParticleGun-&gt;SetParticlePosition(
     directionCmd-&gt;GetNew3VectorValue(newValues)); }
  else if( command==timeCmd )
  { fParticleGun-&gt;SetParticleTime(timeCmd-&gt;
     GetNewDoubleValue(newValues)); }
}

G4String G4ParticleGunMessenger::GetCurrentValue(G4UIcommand * command)
{
  G4String cv;
  
  if( command==directionCmd )
  { cv = directionCmd-&gt;ConvertToString(
     fParticleGun-&gt;GetParticleMomentumDirection()); }
  else if( command==energyCmd )
  { cv = energyCmd-&gt;ConvertToString(
     fParticleGun-&gt;GetParticleEnergy(),"GeV"); }
  else if( command==positionCmd )
  { cv = positionCmd-&gt;ConvertToString(
     fParticleGun-&gt;GetParticlePosition(),"cm"); }
  else if( command==timeCmd )
  { cv = timeCmd-&gt;ConvertToString(
     fParticleGun-&gt;GetParticleTime(),"ns"); }
  else if( command==particleCmd )
  { // update candidate list
    G4String candidateList; 
    G4int nPtcl = particleTable-&gt;entries();
    for(G4int i=0;i&lt;nPtcl;i++)
    {
      candidateList += particleTable-&gt;GetParticleName(i);
      candidateList += " ";
    }
    particleCmd-&gt;SetCandidates(candidateList);
  }
  return cv;
}
</programlisting>
</informalexample>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.UIDefNew.HowCont">
<title>
How to control the output of G4cout/G4cerr
</title>

<para>
Instead of <emphasis>cout</emphasis> and <emphasis>cerr</emphasis>, 
Geant4 uses <emphasis>G4cout</emphasis> and 
<emphasis>G4cerr</emphasis>. Output streams from
<emphasis>G4cout/G4cerr</emphasis> 
are handled by <emphasis>G4UImanager</emphasis> which allows the application
programmer to control the flow of the stream. Output strings may
therefore be displayed on another window or stored in a file. This
is accomplished as follows:

<orderedlist spacing="compact">
  <listitem><para>
    Derive a class from <emphasis>G4UIsession</emphasis> and implement the two
    methods:

    <para>
    <informalexample>
    <programlisting>
      G4int ReceiveG4cout(G4String coutString);
      G4int ReceiveG4cerr(G4String cerrString);
    </programlisting>
    </informalexample> 

    These methods receive the string stream of <emphasis>G4cout</emphasis> and
    <emphasis>G4cerr</emphasis>, respectively. The string can be handled to meet
    specific requirements. The following sample code shows how to make
    a log file of the output stream:

    <informalexample>
    <programlisting>
        ostream logFile;
        logFile.open("MyLogFile");
        G4int MySession::ReceiveG4cout(G4String coutString)
        {
          logFile &lt;&lt; coutString &lt;&lt; flush;
          return 0;
        }
    </programlisting>
    </informalexample>
    </para>
  </para></listitem>
  <listitem><para>
    <para>
    Set the destination of <emphasis>G4cout/G4cerr</emphasis> using
    <literal>G4UImanager::SetCoutDestination(session)</literal>.
    </para>
    <para>
    Typically this method is invoked from the constructor of
    <emphasis>G4UIsession</emphasis> and its derived classes, such as
    <emphasis>G4UIGAG/G4UIteminal</emphasis>. This method sets the destination of
    <emphasis>G4cout/G4cerr</emphasis> to the session. For example, when the
    following code appears in the constructor of <emphasis>G4UIterminal</emphasis>,
    the method <literal>SetCoutDestination(this)</literal> tells 
    <emphasis>UImanager</emphasis> that this instance of 
    <emphasis>G4UIterminal</emphasis> receives the stream
    generated by <emphasis>G4cout</emphasis>.

    <informalexample>
    <programlisting>
        G4UIterminal::G4UIterminal()
        {
          UI = G4UImanager::GetUIpointer();
          UI-&gt;SetCoutDestination(this);
          //  ...
        }
    </programlisting>
    </informalexample>    
 
    Similarly, <literal>UI-&gt;SetCoutDestination(NULL)</literal> must be added
    to the destructor of the class.
    </para>
  </para></listitem>
  <listitem><para>
    Write or modify the main program. To modify <literal>exampleN01</literal>
    to produce a log file, derive a class as described in step 1 above,
    and add the following lines to the main program:

    <informalexample>
    <programlisting>
        #include "MySession.hh"
        main()
        {
          // get the pointer to the User Interface manager
          G4UImanager* UI = G4UImanager::GetUIpointer();
          // construct a session which receives G4cout/G4cerr
          MySession * LoggedSession = new MySession;
          UI-&gt;SetCoutDestination(LoggedSession);
          // session-&gt;SessionStart(); // not required in this case
          // .... do simulation here ...

          delete LoggedSession;
          return 0;
        }
    </programlisting>
    </informalexample> 
  </para></listitem>
</orderedlist>
</para>

<note>
<para>
<emphasis>G4cout/G4cerr</emphasis> should not be used in the constructor of a
class if the instance of the class is intended to be used as
<literal>static</literal>. This restriction comes from the language
specification of C++. See the documents below for details:

<itemizedlist spacing="compact">
   <listitem><para>
     M.A.Ellis, B.Stroustrup, ``Annotated C++ Reference Manual'', Section 3.4
     <citation>
     <xref linkend="biblio.ellis1990" endterm="biblio.ellis1990.abbrev" />
     </citation>     
   </para></listitem>
   <listitem><para>
     P.J.Plauger, ``The Draft Standard C++ Library''
     <citation>
     <xref linkend="biblio.plauger1995" endterm="biblio.plauger1995.abbrev" />
     </citation>     
   </para></listitem>
</itemizedlist>
</para>
</note>


</sect2>
</sect1>