VAPoR  3.0.0
Public Types | Public Member Functions | Static Public Member Functions | List of all members
VAPoR::ParamsBase Class Reference

Nodes with state in Xml tree representation. More...

#include <ParamsBase.h>

Inheritance diagram for VAPoR::ParamsBase:
VAPoR::Box VAPoR::Params VAPoR::Viewpoint VAPoR::AnimationParams VAPoR::BasicParams VAPoR::RegionParams VAPoR::RenderParams VAPoR::ViewpointParams VAPoR::InstanceParams VAPoR::MouseModeParams VAPoR::VizWinParams VAPoR::ArrowParams VAPoR::HelloParams VAPoR::IsolineParams

Public Types

typedef int ParamsBaseType
 

Public Member Functions

 ParamsBase (XmlNode *parent, const string &name)
 
 ParamsBase (const string &name)
 Default constructor. More...
 
 ParamsBase (const ParamsBase &pbase)
 Copy constructor. More...
 
virtual ~ParamsBase ()
 destructor..destroys the xml tree based at the root node. More...
 
ParamNodeGetRootNode () const
 
const string GetName () const
 
virtual long GetValueLong (const string &tag, const vector< long > &defaultVal=_emptyLongVec)
 
virtual double GetValueDouble (const string &tag, const vector< double > &defaultVal=_emptyDoubleVec)
 
virtual const string GetValueString (const string &tag, const string &defaultVal=_emptyString)
 
virtual const vector< long > GetValueLongVec (const string &tag, const vector< long > &defaultVal=_emptyLongVec)
 
virtual const vector< double > GetValueDoubleVec (const string &tag, const vector< double > &defaultVal=_emptyDoubleVec)
 
virtual void GetValueStringVec (const string &tag, vector< string > &vec, const vector< string > &defaultVal=_emptyStringVec)
 
virtual int SetValueLong (string tag, const char *description, long value, Params *p)
 
virtual int SetValueLong (string tag, const char *description, const vector< long > &value, Params *p)
 
virtual int SetValueDouble (string tag, const char *description, double value, Params *p)
 
virtual int SetValueDouble (string tag, const char *description, const vector< double > &value, Params *p)
 
virtual int SetValueString (string tag, const char *description, const string &value, Params *p)
 
virtual int SetValueStringVec (string tag, const char *description, const vector< string > &value, Params *p)
 
ParamsBaseType GetParamsBaseTypeId ()
 
virtual void SetRootParamNode (ParamNode *pn)
 
ParamsBaseGetParamsBase (const vector< string > &path) const
 
int SetParamsBase (const vector< string > &path, ParamsBase *pbase)
 
int RemoveParamsBase (const vector< string > &path, ParamsBase *pbase)
 
Internal

Internal methods not intended for general use

void SetParent (XmlNode *parent)
 
virtual bool elementStartHandler (ExpatParseMgr *pm, int depth, string &tag, const char **attribs)
 
virtual bool elementEndHandler (ExpatParseMgr *pm, int depth, string &tag)
 
virtual ParamNodebuildNode ()
 
ParamNodeGetCurrentNode ()
 
ParamNodePush (string &tag, ParamsBase *pBase=0)
 
ParamNodePop ()
 
void Remove (const string &name)
 
const map< string, string > & GetAttributes ()
 
void Clear ()
 

Static Public Member Functions

static ParamsBaseType GetTypeFromTag (const string &tag)
 
static const string GetTagFromType (ParamsBaseType t)
 
static ParamsBaseCreateDefaultParamsBase (int pType)
 
static ParamsBaseCreateDefaultParamsBase (const string &tag)
 
static int RegisterParamsBaseClass (const string &tag, BaseCreateFcn fcn, bool isParams)
 
static int ReregisterParamsBaseClass (const string &tag, const string &newtag, bool isParams)
 
static int GetNumParamsClasses ()
 
static int GetNumBasicParamsClasses ()
 
static bool IsParamsTag (const string &tag)
 

Detailed Description

Nodes with state in Xml tree representation.

Author
John Clyne
Version
3.0
Date
March 2014

This is abstract parent of Params and related classes with state kept in an xml node. Used with the ParamNode class to support user-defined Params classes as well as other classes such as the TransferFunction class.

The ParamsBase class provides SetValue and GetValue methods supporting setting and retrieving values from an XML representation. In addition, the SetValue methods can be used to support Undo and Redo when a Params object is specified as its argument. Likewise the Params object is used to validate the SetValue() results by calling its Validate() method.
The Params class is derived from ParamsBase, which provides the association between a Params class and its representation as a set of (key,value) pairs. All the parameters in a ParamsBase instance are stored in an XML tree, and can be retrieved based on the value of the associated tag (key). Params instances have additional capabilities (not found in ParamsBase instances), including the Undo/Redo support and the ability to be associated with a tab in the gui. When it is desired to contain a class within a Params class (such as a Transfer Function within a RenderParams) then the embedded class should be derived from ParamsBase, so that its state will be represented in the state of the containing Params instance.
Implementers of VAPOR extensions may find it useful to implement classes that are contained in Params classes, and whose XML representation will then be a subtree of the root ParamNode of the Params class. These classes should be derived from ParamsBase, and can be included in many different Params classes. Examples of ParamsBase classes include TransferFunction, Box, and Viewpoint. When using a ParamsBase class in a Params instance, instances of the ParamsBase class should be created using the ParamsBase constructor; however these instances should be installed in the Params instance using ParamsBase::SetParamsBase(), which will insert the ParamsBase node at a specified location in the Params XML hierarchy. The ParamsBase instance can be retrieved using ParamsBase::GetParamsBase() and the ParamsBase instance can be changed using ParamsBase::SetParamsBase(). Programmers should not invoke destructors on such ParamsBase instances, as the deletion will be performed when necessary. The destructor of the ParamsBase instance is invoked whenever the Params instance is destroyed, or when the instance is replaced using ParamsBase::SetParamsBase().
See also
Box, Viewpoint, TransferFunction

Definition at line 90 of file ParamsBase.h.

Member Typedef Documentation

Definition at line 99 of file ParamsBase.h.

Constructor & Destructor Documentation

VAPoR::ParamsBase::ParamsBase ( XmlNode *  parent,
const string &  name 
)
VAPoR::ParamsBase::ParamsBase ( const string &  name)
inline

Default constructor.

Definition at line 101 of file ParamsBase.h.

VAPoR::ParamsBase::ParamsBase ( const ParamsBase pbase)

Copy constructor.

virtual VAPoR::ParamsBase::~ParamsBase ( )
virtual

destructor..destroys the xml tree based at the root node.

Member Function Documentation

virtual ParamNode* VAPoR::ParamsBase::buildNode ( )
virtual

Method to build an xml node from state. This only needs to be implemented if the state of the ParamsBase is not specified by the root ParamNode

Return values
nodeParamNode representing the current ParamsBase instance
void VAPoR::ParamsBase::Clear ( )

Remove (undefine) all parameters

This method deletes any and all paramters contained in the base class as well as deleting any tree branches.

static ParamsBase* VAPoR::ParamsBase::CreateDefaultParamsBase ( int  pType)
inlinestatic

Static method for constructing a default instance of a ParamsBase class based on the typeId.

Parameters
[in]pTypeTypeId of the ParamsBase instance to be created.
Return values
instancenewly created ParamsBase instance

Definition at line 352 of file ParamsBase.h.

static ParamsBase* VAPoR::ParamsBase::CreateDefaultParamsBase ( const string &  tag)
static

Static method for constructing a default instance of a ParamsBase class based on the Tag.

Parameters
[in]tagXML tag of the ParamsBase instance to be created.
Return values
instancenewly created ParamsBase instance
virtual bool VAPoR::ParamsBase::elementEndHandler ( ExpatParseMgr *  pm,
int  depth,
string &  tag 
)
virtual

Xml end tag parsing method

This method is called to handle parsing of an XML file. The contents of the file will replace any current parameter settings. The method is virtual so that derived classes may receive notification when an object instance has finished reseting state from an XML file. Override the default method if the class is not based on a hierarchy of ParamNode objects representing the XML representation of the class

See also
elementStartHandler
Return values
statusFalse indicates parse error
virtual bool VAPoR::ParamsBase::elementStartHandler ( ExpatParseMgr *  pm,
int  depth,
string &  tag,
const char **  attribs 
)
virtual

Xml start tag parsing method

This method is called to handle parsing of an XML file. The contents of the file will replace any current parameter settings. The method is virtual so that derived classes may receive notification when an object instance is reseting state from an XML file

Override this method if you are not using the ParamNode API to specify the state in terms of the xml representation of the class

See also
elementEndHandler
Return values
statusFalse indicates parse error
const map<string, string>& VAPoR::ParamsBase::GetAttributes ( )

Return the attributes associated with the current branch

Return values
mapattribute mapping
ParamNode* VAPoR::ParamsBase::GetCurrentNode ( )
inline

Return the current node in the parameter node tree

This method returns the current node in the parameter node tree.

See also
Push(), Pop()
Return values
nodeCurrent ParamNode

Definition at line 504 of file ParamsBase.h.

const string VAPoR::ParamsBase::GetName ( ) const
inline

Method for obtaining the name and/or tag associated with the instance

Definition at line 184 of file ParamsBase.h.

Referenced by VAPoR::Command::CaptureEnd().

static int VAPoR::ParamsBase::GetNumBasicParamsClasses ( )
inlinestatic

Static method to determine how many of the Basic Params classes are registered, ie. the number of Global params that are not associated with a tab.

Return values
countNumber of UndoRedo Params classes

Definition at line 401 of file ParamsBase.h.

static int VAPoR::ParamsBase::GetNumParamsClasses ( )
inlinestatic

Static method to determine how many Params classes are registered

Return values
countNumber of registered Params classes

Definition at line 395 of file ParamsBase.h.

ParamsBase* VAPoR::ParamsBase::GetParamsBase ( const vector< string > &  path) const

Obtain the ParamsBase instance at specified path from this root node.

Parameters
[in]vector<string>sequence of tags to specified ParamsBase, starting at the root node of the ParamsBase (or Params) containing the requested ParamsBase instance.
Return values
ParamsBase*instance at specified path, or NULL if does not exist.
ParamsBaseType VAPoR::ParamsBase::GetParamsBaseTypeId ( )
inline

Method for obtaining the type Id associated with a ParamsBase instance

Return values
intParamsBase TypeID for ParamsBase instance

Definition at line 332 of file ParamsBase.h.

ParamNode* VAPoR::ParamsBase::GetRootNode ( ) const
inline

Return the top (root) of the parameter node tree

This method returns the top node in the parameter node tree

Definition at line 177 of file ParamsBase.h.

Referenced by VAPoR::Command::CaptureEnd().

static const string VAPoR::ParamsBase::GetTagFromType ( ParamsBaseType  t)
static

Static method for converting a ParamsBase typeID to a Tag

Return values
stringTag (Name) associated with ParamsBase TypeID
static ParamsBaseType VAPoR::ParamsBase::GetTypeFromTag ( const string &  tag)
static

Static method for converting a Tag to a ParamsBase typeID

Return values
intParamsBase TypeID for Tag
virtual double VAPoR::ParamsBase::GetValueDouble ( const string &  tag,
const vector< double > &  defaultVal = _emptyDoubleVec 
)
inlinevirtual

Obtain a single value of type double associated with a tag. Optionally specify a vector of doubles whose first element is the default value if the value has not been assigned.

Parameters
[in]tagXML tag associated with the desired long parameter
[in]defaultVal(optional) const vector<double> to be assigned if specified element does not exist.
Return values
longvalue associated with the named parameter

Definition at line 205 of file ParamsBase.h.

virtual const vector<double> VAPoR::ParamsBase::GetValueDoubleVec ( const string &  tag,
const vector< double > &  defaultVal = _emptyDoubleVec 
)
inlinevirtual

Obtain a vector of values of type double associated with a tag. Optionally specify a vector of doubles which is the default value if the value has not been assigned.

Parameters
[in]tagXML tag associated with the desired double parameter
[in]defaultVal(optional) const vector<double>& to be assigned if specified element does not exist.
Return values
constvector<double> value associated with the named parameter

Definition at line 235 of file ParamsBase.h.

virtual long VAPoR::ParamsBase::GetValueLong ( const string &  tag,
const vector< long > &  defaultVal = _emptyLongVec 
)
inlinevirtual

Obtain a single value of type long associated with a tag. Optionally specify a vector of longs whose first element is the default value if the value has not been assigned.

Parameters
[in]tagXML tag associated with the desired long parameter
[in]defaultVal(optional) const vector<long> to be assigned if specified element does not exist.
Return values
longvalue associated with the named parameter

Definition at line 193 of file ParamsBase.h.

virtual const vector<long> VAPoR::ParamsBase::GetValueLongVec ( const string &  tag,
const vector< long > &  defaultVal = _emptyLongVec 
)
inlinevirtual

Obtain a vector of values of type long associated with a tag. Optionally specify a vector of longs as the default value if the value has not been assigned.

Parameters
[in]tagXML tag associated with the desired long parameter
[in]defaultVal(optional) const vector<long> to be assigned if specified element does not exist.
Return values
constvector<long>& value associated with the named parameter

Definition at line 225 of file ParamsBase.h.

virtual const string VAPoR::ParamsBase::GetValueString ( const string &  tag,
const string &  defaultVal = _emptyString 
)
inlinevirtual

Obtain a single value of type std::string associated with a tag. Optionally specify a string which will be the default value if the value has not been assigned.

Parameters
[in]tagXML tag associated with the desired string parameter
[in]defaultVal(optional) const string to be assigned if specified element does not exist.
Return values
conststring value associated with the named parameter

Definition at line 215 of file ParamsBase.h.

virtual void VAPoR::ParamsBase::GetValueStringVec ( const string &  tag,
vector< string > &  vec,
const vector< string > &  defaultVal = _emptyStringVec 
)
inlinevirtual

Obtain a vector of values of type string associated with a tag. Optionally specify a vector of string which is the default value if the value has not been assigned.

Parameters
[in]tagXML tag associated with the desired double parameter
[out]vector<string>&vec string vector to which the strings will be assigned.
[in]defaultVal(optional) const vector<double>& to be assigned if specified element does not exist.

Definition at line 245 of file ParamsBase.h.

static bool VAPoR::ParamsBase::IsParamsTag ( const string &  tag)
inlinestatic

Static method to determine if a ParamsBase class is a Params class

Parameters
[in]tagXML tag associated with ParamsBase class
Return values
statusTrue if the specified class is a Params class

Definition at line 407 of file ParamsBase.h.

ParamNode* VAPoR::ParamsBase::Pop ( )

Move up one level in the paramter tree

This method move back up the tree hierarchy by one level. Moving up past the root of the tree is prohibited and will silenty fail with no ill effects.

Return values
nodeReturns the new current node
See also
Pop(), Delete()
ParamNode* VAPoR::ParamsBase::Push ( string &  tag,
ParamsBase pBase = 0 
)

Move down a level in the parameter tree

The underlying storage model for parameter data is a hierarchical tree. By default the hierarchy is flat. This method can be used to add and navigate branches of the tree. Invoking this method makes the branch named by name the current branch (node). If the branch name does not exist it will be created with the name provided. Subsequent set and get methods will operate relative to the current branch. User-specific subtrees can be provided by extending this method

Parameters
[in]tagThe name of the branch
[in]pBaseoptional ParamsBase object to be associated with ParamNode
Return values
nodeReturns the new current node
See also
Pop(), Delete(), GetCurrentNode()
static int VAPoR::ParamsBase::RegisterParamsBaseClass ( const string &  tag,
BaseCreateFcn  fcn,
bool  isParams 
)
static

Static method for registering a ParamsBase class. This calls CreateDefaultInstance on the class.

Parameters
[in]tagTag of class to be registered
[in]fcnMethod that creates default instance of ParamsBase class
[in]isParamsset true if the ParamsBase class is derived from Params
Return values
classIDReturns the ParamsBaseClassId, or 0 on failure
void VAPoR::ParamsBase::Remove ( const string &  name)

Delete the named branch.

This method deletes the named child, and all decendents, of the current destroying it's contents in the process. The named node must be a child of the current node. If the named node does not exist the result is a no-op.

Parameters
[in]nameThe name of the branch
int VAPoR::ParamsBase::RemoveParamsBase ( const vector< string > &  path,
ParamsBase pbase 
)

Following method is to be used to remove a ParamsBase instance that is inside a Params (or ParamsBase) instance, The path from the root node as well as the ParamsBase instance must be specified. This will remove (and delete) the existing ParamsBase instance at specified path.

Parameters
[in]vector<string>sequence of tags to specified ParamsBase, starting at the root node of the ParamsBase (or Params) containing the requested ParamsBase instance.
[in]ParamsBase*pbase class instance to be set
Return values
0if successful, -1 otherwise
static int VAPoR::ParamsBase::ReregisterParamsBaseClass ( const string &  tag,
const string &  newtag,
bool  isParams 
)
static

Static method for registering a tag for an already registered ParamsBaseClass. This is needed for backwards compatibility when a tag is changed. The class must first be registered with the new tag.

Parameters
[in]tagTag of class to be registered
[in]newtagPreviously registered tag (new name of class)
[in]isParamsset true if the ParamsBase class is derived from Params
Return values
classIDReturns the ParamsBaseClassId, or 0 on failure
int VAPoR::ParamsBase::SetParamsBase ( const vector< string > &  path,
ParamsBase pbase 
)

Following method is to be used to specify a ParamsBase instance that will be inside a Params (or ParamsBase) instance, or to replace an existing ParamsBase instance. This is for example useful for inserting and/or replacing a Box or a Viewpoint in a Params instance. The path from the root node as well as the ParamsBase instance must be specified. This will replace (and delete) any existing ParamsBase instance at specified path. If there is no pre-existing node at the specified path, a new child is added as the last child of its parent. Constructs path to specified ParamsBase if it does not already exist.

Parameters
[in]vector<string>sequence of tags to specified ParamsBase, starting at the root node of the ParamsBase (or Params) containing the requested ParamsBase instance.
[in]ParamsBase*pbase class instance to be set
Return values
0if successful, -1 otherwise
void VAPoR::ParamsBase::SetParent ( XmlNode *  parent)

Set the parent node of the XmlNode tree.

Sets a new parent node for the XmlNode tree parameter data base. The parent node, parent, must have been previously initialized by passing it as an argument to the class constructor ParamBase(). This method permits wholesale changing of the entire parameter database.

Parameters
[in]parentParent XmlNode.
virtual void VAPoR::ParamsBase::SetRootParamNode ( ParamNode pn)
inlinevirtual

Specify the Root ParamNode of a ParamsBase instance

Parameters
[in]pnParamNode of new root

Definition at line 390 of file ParamsBase.h.

virtual int VAPoR::ParamsBase::SetValueDouble ( string  tag,
const char *  description,
double  value,
Params p 
)
virtual

Method for setting a single double value associated with a tag. This will capture the state of the Params argument before the value is set, then set the values, then Validate(), and finally capture the state of the Params after the Validate() Returns 0 if successful, -1 if the value cannot be set

See also
Validate()
Parameters
[in]stringtag
[in]char*description
[in]doublevalue
[in]Params*instance that contains the change; usually p is the invoker of this method
Return values
intzero if successful -1 if not
virtual int VAPoR::ParamsBase::SetValueDouble ( string  tag,
const char *  description,
const vector< double > &  value,
Params p 
)
virtual

Method for making a Set of double values associated with a tag. This will capture the state of the Params argument before the value is set, then set the values, then Validate(), and finally capture the state of the Params after the Validate() Returns 0 if successful, -1 if the value cannot be set

See also
Validate()
Parameters
[in]stringtag
[in]char*description
[in]vector<double>value
[in]Params*instance that contains the change; usually p is the invoker of this method
Return values
intzero if successful, -1 if not
virtual int VAPoR::ParamsBase::SetValueLong ( string  tag,
const char *  description,
long  value,
Params p 
)
virtual

Method for setting a single long value associated with a tag. This will capture the state of the Params argument before the value is set, then set the values, then Validate(), and captures the state of the Params after the Validate() in the Undo/Redo queue Returns 0 if successful, -1 if the value cannot be set

See also
Validate()
Parameters
[in]stringtag
[char*]description
[in]longvalue
[in]Params*instance that contains the change; usually p = (Params*)this.
Return values
intzero if successful, -1 if not
virtual int VAPoR::ParamsBase::SetValueLong ( string  tag,
const char *  description,
const vector< long > &  value,
Params p 
)
virtual

Method for setting long values associated with a tag. This will capture the state of the Params argument before the value is set, then set the values, then Validate(), and finally capture the state of the Params after the Validate() Returns 0 if successful, -1 if the value cannot be set

See also
Validate()
Parameters
[in]stringtag
[in]char*description
[in]vector<long>value
[in]Params*instance that contains the change; usually p = (Params*)this.
Return values
intzero if successful, -1 if not
virtual int VAPoR::ParamsBase::SetValueString ( string  tag,
const char *  description,
const string &  value,
Params p 
)
virtual

Method for making a Set of a single string value associated with a tag. This will capture the state of the Params argument before the value is set, then set the value, then Validate(), and finally capture the state of the Params after the Validate() Returns 0 if successful, -1 if the value cannot be set

See also
Validate()
Parameters
[in]stringtag
[in]char*description
[in]stringvalue
[in]Params*instance that contains the change; usually p is the invoker
Return values
intzero if successful, -1 if not
virtual int VAPoR::ParamsBase::SetValueStringVec ( string  tag,
const char *  description,
const vector< string > &  value,
Params p 
)
virtual

Method for making a Set of string values associated with a tag. This will capture the state of the Params argument before the value is set, then set the values, then Validate(), and finally capture the state of the Params after the Validate() Returns 0 if successful, -1 if the value cannot be set

See also
Params::Validate()
Parameters
[in]stringtag
[in]char*description
[in]vector<string>value
[in]Params*instance that contains the change; usually p is the invoker
Return values
intzero if successful, -1 if not

The documentation for this class was generated from the following file: