#include <TreeParameter.h>
class CTreeParameter
{
CTreeParameter();
CTreeParameter(std::string name);
CTreeParameter(std::string name, std::string units);
CTreeParameter(std::string name, double lowLimit, double highLimit,
std::string units);
CTreeParameter(std::string name, UInt_t channels,
double lowLimit, double highLimit, std::string units);
CTreeParameter(std::string name, UInt_t resolution);
CTreeParameter(std::string name, UInt_t resolution,
double lowLimit, double widthOrHigh,
std::string units, bool widthOrHighGiven);
CTreeParameter(std::string name, const CTreeParameter& Template);
CTreeParameter(const CTreeParameter& rhs);
~CTreeParameter();
void Initialize(std::string name, UInt_t resolution);
void Initialize(std::string name, UInt_t resolution,
double lowLimit, double highOrWidth, std::string units,
bool highOrWidthGiven);
void Initialize(std::string name);
void Initialize(std::string name, std::string units);
void Initialize(std::string name, UInt_t channels,
double lowLimit, double highLimit, std::string units);
static void BindParameters();
static void setEvent(CEvent& rEvent);
bool isBound();
// Arithmetic operations...
operator double();
CTreeParameter& operator= (double newValue);
CTreeParameter& operator= (CTreeParameter& rhs);
CTreeParameter& operator+=(double rhs);
CTreeParameter& operator-=(double rhs);
CTreeParameter& operator*=(double rhs);
CTreeParameter& operator/=(double rhs);
double operator++(int dummy);
CTreeParameter& operator++();
double operator--(int dummy);
CTreeParameter& operator--();
std::string getName();
int getId();
double getValue();
void setValue(double newValue);
UInt_t getBins();
void setBins(UInt_t channels);
double getStart();
void setStart(double low);
double getStop();
void setStop(double high);
double getInc();
void setInc(double channelWidth);
std::string getUnit();
void setUnit(std::string units);
bool isValid();
void setInvalid();
void Reset();
void clear();
bool hasChanged();
void setChanged();
void resetChanged();
static void ResetAll();
static std::multimap<std::string, CTreeParameter*>::iterator begin();
static std::multimap<std::string, CTreeParameter*>::iterator end();
static std::multimap<std::string, CTreeParameter*>::iterator find(std::string name);
void Bind();
};
A CTreeParameter object is an alias
for an element of an event array. By providing this independent
alias:
CTreeParameter objects
can be organized into arbitrary structures
Additional metadata can be associated with the
parameter that's held by the CTreeParameter
object.
The life cycle of a tree parameter is that it is constructed and initialized. Some of the constructors provide for one step construction/initialization.
Once initialized the tree parameters need to be bound to the underlying parameters. This binding is many to one in the sense that two tree parameters may have the same name and will bind to the same underlying parameter. Binding involves associating a parameter id with the tree parameter object. If the parameter is already known to SpecTcl the existing Id is used. If not, a new parameter is created with an Id allocated by SpecTcl and the resulting Id is used to bind the tree parameter. SpecTcl will perform this binding late in its initialization process.
For each event SpecTcl processes, a CEvent
object must associated with the tree parameter subsystem.
This association tells the tree parameter exactly which element
of which CEvent object to fetch
when referenced or to set when assigned or modified.
The tree parameter methods are divided into several categories. The first set we will describe are constructors and initialization methods:
CTreeParameter();
Default constructor. This constructor requires
two phase initialization. That is at some point
opne of the Initialize
methods must be called to make this a usable
object.
Note that a constructed tree parameter can be reinitialized at any time, though if its name changes it must be bound again.
CTreeParameter( std::string name);
Constructs a tree parameter with a name and no
metadata. The metadata can be added later either by
invoking a Initialize
method or by invoking individual metadata setters.
Note if Initialize
is called with a different name after the object
has been bound, it must be bound again.
CTreeParameter( std::string name, std::string units);
Constructs a tree parameter specifying its
name and the
units of measure metadata.
CTreeParameter( std::string name, double lowLimit, double highLimit, std::string units);
Constructs a tree parameter named
name. Metadata is provided
that sets the range of the parameter to a low limit
of
lowLimit and high limit of
highLimit. The
units parameter specifies the
units of measure.
Note that parameter limits are always advisory limits. Nothing happens if the parameter is given a value outside those limits. Portions of the SpecTcl user interface, however, do use those limits to inform default choices for spectrum axis limits.
CTreeParameter( std::string name, UInt_t channels, double lowLimit, double highLimit, std::string units);
This constructor provides not only the parameter's name,
limits and units but also recommends that spectra
with this parameter on an axis allocate
channels channels for that axis.
CTreeParameter( std::string name, UInt_t resolution);
In this constructor, the metadata for the
tree parameter is the resolution.
This is well suited for a tree parameter that
reflects raw digitizer value.
The resolution specifies the
number of bits of data the digitizer provides.
This implies a parameter range of
[0, 2^resolution)
with a suggested channel count for a unit mapping
between parameter and spectrum coordinates.
CTreeParameter( std::string name, UInt_t resolution, double lowLimit, double widthOrHigh, std::string units, bool widthOrHighGiven);
Constructs a tree parameter with a rather complex
set of metadata that depends on the value of
the widthOrHeightGiven flag.
resolution specifies that the
spectrum channel recommendation is for
2^resolution
channels to be allocated on the axis.
The parameter (axis) low limit is recommended to
be lowLimit. The
widthOrHigh meaning depends
on the widthOrHighGiven.
If this is false,
widthOrHigh is the
recommended high limit for the parameter.
If true widthOrHigh
represents the width of each channel. The high limit
will be computed from widthOrHigh
and the resolution as follows:
lowLimit + widthorHigh * 2^resolution.
CTreeParameter( std::string name, const CTreeParameter& Template);
Constructs a new tree parameter that is a copy of
Template, except that it has
the name name. This can be
used to construct several parameters with the same
properties where a CTreeParameterArray
is not really appropriate for example:
CTreeParameter(const CTreeParameter& rhs);
Tree parameter copy constructor. Among other things, this allows a tree parameter to be passed by value to methods.
void Initialize( std::string name, UInt_t resolution);
,
void Initialize( std::string name, UInt_t resolution, double lowLimit, double highOrWidth, std::string units, bool highOrWidthGiven);
,
void Initialize( std::string name);
,
void Initialize( std::string name, std::string units);
,
void Initialize( std::string name, UInt_t channels, double lowLimit, double highLimit, std::string units);
These initialization methods support two stage
construction. The idea is that you could
construct a tree parameter using the default
constructor and then later complete construction
using the appropriate Initialize
method above. Note that with the exception
of the default constructor, each constructor has a
corresponding Initialize
method with arguments that have the same meaning
as in the construcor. Refer to the constructor
documentation for more information.
A CTreeParameter can be used
mostly as if it were a double precision
floating point value. Specifically, it has
a double method which can
convert the object into a double. It also supports
several types of arithmetic operations of the
compute-and-assign variety.
Note that those which require a right hand side parameter
(e.g. operator+=) take a
double. This in conjuntion with the
conversion operator alows the use of tree parameters
as well on the righ hand side.
Note as well that a CException
will be thrown if a method needs the value of the parameter
prior to it having been given a value.
operator double();
This is a conversion operator that extracts extracts and returns the double value of the parameter to which the object is bound for the current event.
CTreeParameter& operator= ( double newValue);
Gives the underlying parameter in the current
event the double precision value
newValue. Note that
CTreeParameter objects
or any other object with conversion operators
to doubles can also be on the right hand side
of this operator.
CTreeParameter& operator+=( double rhs);
Adds the double value on the right hand side of the += operator to the object's parameter in the current event. Returning a reference to the parameter allows operator chaining such as
tp1 = tp2 += 1234.0;
Where both tp1 and
tp2 are tree parameters.
CTreeParameter& operator-=(double rhs( double rhs);
Subtracts the rhs
from the object and returns a reference to the
object.
CTreeParameter& operator*=( double rhs);
Multiplies the object by the
rhs and returns a
reference to the object.
CTreeParameter& operator/=( double rhs);
Divides the value of the object by
rhs. A reference
to the object is returned.
double operator++( int dummy);
Provides a post decrement operator. Because
of the semantics of tree parameters, this is
not exactly possible. The value
of the parameter prior to incrementing it is
returned. That's why the return is a
double not a
CTreeParameter&
double f = tp++; // tp a tree parameter.
CTreeParameter& operator++();
Increments the value of the tree parameter object then returns a reference to that object. This is the normal pre-decrement semantics.
tp2 = ++tp1; // Both tp2 and tp1 tree parameters.
double operator--( int dummy);
Post decrement operator. Note that like the post increment operator, a double is returned, not a reference to the object or a copy of it.
CTreeParameter& operator--();
predecrement operator. The reference to the object is returned, after it is decremented.
Note that many of the arithmetic operations are not inplemented.
For example, there is no operator+.
This is because the operator double
makes those operations unecessary. For example, given
tree parameters tp1, tp2
tp1 = tp2 * 100 + 3.1416;
Is perfectly legal and does the right thing.
tp2 is replaced by its value due to the
operator double. The computation
produces a double and that is assigned to tp1
via operator=(double).
The next clump of methods are non arithmetic methods. These includes getters and setter for the metata the object has as well as tests that might be needed either to support some Tcl level commands or computation during an event processor.
std::string getName();
Returns the name of the tree parameter.
While it is possible to change the name of a tree parameter and then bind it to a different underlying parameter, that's not considered the way to do things (why not just instantiate a different tree parameter instead of flopping around the meaning of an existing one). Therefore, there is no method that directly just changes the name of a tree parameter.
int getId();
Returns the Id of the underlying parameter.
If the tree parameter has not yet been bound
to its parameter, this will throw a
CTreeException
(defined in CTreeException.h).
double getValue();
This is identical to the operator double
method. The value of the parameter is fetched.
CTreeException is thrown
if there is no current event
std::string is thrown if
the parameter has not yet been given a value
in the processing of this event.
void setValue( double newValue);
Sets the underlying parameter value to
newValue. This is identical
to operator=(double).
Note that CTreeException
is thrown if the object has not yet been bound
or there's no current event to get the value from.
UInt_t getBins();
,
void setBins( UInt_t channels);
Sets/Gets the number of recommended bins for an axis
on this parameter. channels
is the new suggested number of bins.
double getStart();
,
void setStart( double low);
Gets/Sets the suggested low limit for spectrum
axes on the parameter. low
will be the new suggested low limit.
Note that this and all parameter metadata can be set before the parameter is bound.
double getStop();
void setStop( double high);
Gets/Sets the suggested high limit
for spectrum axes on the parameter.
high will be the new
suggested high limit.
double getInc();
,
void setInc( double channelWidth);
Gets/Sets the channel width if the suggested
channel count, low and high limits are used for
spectrum parameters. The channel width is
in parameter coordinates. channelWidth
is a new channel width.
Note that this is computed metadata. The primitive
metadata are the low limit, high limit and
number of channels. There fore,
setInc is actually
modifying the suggested number of channels to
get the requested channel width.
std::string getUnit();
,
void setUnit( std::string units);
Gets/Sets the units of measure for the parameter.
units is the new
units of measure string for the parameter.
bool isValid();
Returns true if, for this event, the parameter has been given a value. This means that the parameter can be used in situations where it is an rvalue without throwing an exception
For this method to work, the parameter must be
bound and there must be a current event.
If either of these conditions is not met,
a CTreeException is
thrown.
void setInvalid();
,
void Reset();
,
void clear();
Invalidates the parameter for the current
event. Once invalidated, the parameter
will throw an std::string
exception if used as an r value prior to being
used as an l value.
CTreeException is thrown
if the parameter as either not been bound or
there is no current event.
bool hasChanged();
,
void setChanged();
,
void resetChanged();
Each tree parameter has a flag that is set
whenever any of the metadata for the parameter are
modified. hasChanged
returns the value of this boolean flag.
setChanged sets the flag
to true
and resetChanged
set the flag to false
static void ResetAll();
This is normally called by SpecTcl's event
processing subsystem before starting to
process each event. It iterates through
all tree parameters that have been defined and
invokes their Reset
method, which marks them as invalid.
Creating a CTreeParameter object
registers it with a static registry. This registry is
used by SpecTcl to, e.g. bind the tree parameters to
base parameters after initialization, and to
reset the validity on all parameters.
The following methods deal with this registry and parameter binding.
void Bind();
Binds this tree parameter to the underlying parameter. If no underlying parameter with the tree parameter's name exists, one is created and assigned a unique id.
Binding a tree parameter that has not been given a name yet binds the tree parameter to a parameter with an empty name string. This is perfectly legal but probably not what you want.
static void BindParameters();
Iterates through all registered
CTreeParameter objects
binding them to underlying parameters.
static void setEvent( CEvent& rEvent);
Sets the event that all tree parameters are
working on. All tree parameters share this
object. Parameter bindings supply each tree
parameter with a parameter id. When the value
of a parameter is retrieved/set/modified, that id
is the index into rEvent
that is accessed.
bool isBound();
If the object has been bound to its underlying parameter, this returns true. If not it returns false. Many tree parameter operations require tht the object be bound. Some also require there be a current event.
static std::multimap<std::string, CTreeParameter*>::iterator begin();
,
static std::multimap<std::string, CTreeParameter*>::iterator end();
Supports iteration through the tree parameter
registry by providing a start of iteration
iterator. Note that using an
std::multimap for the
registry cleanly supports the many to one mapping
of tree parameters to underlying parameters.
An iterator is a pointer like object.
In this case these pointer point to
std::pair<std::string, CTreeParameter*>
objects where the first element of the par is the
name of the tree parameter and the second is a
pointer to the tree parameter itself.
Iterators can be incremented. When incremented they point to the next item in the container. Note that multimap iterators will step through the map in key (parameter name) sort order. This means that all of the tree parameters that share the same name will be clumped together.
If an iterator points to the last item in the
collection, incrementing it will produce
an iterator that is equal to the iterator
returned from end
static std::multimap<std::string, CTreeParameter*>::iterator find( std::string name);
Returns an iterator to an element of the registry
that has the indicated name.
Note that more than one tree parameter can have
this name. In that case, this iterator will
point to the first of them. Incrementing the
iterator will get successive tree parameters
with the same name until either the end of the
multimap is reached or a tree parameter with a
different name is reached.
In practice this iteration over identically named tree parameters is not necessary because like named tree parameters share underlying metadata and data and parameter bindings make each such object interchangeable with the others.