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

#include <ParamsBase.h>

Inheritance diagram for VAPoR::ParamsBase:

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...

ParamNode *	GetRootNode () 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)

ParamsBase *	GetParamsBase (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 ParamNode *	buildNode ()

ParamNode *	GetCurrentNode ()

ParamNode *	Push (string &tag, ParamsBase *pBase=0)

ParamNode *	Pop ()

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 ParamsBase *	CreateDefaultParamsBase (int pType)

static ParamsBase *	CreateDefaultParamsBase (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

typedef int VAPoR::ParamsBase::ParamsBaseType

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

node	ParamNode 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] pType TypeId of the ParamsBase instance to be created.

Return values

instance newly 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] tag XML tag of the ParamsBase instance to be created.

Return values

instance newly 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

status False 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

status False indicates parse error

const map<string, string>& VAPoR::ParamsBase::GetAttributes ( )

Return the attributes associated with the current branch

Return values

map	attribute 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

node	Current 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

count Number 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

count Number 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

int	ParamsBase 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

string Tag (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

int	ParamsBase 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]	tag	XML tag associated with the desired long parameter
[in]	defaultVal	(optional) const vector<double> to be assigned if specified element does not exist.

Return values

long	value 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]	tag	XML tag associated with the desired double parameter
[in]	defaultVal	(optional) const vector<double>& to be assigned if specified element does not exist.

Return values

const vector<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]	tag	XML tag associated with the desired long parameter
[in]	defaultVal	(optional) const vector<long> to be assigned if specified element does not exist.

Return values

long	value 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]	tag	XML tag associated with the desired long parameter
[in]	defaultVal	(optional) const vector<long> to be assigned if specified element does not exist.

Return values

const vector<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]	tag	XML tag associated with the desired string parameter
[in]	defaultVal	(optional) const string to be assigned if specified element does not exist.

Return values

const string 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]	tag	XML 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] tag XML tag associated with ParamsBase class

Return values

status True 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

node	Returns 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]	tag	The name of the branch
[in]	pBase	optional ParamsBase object to be associated with ParamNode

Return values

node	Returns 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]	tag	Tag of class to be registered
[in]	fcn	Method that creates default instance of ParamsBase class
[in]	isParams	set true if the ParamsBase class is derived from Params

Return values

classID Returns 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] name The 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

0	if 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]	tag	Tag of class to be registered
[in]	newtag	Previously registered tag (new name of class)
[in]	isParams	set true if the ParamsBase class is derived from Params

Return values

classID Returns 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

0	if 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] parent Parent XmlNode.

virtual void VAPoR::ParamsBase::SetRootParamNode ( ParamNode * pn )

inlinevirtual

Specify the Root ParamNode of a ParamsBase instance

Parameters

[in] pn ParamNode 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]	string	tag
[in]	char*	description
[in]	double	value
[in]	Params*	instance that contains the change; usually p is the invoker of this method

Return values

int	zero 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]	string	tag
[in]	char*	description
[in]	vector<double>	value
[in]	Params*	instance that contains the change; usually p is the invoker of this method

Return values

int	zero 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]	string	tag
	[char*]	description
[in]	long	value
[in]	Params*	instance that contains the change; usually p = (Params*)this.

Return values

int	zero 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]	string	tag
[in]	char*	description
[in]	vector<long>	value
[in]	Params*	instance that contains the change; usually p = (Params*)this.

Return values

int	zero 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]	string	tag
[in]	char*	description
[in]	string	value
[in]	Params*	instance that contains the change; usually p is the invoker

Return values

int	zero 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]	string	tag
[in]	char*	description
[in]	vector<string>	value
[in]	Params*	instance that contains the change; usually p is the invoker

Return values

int	zero if successful, -1 if not

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

/Users/clyne/src/vapor-3.0/include/vapor/ParamsBase.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation