rviz::Property Class Reference

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

#include <property.h>

Inheritance diagram for rviz::Property:
Inheritance graph
[legend]

List of all members.

Signals

void aboutToChange ()
 Emitted by setValue() just before the value has changed.
void changed ()
 Emitted by setValue() just after the value has changed.
void hiddenChanged (bool hidden)
 Emitted by setHidden().

Public Member Functions

virtual void addChild (Property *child, int index=-1)
 Add a child property.
PropertychildAt (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 PropertychildAtUnchecked (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.
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 getHidden () const
 Return the hidden/shown state. True means hidden, false means visible.
PropertyTreeModelgetModel () 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.
PropertygetParent () 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 YAML::Node &yaml_node)
 Load the value of this property and/or its children from the given YAML node.
virtual void loadChildren (const YAML::Node &yaml_node)
 Load the children of this property from the given YAML node, which should be a map node.
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 removeAllChildren ()
 Remove and delete 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 (YAML::Emitter &emitter)
 Write the value of this property and/or its children to the given YAML emitter.
virtual void saveChildren (YAML::Emitter &emitter)
 Write the children of this property to the given YAML emitter, which should be in a map context.
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.
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.
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.
virtual bool shouldBeSaved () const
 Override this function to return true if this property should be saved to the config file, or false if it should not. The default implementation returns the opposite of getReadOnly().
void show ()
 Show this Property in any PropertyTreeWidgets.
virtual PropertysubProp (const QString &sub_name)
 Return the first child Property with the given name, or the FailureProperty if no child has the name.
PropertytakeChild (Property *child)
 Remove a given child object and return a pointer to it.
virtual PropertytakeChildAt (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 YAML::Node &yaml_node)
 Load the value of this property specifically, not including children.
void saveValue (YAML::Emitter &emitter)
 Save 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.
PropertyTreeModelmodel_
 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_
Propertyparent_
int row_number_within_parent_

Static Private Attributes

static Propertyfailprop_ = 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 103 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 58 of file property.cpp.

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

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

Definition at line 87 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::DisplayGroup.

Definition at line 307 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 192 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 203 of file property.cpp.

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 588 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::ColorProperty, rviz::EditableEnumProperty, rviz::EnumProperty, and rviz::IntProperty.

Definition at line 540 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 580 of file property.cpp.

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

Return the description.

Reimplemented in rviz::FailedDisplay.

Definition at line 164 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 386 of file property.h.

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

Return the model managing this Property and its childrent.

Definition at line 324 of file property.h.

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

Return the name of this Property as a QString.

Definition at line 154 of file property.cpp.

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

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

Definition at line 178 of file property.h.

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

Return the parent Property.

Definition at line 208 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 399 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 140 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::Display, rviz::DisplayGroup, rviz::FailedDisplay, and rviz::StatusProperty.

Definition at line 218 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::Display, rviz::DisplayGroup, and rviz::StatusProperty.

Definition at line 246 of file property.cpp.

void rviz::Property::hiddenChanged ( bool  hidden  )  [signal]

Emitted by setHidden().

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 366 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 263 of file property.cpp.

void rviz::Property::load ( const YAML::Node &  yaml_node  )  [virtual]

Load the value of this property and/or its children from the given YAML node.

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

Definition at line 378 of file property.cpp.

void rviz::Property::loadChildren ( const YAML::Node &  yaml_node  )  [virtual]

Load the children of this property from the given YAML node, which should be a map node.

This base version presumes the children to be loaded already exist as sub-properties of this, and looks for keys in the YAML map which match their names.

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

Definition at line 434 of file property.cpp.

void rviz::Property::loadValue ( const YAML::Node &  yaml_node  )  [protected]

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

This base implementation handles value_ types of string, double, float, and int. Override to handle other types.

Definition at line 395 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 371 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 211 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 269 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 346 of file property.cpp.

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

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

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

Reimplemented in rviz::DisplayGroup.

Definition at line 104 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 357 of file property.cpp.

void rviz::Property::save ( YAML::Emitter &  emitter  )  [virtual]

Write the value of this property and/or its children to the given YAML emitter.

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

Definition at line 479 of file property.cpp.

void rviz::Property::saveChildren ( YAML::Emitter &  emitter  )  [virtual]

Write the children of this property to the given YAML emitter, which should be in a map context.

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

Definition at line 525 of file property.cpp.

void rviz::Property::saveValue ( YAML::Emitter &  emitter  )  [protected]

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

This base implementation handles value_ types of string, double, float, and int. Override to handle other types.

Definition at line 510 of file property.cpp.

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

Set the description.

Parameters:
description the new description.

Definition at line 159 of file property.cpp.

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

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

Causes hiddenChanged() signal to be emitted if this changes the state.

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

Definition at line 568 of file property.cpp.

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

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

Definition at line 335 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::CameraDisplay, rviz::ImageDisplay, and rviz::StatusList.

Definition at line 145 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 213 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 395 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::ColorProperty, rviz::FloatProperty, rviz::IntProperty, rviz::QuaternionProperty, rviz::StatusProperty, rviz::TfFrameProperty, and rviz::VectorProperty.

Definition at line 125 of file property.cpp.

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

Override this function to return true if this property should be saved to the config file, or false if it should not. The default implementation returns the opposite of getReadOnly().

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

Definition at line 360 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 372 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 169 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 273 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 285 of file property.cpp.


Member Data Documentation

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 465 of file property.h.

Definition at line 473 of file property.h.

QString rviz::Property::description_ [private]

Definition at line 474 of file property.h.

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

Definition at line 479 of file property.h.

bool rviz::Property::hidden_ [private]

Definition at line 475 of file property.h.

Definition at line 482 of file property.h.

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 458 of file property.h.

Definition at line 472 of file property.h.

Definition at line 481 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 444 of file property.h.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Defines


rviz
Author(s): Dave Hershberger, Josh Faust
autogenerated on Wed Jun 6 11:25:48 2012