OpenSim  OpenSim 3.2
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Pages
OpenSim::Object Class Referenceabstract

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

#include <Object.h>

Inheritance diagram for OpenSim::Object:
OpenSim::AbstractTool OpenSim::Analysis OpenSim::Bhargava2004MuscleMetabolicsProbe_MetabolicMuscleParameter OpenSim::BodyScale OpenSim::Condition OpenSim::Control OpenSim::ControlLinearNode OpenSim::DisplayGeometry OpenSim::Function OpenSim::GenericModelMaker OpenSim::IKTask OpenSim::Marker OpenSim::MarkerData OpenSim::MarkerFrame OpenSim::MarkerPair OpenSim::MarkerPlacer OpenSim::MarkerWeight OpenSim::Measurement OpenSim::ModelComponent OpenSim::ModelScaler OpenSim::MuscleFirstOrderActivationDynamicModel OpenSim::MuscleFixedWidthPennationModel OpenSim::MuscleSecondOrderActivationDynamicModel OpenSim::ObjectGroup OpenSim::PathPoint OpenSim::Reference_< T > OpenSim::Scale OpenSim::ScaleTool OpenSim::Set< T > OpenSim::SimbodyEngine OpenSim::Solver OpenSim::SpatialTransform OpenSim::StorageInterface OpenSim::Tool OpenSim::TrackingTask OpenSim::TransformAxis OpenSim::Umberger2010MuscleMetabolicsProbe_MetabolicMuscleParameter OpenSim::VectorFunction OpenSim::VisibleObject OpenSim::Reference_< double > OpenSim::Reference_< SimTK::Vec3 > OpenSim::Set< Analysis > OpenSim::Set< Bhargava2004MuscleMetabolicsProbe_MetabolicMuscleParameter > OpenSim::Set< Body > OpenSim::Set< BodyScale > OpenSim::Set< Constraint > OpenSim::Set< ContactGeometry > OpenSim::Set< Control > OpenSim::Set< Controller > OpenSim::Set< Coordinate > OpenSim::Set< DisplayGeometry > OpenSim::Set< ExternalForce > OpenSim::Set< Force > OpenSim::Set< Function > OpenSim::Set< IKTask > OpenSim::Set< Joint > OpenSim::Set< Marker > OpenSim::Set< MarkerPair > OpenSim::Set< Measurement > OpenSim::Set< ModelComponent > OpenSim::Set< OpenSim::Actuator > OpenSim::Set< OpenSim::Constraint > OpenSim::Set< OpenSim::Force > OpenSim::Set< OpenSim::MarkerWeight > OpenSim::Set< OpenSim::Muscle > OpenSim::Set< PathPoint > OpenSim::Set< Probe > OpenSim::Set< Scale > OpenSim::Set< TrackingTask > OpenSim::Set< Umberger2010MuscleMetabolicsProbe_MetabolicMuscleParameter >

Public Member Functions

virtual ~Object ()
 Virtual destructor for cleanup. More...
 
virtual Objectclone () 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...
 
virtual const VisibleObjectgetDisplayer () const
 Methods to support making the object displayable in the GUI or Visualizer Implemented only in few objects. More...
 
virtual VisibleObjectupdDisplayer ()
 get Non const pointer to VisibleObject More...
 
bool isEqualTo (const Object &aObject) const
 Equality operator wrapper for use from languages not supporting operator overloading. More...
 
Objectoperator= (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, call this method in your constructor if needed. 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 ObjectgetDefaultInstanceOfType (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 ObjectnewInstanceOfType (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) SWIG_DECLARE_EXCEPTION
 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...
 

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 AbstractPropertygetPropertyByIndex (int propertyIndex) const
 Get a const reference to a property by its index number, returned as an AbstractProperty. More...
 
AbstractPropertyupdPropertyByIndex (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 AbstractPropertygetPropertyByName (const std::string &name) const
 Get a const reference to a property by its name, returned as an AbstractProperty. More...
 
AbstractPropertyupdPropertyByName (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...
 
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...
 
bool isObjectUpToDateWithProperties () const
 Returns true if no property's value has changed since the last time setObjectIsUpToDateWithProperties() was called. More...
 
static void PrintPropertyInfo (std::ostream &os, const std::string &classNameDotPropertyName)
 Dump formatted property information to a given output stream, useful for creating a "help" facility for registered objects. More...
 
static void PrintPropertyInfo (std::ostream &os, const std::string &className, const std::string &propertyName)
 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...
 
virtual void updateXMLNode (SimTK::Xml::Element &parent)
 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...
 
void setAllPropertiesUseDefault (bool aUseDefault)
 
bool print (const std::string &fileName)
 Write this Object into an XML file of the given name; conventionally the suffix to use is ".osim". More...
 
std::string dump (bool dumpName=false)
 dump the XML representation of this Object into an std::string and return it. More...
 
static ObjectmakeObjectFromFile (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 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 XMLDocumentgetDocument () const
 Get a const pointer to the document (if any) associated with this object. More...
 
XMLDocumentupdDocument ()
 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.

void clearObjectIsUpToDateWithProperties ()
 For testing or debugging purposes, manually clear the "object is up to date with respect to properties" flag. More...
 
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...
 
PropertySetgetPropertySet ()
 OBSOLETE: Get a reference to the PropertySet maintained by the Object. More...
 
const PropertySetgetPropertySet () 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 debug level to get verbose output. More...
 
static int getDebugLevel ()
 Get current setting of debug level. More...
 
static ObjectSafeCopy (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

  1. Primitive data types (int, bool, double, std::string, ...)
  2. Properties that contain other Objects,
  3. 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

virtual OpenSim::Object::~Object ( )
virtual

Virtual destructor for cleanup.

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.

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.

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.

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

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 proprty table for this object.
See Also
addProperty(), addOptionalProperty()

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

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 proprty table for this object.
See Also
addProperty(), addOptionalProperty()

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

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

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

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

void OpenSim::Object::clearObjectIsUpToDateWithProperties ( )
inline

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

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::ControlLinear::insertNewMaxNode(), OpenSim::ControlLinear::insertNewMinNode(), OpenSim::ControlLinear::insertNewValueNode(), SafeCopy(), OpenSim::CoordinateCouplerConstraint::setFunction(), OpenSim::PropertyObj::setValueAsObject(), and OpenSim::PropertyObjPtr< OpenSim::Function >::setValueAsObject().

std::string OpenSim::Object::dump ( bool  dumpName = false)

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.

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

Get Authors of this Object.

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.

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

static int OpenSim::Object::getDebugLevel ( )
inlinestatic

Get current setting of debug level.

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()
const std::string& OpenSim::Object::getDescription ( ) const

Get description, a one-liner summary.

virtual const VisibleObject* OpenSim::Object::getDisplayer ( ) const
inlinevirtual

Methods to support making the object displayable in the GUI or Visualizer Implemented only in few objects.

Get const pointer to VisibleObject that contains geometry

Reimplemented in OpenSim::PathSpring, OpenSim::GeometryPath, OpenSim::ExpressionBasedPointToPointForce, OpenSim::ContactGeometry, OpenSim::PathPoint, OpenSim::Body, OpenSim::Marker, OpenSim::PathActuator, OpenSim::Ligament, and OpenSim::PointToPointSpring.

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

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

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.

bool OpenSim::Object::getInlined ( ) const

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

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

Get the name of this Object.

Referenced by OpenSim::ProbeReporter::disableIntegrationOnlyProbes().

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.

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.

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

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

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.

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

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

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

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

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

const PropertySet& OpenSim::Object::getPropertySet ( ) const
inline
const std::string& OpenSim::Object::getReferences ( ) const
inline

Get references or publications to cite if using this object.

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.

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.

static bool OpenSim::Object::getSerializeAllDefaults ( )
inlinestatic

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

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.

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

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.

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

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

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.

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()
bool OpenSim::Object::isObjectUpToDateWithProperties ( ) const
inline

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

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.

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.

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

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

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

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

Referenced by OpenSim::StorageInterface::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.

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

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.

static void OpenSim::Object::PrintPropertyInfo ( std::ostream &  os,
const std::string &  classNameDotPropertyName 
)
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
osOutput stream to which info is printed.
classNameDotPropertyNameA 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.
static void OpenSim::Object::PrintPropertyInfo ( std::ostream &  os,
const std::string &  className,
const std::string &  propertyName 
)
static

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

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.

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

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

OBSOLETE alternate name for registerType().

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.

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

OBSOLETE alternate name for renameType().

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

void OpenSim::Object::setAllPropertiesUseDefault ( bool  aUseDefault)
void OpenSim::Object::setAuthors ( const std::string &  authors)
inline

Set Authors of this object, call this method in your constructor if needed.

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

Set the debug level to get verbose output.

Zero means no debugging.

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

Set description, a one-liner summary.

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.

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.

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

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

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

Set references or publications to cite if using this object.

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.

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.

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.

Referenced by OpenSim::Set< Control >::Set().

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::Model, OpenSim::AbstractTool, OpenSim::VisibleObject, OpenSim::CMC_Task, OpenSim::RRATool, OpenSim::GCVSpline, OpenSim::SimmSpline, OpenSim::PiecewiseLinearFunction, OpenSim::InverseKinematicsTool, OpenSim::PrescribedForce, OpenSim::PathActuator, OpenSim::ForwardTool, OpenSim::ExternalForce, OpenSim::MovingPathPoint, OpenSim::CMC_Joint, OpenSim::InverseDynamicsTool, OpenSim::CMC_Point, OpenSim::ExternalLoads, OpenSim::CustomJoint, and OpenSim::ConditionalPathPoint.

virtual void OpenSim::Object::updateXMLNode ( SimTK::Xml::Element &  parent)
virtual

Serialize this object into the XML node that represents it.

Parameters
parentParent 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.
virtual VisibleObject* OpenSim::Object::updDisplayer ( )
inlinevirtual

get Non const pointer to VisibleObject

Reimplemented in OpenSim::ContactGeometry, OpenSim::PathPoint, OpenSim::Body, and OpenSim::Marker.

XMLDocument* OpenSim::Object::updDocument ( )
inlineprotected

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

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.

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

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

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

#define OpenSim_DECLARE_ABSTRACT_OBJECT (   ConcreteClass,
  SuperClass 
)
related
Value:
OpenSim_OBJECT_ANY_DEFS(ConcreteClass, SuperClass); \
OpenSim_OBJECT_NONTEMPLATE_DEFS(ConcreteClass, SuperClass); \
OpenSim_OBJECT_ABSTRACT_DEFS(ConcreteClass);

Macro to be included as the first line of the class declaration for any still-abstract class that derives from OpenSim::Object.

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

#define OpenSim_DECLARE_ABSTRACT_OBJECT_T (   ConcreteClass,
  TArg,
  SuperClass 
)
related
Value:
OpenSim_OBJECT_ANY_DEFS(ConcreteClass, SuperClass); \
OpenSim_OBJECT_TEMPLATE_DEFS(ConcreteClass, TArg, SuperClass); \
OpenSim_OBJECT_ABSTRACT_DEFS(ConcreteClass);

Macro to be included as the first line of the class declaration for any templatized, still-abstract class that derives from OpenSim::Object.

#define OpenSim_DECLARE_CONCRETE_OBJECT (   ConcreteClass,
  SuperClass 
)
related
Value:
OpenSim_OBJECT_ANY_DEFS(ConcreteClass, SuperClass); \
OpenSim_OBJECT_NONTEMPLATE_DEFS(ConcreteClass, SuperClass); \
OpenSim_OBJECT_CONCRETE_DEFS(ConcreteClass);

Macro to be included as the first line of the class declaration for any non-templatized, concrete class that derives from OpenSim::Object.

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

#define OpenSim_DECLARE_CONCRETE_OBJECT_T (   ConcreteClass,
  TArg,
  SuperClass 
)
related
Value:
OpenSim_OBJECT_ANY_DEFS(ConcreteClass, SuperClass); \
OpenSim_OBJECT_TEMPLATE_DEFS(ConcreteClass, TArg, SuperClass); \
OpenSim_OBJECT_CONCRETE_DEFS(ConcreteClass);

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

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 OpenSim::Object::_propertySet
protected

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

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: