A Property<T> is a serializable (name, list-of-values) pair, where each value is of type T. More...

#include <Property.h>

Inheritance diagram for OpenSim::Property< T >:

Classes
struct	TypeHelper
	This is the generic definition of Property::TypeHelper to be used whenever T does not have a specialization, meaning that T must be a type derived from class Object. More...

Public Member Functions
Property *	clone () const override=0
	Make a new, deep copy (clone) of this concrete property and return a pointer to the heap space. More...

std::string	getTypeName () const final
	Use TypeHelper's getTypeName() to satisfy this pure virtual. More...

const T &	operator[] (int i) const
	Get a const reference to one of the values in the value list. More...

T &	operator[] (int i)
	Get a writable reference to one of the values in the value list. More...

Property &	operator= (const T &value)
	Assignment to a value of type T sets the value of this single-valued property to a copy of the supplied value; not allowed for a list property. More...

template<template< class > class Container>
Property &	operator= (const Container< T > &valueList)
	Assignment to a container of values of type T sets the entire value list of this list property to a copy of the values in the container. More...

void	setValue (int i, const T &value)
	Replace the i'th value list element with a copy of the given value. More...

void	setValue (const T &value)
	Provide a new value for a single-valued property. More...

template<template< class > class Container>
void	setValue (const Container< T > &valueList)
	Assignment to a container of values of type T sets the entire value list of this list property to a copy of the values in the container. More...

const T &	getValue (int index=-1) const
	Return a const reference to the selected value from this property's value list. More...

T &	updValue (int index=-1)
	Return a writable reference to the selected value from this property's value list. More...

int	appendValue (const T &value)
	Append a copy of the supplied value to the end of this property's value list. More...

int	appendValue (const T *value)
	Append a copy of the supplied value to the end of this property's value list. More...

int	adoptAndAppendValue (T *value)
	Add a new value to the end of this property's value list, taking over ownership of the supplied heap-allocated object. More...

int	findIndex (const T &value) const
	Search the value list for an element that has the given value and return its index if found, otherwise -1. More...

Public Member Functions inherited from OpenSim::AbstractProperty
void	setAllowableListSize (int aMin, int aMax)
	Require that the number of values n in the value list of this property be in the range aMin <= n <= aMax. More...

void	setAllowableListSize (int aNum)
	Require that the number of values n in the value list of this property be exactly n=aNum values. More...

virtual	~AbstractProperty ()
	Return all heap space used by this property. More...

virtual std::string	toString () const =0
	For relatively simple types, return the current value of this property in a string suitable for displaying to a user in the GUI. More...

virtual bool	isObjectProperty () const =0
	Return true if this is an "object property", meaning that its values are all concrete objects of types that ultimately derive from the OpenSim serializable base class Object. More...

virtual bool	isUnnamedProperty () const =0
	An unnamed property is a one-object property whose name was given as null or as the contained object's type tag. More...

bool	equals (const AbstractProperty &other) const
	Compare this property with another one; this is primarily used for testing. More...

bool	isSamePropertyClass (const AbstractProperty &other) const
	Return true if the other property is an object of exactly the same concrete class as this one. More...

bool	operator== (const AbstractProperty &other) const
	See the equals() method for the meaning of this operator. More...

void	setAllPropertiesUseDefault (bool shouldUseDefault)
	This method sets the "use default" flag for this property and the properties of any objects it contains to the given value. More...

void	readFromXMLParentElement (SimTK::Xml::Element &parent, int versionNumber)
	Given an XML parent element expected to contain a value for this property as an immediate child element, find that property element and set the property value from it. More...

void	writeToXMLParentElement (SimTK::Xml::Element &parent)
	Given an XML parent element, append a single child element representing the serialized form of this property. More...

void	setName (const std::string &name)
	Set the property name. More...

void	setComment (const std::string &aComment)
	Set a user-friendly comment to be associated with property. More...

void	setValueIsDefault (bool isDefault)
	Set flag indicating whether the value of this property was simply taken from a default object and thus should not be written out when serializing. More...

const std::string &	getName () const
	Get the property name. More...

const std::string &	getComment () const
	Get the comment associated with this property. More...

bool	getValueIsDefault () const
	Get the flag indicating whether the current value is just the default value for this property (in which case it doesn't need to be written out). More...

int	getMinListSize () const
	Get the minimum number of values allowed in this property's value list. More...

int	getMaxListSize () const
	Get the maximum number of values allowed in this property's value list. More...

bool	isOptionalProperty () const
	This is an "optional" property if its value list can contain at most one value. More...

bool	isListProperty () const
	This is a "list" property if its value list can contain more than one value. More...

bool	isOneValueProperty () const
	This is a "one-value" property if its value list must always contain exactly one value. More...

bool	isOneObjectProperty () const
	This is a "one-object" property if it is a "one-value" property and it contains an Object-derived value. More...

int	size () const
	Return the number of values currently in this property's value list. More...

bool	empty () const
	Return true if this property's value list is currently empty. More...

void	clear ()
	Empty the value list for this property; fails if zero is not an allowable size for this property. More...

virtual const Object &	getValueAsObject (int index=-1) const =0
	For an object property, the values can be obtained as references to the abstract base class Object from which all the objects derive. More...

virtual Object &	updValueAsObject (int index=-1)=0
	Get writable access to an existing object value. More...

virtual void	setValueAsObject (const Object &obj, int index=-1)=0
	Set the indicated value element to a new copy of the supplied object. More...

template<class T >
const T &	getValue (int index=-1) const
	Return one of the values in this property as type T; this works only if the underlying concrete property stores type T and if the indexed element is present, otherwise throws an exception. More...

template<class T >
T &	updValue (int index=-1)
	Return a writable reference to one of the values in this property as type T; this works only if the underlying concrete property is actually of type T and the indexed element is present. More...

template<class T >
int	appendValue (const T &value)
	Append a new value of type T to the end of the list of values currently contained in this property. More...

Static Public Member Functions
static bool	isA (const AbstractProperty &prop)
	Return true if the given AbstractProperty references a concrete property of this type (Property<T>). More...

static const Property &	getAs (const AbstractProperty &prop)
	Downcast the given AbstractProperty to a concrete property of this type (Property<T>). More...

static Property &	updAs (AbstractProperty &prop)
	Downcast the given AbstractProperty to a writable concrete property of this type (Property<T>). More...

Related Functions
(Note that these are not member functions.)
#define	OpenSim_DECLARE_PROPERTY(name, T, comment)
	Declare a required, single-value property of the given name and type T, with an associated comment. More...

#define	OpenSim_DECLARE_UNNAMED_PROPERTY(T, comment)
	Declare a required, unnamed property holding exactly one object of type T derived from OpenSim's Object class and identified by that object's class name rather than a property name. More...

#define	OpenSim_DECLARE_OPTIONAL_PROPERTY(name, T, comment)
	Declare a property of the given name containing an optional value of the given type T (that is, the value list can be of length 0 or 1 only). More...

#define	OpenSim_DECLARE_LIST_PROPERTY(name, T, comment)
	Declare a property of the given name containing a variable-length list of values of the given type T. More...

#define	OpenSim_DECLARE_LIST_PROPERTY_SIZE(name, T, listSize, comment)
	Declare a property of the given name containing a list of values of the given type T, with the number of values in the list restricted to be exactly listSize (> 0) elements, no more or less. More...

#define	OpenSim_DECLARE_LIST_PROPERTY_ATLEAST(name, T, minSize, comment)
	Declare a property of the given name containing a list of values of the given type T, with the number of values required to be at least minSize (> 0) elements. More...

#define	OpenSim_DECLARE_LIST_PROPERTY_ATMOST(name, T, maxSize, comment)
	Declare a property of the given name containing a list of values of the given type T, with the number of values in the list restricted to be no more than maxSize (> 0) elements. More...

#define	OpenSim_DECLARE_LIST_PROPERTY_RANGE(name, T, minSize, maxSize, comment)
	Declare a property of the given name containing a list of values of the given type T, with the number of values in the list restricted to be in the range minSize (> 0) to maxSize (> minSize). More...

Additional Inherited Members
Protected Member Functions inherited from OpenSim::AbstractProperty
	AbstractProperty ()

	AbstractProperty (const std::string &name, const std::string &comment)

virtual bool	isEqualTo (const AbstractProperty &other) const =0
	The base class equals() method will have already done a lot of checking prior to calling this method, including verifying that both values are non-default and that the value lists are the same size; the concrete property need only compare the values. More...

virtual void	readFromXMLElement (SimTK::Xml::Element &propertyElement, int versionNumber)=0
	Read in a new value for this property from the XML element propertyElement. More...

virtual void	writeToXMLElement (SimTK::Xml::Element &propertyElement) const =0
	Output a serialized representation of this property by writing its value to the given XML property element. More...

virtual int	getNumValues () const =0
	How may values are currently stored in this property? If this is an object property you can use this with getValueAsObject() to iterate over the contained objects. More...

virtual void	clearValues ()=0
	If the concrete property allows it, clear the value list. More...

virtual bool	isAcceptableObjectTag (const std::string &objectTypeTag) const =0
	Return true if the given string is the XML tag name for one of the Object-derived types that is allowed by this property. More...

Detailed Description

template<class T>
class OpenSim::Property< T >

A Property<T> is a serializable (name, list-of-values) pair, where each value is of type T.

The number of values allowed in the list is an attribute of the property; often it is just a single value. Properties are owned by classes that derive from OpenSim's serializable Object base class. The documentation here is most useful for developers who are interested in creating a new ModelComponent or other serializable class derived from Object.

A property's contained type T must be a serializable type. Serializable types come in two flavors:

simple types (like int or string) for which serialization instructions have been provided, and
object types, in which case type T derives from Object and knows how to serialize itself.

When T is a simple type we'll write T=S and refer to a Property<S> as a "simple property". When T is an object type, we'll write T=O and refer to a Property<O> as an "object property".

In case type O is a still-abstract Object-derived type like Function or Controller, a Property<O> can hold a mix of any concrete objects derived from O (e.g., any Object that can be dynamic_cast to a Function can be held by a Property<Function>).

The objects in an object property will themselves have properties so a Property<O> can be viewed as a node in the tree of objects that constitute an OpenSim Model. Simple properties Property<S> can be viewed as the terminal nodes of that tree. Properties are thus an integral part of the structure of an OpenSim Model; anything contained in a property is owned by that property; deleting the property deletes its contained objects. If you want to reference another Object from within a property, use a string property to reference it by name; the result is a simple property. It is not permitted for type T to be a pointer or reference.

XML file representation of properties

The general representation for a Property<T> with name "prop_name" is

<prop_name> T T ... T </prop_name>

where "T" is the XML representation for objects of type T. Note that if T is an object type O, its representation follows the pattern

<OTypeName> OContents </OTypeName>

where OTypeName stands for the name of the concrete, Object-derived class being serialized, and OContents is the representation generated by that class when asked to serialize itself.

A Property<O> that is restricted to holding exactly one object of type O is called a "one-object property". It could be represented in XML as

<prop_name> <OTypeName> OContents </OTypeName> </prop_name>

but we allow a more compact representation for one-object properties:

<OTypeName name="prop_name"> OContents </OTypeName>

In the one-object case it is also permissible for the property to be unnamed, in which case it may be referenced as though its name were the same as the object type name, and there is no separate "name" attribute. The XML representation for an unnamed property is just:

<OTypeName> OContents </OTypeName>

On input, if a name attribute is seen for an unnamed property it is ignored; only the object type name tag matters in the unnamed case. Note that only one-object properties can be unnamed, and no single OpenSim object can have more than one unnamed property of the same type.

Property attributes

In addition to the name and list of values, every property has the following attributes:

A comment string, provided at the time the property is created.
The minimum and maximum number of values allowed.
A "used default value" flag.

The "used default value" flag specifies that the value stored with this property was taken from a default object and not subsequently changed. A property with this flag set is not written out when a model is serialized.

How to declare properties in your class declaration

Properties are maintained in a PropertyTable by OpenSim's Object base class that is used for all serializable objects. Do not create Property objects directly; instead, use the provided macros to declare them in the class declarations for objects derived from Object. These macros should appear in the header file near the top of your class declaration, and should be preceded by Doxygen comments describing the property being declared.

Naming conventions: OpenSim property names should use lower case letters with words_separated_by_underscores. In contrast, OpenSim object types begin with a capital letter and use camel case, that is, MixedUpperAndLowerLikeThis. This prevents any possible collisions between property names and object types, allowing both to be used as XML tag identifiers with no conflicts.

These are the most common forms of property declaration. Click on the macro names below for more information.

// Exactly one value required; this is the basic property type.
OpenSim_DECLARE_PROPERTY(name, T, "property description");
// Zero or one value only.
OpenSim_DECLARE_OPTIONAL_PROPERTY(name, T, "property description");
// Zero or more values.
OpenSim_DECLARE_LIST_PROPERTY(name, T, "property description");

In the above, T may be a simple type S or object type O. In the case of a single-value property where type T is a type derived from Object (i.e., T=O), you can declare the property to be unnamed and instead use the class name of the object type O to identify the property:

// Exactly one value of object type O required.

OpenSim_DECLARE_UNNAMED_PROPERTY(O, "property description");

Only one unnamed property of a particular object type O may be declared in any given Object.

Finally, for list properties you can declare restrictions on the allowable list length:

// List must contain exactly listSize (> 0) elements.
OpenSim_DECLARE_LIST_PROPERTY_SIZE(name, T, listSize, 
                                   "property description");
// List must contain at least minSize (> 0) elements.
OpenSim_DECLARE_LIST_PROPERTY_ATLEAST(name, T, minSize, 
                                      "property description");
// List must contain at most maxSize (> 0) elements.
OpenSim_DECLARE_LIST_PROPERTY_ATMOST(name, T, maxSize, 
                                     "property description");
// List must contain between minSize (> 0) and maxSize (>minSize) elements.
OpenSim_DECLARE_LIST_PROPERTY_RANGE(name, T, minSize, maxSize, 
                                    "property description");

Here is an example of an object declaring two properties, including our convention of documenting the property declarations in their own Doxygen group entitled "Property declarations".

///  class ActuatorWorkMeter : public ModelComponent {
///  OpenSim_DECLARE_CONCRETE_OBJECT(ActuatorWorkMeter, ModelComponent);
///  public:
///  //=======================================================================
///  // PROPERTIES
///  //=======================================================================
///      /** @name Property declarations
///      These are the serializable properties associated with this class. **/
///      /**@{**/
///      OpenSim_DECLARE_PROPERTY(actuator_name, std::string,
///          "The name of the actuator whose work use will be calculated.");
///      OpenSim_DECLARE_PROPERTY(initial_actuator_work, double,
///          "Initial value for work; normally zero.");
///      /**@}**/
///  //=======================================================================
///  // PUBLIC METHODS
///  //=======================================================================
///      ...
///  };
///

How to construct properties in your constructors

The constructors for your Object-derived class are required to construct and initialize the properties to whatever default values you want them to have. The above macros will have generated for each property a method for this purpose. If your property is named prop_name, then the method will be called constructProperty_prop_name(). (In the case of unnamed properties, the object type serves as prop_name.) The initial value is provided as an argument, which is optional for those properties that are allowed to contain a zero-length value list. Here are the various types of generated construction methods:

// Construct and initialize a single-valued property containing type T.
void constructProperty_prop_name(const T& value);
// Construct a property with a zero-length value list. 
void constructProperty_prop_name();
// Construct a list property, initializing from a container.
template <template <class> class Container>
void constructProperty_prop_name(const Container<T>& valueList);

The first form above is generated for basic, optional, and unnamed properties. The second, uninitialized form is generated for optional, unrestricted list, and list "atmost" properties, since those can accept a zero-element value list. The last form is generated for all list properties, regardless of size restriction; a runtime check verifies that size restrictions are met. That form accepts any container type that supports a size() method and random access element selection with operator[], such as std::vector<T>, OpenSim::Array<T>, or SimTK::Array_<T>.

The above methods are conventionally collected into a private method of each object class called constructProperties(). This method is then invoked from every constructor, except the copy constructor (which you normally should let the compiler generate, but see below).

Copy constructor and copy assignment operator

Your best bet is to use the compiler-generated default copy constructor and default copy assignment operator that you get whenever you leave these methods undefined. If you do that, all your properties and their associated local data will be copied automatically. It is worth some effort to design your objects so that their data members can copy and assign themselves correctly; you might find SimTK::ReferencePtr<T> and SimTK::ClonePtr<T> useful for getting pointer members to behave themselves properly.

However, if you do have to write your own copy constructor and copy assignment operator (and if you write one you must write the other also), the property table will still have been copied properly by your superclass, it is only the local property indices that you have to deal with. For that, each property has defined a method like:

// Copy the local data member associated with property prop_name.

void copyProperty_prop_name(const Self& source);

In the above, Self is the type of the object being defined and source is the argument that was passed to the containing copy constructor or copy assignment operator.

Runtime access to property values

The property declaration macros also generate per-property methods for getting access to property values or the the Property objects themselves. These inline methods are very fast and can be used whenever you need access to a property value. The following are generated for single-valued property types, including the basic, optional, and unnamed properties:

// Get a const reference to the value of a single-valued property 
// named "prop_name" (basic, optional, unnamed properties only).
const T& get_prop_name() const;
// Same, but returns a writable reference.
T& upd_prop_name();
// Set the value of a single-valued property.
void set_prop_name(const T& value);

Additional methods are generated for list properties:

// Get a const reference to the i'th element in a list property's value 
// list.
const T& get_prop_name(int i) const;
// Same, but returns a writable reference.
T& upd_prop_name(int i);
// Set the i'th element of a list property to the given value. Only 
// allowed if the list currently has at least i elements, so no gaps can
// be created with this method.
void set_prop_name(int i, const T& value);
// Use this to append one element to a list property's value list; the
// assigned index is returned.
int append_prop_name(const T& value);
// Use this to set all the values of a list-valued property.
template <template <class> class Container>
void set_prop_name(const Container<T>& valueList);

The last form accepts any container that has a size() method and allows element access using operator[]. Runtime checks verify that the list length is within the allowable range for the property. Note that every property is considered to have a value list (even when restricted to one element) so the indexed forms above can also be used with single-valued properties as long as the index is zero.

To get access to the Property object rather than one of its values, the following methods are provided:

// Get a const reference to the Property<T> object for "prop_name".
const Property<T>& getProperty_prop_name() const;
// Same, but returns a writable reference.
Property<T>& updProperty_prop_name();

The Property<T> class acts as a container of values, and has the usual size(), empty(), and operator[] methods available so you can use getProperty...() above to get access to those methods. For example, to write out all the values of any property:

// Assumes type T can be written to a stream with operator<<.
for (int i=0; i < getProperty_prop_name().size(); ++i)
    std::cout << get_prop_name(i) << std::endl;

See Also: OpenSim::Object, OpenSim::AbstractProperty

Author: Michael Sherman

Member Function Documentation

template<class T>

int OpenSim::Property< T >::adoptAndAppendValue ( T * value)

inline

Add a new value to the end of this property's value list, taking over ownership of the supplied heap-allocated object.

An exception is thrown if the property can't hold any more values. The index assigned to this value is returned.

References OpenSim::AbstractProperty::getMaxListSize(), OpenSim::AbstractProperty::getName(), OpenSim::AbstractProperty::getNumValues(), and OpenSim::AbstractProperty::setValueIsDefault().

template<class T>

int OpenSim::Property< T >::appendValue ( const T & value)

inline

Append a copy of the supplied value to the end of this property's value list.

An exception is thrown if the property can't hold any more values. The index assigned to this value is returned.

References OpenSim::AbstractProperty::getMaxListSize(), OpenSim::AbstractProperty::getName(), OpenSim::AbstractProperty::getNumValues(), and OpenSim::AbstractProperty::setValueIsDefault().

Referenced by OpenSim::Object::addListProperty(), OpenSim::Object::addOptionalProperty(), OpenSim::Object::addProperty(), OpenSim::AbstractProperty::appendValue(), and OpenSim::Property< T >::setValue().

template<class T>

int OpenSim::Property< T >::appendValue ( const T * value)

inline

Append a copy of the supplied value to the end of this property's value list.

An exception is thrown if the property can't hold any more values. The index assigned to this value is returned. Note that although we accept a pointer here, we do not take over ownership. See adoptAndAppendValue() if you want the property to take ownership.

References OpenSim::AbstractProperty::getMaxListSize(), OpenSim::AbstractProperty::getName(), OpenSim::AbstractProperty::getNumValues(), and OpenSim::AbstractProperty::setValueIsDefault().

template<class T>

Property* OpenSim::Property< T >::clone ( ) const

overridepure virtual

Make a new, deep copy (clone) of this concrete property and return a pointer to the heap space.

Caller must delete the returned object when done with it.

Implements OpenSim::AbstractProperty.

template<class T>

int OpenSim::Property< T >::findIndex ( const T & value) const

inline

Search the value list for an element that has the given value and return its index if found, otherwise -1.

This requires only that the template type T supports operator==(). This is a linear search so will take time proportional to the length of the value list.

References OpenSim::AbstractProperty::getNumValues(), and OpenSim::Property< T >::getValue().

template<class T>

static const Property& OpenSim::Property< T >::getAs ( const AbstractProperty< T > & prop)

inlinestatic

Downcast the given AbstractProperty to a concrete property of this type (Property<T>).

An exception is thrown if this is not the right type only in DEBUG mode; see isA() if you need to check first.

References OpenSim::AbstractProperty::getName().

Referenced by OpenSim::PropertyTable::getProperty().

template<class T >

std::string OpenSim::Property< T >::getTypeName ( ) const

inlinefinalvirtual

Use TypeHelper's getTypeName() to satisfy this pure virtual.

Implements OpenSim::AbstractProperty.

template<class T>

const T& OpenSim::Property< T >::getValue ( int index = -1) const

inline

Return a const reference to the selected value from this property's value list.

If the property is at most single valued then the index is optional and we'll behave as though index=0 were supplied. You can use the square bracket operator property[index] instead.

References OpenSim::AbstractProperty::getMaxListSize().

Referenced by OpenSim::Property< T >::findIndex(), OpenSim::AbstractProperty::getValue(), and OpenSim::Property< T >::operator[]().

template<class T>

static bool OpenSim::Property< T >::isA ( const AbstractProperty< T > & prop)

inlinestatic

Return true if the given AbstractProperty references a concrete property of this type (Property<T>).

Note that for this to return true, the type T must be exactly the type used when the concrete property was allocated; it is not sufficient for T to be a more general base type from which the actual type was derived.

template<class T>

Property& OpenSim::Property< T >::operator= ( const T & value)

inline

Assignment to a value of type T sets the value of this single-valued property to a copy of the supplied value; not allowed for a list property.

This does not invoke the assignment operator on the existing value. Instead, the value list is cleared and then replaced by the new value. This is synonymous with setValue(value).

References OpenSim::Property< T >::setValue().

template<class T>

template<template< class > class Container>

Property& OpenSim::Property< T >::operator= ( const Container< T > & valueList)

inline

Assignment to a container of values of type T sets the entire value list of this list property to a copy of the values in the container.

The current value list is cleared before the assignment. This is synonymous with setValue(valueList).

References OpenSim::Property< T >::setValue().

template<class T>

const T& OpenSim::Property< T >::operator[] ( int i) const

inline

Get a const reference to one of the values in the value list.

This will throw an exception if the index does not refer to an already-existing value. This operator is synonymous with getValue(i).

References OpenSim::Property< T >::getValue().

template<class T>

T& OpenSim::Property< T >::operator[] ( int i)

inline

Get a writable reference to one of the values in the value list.

This will throw an exception if the index does not refer to an already-existing value. This operator is synonymous with updValue(i).

References OpenSim::Property< T >::updValue().

template<class T>

void OpenSim::Property< T >::setValue	(	int	i,
		const T &	value
	)

inline

Replace the i'th value list element with a copy of the given value.

The index i must be between 0 and the current list length, meaning it is OK to refer one element past the last element. In that case the new value is appended to the list using appendValue(), which will throw an exception if the list is already at its maximum allowable size. In the case where index i refers to an existing element, a simple property will assign a new value to the existing element but an object property will delete the old object and replace it with a clone() of the new one – it will not invoke the old object's assignment operator. That means that the concrete object type may be changed by this operation, provided it is still a type derived from object type T. If you want to invoke the existing value's assignment operator, use updValue(i) rather than setValue(i).

References OpenSim::Property< T >::appendValue(), OpenSim::AbstractProperty::getName(), OpenSim::AbstractProperty::getNumValues(), and OpenSim::AbstractProperty::setValueIsDefault().

Referenced by OpenSim::Property< T >::operator=(), and OpenSim::Property< T >::setValue().

template<class T>

void OpenSim::Property< T >::setValue ( const T & value)

inline

Provide a new value for a single-valued property.

The current value (if any) is replaced, and size()==1 afterwards. An exception is thrown if this is a list property.

References OpenSim::AbstractProperty::getName(), OpenSim::AbstractProperty::isListProperty(), and OpenSim::Property< T >::setValue().

template<class T>

template<template< class > class Container>

void OpenSim::Property< T >::setValue ( const Container< T > & valueList)

inline

Assignment to a container of values of type T sets the entire value list of this list property to a copy of the values in the container.

The current value is cleared before the assignment.

References OpenSim::AbstractProperty::clear(), OpenSim::AbstractProperty::getMaxListSize(), OpenSim::AbstractProperty::getMinListSize(), OpenSim::AbstractProperty::getName(), and OpenSim::AbstractProperty::setValueIsDefault().

template<class T>

static Property& OpenSim::Property< T >::updAs ( AbstractProperty< T > & prop)

inlinestatic

Downcast the given AbstractProperty to a writable concrete property of this type (Property<T>).

An exception is thrown if this is not the right type only in DEBUG mode; see isA() if you need to check first.

References OpenSim::AbstractProperty::getName().

Referenced by OpenSim::PropertyTable::updProperty().

template<class T>

T& OpenSim::Property< T >::updValue ( int index = -1)

inline

Return a writable reference to the selected value from this property's value list.

If the property is at most single valued then the index is optional and we'll behave as though index=0 were supplied. You can use the square bracket operator property[index] instead.

References OpenSim::AbstractProperty::getMaxListSize(), and OpenSim::AbstractProperty::setValueIsDefault().

Referenced by OpenSim::Property< T >::operator[](), and OpenSim::AbstractProperty::updValue().

Friends And Related Function Documentation

template<class T>

#define OpenSim_DECLARE_LIST_PROPERTY	(	name,
		T,
		comment
	)

OpenSim_DECLARE_LIST_PROPERTY_HELPER(name, T, comment,                  \
                                         0, std::numeric_limits<int>::max())\
    void constructProperty_##name()                                         \
    {   PropertyIndex_##name = addListProperty<T>                           \
           (#name, comment, 0, std::numeric_limits<int>::max()); }

Declare a property of the given name containing a variable-length list of values of the given type T.

The property may be constructed as empty, or with initialization to a templatized Container<T> for any Container that supports a size() method and operator[] element selection.

See Also: OpenSim_DECLARE_LIST_PROPERTY_SIZE(); OpenSim_DECLARE_LIST_PROPERTY_ATLEAST(); OpenSim_DECLARE_LIST_PROPERTY_ATMOST(); OpenSim_DECLARE_LIST_PROPERTY_RANGE()

template<class T>

#define OpenSim_DECLARE_LIST_PROPERTY_ATLEAST	(	name,
		T,
		minSize,
		comment
	)

OpenSim_DECLARE_LIST_PROPERTY_HELPER(name, T, comment, \

(minSize), std::numeric_limits<int>::max())

Declare a property of the given name containing a list of values of the given type T, with the number of values required to be at least minSize (> 0) elements.

Such a property must be initialized at construction, by providing a templatized Container<T> with at least minSize elements, using any Container that supports a size() method and operator[] element selection.

template<class T>

#define OpenSim_DECLARE_LIST_PROPERTY_ATMOST	(	name,
		T,
		maxSize,
		comment
	)

OpenSim_DECLARE_LIST_PROPERTY_HELPER(name, T, comment, 0, (maxSize))    \
    void constructProperty_##name()                                         \
    {   PropertyIndex_##name = addListProperty<T>(#name, comment,           \
                                                  0, (maxSize)); }

Declare a property of the given name containing a list of values of the given type T, with the number of values in the list restricted to be no more than maxSize (> 0) elements.

This kind of property may optionally be initialized at construction, by providing a templatized Container<T> with no more than maxSize elements, using any Container that supports a size() method and operator[] element selection.

template<class T>

#define OpenSim_DECLARE_LIST_PROPERTY_RANGE	(	name,
		T,
		minSize,
		maxSize,
		comment
	)

OpenSim_DECLARE_LIST_PROPERTY_HELPER(name, T, comment, \

(minSize), (maxSize))

Declare a property of the given name containing a list of values of the given type T, with the number of values in the list restricted to be in the range minSize (> 0) to maxSize (> minSize).

This kind of property must be initialized with at least minSize values at construction. If you want to allow zero elements, so that initialization is optional, use OpenSim_DECLARE_PROPERTY_ATMOST() rather than this macro.

template<class T>

#define OpenSim_DECLARE_LIST_PROPERTY_SIZE	(	name,
		T,
		listSize,
		comment
	)

OpenSim_DECLARE_LIST_PROPERTY_HELPER(name, T, comment, \

(listSize), (listSize))

Declare a property of the given name containing a list of values of the given type T, with the number of values in the list restricted to be exactly listSize (> 0) elements, no more or less.

A fixed-size property must be initialized at construction, by providing a templatized Container<T> with the right number of elements, using any Container that supports a size() method and operator[] element selection.

template<class T>

#define OpenSim_DECLARE_OPTIONAL_PROPERTY	(	name,
		T,
		comment
	)

OpenSim_DECLARE_PROPERTY_HELPER(name,T)                                 \
    void constructProperty_##name()                                         \
    {   PropertyIndex_##name = addOptionalProperty<T>(#name, comment); }    \
    void constructProperty_##name(const T& initValue)                       \
    {   PropertyIndex_##name = addOptionalProperty<T>(#name, comment,       \
                                                      initValue); }         \
    const T& get_##name() const                                             \
    {   return getProperty_##name().getValue(); }                           \
    T& upd_##name()                                                         \
    {   return updProperty_##name().updValue(); }                           \
    void set_##name(const T& value)                                         \
    {   updProperty_##name().setValue(value); }

Declare a property of the given name containing an optional value of the given type T (that is, the value list can be of length 0 or 1 only).

The property may be constructed as empty, or with initialization to a single value of type T.

template<class T>

#define OpenSim_DECLARE_PROPERTY	(	name,
		T,
		comment
	)

OpenSim_DECLARE_PROPERTY_HELPER(name,T)                                 \
    void constructProperty_##name(const T& initValue)                       \
    {   PropertyIndex_##name = addProperty<T>(#name,comment,initValue); }   \
    const T& get_##name() const                                             \
    {   return getProperty_##name().getValue(); }                           \
    T& upd_##name()                                                         \
    {   return updProperty_##name().updValue(); }                           \
    void set_##name(const T& value)                                         \
    {   updProperty_##name().setValue(value); }

Declare a required, single-value property of the given name and type T, with an associated comment.

The value list for this property will always contain exactly one element, and the property must be initialized at construction. This macro, and the other similar macros, define several related methods. If the property name is my_prop_name, then the defined methods are:

constructProperty_my_prop_name(initialValue)
getProperty_my_prop_name()
updProperty_my_prop_name()
get_my_prop_name()
upd_my_prop_name()
set_my_prop_name(value)

For some property types, the initial value may be omitted during construction. A data member is also created but is intended for internal use only:

PropertyIndex_my_prop_name holds the property table index for this property after it has been constructed

template<class T>

#define OpenSim_DECLARE_UNNAMED_PROPERTY	(	T,
		comment
	)

OpenSim_DECLARE_PROPERTY_HELPER(T,T)                                    \
    void constructProperty_##T(const T& initValue)                          \
    {   PropertyIndex_##T = addProperty<T>("", comment, initValue); }       \
    const T& get_##T() const                                                \
    {   return getProperty_##T().getValue(); }                              \
    T& upd_##T()                                                            \
    {   return updProperty_##T().updValue(); }                              \
    void set_##T(const T& value)                                            \
    {   updProperty_##T().setValue(value); }

Declare a required, unnamed property holding exactly one object of type T derived from OpenSim's Object class and identified by that object's class name rather than a property name.

At construction, this property must be initialized with an object of type T.

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

/home/fitze/repos/opensim/Branches/OpenSim32ForDoxygen/OpenSim/Common/AbstractProperty.h
/home/fitze/repos/opensim/Branches/OpenSim32ForDoxygen/OpenSim/Common/Property.h

Classes

Public Member Functions

Static Public Member Functions

Related Functions

Additional Inherited Members

Detailed Description

template<class T> class OpenSim::Property< T >

XML file representation of properties

Property attributes

How to declare properties in your class declaration

How to construct properties in your constructors

Copy constructor and copy assignment operator

Runtime access to property values

Member Function Documentation

Friends And Related Function Documentation

template<class T>
class OpenSim::Property< T >