A single element of a property tree, with a name, value, description, and possibly children. More...

#include <property.h>

Inheritance diagram for rviz::Property:

Signals
void	aboutToChange ()
	Emitted by setValue() just before the value has changed.
void	changed ()
	Emitted by setValue() just after the value has changed.
void	childListChanged (Property *this_property)
	Emitted after insertions and deletions of child Properties.
Public Member Functions
virtual void	addChild (Property *child, int index=-1)
	Add a child property.
Property *	childAt (int index) const
	Return the child Property with the given index, or NULL if the index is out of bounds or if the child at that index is not a Property.
virtual Property *	childAtUnchecked (int index) const
	Return the child Property with the given index, without checking whether the index is within bounds.
virtual void	collapse ()
	Collapse (hide the children of) this Property.
bool	contains (Property *possible_child) const
	Return true if the list of children includes possible_child, false if not.
virtual QWidget *	createEditor (QWidget *parent, const QStyleOptionViewItem &option)
	Create an editor widget to edit the value of this property.
virtual void	expand ()
	Expand (show the children of) this Property.
virtual QString	getDescription () const
	Return the description.
virtual bool	getDisableChildren ()
	If true, the children of this property should set their ItemIsEnabled flag to false.
virtual bool	getHidden () const
	Return the hidden/shown state. True means hidden, false means visible.
virtual QIcon	getIcon () const
PropertyTreeModel *	getModel () const
	Return the model managing this Property and its childrent.
virtual QString	getName () const
	Return the name of this Property as a QString.
std::string	getNameStd () const
	Return the name of this Property as a std::string.
Property *	getParent () const
	Return the parent Property.
virtual bool	getReadOnly ()
	Return the read-only-ness of this property.
virtual QVariant	getValue () const
	Return the value of this Property as a QVariant. If the value has never been set, an invalid QVariant is returned.
virtual QVariant	getViewData (int column, int role) const
	Return data appropriate for the given column (0 or 1) and role for this Property.
virtual Qt::ItemFlags	getViewFlags (int column) const
	Return item flags appropriate for the given column (0 or 1) for this Property.
void	hide ()
	Hide this Property in any PropertyTreeWidgets.
bool	isAncestorOf (Property *possible_child) const
	Returns true if `this` is an ancestor of possible_child, meaning is the parent or parent of parent etc.
virtual void	load (const Config &config)
	Load the value of this property and/or its children from the given Config reference.
virtual void	moveChild (int from_index, int to_index)
	Move the child at from_index to to_index.
virtual int	numChildren () const
	Return the number of child objects (Property or otherwise).
virtual bool	paint (QPainter *painter, const QStyleOptionViewItem &option) const
	Hook to provide custom painting of the value data (right-hand column) in a subclass.
	Property (const QString &name=QString(), const QVariant default_value=QVariant(), const QString &description=QString(), Property parent=0, const char changed_slot=0, QObject *receiver=0)
	Constructor.
virtual void	removeChildren (int start_index=0, int count=-1)
	Remove and delete some or all child Properties. Does not change the value of this Property.
int	rowNumberInParent () const
	Return the row number of this property within its parent, or -1 if it has no parent.
virtual void	save (Config config) const
	Write the value of this property and/or its children into the given Config reference.
virtual void	setDescription (const QString &description)
	Set the description.
virtual void	setHidden (bool hidden)
	Hide or show this property in any PropertyTreeWidget viewing its parent.
virtual void	setIcon (const QIcon &icon)
	Set the icon to be displayed next to the property.
void	setModel (PropertyTreeModel *model)
	Set the model managing this Property and all its child properties, recursively.
virtual void	setName (const QString &name)
	Set the name.
void	setParent (Property *new_parent)
	Set parent property, without telling the parent.
virtual void	setReadOnly (bool read_only)
	Prevent or allow users to edit this property from a PropertyTreeWidget.
void	setShouldBeSaved (bool save)
	If save is true and getReadOnly() is false, shouldBeSaved will return true; otherwise false. Default is true.
virtual bool	setValue (const QVariant &new_value)
	Set the new value for this property. Returns true if the new value is different from the old value, false if same.
bool	shouldBeSaved () const
	Returns true if the property is not read-only AND has data worth saving.
void	show ()
	Show this Property in any PropertyTreeWidgets.
virtual Property *	subProp (const QString &sub_name)
	Return the first child Property with the given name, or the FailureProperty if no child has the name.
Property *	takeChild (Property *child)
	Remove a given child object and return a pointer to it.
virtual Property *	takeChildAt (int index)
	Take a child out of the child list, but don't destroy it.
virtual	~Property ()
	Destructor. Removes this property from its parent's list of children.
Protected Member Functions
void	loadValue (const Config &config)
	Load the value of this property specifically, not including children.
Protected Attributes
bool	child_indexes_valid_
	True if row_number_within_parent_ of all children is valid, false if not.
QIcon	icon_
PropertyTreeModel *	model_
	Pointer to the PropertyTreeModel managing this property tree.
QVariant	value_
	This is the central property value. If you set it directly in a subclass, do so with care because many things depend on the aboutToChange() and changed() events emitted by setValue().
Private Member Functions
void	reindexChildren ()
	Set row_number_within_parent_ correctly for every child. Sets child_indexes_valid_ to true when done.
Private Attributes
QList< Property * >	children_
QString	description_
bool	hidden_
bool	is_read_only_
Property *	parent_
int	row_number_within_parent_
bool	save_
Static Private Attributes
static Property *	failprop_ = new FailureProperty
	The property returned by subProp() when the requested name is not found.

Detailed Description

A single element of a property tree, with a name, value, description, and possibly children.

A Property in a property tree is a piece of data editable or at least displayable in a PropertyTreeWidget. A Property object owns the data item in question. When client code needs to be informed about changes, it can connect to the Property's aboutToChange() and changed() signals. A slot receiving the changed() signal should then ask the Property itself for the new data. Example:

     RangeDisplay::RangeDisplay()
     {
       color_property_ = new ColorProperty( "Color", Qt::white,
                                            "Color to draw the range.",
                                            this, SLOT( updateColorAndAlpha() ));
     
       alpha_property_ = new FloatProperty( "Alpha", 0.5,
                                            "Amount of transparency to apply to the range.",
                                            this, SLOT( updateColorAndAlpha() ));
     }
     
     void RangeDisplay::updateColorAndAlpha()
     {
       Ogre::ColourValue oc = color_property_->getOgreColor();
       float alpha = alpha_property_->getFloat();
       for( size_t i = 0; i < cones_.size(); i++ )
       {
         cones_[i]->setColor( oc.r, oc.g, oc.b, alpha );
       }
       context_->queueRender();
     }

Many subclasses of Property exist with specializations for storing specific types of data. Most of these ultimately use Property::setValue() to store the data in a QVariant.

It is important that knowledge of subclasses not be *required* to get and set data, so that external code can access and change properties without needing to #include and link against the code in question. For instance:

     prop->subProp( "Offset" )->subProp( "X" )->setValue( 3.14 );

Sets the X component of the VectorProperty called "Offset" which is a child of prop. This works without this code needing to know about the existence of VectorProperty.

To show a Property tree in a PropertyTreeWidget, wrap the root Property in a PropertyTreeModel and call PropertyTreeWidget::setModel() with it.

Definition at line 100 of file property.h.

Constructor & Destructor Documentation

rviz::Property::Property	(	const QString &	name = `QString()`,
		const QVariant	default_value = `QVariant()`,
		const QString &	description = `QString()`,
		Property *	parent = `0`,
		const char *	changed_slot = `0`,
		QObject *	receiver = `0`
	)

Constructor.

Parameters:

name	The name of this property. Appears in the left column of a PropertyTreeWidget.
default_value	The initial value to store in the property. Appears in the right column of a PropertyTreeWidget.
description	Text describing the property. Is shown in the "help" area of a PropertyTreeWithHelp widget.
parent	The parent Property, or NULL if there is no parent at this time.
changed_slot	This should be a Qt slot specification, generated by Qt's `SLOT()` macro. It should be a slot on the receiver object, or if receiver is not specified, it should be a slot on the parent.
receiver	If receiver is non-NULL, the changed() signal is connected to the changed_slot on the receiver object.

All parameters to the constructor are optional and can all be set after construction as well.

If a parent is given, this constructor calls parent->addChild(this) to add itself to the parent's list of children.

If changed_slot is given and either parent or receiver is also, then the changed() signal is connected via QObject::connect() to the slot described by changed_slot on the parent or the receiver. If both parent and receiver are specified, receiver is the one which gets connected. If receiver is not specified, parent is used instead.

Definition at line 54 of file property.cpp.

rviz::Property::~Property ( ) [virtual]

Destructor. Removes this property from its parent's list of children.

Definition at line 84 of file property.cpp.

Member Function Documentation

void rviz::Property::aboutToChange ( ) [signal]

Emitted by setValue() just before the value has changed.

void rviz::Property::addChild	(	Property *	child,
		int	index = `-1`
	)		`[virtual]`

Add a child property.

Parameters:

child	The child property to add.
index	[optional] The index at which to add the child. If less than 0 or greater than the number of child properties, the child will be added at the end.

Reimplemented in rviz::ViewControllerContainer, and rviz::DisplayGroup.

Definition at line 343 of file property.cpp.

void rviz::Property::changed ( ) [signal]

Emitted by setValue() just after the value has changed.

Property * rviz::Property::childAt ( int index ) const

Return the child Property with the given index, or NULL if the index is out of bounds or if the child at that index is not a Property.

This just checks the index against 0 and numChildren() and then calls childAtUnchecked(), so it does not need to be overridden in a subclass.

Definition at line 194 of file property.cpp.

Property * rviz::Property::childAtUnchecked ( int index ) const [virtual]

Return the child Property with the given index, without checking whether the index is within bounds.

You can override this in a subclass to implement different child storage.

Reimplemented in rviz::DisplayGroup.

Definition at line 205 of file property.cpp.

void rviz::Property::childListChanged ( Property * this_property ) [signal]

Emitted after insertions and deletions of child Properties.

void rviz::Property::collapse ( ) [virtual]

Collapse (hide the children of) this Property.

Note:: Properties start out collapsed by default.

See also:: expand()

Definition at line 543 of file property.cpp.

bool rviz::Property::contains ( Property * possible_child ) const

Return true if the list of children includes possible_child, false if not.

Definition at line 210 of file property.cpp.

QWidget * rviz::Property::createEditor	(	QWidget *	parent,
		const QStyleOptionViewItem &	option
	)		`[virtual]`

Create an editor widget to edit the value of this property.

Parameters:

parent	The QWidget to set as the parent of the returned QWidget.
option	A QStyleOptionViewItem with parameters of the editor widget, like the rectangle, alignments, etc.

Returns:: the newly-created editor widget. The default implementation creates a QSpinBox for integer values, a FloatEdit for float or double values, or a QLineEdit for anything else.

If this function returns NULL, a QStyledItemDelegate will make an editor widget.

The widget returned by createEditor() must have one Q_PROPERTY with USER set to true. The PropertyTreeDelegate finds it, sets it with the results of PropertyTreeModel::data() after creation, and after editing is finished it reads it and calls PropertyTreeModel::setData() with the contents.

Reimplemented in rviz::IntProperty, rviz::EnumProperty, rviz::EditableEnumProperty, and rviz::ColorProperty.

Definition at line 495 of file property.cpp.

void rviz::Property::expand ( ) [virtual]

Expand (show the children of) this Property.

Note:: Properties start out collapsed by default.

This function only works if the property is already owned by a PropertyTreeModel connected to a PropertyTreeWidget. If this is called and the model is subsequently attached to a widget, it will not have any effect.

See also:: collapse()

Definition at line 535 of file property.cpp.

QString rviz::Property::getDescription ( ) const [virtual]

Return the description.

Reimplemented in rviz::FailedDisplay, and rviz::FailedViewController.

Definition at line 166 of file property.cpp.

bool rviz::Property::getDisableChildren ( ) [virtual]

If true, the children of this property should set their ItemIsEnabled flag to false.

Reimplemented in rviz::BoolProperty.

Definition at line 268 of file property.cpp.

virtual bool rviz::Property::getHidden ( ) const [inline, virtual]

Return the hidden/shown state. True means hidden, false means visible.

Definition at line 384 of file property.h.

virtual QIcon rviz::Property::getIcon ( ) const [inline, virtual]

Definition at line 189 of file property.h.

PropertyTreeModel* rviz::Property::getModel ( ) const [inline]

Return the model managing this Property and its childrent.

Definition at line 331 of file property.h.

QString rviz::Property::getName ( void ) const [virtual]

Return the name of this Property as a QString.

Definition at line 156 of file property.cpp.

std::string rviz::Property::getNameStd ( ) const [inline]

Return the name of this Property as a std::string.

Definition at line 177 of file property.h.

Property * rviz::Property::getParent ( ) const

Return the parent Property.

Definition at line 223 of file property.cpp.

virtual bool rviz::Property::getReadOnly ( ) [inline, virtual]

Return the read-only-ness of this property.

See also:: setReadOnly()

Definition at line 397 of file property.h.

QVariant rviz::Property::getValue ( ) const [virtual]

Return the value of this Property as a QVariant. If the value has never been set, an invalid QVariant is returned.

Definition at line 142 of file property.cpp.

QVariant rviz::Property::getViewData	(	int	column,
		int	role
	)		const `[virtual]`

Return data appropriate for the given column (0 or 1) and role for this Property.

Parameters:

column	0 for left column, 1 for right column.
role	is a Qt::ItemDataRole

When overriding to add new data (like a color for example), check the role for the thing you know about, and if it matches, return your data. If it does not match, call the parent class version of this function and return its result.

Return values from this function or overridden versions of it are where background and foreground colors, check-box checked-state values, text, and fonts all come from.

Reimplemented in rviz::IconizedProperty, rviz::Display, rviz::ViewController, rviz::StatusProperty, and rviz::FailedDisplay.

Definition at line 233 of file property.cpp.

Qt::ItemFlags rviz::Property::getViewFlags ( int column ) const [virtual]

Return item flags appropriate for the given column (0 or 1) for this Property.

Parameters:

column 0 for left column, 1 for right column.

Returns:: The Qt::ItemFlags for the given column of this property, including Qt::ItemIsSelectable, Qt::ItemIsEditable, etc.

Reimplemented in rviz::ViewControllerContainer, rviz::DisplayGroup, rviz::Display, rviz::ViewController, rviz::DisplayVisibilityProperty, and rviz::StatusProperty.

Definition at line 278 of file property.cpp.

void rviz::Property::hide ( ) [inline]

Hide this Property in any PropertyTreeWidgets.

This is a convenience function which calls setHidden( true ).

See also:: show(), setHidden(), getHidden()

Definition at line 367 of file property.h.

bool rviz::Property::isAncestorOf ( Property * possible_child ) const

Returns true if this is an ancestor of possible_child, meaning is the parent or parent of parent etc.

Definition at line 299 of file property.cpp.

void rviz::Property::load ( const Config & config ) [virtual]

Load the value of this property and/or its children from the given Config reference.

Reimplemented in rviz::ViewController, rviz::Display, rviz::DisplayGroup, rviz::FailedViewController, rviz::FailedDisplay, rviz::QuaternionProperty, and rviz::VectorProperty.

Definition at line 419 of file property.cpp.

void rviz::Property::loadValue ( const Config & config ) [protected]

Load the value of this property specifically, not including children.

This handles value_ types of string, double/float, bool, and int. If config is invalid, this does nothing.

Definition at line 442 of file property.cpp.

void rviz::Property::moveChild	(	int	from_index,
		int	to_index
	)		`[virtual]`

Move the child at from_index to to_index.

Definition at line 412 of file property.cpp.

virtual int rviz::Property::numChildren ( ) const [inline, virtual]

Return the number of child objects (Property or otherwise).

You can override this in a subclass to implement different child storage.

Reimplemented in rviz::DisplayGroup.

Definition at line 215 of file property.h.

virtual bool rviz::Property::paint	(	QPainter *	painter,
		const QStyleOptionViewItem &	option
	)		const `[inline, virtual]`

Hook to provide custom painting of the value data (right-hand column) in a subclass.

Parameters:

painter	The QPainter to use.
option	A QStyleOptionViewItem with parameters of the paint job, like the rectangle, alignments, etc.

Returns:: true if painting has been done, false if not. The default implementation always returns false.

To implement a custom appearance of a Property value, override this function to do the painting and return true.

If this function returns false, a QStyledItemDelegate will do the painting.

Reimplemented in rviz::ColorProperty.

Definition at line 276 of file property.h.

void rviz::Property::reindexChildren ( ) [private]

Set row_number_within_parent_ correctly for every child. Sets child_indexes_valid_ to true when done.

Definition at line 387 of file property.cpp.

void rviz::Property::removeChildren	(	int	start_index = `0`,
		int	count = `-1`
	)		`[virtual]`

Remove and delete some or all child Properties. Does not change the value of this Property.

Parameters:

start_index	The index of the first child to delete.
count	The number of children to delete, or -1 to delete from start_index to the end of the list.

Does not use numChildren() or takeChildAt(), operates directly on internal children_ list.

Definition at line 100 of file property.cpp.

int rviz::Property::rowNumberInParent ( ) const

Return the row number of this property within its parent, or -1 if it has no parent.

This checks child_indexes_valid_ in the parent Property, and if it is false calls reindexChildren(). Then returns row_number_within_parent_ regardless.

Definition at line 398 of file property.cpp.

void rviz::Property::save ( Config config ) const [virtual]

Write the value of this property and/or its children into the given Config reference.

Reimplemented in rviz::ViewController, rviz::Display, rviz::DisplayGroup, rviz::FailedViewController, rviz::QuaternionProperty, and rviz::VectorProperty.

Definition at line 460 of file property.cpp.

void rviz::Property::setDescription ( const QString & description ) [virtual]

Set the description.

Parameters:

description the new description.

Definition at line 161 of file property.cpp.

void rviz::Property::setHidden ( bool hidden ) [virtual]

Hide or show this property in any PropertyTreeWidget viewing its parent.

The hidden/shown state is not saved or loaded, it is expected to be managed by the owner of the property.

Definition at line 523 of file property.cpp.

virtual void rviz::Property::setIcon ( const QIcon & icon ) [inline, virtual]

Set the icon to be displayed next to the property.

Reimplemented in rviz::Display.

Definition at line 187 of file property.h.

void rviz::Property::setModel ( PropertyTreeModel * model )

Set the model managing this Property and all its child properties, recursively.

Definition at line 372 of file property.cpp.

void rviz::Property::setName ( const QString & name ) [virtual]

Set the name.

Parameters:

name	the new name.

Internally, the name is stored with QObject::setObjectName().

Reimplemented in rviz::Display, and rviz::StatusList.

Definition at line 147 of file property.cpp.

void rviz::Property::setParent ( Property * new_parent )

Set parent property, without telling the parent.

Unlike specifying the parent property to the constructor, setParent() does not have any immediate side effects, like adding itself to be a child of the parent. It should only be used by implementations of addChild() and takeChild() and such.

Definition at line 228 of file property.cpp.

virtual void rviz::Property::setReadOnly ( bool read_only ) [inline, virtual]

Prevent or allow users to edit this property from a PropertyTreeWidget.

This only applies to user edits. Calling setValue() will still change the value.

This is not inherently recursive. Parents which need this to propagate to their children must override this to implement that.

Reimplemented in rviz::QuaternionProperty, and rviz::VectorProperty.

Definition at line 393 of file property.h.

void rviz::Property::setShouldBeSaved ( bool save ) [inline]

If save is true and getReadOnly() is false, shouldBeSaved will return true; otherwise false. Default is true.

Definition at line 357 of file property.h.

bool rviz::Property::setValue ( const QVariant & new_value ) [virtual]

Set the new value for this property. Returns true if the new value is different from the old value, false if same.

Parameters:

new_value The new value to store.

Returns:: Returns true if new_value is different from current value, false if they are the same.

If the new value is different from the old value, this emits aboutToChange() before changing the value and emits changed() after.

If the value set is an invalid QVariant (QVariant::isValid() returns false), the value will not be editable in a PropertyTreeWidget.

Reimplemented in rviz::DisplayVisibilityProperty, rviz::IntProperty, rviz::FloatProperty, rviz::TfFrameProperty, rviz::VectorProperty, rviz::QuaternionProperty, rviz::ColorProperty, and rviz::StatusProperty.

Definition at line 127 of file property.cpp.

bool rviz::Property::shouldBeSaved ( ) const [inline]

Returns true if the property is not read-only AND has data worth saving.

Definition at line 353 of file property.h.

void rviz::Property::show ( ) [inline]

Show this Property in any PropertyTreeWidgets.

This is a convenience function which calls setHidden( false ).

See also:: show(), setHidden(), getHidden()

Definition at line 373 of file property.h.

Property * rviz::Property::subProp ( const QString & sub_name ) [virtual]

Return the first child Property with the given name, or the FailureProperty if no child has the name.

If no child is found with the given name, an instance of a special Property subclass named FailureProperty is returned and an error message is printed to stdout. FailureProperty::subProp() always returns itself, which means you can safely chain a bunch of subProp() calls together and not have a crash even if one of the sub-properties does not actually exist. For instance:

float width = prop->subProp( "Dimenshons" )->subProp( "Width" )->getValue().toFloat();

If the first property prop has a "Dimensions" property but not a "Dimenshons" one, width will end up set to 0 and an error message will be printed, but the program will not crash here.

This is an Order(N) operation in the number of subproperties.

Reimplemented in rviz::FailureProperty.

Definition at line 171 of file property.cpp.

Property * rviz::Property::takeChild ( Property * child )

Remove a given child object and return a pointer to it.

Returns:: If child is contained here, it is returned; otherwise NULL.

This performs a linear search through all the children.

This uses only virtual functions, numChildren(), childAtUnchecked(), and takeChildAt(), so it does not need to be virtual itself.

Definition at line 309 of file property.cpp.

Property * rviz::Property::takeChildAt ( int index ) [virtual]

Take a child out of the child list, but don't destroy it.

Returns:: Returns the child property at the given index, or NULL if the index is out of bounds.

This notifies the model about the removal.

Reimplemented in rviz::DisplayGroup.

Definition at line 321 of file property.cpp.

Member Data Documentation

bool rviz::Property::child_indexes_valid_ [protected]

True if row_number_within_parent_ of all children is valid, false if not.

Subclasses should set this false when they add, remove, or reorder children.

Definition at line 457 of file property.h.

QList<Property*> rviz::Property::children_ [private]

Definition at line 467 of file property.h.

QString rviz::Property::description_ [private]

Definition at line 468 of file property.h.

Property * rviz::Property::failprop_ = new FailureProperty [static, private]

The property returned by subProp() when the requested name is not found.

Definition at line 473 of file property.h.

bool rviz::Property::hidden_ [private]

Definition at line 469 of file property.h.

QIcon rviz::Property::icon_ [protected]

Reimplemented in rviz::IconizedProperty.

Definition at line 459 of file property.h.

bool rviz::Property::is_read_only_ [private]

Definition at line 476 of file property.h.

PropertyTreeModel* rviz::Property::model_ [protected]

Pointer to the PropertyTreeModel managing this property tree.

Any time there is a data value or structural change to the properties in this tree, and model_ is non-NULL, it must be notified of the change. Functions to notify it of changes include PropertyTreeModel::beginInsert(), PropertyTreeModel::endInsert(), PropertyTreeModel::beginRemove(), PropertyTreeModel::endRemove(), and PropertyTreeModel::emitDataChanged(). The Property class already does this for itself, but subclasses must be aware of it if they override functions which modify the structure or contents of the tree.

Definition at line 450 of file property.h.

Property* rviz::Property::parent_ [private]

Definition at line 466 of file property.h.

int rviz::Property::row_number_within_parent_ [private]

Definition at line 475 of file property.h.

bool rviz::Property::save_ [private]

Definition at line 477 of file property.h.

QVariant rviz::Property::value_ [protected]

This is the central property value. If you set it directly in a subclass, do so with care because many things depend on the aboutToChange() and changed() events emitted by setValue().

Definition at line 436 of file property.h.

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

Signals

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation