API
4.3
For MATLAB, Python, Java, and C++ users
|
A Property<T> is a serializable (name, list-of-values) pair, where each value is of type T. 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 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... | |
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... | |
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:
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.
The general representation for a Property<T> with name "prop_name" is
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
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
but we allow a more compact representation for one-object properties:
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:
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.
In addition to the name and list of values, every property has the following attributes:
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.
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.
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:
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:
Here is an example of an object declaring two properties:
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:
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).
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:
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.
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:
Additional methods are generated for list properties:
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:
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:
|
protecteddefault |
|
protecteddefault |
|
protecteddefault |
|
protecteddefault |
|
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().
|
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().
|
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().
|
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.
|
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().
|
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.
|
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().
|
inlinefinaloverridevirtual |
Use TypeHelper's getTypeName() to satisfy this pure virtual.
Implements OpenSim::AbstractProperty.
|
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[]().
|
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.
|
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().
|
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().
|
protecteddefault |
|
protecteddefault |
|
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().
|
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().
|
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().
|
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().
|
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().
|
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().
|
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().