source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/UserActions/userInformationClasses.xml@ 1345

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Created by: Makoto Asai, 27-Nov-2004                  -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.UInfoCls">
<title>
User Information Classes
</title>

<para>
Additional user information can be associated with various Geant4
classes. There are basically two ways for the user to do this:

<itemizedlist spacing="compact">
  <listitem><para>
    derive concrete classes from base classes used in Geant4. These
    are classes for run, hit, digit, trajectory and trajectory point,
    which are discussed in 
    <xref linkend="sect.OptUAct" /> for G4Run, 
    <xref linkend="sect.Hits" /> for G4VHit,
    <xref linkend="sect.Digi" /> for G4VDigit, and
    <xref linkend="sect.Track.Traj" /> for G4VTrajectory and G4VTrajectoryPoint
  </para></listitem>
  <listitem><para>
    create concrete classes from provided abstract base classes and
    associate them with classes used in Geant4. Geant4 classes which
    can accommodate user information classes are G4Event, G4Track,
    G4PrimaryVertex, G4PrimaryParticle and G4Region. These classes are
    discussed here.
  </para></listitem>
</itemizedlist>
</para>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.UInfoCls.UEvtInfo">
<title>
G4VUserEventInformation
</title>

<para>
<emphasis>G4VUserEventInformation</emphasis> is an abstract class from 
which the user can derive his/her own concrete class for storing user
information associated with a G4Event class object. It is the
user's responsibility to construct a concrete class object and set
the pointer to a proper G4Event object.
</para>

<para>
Within a concrete implementation of G4UserEventAction, the
SetUserEventInformation() method of G4EventManager may be used to
set a pointer of a concrete class object to G4Event, given that the
G4Event object is available only by "pointer to const".
Alternatively, the user may modify the GenerateEvent() method of
his/her own RunManager to instantiate a G4VUserEventInformation
object and set it to G4Event.
</para>

<para>
The concrete class object is deleted by the Geant4 kernel when
the associated G4Event object is deleted.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.UInfoCls.UTkInfo">
<title>
G4VUserTrackInformation
</title>

<para>
This is an abstract class from which the user can derive his/her
own concrete class for storing user information associated with a
G4Track class object. It is the user's responsibility to construct
a concrete class object and set the pointer to the proper G4Track
object.
</para>

<para>
Within a concrete implementation of G4UserTrackingAction, the
SetUserTrackInformation() method of G4TrackingManager may be used
to set a pointer of a concrete class object to G4Track, given that
the G4Track object is available only by "pointer to const".
</para>

<para>
The ideal place to copy a G4VUserTrackInformation object from a
mother track to its daughter tracks is
<emphasis>G4UserTrackingAction::PostUserTrackingAction()</emphasis>.

<example id="programlist_UInfoCls_1">
<title>
Copying <literal>G4VUserTrackInformation</literal> from mother to daughter tracks
</title>

<programlisting>
void RE01TrackingAction::PostUserTrackingAction(const G4Track* aTrack)
{
  G4TrackVector* secondaries = fpTrackingManager-&gt;GimmeSecondaries();
  if(secondaries)
  {
    RE01TrackInformation* info = (RE01TrackInformation*)(aTrack-&gt;GetUserInformation());
    size_t nSeco = secondaries-&gt;size();
    if(nSeco&gt;0)
    {
      for(size_t i=0; i &lt; nSeco; i++)
      {
        RE01TrackInformation* infoNew = new RE01TrackInformation(info);
        (*secondaries)[i]-&gt;SetUserInformation(infoNew);
      }
    }
  }
}
</programlisting>
</example>
</para>

<para>
The concrete class object is deleted by the Geant4 kernel when
the associated G4Track object is deleted. In case the user wants to
keep the information, it should be copied to a trajectory
corresponding to the track.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.UInfoCls.UPrimVxTk">
<title>
G4VUserPrimaryVertexInformation and G4VUserPrimaryTrackInformation
</title>

<para>
These abstract classes allow the user to attach information
regarding the generated primary vertex and primary particle.
Concrete class objects derived from these classes should be
attached to <emphasis>G4PrimaryVertex</emphasis> and 
<emphasis>G4PrimaryParticle</emphasis> class objects, respectively.
</para>

<para>
The concrete class objects are deleted by the Geant4 Kernel when
the associated G4PrimaryVertex or G4PrimaryParticle class objects
are deleted along with the deletion of G4Event.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.UInfoCls.URegInfo">
<title>
G4VUserRegionInformation
</title>

<para>
This abstract base class allows the user to attach information
associated with a region. For example, it would be quite beneficial
to add some methods returning a boolean flag to indicate the
characteristics of the region (e.g. tracker, calorimeter, etc.).
With this example, the user can easily and quickly identify the
detector component.

<example id="programlist_UInfoCls_2">
<title>
A sample region information class
</title>

<programlisting>
class RE01RegionInformation : public G4VUserRegionInformation
{
  public:
    RE01RegionInformation();
    ~RE01RegionInformation();
    void Print() const;

  private:
    G4bool isWorld;
    G4bool isTracker;
    G4bool isCalorimeter;

  public:
    inline void SetWorld(G4bool v=true) {isWorld = v;}
    inline void SetTracker(G4bool v=true) {isTracker = v;}
    inline void SetCalorimeter(G4bool v=true) {isCalorimeter = v;}
    inline G4bool IsWorld() const {return isWorld;}
    inline G4bool IsTracker() const {return isTracker;}
    inline G4bool IsCalorimeter() const {return isCalorimeter;}
};
</programlisting>
</example>
</para>

<para>
The following code is an example of a stepping action. Here, a
track is suspended when it enters the "calorimeter region" from the
"tracker region".

<example id="programlist_UInfoCls_3">
<title>
Sample use of a region information class
</title>

<programlisting>
void RE01SteppingAction::UserSteppingAction(const G4Step * theStep)
{
  // Suspend a track if it is entering into the calorimeter

  // check if it is alive
  G4Track * theTrack = theStep-&gt;GetTrack();
  if(theTrack-&gt;GetTrackStatus()!=fAlive) { return; }

  // get region information
  G4StepPoint * thePrePoint = theStep-&gt;GetPreStepPoint();
  G4LogicalVolume * thePreLV = thePrePoint-&gt;GetPhysicalVolume()-&gt;GetLogicalVolume();
  RE01RegionInformation* thePreRInfo
   = (RE01RegionInformation*)(thePreLV-&gt;GetRegion()-&gt;GetUserInformation());
  G4StepPoint * thePostPoint = theStep-&gt;GetPostStepPoint();
  G4LogicalVolume * thePostLV = thePostPoint-&gt;GetPhysicalVolume()-&gt;GetLogicalVolume();
  RE01RegionInformation* thePostRInfo
   = (RE01RegionInformation*)(thePostLV-&gt;GetRegion()-&gt;GetUserInformation());

  // check if it is entering to the calorimeter volume
  if(!(thePreRInfo-&gt;IsCalorimeter()) &amp;&amp; (thePostRInfo-&gt;IsCalorimeter()))
  { theTrack-&gt;SetTrackStatus(fSuspend); }
}
</programlisting>
</example>
</para>


</sect2>
</sect1>