Orocos Real-Time Toolkit  2.8.3
Public Types | Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
RTT::Property< T > Class Template Reference

A property represents a named value of any type with a description. More...

#include <rtt/Property.hpp>

Inheritance diagram for RTT::Property< T >:
RTT::base::PropertyBase

Public Types

typedef boost::remove_const< typename boost::remove_reference< T >::type >::type value_t
 The types of this property type. More...
 
typedef boost::call_traits< value_t >::param_type param_t
 
typedef boost::call_traits< value_t >::reference reference_t
 
typedef boost::call_traits< value_t >::const_reference const_reference_t
 
typedef value_t DataSourceType
 

Public Member Functions

 Property ()
 Create an empty Property with no name, no description and no value. More...
 
 Property (const std::string &name)
 The constructor which initializes the property's value to the default. More...
 
 Property (const std::string &name, const std::string &description, param_t value=value_t())
 The constructor which initializes the property's value. More...
 
 Property (const Property< T > &orig)
 Copy constructors copies the name, description and value as deep copies. More...
 
 Property (base::PropertyBase *source)
 Create a Property mirroring another PropertyBase. More...
 
 Property (const std::string &name, const std::string &description, const typename internal::AssignableDataSource< DataSourceType >::shared_ptr &datasource)
 The constructor which initializes the property with a DataSource. More...
 
Property< T > & operator= (param_t value)
 Set the property's value. More...
 
Property< T > & operator= (base::PropertyBase *source)
 Mirror another PropertyBase (name, description and value). More...
 
Property< T > & operator<<= (Property< T > &p)
 Update the value of this property with another property. More...
 
Property< T > & doc (const std::string &descr)
 Documents this property. More...
 
 operator value_t () const
 Get a copy of the value of the property. More...
 
DataSourceType get () const
 Get a copy of the value of the property. More...
 
reference_t set ()
 Access to the value of the Property. More...
 
void set (param_t v)
 Set the value of the Property. More...
 
reference_t value ()
 Access to the value of the Property. More...
 
const_reference_t rvalue () const
 Read-only (const&) access to the value of the Property. More...
 
virtual void identify (base::PropertyIntrospection *pi)
 A call on this method will lead to a call to the PropertyIntrospection interface identifying this Property's proper type. More...
 
virtual void identify (base::PropertyBagVisitor *pi)
 A call on this method will lead to a call to the PropertyBagIntrospection interface identifying this Property's proper type. More...
 
virtual bool update (const base::PropertyBase *other)
 Update the value of this Property with the value of an other Property. More...
 
virtual bool refresh (const base::PropertyBase *other)
 Refresh the value of this Property with the value of an other Property. More...
 
virtual bool copy (const base::PropertyBase *other)
 Copy an other Property onto this property. More...
 
bool copy (const Property< T > &orig)
 Copy the value, complete overwrite of this Property with orig. More...
 
bool update (const Property< T > &orig)
 Update the value, optionally also the description if current description is empty. More...
 
bool refresh (const Property< T > &orig)
 Refresh only the value from a Property. More...
 
virtual Property< T > * clone () const
 Deliver an identical clone of this PropertyBase. More...
 
virtual Property< T > * create () const
 Create a new default instance of the PropertyBase. More...
 
virtual Property< T > * create (const base::DataSourceBase::shared_ptr &datasource) const
 Create a new instance of the PropertyBase with a custom data source. More...
 
virtual base::DataSourceBase::shared_ptr getDataSource () const
 Get an assignable base::DataSource through which this PropertyBase can be manipulated. More...
 
internal::AssignableDataSource< DataSourceType >::shared_ptr getAssignableDataSource () const
 
virtual bool setDataSource (const base::DataSourceBase::shared_ptr &dsb)
 Assign an external assignable base::DataSource to this property. More...
 
virtual std::string getType () const
 Returns the type of this PropertyBase. More...
 
virtual const types::TypeInfogetTypeInfo () const
 Returns the types::TypeInfo object of this Property. More...
 
template<>
void identify (PropertyBagVisitor *pbi)
 A call on this method will lead to a call to the PropertyBagIntrospection interface identifying this Property's proper type. More...
 
template<>
RTT_API bool update (const Property< PropertyBag > &orig)
 Partial specialisations in case of PropertyBag. More...
 
template<>
RTT_API bool refresh (const Property< PropertyBag > &orig)
 
template<>
RTT_API bool copy (const Property< PropertyBag > &orig)
 
template<>
RTT_API void identify (base::PropertyBagVisitor *pbi)
 A call on this method will lead to a call to the PropertyBagIntrospection interface identifying this Property's proper type. More...
 
template<>
bool update (const Property< PropertyBag > &orig)
 
template<>
bool refresh (const Property< PropertyBag > &orig)
 
template<>
bool copy (const Property< PropertyBag > &orig)
 
const std::string & getName () const
 Get the name of the property. More...
 
void setName (const std::string &name)
 Set the name of the property. More...
 
const std::string & getDescription () const
 Get a description of the property. More...
 
void setDescription (const std::string &desc)
 Set the description of the property. More...
 
bool ready () const
 Inspect if this Property is correctly initialised and ready for usage. More...
 
virtual bool compose (const PropertyBag &source)
 Composes the data of this property with information found in a PropertyBag. More...
 

Static Public Member Functions

static Property< T > * narrow (base::PropertyBase *prop)
 Use this method instead of dynamic_cast<> to cast from base::PropertyBase to Property<T>. More...
 

Protected Attributes

internal::AssignableDataSource< DataSourceType >::shared_ptr _value
 
std::string _name
 A short name for this PropertyBase. More...
 
std::string _description
 A lengthy description for this PropertyBase. More...
 

Detailed Description

template<typename T>
class RTT::Property< T >

A property represents a named value of any type with a description.

A property is a tuple of a name, a description and a variable of any type. It's purpose is to provide a hierarchical parameter of a component. They are grouped in PropertyBag objects and a Property can contain a PropertyBag itself.

If you do not provide a name nor description when constructing the Property object, it will be uninitialised and ready() will return false. Such an object may not be used (set(), get(),...) until it has been initialised from another Property. Otherwise, an exception (or assert) will be thrown.

Parameters
TThe type of the data contained within the Property.

Definition at line 76 of file Property.hpp.

Member Typedef Documentation

template<typename T>
typedef boost::call_traits<value_t>::const_reference RTT::Property< T >::const_reference_t

Definition at line 88 of file Property.hpp.

template<typename T>
typedef value_t RTT::Property< T >::DataSourceType

Definition at line 89 of file Property.hpp.

template<typename T>
typedef boost::call_traits<value_t>::param_type RTT::Property< T >::param_t

Definition at line 86 of file Property.hpp.

template<typename T>
typedef boost::call_traits<value_t>::reference RTT::Property< T >::reference_t

Definition at line 87 of file Property.hpp.

template<typename T>
typedef boost::remove_const<typename boost::remove_reference<T>::type>::type RTT::Property< T >::value_t

The types of this property type.

value_t is always the 'bare' value type of T. From this type, we derive the other (param, ref, ...) types.

Definition at line 85 of file Property.hpp.

Constructor & Destructor Documentation

template<typename T>
RTT::Property< T >::Property ( )
inline

Create an empty Property with no name, no description and no value.

Postcondition
ready() will return false. Initialise this Property with another Property object.

Definition at line 95 of file Property.hpp.

template<typename T>
RTT::Property< T >::Property ( const std::string &  name)
inlineexplicit

The constructor which initializes the property's value to the default.

Parameters
nameThe name which will be used to refer to the property.
Postcondition
ready() will always be true.

Definition at line 104 of file Property.hpp.

template<typename T>
RTT::Property< T >::Property ( const std::string &  name,
const std::string &  description,
param_t  value = value_t() 
)
inline

The constructor which initializes the property's value.

Parameters
nameThe name which will be used to refer to the property.
descriptionThe description of the property.
valueThe initial value of the property (optional).
Postcondition
ready() will always be true.

Definition at line 117 of file Property.hpp.

template<typename T>
RTT::Property< T >::Property ( const Property< T > &  orig)
inline

Copy constructors copies the name, description and value as deep copies.

Postcondition
ready() will be true if orig.ready() is true.

Definition at line 127 of file Property.hpp.

template<typename T>
RTT::Property< T >::Property ( base::PropertyBase source)
inline

Create a Property mirroring another PropertyBase.

It copies the name and description, and shallow copies the value.

See also
ready() to inspect if the creation succeeded.

Definition at line 142 of file Property.hpp.

template<typename T>
RTT::Property< T >::Property ( const std::string &  name,
const std::string &  description,
const typename internal::AssignableDataSource< DataSourceType >::shared_ptr &  datasource 
)
inline

The constructor which initializes the property with a DataSource.

Parameters
nameThe name which will be used to refer to the property.
descriptionThe description of the property.
datasourceA new data source to be acquired by this property for storing its data.
Postcondition
ready() will be true if datasource is a valid pointer.

Definition at line 167 of file Property.hpp.

Member Function Documentation

template<typename T>
virtual Property<T>* RTT::Property< T >::clone ( ) const
inlinevirtual

Deliver an identical clone of this PropertyBase.

The original may be deleted and the clone can be transparantly used in its place or vice versa.

Implements RTT::base::PropertyBase.

Definition at line 371 of file Property.hpp.

bool RTT::PropertyBase::compose ( const PropertyBag source)
virtualinherited

Composes the data of this property with information found in a PropertyBag.

This only works for data types that defined a compose/decompose function in their type info structure.

Definition at line 80 of file PropertyBase.cpp.

References RTT::base::PropertyBase::getDataSource(), and RTT::base::DataSourceBase::ref().

template<>
bool RTT::Property< PropertyBag >::copy ( const Property< PropertyBag > &  orig)
template<typename T>
virtual bool RTT::Property< T >::copy ( const base::PropertyBase other)
inlinevirtual

Copy an other Property onto this property.

Copy does a full update of the name, description and value, adding extra information if necessary, or in case of a Property<PropertyBag> adding all Properties.

Copy only works on properties that are ready() and both have the same data type T.

Returns
false if the Properties are of different type.

Implements RTT::base::PropertyBase.

Definition at line 323 of file Property.hpp.

Referenced by RTT::Property< bool >::copy().

template<typename T>
bool RTT::Property< T >::copy ( const Property< T > &  orig)
inline

Copy the value, complete overwrite of this Property with orig.

Definition at line 335 of file Property.hpp.

template<>
RTT_API bool RTT::Property< PropertyBag >::copy ( const Property< PropertyBag > &  orig)
template<typename T>
virtual Property<T>* RTT::Property< T >::create ( ) const
inlinevirtual

Create a new default instance of the PropertyBase.

This is a factory method to 'make something of the same type'. The new PropertyBase has the same name and description as this.

Implements RTT::base::PropertyBase.

Definition at line 376 of file Property.hpp.

template<typename T>
virtual Property<T>* RTT::Property< T >::create ( const base::DataSourceBase::shared_ptr datasource) const
inlinevirtual

Create a new instance of the PropertyBase with a custom data source.

This is a factory method to 'make something of the same type'. The new PropertyBase has the same name and description as this.

Implements RTT::base::PropertyBase.

Definition at line 381 of file Property.hpp.

template<typename T>
Property<T>& RTT::Property< T >::doc ( const std::string &  descr)
inline

Documents this property.

Parameters
descrThe description of this property
Returns
A reference to this object.

Definition at line 228 of file Property.hpp.

template<typename T>
DataSourceType RTT::Property< T >::get ( ) const
inline
template<typename T>
internal::AssignableDataSource<DataSourceType>::shared_ptr RTT::Property< T >::getAssignableDataSource ( ) const
inline

Definition at line 397 of file Property.hpp.

template<typename T>
virtual base::DataSourceBase::shared_ptr RTT::Property< T >::getDataSource ( ) const
inlinevirtual

Get an assignable base::DataSource through which this PropertyBase can be manipulated.

Implements RTT::base::PropertyBase.

Definition at line 393 of file Property.hpp.

Referenced by RTT::types::composePropertyBag(), RTT::types::TemplateCompositionFactory< bool >::decomposeType(), and RTT::updateProperties().

const std::string& RTT::base::PropertyBase::getDescription ( ) const
inlineinherited
const std::string& RTT::base::PropertyBase::getName ( ) const
inlineinherited
template<typename T>
virtual std::string RTT::Property< T >::getType ( ) const
inlinevirtual

Returns the type of this PropertyBase.

Uses the naming scheme of DataSourceTypeInfo.

Implements RTT::base::PropertyBase.

Definition at line 417 of file Property.hpp.

Referenced by RTT::Property< bool >::create(), and RTT::Property< bool >::Property().

template<typename T>
virtual const types::TypeInfo* RTT::Property< T >::getTypeInfo ( ) const
inlinevirtual

Returns the types::TypeInfo object of this Property.

Implements RTT::base::PropertyBase.

Definition at line 421 of file Property.hpp.

Referenced by RTT::extras::composeProperty().

template<>
void RTT::Property< PropertyBag >::identify ( PropertyBagVisitor pi)
virtual

A call on this method will lead to a call to the PropertyBagIntrospection interface identifying this Property's proper type.

Deprecated:
DO NOT USE. Will be removed in 2.x release series.

Reimplemented from RTT::base::PropertyBase.

Definition at line 53 of file Property.cpp.

References RTT::base::PropertyBagVisitor::introspect().

template<class T >
void RTT::Property< T >::identify ( base::PropertyIntrospection pi)
virtual

A call on this method will lead to a call to the PropertyIntrospection interface identifying this Property's proper type.

Deprecated:
DO NOT USE. Will be removed in 2.x release series.

Implements RTT::base::PropertyBase.

Definition at line 462 of file Property.hpp.

References RTT::base::PropertyIntrospection::introspect().

Referenced by RTT::Property< T >::identify(), and RTT::Property< bool >::rvalue().

template<class T >
void RTT::Property< T >::identify ( base::PropertyBagVisitor pi)
virtual

A call on this method will lead to a call to the PropertyBagIntrospection interface identifying this Property's proper type.

Deprecated:
DO NOT USE. Will be removed in 2.x release series.

Reimplemented from RTT::base::PropertyBase.

Definition at line 468 of file Property.hpp.

References RTT::base::PropertyBase::identify(), RTT::Property< T >::identify(), and RTT_API.

template<>
RTT_API void RTT::Property< PropertyBag >::identify ( base::PropertyBagVisitor pi)
virtual

A call on this method will lead to a call to the PropertyBagIntrospection interface identifying this Property's proper type.

Deprecated:
DO NOT USE. Will be removed in 2.x release series.

Reimplemented from RTT::base::PropertyBase.

template<class T >
Property< T > * RTT::Property< T >::narrow ( base::PropertyBase prop)
static

Use this method instead of dynamic_cast<> to cast from base::PropertyBase to Property<T>.

You need to delete the returned property if it is no longer needed.

Parameters
TThe Desired property type, for example 'double'.
propThe property to narrow to Property<T>.
Returns
Null if prop is not convertible to type Property<T>, a new Property<T> instance otherwise.

Definition at line 451 of file Property.hpp.

Referenced by RTT::Property< bool >::rvalue().

template<typename T>
RTT::Property< T >::operator value_t ( ) const
inline

Get a copy of the value of the property.

Returns
A copy of the value of the property.

Definition at line 237 of file Property.hpp.

template<typename T>
Property<T>& RTT::Property< T >::operator<<= ( Property< T > &  p)
inline

Update the value of this property with another property.

Definition at line 217 of file Property.hpp.

template<typename T>
Property<T>& RTT::Property< T >::operator= ( param_t  value)
inline

Set the property's value.

Parameters
valueThe value to be set.
Returns
A reference to newly set property value.

Definition at line 181 of file Property.hpp.

template<typename T>
Property<T>& RTT::Property< T >::operator= ( base::PropertyBase source)
inlinevirtual

Mirror another PropertyBase (name, description and value).

Parameters
sourceA pointer to the property to mirror.

Implements RTT::base::PropertyBase.

Definition at line 191 of file Property.hpp.

bool RTT::base::PropertyBase::ready ( ) const
inlineinherited
template<>
bool RTT::Property< PropertyBag >::refresh ( const Property< PropertyBag > &  orig)

Definition at line 274 of file PropertyBag.cpp.

References RTT::refreshProperties(), and RTT::Property< T >::rvalue().

template<typename T>
virtual bool RTT::Property< T >::refresh ( const base::PropertyBase other)
inlinevirtual

Refresh the value of this Property with the value of an other Property.

Refresh does only the minimal update of the value, not adding extra information, or in case of a Property<PropertyBag> not adding extra Properties.

Refresh only works on properties that are ready() and both have the same data type T.

Returns
false if the Properties are of different type.

Implements RTT::base::PropertyBase.

Definition at line 314 of file Property.hpp.

Referenced by RTT::Property< bool >::refresh().

template<typename T>
bool RTT::Property< T >::refresh ( const Property< T > &  orig)
inline

Refresh only the value from a Property.

This is a real-time operation.

Definition at line 363 of file Property.hpp.

template<>
RTT_API bool RTT::Property< PropertyBag >::refresh ( const Property< PropertyBag > &  orig)
template<typename T>
const_reference_t RTT::Property< T >::rvalue ( ) const
inline
template<typename T>
reference_t RTT::Property< T >::set ( )
inline

Access to the value of the Property.

Identical to value().

Warning
This function is not suitable for remote (distributed) access of properties, use operator=() or set( param_t v ) to assign a value.

Definition at line 257 of file Property.hpp.

Referenced by RTT::scripting::PropertyParser::reset().

template<typename T>
void RTT::Property< T >::set ( param_t  v)
inline

Set the value of the Property.

Definition at line 265 of file Property.hpp.

template<typename T>
virtual bool RTT::Property< T >::setDataSource ( const base::DataSourceBase::shared_ptr dsb)
inlinevirtual

Assign an external assignable base::DataSource to this property.

Parameters
dsbThe other data source
Returns
false if the properties are of different type.

Implements RTT::base::PropertyBase.

Definition at line 406 of file Property.hpp.

Referenced by RTT::Property< bool >::operator=(), and RTT::Property< bool >::Property().

void RTT::PropertyBase::setDescription ( const std::string &  desc)
inherited

Set the description of the property.

Parameters
descThe description of the property.

Definition at line 64 of file PropertyBase.cpp.

References RTT::base::PropertyBase::_description.

Referenced by RTT::Property< bool >::doc(), and RTT::Property< bool >::operator=().

void RTT::PropertyBase::setName ( const std::string &  name)
inherited

Set the name of the property.

Parameters
nameThe name of the property.

Definition at line 59 of file PropertyBase.cpp.

References RTT::base::PropertyBase::_name.

Referenced by RTT::ConfigurationInterface::addProperty(), and RTT::Property< bool >::operator=().

template<>
bool RTT::Property< PropertyBag >::update ( const Property< PropertyBag > &  orig)
template<typename T>
virtual bool RTT::Property< T >::update ( const base::PropertyBase other)
inlinevirtual

Update the value of this Property with the value of an other Property.

Update does a full update of the value, adding extra information if necessary, or in case of a Property<PropertyBag> adding missing Properties.

Update only works on properties that are ready() and both have the same data type T.

Returns
false if the Properties are of different type or if this->ready() == false.

Implements RTT::base::PropertyBase.

Definition at line 305 of file Property.hpp.

Referenced by RTT::Property< bool >::operator<<=(), and RTT::Property< bool >::update().

template<typename T>
bool RTT::Property< T >::update ( const Property< T > &  orig)
inline

Update the value, optionally also the description if current description is empty.

Definition at line 349 of file Property.hpp.

template<>
RTT_API bool RTT::Property< PropertyBag >::update ( const Property< PropertyBag > &  orig)

Partial specialisations in case of PropertyBag.

template<typename T>
reference_t RTT::Property< T >::value ( )
inline

Member Data Documentation

std::string RTT::base::PropertyBase::_description
protectedinherited
std::string RTT::base::PropertyBase::_name
protectedinherited
template<typename T>
internal::AssignableDataSource<DataSourceType>::shared_ptr RTT::Property< T >::_value
protected

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