This is the base class for all OpenSim objects that are serializable (meaning they can be written to and read back from files). More...

Inheritance diagram for OpenSim::Object:

Public Member Functions
virtual	~Object ()
	Virtual destructor for cleanup. More...

virtual Object *	clone () const =0
	Create a new heap-allocated copy of the concrete object to which this Object refers. More...

virtual const std::string &	getConcreteClassName () const =0
	Returns the class name of the concrete Object-derived class of the actual object referenced by this Object, as a string. More...

bool	isEqualTo (const Object &aObject) const
	Equality operator wrapper for use from languages not supporting operator overloading. More...

Object &	operator= (const Object &aObject)
	Copy assignment copies he base class fields, including the properties. More...

virtual bool	operator== (const Object &aObject) const
	Determine if two objects are equal. More...

virtual bool	operator< (const Object &aObject) const
	Provide an ordering for objects so they can be put in sorted containers. More...

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

const std::string &	getName () const
	Get the name of this Object. More...

void	setDescription (const std::string &description)
	Set description, a one-liner summary. More...

const std::string &	getDescription () const
	Get description, a one-liner summary. More...

const std::string &	getAuthors () const
	Get Authors of this Object. More...

void	setAuthors (const std::string &authors)
	Set Authors of this object. More...

const std::string &	getReferences () const
	Get references or publications to cite if using this object. More...

void	setReferences (const std::string &references)
	Set references or publications to cite if using this object. More...

Static Public Member Functions
Registration of types and default objects
Methods in this section deal with the requirement that all OpenSim types derived from Object must be registered and a default instance provided. This enables reading these objects from XML files. You can also recognize now-obsolete names for objects and have them quietly mapped to their modern names using the renameType() method. Rename can also be used programmatically to replace one registered type with another, because renaming occurs prior to object lookup.
static void	registerType (const Object &defaultObject)
	Register an instance of a class; if the class is already registered it will be replaced. More...

static void	renameType (const std::string &oldTypeName, const std::string &newTypeName)
	Support versioning by associating the current Object type with an old name. More...

static const Object *	getDefaultInstanceOfType (const std::string &concreteClassName)
	Return a pointer to the default instance of the registered (concrete) Object whose class name is given, or NULL if the type is not registered. More...

template<class T >
static bool	isObjectTypeDerivedFrom (const std::string &concreteClassName)
	Return true if the given concrete object type represents a subclass of the template object type T, and thus could be referenced with a T*. More...

static Object *	newInstanceOfType (const std::string &concreteClassName)
	Create a new instance of the concrete Object type whose class name is given as concreteClassName. More...

static void	getRegisteredTypenames (Array< std::string > &typeNames)
	Retrieve all the typenames registered so far. More...

template<class T >
static void	getRegisteredObjectsOfGivenType (ArrayPtrs< T > &rArray)
	Return an array of pointers to the default instances of all registered (concrete) Object types that derive from a given Object-derived type that does not have to be concrete. More...

Static Public Attributes
static const std::string	DEFAULT_NAME
	Name used for default objects when they are serialized. More...

Protected Member Functions
	Object ()
	The default constructor is only for use by constructors of derived types. More...

	Object (const std::string &fileName, bool aUpdateFromXMLNode=true)
	Constructor from a file, to be called from other constructors that take a file as input. More...

	Object (const Object &source)
	Copy constructor is invoked automatically by derived classes with default copy constructors; otherwise it must be invoked explicitly. More...

	Object (SimTK::Xml::Element &aElement)
	Construct the base class portion of an Object from a given Xml element that describes this Object. More...

template<class T >
PropertyIndex	addProperty (const std::string &name, const std::string &comment, const T &value)
	Define a new single-value property of known type T, with the given name, associated comment, and initial value. More...

template<class T >
PropertyIndex	addOptionalProperty (const std::string &name, const std::string &comment)
	Add an optional property, meaning it can contain either no value or a single value. More...

template<class T >
PropertyIndex	addOptionalProperty (const std::string &name, const std::string &comment, const T &value)
	Add an optional property, meaning it can contain either no value or a single value. More...

template<class T >
PropertyIndex	addListProperty (const std::string &name, const std::string &comment, int minSize, int maxSize)
	Define a new list-valued property of known type T, with the given name, associated comment, minimum (==0) and maximum (>0) allowable list lengths, and a zero-length initial value. More...

template<class T , template< class > class Container>
PropertyIndex	addListProperty (const std::string &name, const std::string &comment, int minSize, int maxSize, const Container< T > &valueList)
	Define a new list-valued property as above, but assigning an initial value via some templatized container class that supports size() and indexing. More...

PropertyIndex	getPropertyIndex (const std::string &name) const
	Look up a property by name and return its PropertyIndex if it is found. More...

template<class T >
PropertyIndex	getPropertyIndex () const
	Look up an unnamed property by the type of object it contains, and return its PropertyIndex if it is found. More...

template<class T >
void	checkPropertyValueIsPositive (const Property< T > &p) const
	Throw an exception if any of the property's values are not positive. More...

template<class T >
void	checkPropertyValueIsInSet (const Property< T > &p, const std::set< T > &set) const
	Throw an exception if any of the property's values are not in the provided set. More...

template<class T >
void	checkPropertyValueIsInRangeOrSet (const Property< T > &p, const T &lower, const T &upper, const std::set< T > &set) const
	Throw an exception if any of the property's values are neither in the provided range nor in the provided set. More...

Protected Attributes
PropertySet	_propertySet
	OBSOLETE: Property_Deprecated set for serializable member variables of this and derived classes. More...

Friends
std::ostream &	operator<< (std::ostream &aOut, const Object &aObject)
	Write the type and name of this object into the given output stream. More...

Related Functions
(Note that these are not member functions.)
Object Declaration Macros
One of these macros must appear as the first line of any class declaration that derives directly or indirectly from OpenSim's Object class. In almost all cases, the right macro to use is `OpenSim_DECLARE_CONCRETE_OBJECT()`. Use of these macros provides: a public typedef Super that is the immediate parent class, implementation of required Object pure virtual methods, including the clone() method that will create a new heap-allocated copy of any concrete Object, uniform treatment of class names, which are used as tags in XML and for interfacing with Java using class names as strings to identify C++ objects. The static getClassName() returns the name of any class, and the member getConcreteClassName() returns the class name of the concrete object being referenced, and an assortment of methods used only for interfacing with Java.
#define	OpenSim_DECLARE_CONCRETE_OBJECT(ConcreteClass, SuperClass)
	Macro to be included as the first line of the class declaration for any non-templatized, concrete class that derives from OpenSim::Object. More...

#define	OpenSim_DECLARE_ABSTRACT_OBJECT(ConcreteClass, SuperClass)
	Macro to be included as the first line of the class declaration for any still-abstract class that derives from OpenSim::Object. More...

#define	OpenSim_DECLARE_CONCRETE_OBJECT_T(ConcreteClass, TArg, SuperClass)
	Macro to be included as the first line of the class declaration for any templatized, concrete class that derives from OpenSim::Object, like Set<T>. More...

#define	OpenSim_DECLARE_ABSTRACT_OBJECT_T(ConcreteClass, TArg, SuperClass)
	Macro to be included as the first line of the class declaration for any templatized, still-abstract class that derives from OpenSim::Object. More...

Public access to properties
Methods in this section are for public access to the properties maintained by this OpenSim Object. Properties are normally accessed through methods of the concrete Object-derived classes that are generated by the Property declaration macros; see OpenSim::Property for information. However, when dealing with Objects from "the outside", as is done in the GUI, these methods allow access to properties via the property base class AbstractProperty to support various type-independent property services. That is particularly useful for Object-containing properties since the objects can be obtained without knowing their concrete types. For simple types (e.g. int, std::string) you can only obtain the values if you know the expected type. For those types, or when you know the expected Object type, you can use the templatized methods to deal with the concrete values.
int	getNumProperties () const
	Determine how many properties are stored with this Object. More...

const AbstractProperty &	getPropertyByIndex (int propertyIndex) const
	Get a const reference to a property by its index number, returned as an AbstractProperty. More...

AbstractProperty &	updPropertyByIndex (int propertyIndex)
	Get a writable reference to a property by its index number, returned as an AbstractProperty. More...

bool	hasProperty (const std::string &name) const
	Return true if this Object has a property of any type with the given name, which must not be empty. More...

const AbstractProperty &	getPropertyByName (const std::string &name) const
	Get a const reference to a property by its name, returned as an AbstractProperty. More...

AbstractProperty &	updPropertyByName (const std::string &name)
	Get a writable reference to a property by its name, returned as an AbstractProperty. More...

template<class T >
bool	hasProperty () const
	Return true if this Object contains an unnamed, one-object property that contains objects of the given template type T. More...

template<class T >
const Property< T > &	getProperty (const PropertyIndex &index) const
	Get property of known type Property<T> as a const reference; the property must be present and have the right type. More...

template<class T >
Property< T > &	updProperty (const PropertyIndex &index)
	Get property of known type Property<T> as a writable reference; the property must be present and have the right type. More...

bool	isObjectUpToDateWithProperties () const
	Returns `true` if no property's value has changed since the last time setObjectIsUpToDateWithProperties() was called. More...

static bool	PrintPropertyInfo (std::ostream &os, const std::string &classNameDotPropertyName, bool printFlagInfo=true)
	Dump formatted property information to a given output stream, useful for creating a "help" facility for registered objects. More...

static bool	PrintPropertyInfo (std::ostream &os, const std::string &className, const std::string &propertyName, bool printFlagInfo=true)
	Same as the other signature but the class name and property name are provided as two separate strings. More...

XML reading and writing
These methods deal with writing out in-memory objects to XML files (serializing) and reading XML files to reconstruct in-memory objects (deserializing).
void	readObjectFromXMLNodeOrFile (SimTK::Xml::Element &objectElement, int versionNumber)
	We're given an XML element from which we are to populate this Object. More...

virtual void	updateFromXMLNode (SimTK::Xml::Element &objectElement, int versionNumber)
	Use this method to deserialize an object from a SimTK::Xml::Element. More...

void	updateXMLNode (SimTK::Xml::Element &parent, const AbstractProperty *prop=nullptr) const
	Serialize this object into the XML node that represents it. More...

bool	getInlined () const
	Inlined means an in-memory Object that is not associated with an XMLDocument. More...

void	setInlined (bool aInlined, const std::string &aFileName="")
	Mark this as inlined or not and optionally provide a file name to associate with the new XMLDocument for the non-inline case. More...

std::string	getDocumentFileName () const
	If there is a document associated with this object then return the file name maintained by the document. More...

int	getDocumentFileVersion () const
	If there is a document associated with this object then return its version number. More...

void	setAllPropertiesUseDefault (bool aUseDefault)

bool	print (const std::string &fileName) const
	Write this Object into an XML file of the given name; conventionally the suffix to use is ".osim". More...

std::string	dump () const
	dump the XML representation of this Object into an std::string and return it. More...

static Object *	makeObjectFromFile (const std::string &fileName)
	Create an OpenSim object whose type is based on the tag at the root node of the XML file passed in. More...

void	setObjectIsUpToDateWithProperties ()
	When an object is initialized using the current values of its properties, it can set a flag indicating that it is up to date. More...

void	clearObjectIsUpToDateWithProperties ()
	For testing or debugging purposes, manually clear the "object is up to date with respect to properties" flag. More...

void	makeObjectNamesConsistentWithProperties ()
	Make sure the name of an object is consistent with its property type. More...

void	updateFromXMLDocument ()
	Use this method only if you're deserializing from a file and the object is at the top level; that is, primarily in constructors that take a file name as input. More...

void	setDocument (XMLDocument *doc)
	Unconditionally set the XMLDocument associated with this object. More...

const XMLDocument *	getDocument () const
	Get a const pointer to the document (if any) associated with this object. More...

XMLDocument *	updDocument ()
	Get a writable pointer to the document (if any) associated with this object. More...

Advanced/Obscure
Methods in this section are for specialized purposes not of interest to most OpenSim API users. For example, some of these are services needed by the OpenSim GUI which is written in Java.
virtual bool	isA (const char *type) const
	The default implementation returns true only if the supplied string is "Object"; each Object-derived class overrides this to match its own class name. More...

const std::string &	toString () const
	Wrapper to be used on Java side to display objects in tree; this returns just the object's name. More...

PropertySet &	getPropertySet ()
	OBSOLETE: Get a reference to the PropertySet maintained by the Object. More...

const PropertySet &	getPropertySet () const

static const std::string &	getClassName ()
	Return the name of this class as a string; i.e., "Object". More...

static void	setSerializeAllDefaults (bool shouldSerializeDefaults)
	Static function to control whether all registered objects and their properties are written to the defaults section of output files rather than only those values for which the default was explicitly overwritten when read in from an input file or set programmatically. More...

static bool	getSerializeAllDefaults ()
	Report the value of the "serialize all defaults" flag. More...

static bool	isKindOf (const char *type)
	Returns true if the passed-in string is "Object"; each Object-derived class defines a method of this name for its own class name. More...

static void	setDebugLevel (int newLevel)
	Set the amount of logging output. More...

static int	getDebugLevel ()
	Get the current setting of debug level. More...

static Object *	SafeCopy (const Object *aObject)
	Use the clone() method to duplicate the given object unless the pointer is null in which case null is returned. More...

static void	RegisterType (const Object &defaultObject)
	OBSOLETE alternate name for registerType(). More...

static void	RenameType (const std::string &oldName, const std::string &newName)
	OBSOLETE alternate name for renameType(). More...

Detailed Description

This is the base class for all OpenSim objects that are serializable (meaning they can be written to and read back from files).

In particular, all ModelComponent objects derive from Object. It provides a common base class from which to derive serializable objects and also some basic functionality, such as writing to files in XML format, managing properties, and the equality, less than, and output operators.

An Object maintains a table of "properties" that know how to read themselves from XML and write themselves to XML. The available Property types are

Primitive data types (int, bool, double, std::string, ...)
Properties that contain other Objects,
Properties containing lists of either of the previous 2 categories

It is important to note that Objects and Properties together form a recursive tree structure that is the representation of an OpenSim Model. See the documentation for the OpenSim::Property class for more information.

Object declaration

The declaration of every class derived from Object must have its first line (that is, immediately after the "{" in the class declaration) one of four standard "boilerplate" macros:

OpenSim_DECLARE_CONCRETE_OBJECT  (ClassName, SuperclassName);
OpenSim_DECLARE_CONCRETE_OBJECT_T(ClassName, T, SuperclassName);
OpenSim_DECLARE_ABSTRACT_OBJECT  (ClassName, SuperclassName);
OpenSim_DECLARE_ABSTRACT_OBJECT_T(ClassName, T, SuperclassName);

("Superclass" means the immediate class from which the class derives; that terminology is borrowed from Java. It is often called the "Parent" class but we'll use "Super" which is more precise.) The "_T" variants of the above macros are used for objects that are templatized, like Set<T>.

These macros provide a standardized set of declarations for every object, including

typedef ClassName      Self;                // for all classes
typedef SuperclassName Super;               // for all classes
static const std::string& getClassName();   // for all classes
const std::string& getConcreteClassName();  // for concrete classes only
ClassName* clone() const;                   // see below

getClassName() is a static method that returns the name of the Object-derived class for which it is invoked. For example, ModelComponent::getClassName() returns "ModelComponent". In contrast, getConcreteClassName() is a pure virtual method of Object that returns the class name of the actual concrete object being referenced through the abstract base class. This method is implemented only in concrete classes.

Note that getClassName() and getConcreteClassName() will return the same string only if the referenced class is concrete. For example,

Function* funcp = new LinearFunction(...);
std::cout << funcp->getClassName();          // output: "Function"
std::cout << funcp->getConcreteClassName();  // output: "LinearFunction"

For concrete objects, the class name is used as the "object type tag", the tag string that will appear in XML files. Also, when a Property<T> has no name (allowed for properties that contain just a single object) the object class name T (which may be abstract like Function or ModelComponent) is used to select the property. See OpenSim::Property for more information.

The standard clone() method produces a duplicate of a concrete object and thus is implemented only for concrete classes. However, the return type must always match the type of the invoking object (this is called a "covariant type" and does not change the method's identity). It is therefore redeclared even in abstract classes, but remains pure virtual in those cases. That means if you invoke Function::clone() you'll get back a Function* rather than an Object*; this avoids many unnecessary invocations of the awkward and expensive dynamic_cast operator.

Object registration and renaming

An Object type needs to be "registered" by calling Object::registerType() with an instance of a concrete object so that the serialization infrastructure knows what kind of Object to create when it encounters a specific XML tag. This associates the concrete object's class name (object type tag) with a default instance of that object. The registration process is normally done during dynamic library (DLL) loading, that is, as part of the static initializer execution that occurs before program execution.

For backwards compatibility, we support a renaming mechanism in which now-deprecated class names can be mapped to their current equivalents. This is done via a string-to-string table mapping the old names to the new ones; only the current names appear in the registered objects table. Specification of these aliases is done immediately after registration in the DLL static initializer.

Defaults mechanism

When an Object is registered (either programmatically, or overridden in the defaults section of a document), a copy of it is maintained in a dictionary as a "default" object of its class. When new instances of this class are requested, the contents of the default object are used to populate the new instance before deserialization. This allows for specifying default values that will be commonly used in one place in the XML file rather than with each object which leads to smaller files that are easier to read. Property values that obtain their values from the defaults and are not subsequently overridden are marked as being default values, allowing us to avoid writing them back out when serializing.

Author: Frank C. Anderson, Ayman Habib, Ajay Seth, Michael Sherman

See also: OpenSim::Property

Constructor & Destructor Documentation

◆ ~Object()

virtual OpenSim::Object::~Object ( )

virtual

Virtual destructor for cleanup.

◆ Object() [1/4]

OpenSim::Object::Object ( )

protected

The default constructor is only for use by constructors of derived types.

Initializes all base class data members to innocuous values.

◆ Object() [2/4]

OpenSim::Object::Object	(	const std::string &	fileName,
		bool	aUpdateFromXMLNode = `true`
	)

explicitprotected

Constructor from a file, to be called from other constructors that take a file as input.

◆ Object() [3/4]

OpenSim::Object::Object ( const Object & source )

protected

Copy constructor is invoked automatically by derived classes with default copy constructors; otherwise it must be invoked explicitly.

◆ Object() [4/4]

OpenSim::Object::Object ( SimTK::Xml::Element & aElement )

explicitprotected

Construct the base class portion of an Object from a given Xml element that describes this Object.

Assumes latest XML file format; there is no provision for version numbering.

Member Function Documentation

◆ addListProperty() [1/2]

template<class T >

PropertyIndex OpenSim::Object::addListProperty	(	const std::string &	name,
		const std::string &	comment,
		int	minSize,
		int	maxSize
	)

protected

Define a new list-valued property of known type T, with the given name, associated comment, minimum (==0) and maximum (>0) allowable list lengths, and a zero-length initial value.

The property must have a name (the empty string is not acceptable), and that name must be unique within this Object's property table.

Returns: The PropertyIndex of this property in the property table for this object.

See also: addProperty(), addOptionalProperty()

References OpenSim::AbstractProperty::setAllowableListSize(), OpenSim::AbstractProperty::setComment(), and OpenSim::AbstractProperty::setValueIsDefault().

◆ addListProperty() [2/2]

template<class T , template< class > class Container>

PropertyIndex OpenSim::Object::addListProperty	(	const std::string &	name,
		const std::string &	comment,
		int	minSize,
		int	maxSize,
		const Container< T > &	valueList
	)

protected

Define a new list-valued property as above, but assigning an initial value via some templatized container class that supports size() and indexing.

Here the minimum size may be greater than zero, provided that the initial value has at least that many element (and no more than the allowed maximum).

Returns: The PropertyIndex of this property in the property table for this object.

See also: addProperty(), addOptionalProperty()

References OpenSim::Property< T >::appendValue(), OpenSim::AbstractProperty::setAllowableListSize(), OpenSim::AbstractProperty::setComment(), and OpenSim::AbstractProperty::setValueIsDefault().

◆ addOptionalProperty() [1/2]

template<class T >

PropertyIndex OpenSim::Object::addOptionalProperty	(	const std::string &	name,
		const std::string &	comment
	)

protected

Add an optional property, meaning it can contain either no value or a single value.

Here no initial value is provided. The property must have a name (the empty string is not acceptable), and that name must be unique within this Object's property table.

Returns: Reference to the new Property object stored in this object's property table.

See also: addProperty(), addListProperty()

References OpenSim::AbstractProperty::setAllowableListSize(), OpenSim::AbstractProperty::setComment(), and OpenSim::AbstractProperty::setValueIsDefault().

◆ addOptionalProperty() [2/2]

template<class T >

PropertyIndex OpenSim::Object::addOptionalProperty	(	const std::string &	name,
		const std::string &	comment,
		const T &	value
	)

protected

Add an optional property, meaning it can contain either no value or a single value.

Here an initial value is provided. The property must have a name (the empty string is not acceptable), and that name must be unique within this Object's property table.

Returns: Reference to the new Property object stored in this object's property table.

See also: addProperty(), addListProperty()

References OpenSim::Property< T >::appendValue(), OpenSim::AbstractProperty::setAllowableListSize(), OpenSim::AbstractProperty::setComment(), and OpenSim::AbstractProperty::setValueIsDefault().

◆ addProperty()

template<class T >

PropertyIndex OpenSim::Object::addProperty	(	const std::string &	name,
		const std::string &	comment,
		const T &	value
	)

protected

Define a new single-value property of known type T, with the given name, associated comment, and initial value.

The name must be unique within this Object's property table.

If T is an object type (i.e., derived from Object), it is permissible for the property to be unnamed; pass an empty string for name. You will then be able to select the property using the object class name (that is, T::getClassName()) as though it were the property's name. An Object can thus only have one unnamed property of any particular object type.

Returns: Reference to the new Property object stored in this object's property table.

See also: addOptionalProperty(), addListProperty()

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

◆ checkPropertyValueIsInRangeOrSet()

template<class T >

void OpenSim::Object::checkPropertyValueIsInRangeOrSet	(	const Property< T > &	p,
		const T &	lower,
		const T &	upper,
		const std::set< T > &	set
	)		const

protected

Throw an exception if any of the property's values are neither in the provided range nor in the provided set.

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

◆ checkPropertyValueIsInSet()

template<class T >

void OpenSim::Object::checkPropertyValueIsInSet	(	const Property< T > &	p,
		const std::set< T > &	set
	)		const

protected

Throw an exception if any of the property's values are not in the provided set.

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

◆ checkPropertyValueIsPositive()

template<class T >

void OpenSim::Object::checkPropertyValueIsPositive ( const Property< T > & p ) const

protected

Throw an exception if any of the property's values are not positive.

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

◆ clearObjectIsUpToDateWithProperties()

void OpenSim::Object::clearObjectIsUpToDateWithProperties ( )

inlineprotected

For testing or debugging purposes, manually clear the "object is up to date with respect to properties" flag.

This is normally done automatically when a property is modified. Setting the flag is always done manually, however, see setObjectIsUpToDateWithProperties().

◆ clone()

virtual Object* OpenSim::Object::clone ( ) const

pure virtual

Create a new heap-allocated copy of the concrete object to which this Object refers.

It is up to the caller to delete the returned object when no longer needed. Every concrete object deriving from Object implements this pure virtual method automatically, via the declaration macro it invokes (e.g., OpenSim_DECLARE_CONCRETE_OBJECT()). Note that the concrete class overrides modify the return type to be a pointer to the concrete object; that still overrides the base class method because the return type is covariant with (that is, derives from) Object.

Referenced by OpenSim::Object_GetClassName< SimTK::Quaternion_< SimTK::Real > >::name(), SafeCopy(), OpenSim::PropertyObj::setValueAsObject(), OpenSim::PropertyObjArray< Control >::setValueAsObject(), and OpenSim::PropertyObjPtr< OpenSim::Function >::setValueAsObject().

◆ dump()

std::string OpenSim::Object::dump ( ) const

dump the XML representation of this Object into an std::string and return it.

Mainly intended for debugging and for use by the XML browser in the GUI.

◆ getAuthors()

const std::string& OpenSim::Object::getAuthors ( ) const

inline

Get Authors of this Object.

◆ getClassName()

static const std::string& OpenSim::Object::getClassName ( )

inlinestatic

Return the name of this class as a string; i.e., "Object".

See getConcreteClassName() if you want the class name of the underlying concrete object instead. Note that this method is automatically supplied for every class declaration that derives from Object via the standard macro provided for that purpose. See introductory text for this Object class for more information.

◆ getConcreteClassName()

virtual const std::string& OpenSim::Object::getConcreteClassName ( ) const

pure virtual

Returns the class name of the concrete Object-derived class of the actual object referenced by this Object, as a string.

This is the string that is used as the tag for this concrete object in an XML file. Every concrete class derived from Object automatically overrides this method via the declaration macro it uses. See getClassName() to get the class name of the referencing (possibly abstract) class rather than the concrete object.

See also: getClassName()

Referenced by OpenSim::PropertyObjArray< Control >::appendValue(), and OpenSim::Object_GetClassName< SimTK::Quaternion_< SimTK::Real > >::name().

◆ getDebugLevel()

static int OpenSim::Object::getDebugLevel ( )

static

Get the current setting of debug level.

(Deprecated) Use Log::getLevel() instead.

◆ getDefaultInstanceOfType()

static const Object* OpenSim::Object::getDefaultInstanceOfType ( const std::string & concreteClassName )

static

Return a pointer to the default instance of the registered (concrete) Object whose class name is given, or NULL if the type is not registered.

Note that this refers to the default Object instance that is stored with the Object class; do not delete it! If you want a copy of this object instead, use newInstanceOfType(). The given concreteClassName will be mapped through the renamed type table if necessary but the returned object will always have the new type name, which may differ from the supplied one. Note that renaming is applied first, prior to looking up the name in the registered objects table.

See also: registerType(), renameType()

◆ getDescription()

const std::string& OpenSim::Object::getDescription ( ) const

Get description, a one-liner summary.

◆ getDocument()

const XMLDocument* OpenSim::Object::getDocument ( ) const

inlineprotected

Get a const pointer to the document (if any) associated with this object.

◆ getDocumentFileName()

std::string OpenSim::Object::getDocumentFileName ( ) const

If there is a document associated with this object then return the file name maintained by the document.

Otherwise return an empty string.

◆ getDocumentFileVersion()

int OpenSim::Object::getDocumentFileVersion ( ) const

If there is a document associated with this object then return its version number.

For example this is 30000 for OpenSim 3.x documents and is 305xx for OpenSim 4.0 beta and above. If there is no document associated with the object, the method returns -1.

◆ getInlined()

bool OpenSim::Object::getInlined ( ) const

Inlined means an in-memory Object that is not associated with an XMLDocument.

◆ getName()

const std::string& OpenSim::Object::getName ( ) const

Get the name of this Object.

Referenced by OpenSim::ProbeReporter::disableIntegrationOnlyProbes(), OpenSim::ModelComponentSet< Constraint >::extendFinalizeFromProperties(), OpenSim::Input< T >::finalizeConnection(), OpenSim::Object_GetClassName< SimTK::Quaternion_< SimTK::Real > >::name(), and OpenSim::TableProcessor::processAndConvertToRadians().

◆ getNumProperties()

int OpenSim::Object::getNumProperties ( ) const

Determine how many properties are stored with this Object.

These are numbered 0..n-1 in the order they were created.

◆ getProperty()

template<class T >

const Property< T > & OpenSim::Object::getProperty ( const PropertyIndex & index ) const

Get property of known type Property<T> as a const reference; the property must be present and have the right type.

This is primarily used by the Property declaration macros for fast access to properties.

◆ getPropertyByIndex()

const AbstractProperty& OpenSim::Object::getPropertyByIndex ( int propertyIndex ) const

Get a const reference to a property by its index number, returned as an AbstractProperty.

◆ getPropertyByName()

const AbstractProperty& OpenSim::Object::getPropertyByName ( const std::string & name ) const

Get a const reference to a property by its name, returned as an AbstractProperty.

An exception is thrown if no property by this name is present in this Object.

◆ getPropertyIndex() [1/2]

PropertyIndex OpenSim::Object::getPropertyIndex ( const std::string & name ) const

inlineprotected

Look up a property by name and return its PropertyIndex if it is found.

If no property of that name is present, the returned index will be invalid; check with isValid().

◆ getPropertyIndex() [2/2]

template<class T >

PropertyIndex OpenSim::Object::getPropertyIndex ( ) const

inlineprotected

Look up an unnamed property by the type of object it contains, and return its PropertyIndex if it is found.

If no unnamed property of that type is present, the returned index will be invalid; check with isValid().

◆ getPropertySet() [1/2]

PropertySet& OpenSim::Object::getPropertySet ( )

inline

OBSOLETE: Get a reference to the PropertySet maintained by the Object.

Referenced by OpenSim::CMC_TaskSet::CMC_TaskSet().

◆ getPropertySet() [2/2]

const PropertySet& OpenSim::Object::getPropertySet ( ) const

inline

◆ getReferences()

const std::string& OpenSim::Object::getReferences ( ) const

inline

Get references or publications to cite if using this object.

◆ getRegisteredObjectsOfGivenType()

template<class T >

static void OpenSim::Object::getRegisteredObjectsOfGivenType ( ArrayPtrs< T > & rArray )

inlinestatic

Return an array of pointers to the default instances of all registered (concrete) Object types that derive from a given Object-derived type that does not have to be concrete.

This is useful, for example, to find all Joints, Constraints, ModelComponents, Analyses, etc.

◆ getRegisteredTypenames()

static void OpenSim::Object::getRegisteredTypenames ( Array< std::string > & typeNames )

static

Retrieve all the typenames registered so far.

This is done by traversing the registered objects map, so only concrete classes that have registered instances are returned; renamed types will not appear unless they were separately registered. (Note that even if one registered type has been renamed to another, both will appear in the returned list.) The result returned in typeNames should not be cached while more shared libraries or plugins are loaded, because more types may be registered as a result. Instead the list should be reconstructed whenever in doubt.

◆ getSerializeAllDefaults()

static bool OpenSim::Object::getSerializeAllDefaults ( )

inlinestatic

Report the value of the "serialize all defaults" flag.

◆ hasProperty() [1/2]

bool OpenSim::Object::hasProperty ( const std::string & name ) const

Return true if this Object has a property of any type with the given name, which must not be empty.

◆ hasProperty() [2/2]

template<class T >

bool OpenSim::Object::hasProperty ( ) const

Return true if this Object contains an unnamed, one-object property that contains objects of the given template type T.

The type must match exactly the type used when this property was created with addProperty<T>().

◆ isA()

virtual bool OpenSim::Object::isA ( const char * type ) const

inlinevirtual

The default implementation returns true only if the supplied string is "Object"; each Object-derived class overrides this to match its own class name.

◆ isEqualTo()

bool OpenSim::Object::isEqualTo ( const Object & aObject ) const

inline

Equality operator wrapper for use from languages not supporting operator overloading.

◆ isKindOf()

static bool OpenSim::Object::isKindOf ( const char * type )

inlinestatic

Returns true if the passed-in string is "Object"; each Object-derived class defines a method of this name for its own class name.

◆ isObjectTypeDerivedFrom()

template<class T >

static bool OpenSim::Object::isObjectTypeDerivedFrom ( const std::string & concreteClassName )

inlinestatic

Return true if the given concrete object type represents a subclass of the template object type T, and thus could be referenced with a T*.

The object type to be tested is given by its class name as a string. For this to work the name must represent an already-registered object type. If necessary concreteClassName will be mapped through the renamed type table, so we'll return true if the class it maps to satisfies the condition. Note that renaming is applied first, prior to looking up the name in the registered objects table.

See also: registerType(), renameType()

◆ isObjectUpToDateWithProperties()

bool OpenSim::Object::isObjectUpToDateWithProperties ( ) const

inline

Returns true if no property's value has changed since the last time setObjectIsUpToDateWithProperties() was called.

◆ makeObjectFromFile()

static Object* OpenSim::Object::makeObjectFromFile ( const std::string & fileName )

static

Create an OpenSim object whose type is based on the tag at the root node of the XML file passed in.

This is useful since the constructor of Object doesn't have the proper type info. This works by using the defaults table so that Object does not need to know about its derived classes. It uses the defaults table to get an instance.

◆ makeObjectNamesConsistentWithProperties()

void OpenSim::Object::makeObjectNamesConsistentWithProperties ( )

protected

Make sure the name of an object is consistent with its property type.

A name can be changed independent of the property name, which may be inconsistent with any restrictions specified by the Property. For example, unnamed property object should not have a name. Furthermore, named properties whose object name is empty, should have the property name.

◆ newInstanceOfType()

static Object* OpenSim::Object::newInstanceOfType ( const std::string & concreteClassName )

static

Create a new instance of the concrete Object type whose class name is given as concreteClassName.

The instance is initialized to the default object of corresponding type, possibly after renaming to the current class name. Writes a message to stderr and returns null if the tag isn't registered.

◆ operator<()

virtual bool OpenSim::Object::operator< ( const Object & aObject ) const

virtual

Provide an ordering for objects so they can be put in sorted containers.

◆ operator=()

Object& OpenSim::Object::operator= ( const Object & aObject )

Copy assignment copies he base class fields, including the properties.

◆ operator==()

virtual bool OpenSim::Object::operator== ( const Object & aObject ) const

virtual

Determine if two objects are equal.

They are equal if all the simple base class members are equal, both objects have the same number of properties and corresponding properties are equal, and if the objects are the same concrete type and the concrete class says they are equal. Concrete object classes must override this if they have any fields to compare, but be sure to invoke the base class operator too. To print information about the exact differences, set the debug level (setDebugLevel()) to a number greater than 0.

◆ print()

bool OpenSim::Object::print ( const std::string & fileName ) const

Write this Object into an XML file of the given name; conventionally the suffix to use is ".osim".

This is useful for writing out a Model that has been created programmatically, and also very useful for testing and debugging. If object has invalid connections, then printing is aborted. You can override this behavior by setting the debug level to at least 1 (e.g., Object::setDebugLevel(1)) prior to printing.

Examples:: exampleHangingMuscle.cpp, exampleSlidingMass.cpp, and exampleTracking.cpp.

◆ PrintPropertyInfo() [1/2]

static bool OpenSim::Object::PrintPropertyInfo	(	std::ostream &	os,
		const std::string &	classNameDotPropertyName,
		bool	printFlagInfo = `true`
	)

static

Dump formatted property information to a given output stream, useful for creating a "help" facility for registered objects.

Object name, property name, and property comment are output. Input is a class name and property name. If the property name is the empty string or just "*", then information for all properties in the class is printed. If the class name is empty, information in all properties of all registered classes is printed.

Parameters

os	Output stream to which info is printed.
classNameDotPropertyName	A string combining the class name and property name. The two names should be separated by a period (ClassName.PropertyName). If PropertyName is empty or "*", the information for all properties in the class is printed. If ClassName is empty, the information for the properties of all registered classes is printed.
printFlagInfo	Print to the ostream some instructions for using the -PropertyInfo command line flag.

Returns false if the provided names do not match known classes or properties; otherwise, returns true.

◆ PrintPropertyInfo() [2/2]

static bool OpenSim::Object::PrintPropertyInfo	(	std::ostream &	os,
		const std::string &	className,
		const std::string &	propertyName,
		bool	printFlagInfo = `true`
	)

static

Same as the other signature but the class name and property name are provided as two separate strings.

Returns false if the provided names do not match known classes or properties; otherwise, returns true.

◆ readObjectFromXMLNodeOrFile()

void OpenSim::Object::readObjectFromXMLNodeOrFile	(	SimTK::Xml::Element &	objectElement,
		int	versionNumber
	)

We're given an XML element from which we are to populate this Object.

If the element has a file attribute, we'll instead read the Object from that file. Otherwise we'll invoke updateFromXMLNode() to read the Object directly from the supplied element. Note that a relative file name will be interpreted relative to the current working directory, but that will normally have been set earlier to the directory containing the top-level (root) Object, such as the Model file.

◆ registerType()

static void OpenSim::Object::registerType ( const Object & defaultObject )

static

Register an instance of a class; if the class is already registered it will be replaced.

This is normally called as part of the static initialization of a dynamic library (DLL). The supplied object's concrete class name will be used as a key, and a copy (via clone()) of the supplied Object is used as the default value for objects of this type when created (typically during the deserialization process when reading an XML file).

◆ RegisterType()

static void OpenSim::Object::RegisterType ( const Object & defaultObject )

inlinestatic

OBSOLETE alternate name for registerType().

◆ renameType()

static void OpenSim::Object::renameType	(	const std::string &	oldTypeName,
		const std::string &	newTypeName
	)

static

Support versioning by associating the current Object type with an old name.

This is only allowed if newTypeName has already been registered with registerType(). Renaming is applied first prior to lookup so can be used both for translating now-obsolete names to their new names and for overriding one registered type with another.

◆ RenameType()

static void OpenSim::Object::RenameType	(	const std::string &	oldName,
		const std::string &	newName
	)

inlinestatic

OBSOLETE alternate name for renameType().

◆ SafeCopy()

static Object* OpenSim::Object::SafeCopy ( const Object * aObject )

inlinestatic

Use the clone() method to duplicate the given object unless the pointer is null in which case null is returned.

References clone().

◆ setAllPropertiesUseDefault()

void OpenSim::Object::setAllPropertiesUseDefault ( bool aUseDefault )

◆ setAuthors()

void OpenSim::Object::setAuthors ( const std::string & authors )

inline

Set Authors of this object.

Call this method in your constructor if needed.

Referenced by OpenSim::PolynomialFunction::createSimTKFunction().

◆ setDebugLevel()

static void OpenSim::Object::setDebugLevel ( int newLevel )

static

Set the amount of logging output.

Higher numbers generate more logging output.

-4: Off
-3: Critical
-2: Error
-1: Warn
0: Info
1: Debug
2: Trace
3: Trace (for backwards compatibility). (Deprecated) Use Log::setLevel() instead.

◆ setDescription()

void OpenSim::Object::setDescription ( const std::string & description )

Set description, a one-liner summary.

◆ setDocument()

void OpenSim::Object::setDocument ( XMLDocument * doc )

inlineprotected

Unconditionally set the XMLDocument associated with this object.

Use carefully – if there was already a document its heap space is lost here.

◆ setInlined()

void OpenSim::Object::setInlined	(	bool	aInlined,
		const std::string &	aFileName = `""`
	)

Mark this as inlined or not and optionally provide a file name to associate with the new XMLDocument for the non-inline case.

If there was already a document associated with this object it is deleted.

◆ setName()

void OpenSim::Object::setName ( const std::string & name )

Set the name of the Object.

Examples:: example2DWalking.cpp, example2DWalkingMetabolics.cpp, exampleHangingMuscle.cpp, exampleMarkerTracking.cpp, exampleMocoCustomEffortGoal.cpp, exampleMocoInverse.cpp, exampleMocoTrack.cpp, exampleSlidingMass.cpp, exampleSlidingMassAdvanced.cpp, and exampleTracking.cpp.

Referenced by OpenSim::ModelComponentSet< Constraint >::extendFinalizeFromProperties(), and OpenSim::Set< Force, ModelComponent >::renameGroup().

◆ setObjectIsUpToDateWithProperties()

void OpenSim::Object::setObjectIsUpToDateWithProperties ( )

protected

When an object is initialized using the current values of its properties, it can set a flag indicating that it is up to date.

This flag is automatically cleared when any property is modified. This allows objects to avoid expensive reinitialization if it is unnecessary (that is, whenever this Object hands out writable access to a property). Note that use of this flag is entirely optional; most Object classes don't have any expensive initialization to worry about.

This flag is cleared automatically but if you want to clear it manually for testing or debugging, see clearObjectIsUpToDateWithProperties().

◆ setReferences()

void OpenSim::Object::setReferences ( const std::string & references )

inline

Set references or publications to cite if using this object.

◆ setSerializeAllDefaults()

static void OpenSim::Object::setSerializeAllDefaults ( bool shouldSerializeDefaults )

inlinestatic

Static function to control whether all registered objects and their properties are written to the defaults section of output files rather than only those values for which the default was explicitly overwritten when read in from an input file or set programmatically.

◆ toString()

const std::string& OpenSim::Object::toString ( ) const

Wrapper to be used on Java side to display objects in tree; this returns just the object's name.

◆ updateFromXMLDocument()

void OpenSim::Object::updateFromXMLDocument ( )

protected

Use this method only if you're deserializing from a file and the object is at the top level; that is, primarily in constructors that take a file name as input.

◆ updateFromXMLNode()

virtual void OpenSim::Object::updateFromXMLNode	(	SimTK::Xml::Element &	objectElement,
		int	versionNumber
	)

virtual

Use this method to deserialize an object from a SimTK::Xml::Element.

The element is assumed to be in the format consistent with the passed-in versionNumber. If there is a file attribute in objectElement it will be ignored; if you want it processed you should call readObjectFromXMLNodeOrFile() instead.

Reimplemented in OpenSim::Component, OpenSim::Model, OpenSim::AbstractTool, OpenSim::Joint, OpenSim::ModelComponent, OpenSim::Coordinate, OpenSim::Force, OpenSim::TwoFrameLinker< Force, PhysicalFrame >, OpenSim::TwoFrameLinker< Constraint, PhysicalFrame >, OpenSim::Probe, OpenSim::RRATool, OpenSim::PhysicalFrame, OpenSim::RollingOnSurfaceConstraint, OpenSim::ContactGeometry, OpenSim::WrapObject, OpenSim::GCVSpline, OpenSim::Controller, OpenSim::CustomJoint, OpenSim::PointToPointSpring, OpenSim::Appearance, OpenSim::PrescribedForce, OpenSim::SimmSpline, OpenSim::PiecewiseLinearFunction, OpenSim::Constraint, OpenSim::ConstantDistanceConstraint, OpenSim::CMC_Joint, OpenSim::ForwardTool, OpenSim::CMC_Point, OpenSim::InverseDynamicsTool, OpenSim::ExternalLoads, OpenSim::PointConstraint, OpenSim::AbstractPathPoint, OpenSim::Marker, OpenSim::InverseKinematicsTool, OpenSim::MovingPathPoint, and OpenSim::PointOnLineConstraint.

◆ updateXMLNode()

void OpenSim::Object::updateXMLNode	(	SimTK::Xml::Element &	parent,
		const AbstractProperty *	prop = `nullptr`
	)		const

Serialize this object into the XML node that represents it.

Parameters

parent Parent XML node of this object. Sending in a parent node allows an XML node to be generated for this object if it doesn't already have one. If no parent node is supplied and this object doesn't already have an XML node, this object will become the root node for a new XML document. If this object already has an XML node associated with it, no new nodes are ever generated and the parent node is not used.

prop (optional) The pointer to the property that contains this object. If it is present, check if the property is unnamed and if NOT, use the property name as its name when updating the XML node.

◆ updDocument()

XMLDocument* OpenSim::Object::updDocument ( )

inlineprotected

Get a writable pointer to the document (if any) associated with this object.

◆ updProperty()

template<class T >

Property< T > & OpenSim::Object::updProperty ( const PropertyIndex & index )

Get property of known type Property<T> as a writable reference; the property must be present and have the right type.

This is primarily used by the Property declaration macros for fast access to properties.

◆ updPropertyByIndex()

AbstractProperty& OpenSim::Object::updPropertyByIndex ( int propertyIndex )

Get a writable reference to a property by its index number, returned as an AbstractProperty.

◆ updPropertyByName()

AbstractProperty& OpenSim::Object::updPropertyByName ( const std::string & name )

Get a writable reference to a property by its name, returned as an AbstractProperty.

An exception is thrown if no property by this name is present in this Object.

Friends And Related Function Documentation

◆ OpenSim_DECLARE_ABSTRACT_OBJECT

#define OpenSim_DECLARE_ABSTRACT_OBJECT	(	ConcreteClass,
		SuperClass
	)

These are classes that represent categories of objects, like Function and ModelComponent. This macro leaves Object pure virtuals clone() and getConcreteClassName() unimplemented, however it does redeclare the return type of clone() to be ConcreteClass*.

◆ OpenSim_DECLARE_ABSTRACT_OBJECT_T

#define OpenSim_DECLARE_ABSTRACT_OBJECT_T	(	ConcreteClass,
		TArg,
		SuperClass
	)

◆ OpenSim_DECLARE_CONCRETE_OBJECT

#define OpenSim_DECLARE_CONCRETE_OBJECT	(	ConcreteClass,
		SuperClass
	)

You should use this for any such class, even if you intend to derive more specific concrete objects from it. Don't use this for a still-abstract class, or a templatized concrete class like Set<T>.

◆ OpenSim_DECLARE_CONCRETE_OBJECT_T

#define OpenSim_DECLARE_CONCRETE_OBJECT_T	(	ConcreteClass,
		TArg,
		SuperClass
	)

◆ operator<<

std::ostream& operator<<	(	std::ostream &	aOut,
		const Object &	aObject
	)

friend

Write the type and name of this object into the given output stream.

Member Data Documentation

◆ _propertySet

PropertySet OpenSim::Object::_propertySet

protected

OBSOLETE: Property_Deprecated set for serializable member variables of this and derived classes.

◆ DEFAULT_NAME

const std::string OpenSim::Object::DEFAULT_NAME

static

Name used for default objects when they are serialized.

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

OpenSim/Common/Object.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Friends

Related Functions

Public access to properties

XML reading and writing

Advanced/Obscure

Detailed Description

Object declaration

Object registration and renaming

Defaults mechanism

Constructor & Destructor Documentation

◆ ~Object()

◆ Object() [1/4]

◆ Object() [2/4]

◆ Object() [3/4]

◆ Object() [4/4]

Member Function Documentation

◆ addListProperty() [1/2]

◆ addListProperty() [2/2]

◆ addOptionalProperty() [1/2]

◆ addOptionalProperty() [2/2]

◆ addProperty()

◆ checkPropertyValueIsInRangeOrSet()

◆ checkPropertyValueIsInSet()

◆ checkPropertyValueIsPositive()

◆ clearObjectIsUpToDateWithProperties()

◆ clone()

◆ dump()

◆ getAuthors()

◆ getClassName()

◆ getConcreteClassName()

◆ getDebugLevel()

◆ getDefaultInstanceOfType()

◆ getDescription()

◆ getDocument()

◆ getDocumentFileName()

◆ getDocumentFileVersion()

◆ getInlined()

◆ getName()

◆ getNumProperties()

◆ getProperty()

◆ getPropertyByIndex()

◆ getPropertyByName()

◆ getPropertyIndex() [1/2]

◆ getPropertyIndex() [2/2]

◆ getPropertySet() [1/2]

◆ getPropertySet() [2/2]

◆ getReferences()

◆ getRegisteredObjectsOfGivenType()

◆ getRegisteredTypenames()

◆ getSerializeAllDefaults()

◆ hasProperty() [1/2]

◆ hasProperty() [2/2]

◆ isA()

◆ isEqualTo()

◆ isKindOf()

◆ isObjectTypeDerivedFrom()

◆ isObjectUpToDateWithProperties()

◆ makeObjectFromFile()

◆ makeObjectNamesConsistentWithProperties()

◆ newInstanceOfType()

◆ operator<()

◆ operator=()

◆ operator==()

◆ print()

◆ PrintPropertyInfo() [1/2]

◆ PrintPropertyInfo() [2/2]

◆ readObjectFromXMLNodeOrFile()

◆ registerType()

◆ RegisterType()

◆ renameType()

◆ RenameType()

◆ SafeCopy()

◆ setAllPropertiesUseDefault()

◆ setAuthors()

◆ setDebugLevel()