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

Inheritance diagram for OpenSim::Property< T >:

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

void	removeValueAtIndex (int index)
	Remove specific entry of the list at index. 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...

virtual int	findIndexForName (const SimTK::String &name) const =0
	Return index of passed in name if the Property contains objects that are derived from OpenSim::Object, and -1 if no such Object is found. 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 (i.e., this number may be rounded and not an exact representation of the actual value being used). More...

virtual std::string	toStringForDisplay (const int precision) const
	For relatively simple types, return the current value of this property in a string suitable for displaying to a user in the GUI (i.e., this number may be rounded and not an exact representation of the actual value being used). 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) const
	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...

virtual void	assign (const AbstractProperty &that)=0
	Assign (copy) property that to this object. 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...

Protected Member Functions
	Property ()=default

	~Property ()=default

	Property (const Property &)=default

	Property (Property &&)=default

Property &	operator= (const Property &)=default

Property &	operator= (Property &&)=default

Protected Member Functions inherited from OpenSim::AbstractProperty
	AbstractProperty ()

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

	AbstractProperty (const AbstractProperty &)=default

	AbstractProperty (AbstractProperty &&)=default

AbstractProperty &	operator= (const AbstractProperty &)=default

AbstractProperty &	operator= (AbstractProperty &&)=default

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

Related Functions
(Note that these are not member functions.)
#define	OpenSim_DECLARE_PROPERTY(pname, T, comment)
	Declare a required, single-value property of the given pname 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(pname, T, comment)
	Declare a property of the given pname 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(pname, T, comment)
	Declare a property of the given pname containing a variable-length list of values of the given type T. More...

#define	OpenSim_DECLARE_LIST_PROPERTY_SIZE(pname, T, listSize, comment)
	Declare a property of the given pname 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(pname, T, minSize, comment)
	Declare a property of the given pname 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(pname, T, maxSize, comment)
	Declare a property of the given pname 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(pname, T, minSize, maxSize, comment)
	Declare a property of the given pname 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...

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

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 Component, 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. Comments that should appear in the generated Doxygen documentation as well as in XML files should be in the comment string; if you have a comment that should appear in Doxygen documentation but not in XML, then you can place it in a Doxygen comment just above the line where you declare your property.

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:

class ActuatorWorkMeter : public ModelComponent {
OpenSim_DECLARE_CONCRETE_OBJECT(ActuatorWorkMeter, ModelComponent);
public:
//=======================================================================
// PROPERTIES
//=======================================================================
    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 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

Constructor & Destructor Documentation

◆ Property() [1/3]

template<class T>

OpenSim::Property< T >::Property ( )

protecteddefault

◆ ~Property()

template<class T>

OpenSim::Property< T >::~Property ( )

protecteddefault

◆ Property() [2/3]

template<class T>

OpenSim::Property< T >::Property ( const Property< T > & )

protecteddefault

◆ Property() [3/3]

template<class T>

OpenSim::Property< T >::Property ( Property< T > && )

protecteddefault

Member Function Documentation

◆ adoptAndAppendValue()

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

◆ appendValue() [1/2]

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

◆ appendValue() [2/2]

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

◆ clone()

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.

◆ findIndex()

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

◆ findIndexForName()

template<class T>

virtual int OpenSim::Property< T >::findIndexForName ( const SimTK::String & name ) const

pure virtual

Return index of passed in name if the Property contains objects that are derived from OpenSim::Object, and -1 if no such Object is found.

Throws an Exception if the List doesn't contain OpenSim Objects (e.g. primitive types) since these are not named. When a search is performed, it's a linear search.

◆ getAs()

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

◆ getTypeName()

template<class T >

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

inlinefinaloverridevirtual

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

Implements OpenSim::AbstractProperty.

◆ getValue()

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::Object::checkPropertyValueIsInRangeOrSet(), OpenSim::Object::checkPropertyValueIsInSet(), OpenSim::Object::checkPropertyValueIsPositive(), OpenSim::Property< T >::findIndex(), OpenSim::AbstractProperty::getValue(), and OpenSim::Property< T >::operator[]().

◆ isA()

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.

◆ operator=() [1/4]

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

◆ operator=() [2/4]

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

◆ operator=() [3/4]

template<class T>

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

protecteddefault

◆ operator=() [4/4]

template<class T>

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

protecteddefault

◆ operator[]() [1/2]

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

◆ operator[]() [2/2]

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

◆ removeValueAtIndex()

template<class T>

void OpenSim::Property< T >::removeValueAtIndex ( int index )

inline

Remove specific entry of the list at index.

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

◆ setValue() [1/3]

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

◆ setValue() [2/3]

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

◆ setValue() [3/3]

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

◆ updAs()

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

◆ updValue()

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

◆ OpenSim_DECLARE_LIST_PROPERTY

template<class T>

#define OpenSim_DECLARE_LIST_PROPERTY	(	pname,
		T,
		comment
	)

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()

◆ OpenSim_DECLARE_LIST_PROPERTY_ATLEAST

template<class T>

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

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.

◆ OpenSim_DECLARE_LIST_PROPERTY_ATMOST

template<class T>

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

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.

◆ OpenSim_DECLARE_LIST_PROPERTY_RANGE

template<class T>

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

Declare a property of the given pname 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.

◆ OpenSim_DECLARE_LIST_PROPERTY_SIZE

template<class T>

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

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.

◆ OpenSim_DECLARE_OPTIONAL_PROPERTY

template<class T>

#define OpenSim_DECLARE_OPTIONAL_PROPERTY	(	pname,
		T,
		comment
	)

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

◆ OpenSim_DECLARE_PROPERTY

template<class T>

#define OpenSim_DECLARE_PROPERTY	(	pname,
		T,
		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

◆ OpenSim_DECLARE_UNNAMED_PROPERTY

template<class T>

#define OpenSim_DECLARE_UNNAMED_PROPERTY	(	T,
		comment
	)

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

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

OpenSim/Common/AbstractProperty.h
OpenSim/Common/Property.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Related Functions

Nested Classes

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

Constructor & Destructor Documentation

◆ Property() [1/3]

◆ ~Property()

◆ Property() [2/3]

◆ Property() [3/3]

Member Function Documentation

◆ adoptAndAppendValue()

◆ appendValue() [1/2]

◆ appendValue() [2/2]

◆ clone()

◆ findIndex()

◆ findIndexForName()

◆ getAs()

◆ getTypeName()

◆ getValue()

◆ isA()

◆ operator=() [1/4]

◆ operator=() [2/4]

◆ operator=() [3/4]

◆ operator=() [4/4]

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ removeValueAtIndex()

◆ setValue() [1/3]

◆ setValue() [2/3]

◆ setValue() [3/3]

◆ updAs()

◆ updValue()

Friends And Related Function Documentation

◆ OpenSim_DECLARE_LIST_PROPERTY

◆ OpenSim_DECLARE_LIST_PROPERTY_ATLEAST

◆ OpenSim_DECLARE_LIST_PROPERTY_ATMOST

◆ OpenSim_DECLARE_LIST_PROPERTY_RANGE

◆ OpenSim_DECLARE_LIST_PROPERTY_SIZE

◆ OpenSim_DECLARE_OPTIONAL_PROPERTY

◆ OpenSim_DECLARE_PROPERTY

◆ OpenSim_DECLARE_UNNAMED_PROPERTY

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