Signals | Public Member Functions | Protected Member Functions | Protected Attributes | Private Member Functions | Private Attributes | Static Private Attributes
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 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.
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.
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
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 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 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 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_
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_
bool save_

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 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:
nameThe name of this property. Appears in the left column of a PropertyTreeWidget.
default_valueThe initial value to store in the property. Appears in the right column of a PropertyTreeWidget.
descriptionText describing the property. Is shown in the "help" area of a PropertyTreeWithHelp widget.
parentThe parent Property, or NULL if there is no parent at this time.
changed_slotThis 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.
receiverIf 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.

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:
childThe 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 350 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 197 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 208 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 550 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 213 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:
parentThe QWidget to set as the parent of the returned QWidget.
optionA 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 502 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 542 of file property.cpp.

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

Return the description.

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

Definition at line 169 of file property.cpp.

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

Reimplemented in rviz::BoolProperty.

Definition at line 275 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.

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

Return the parent Property.

Definition at line 226 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 145 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:
column0 for left column, 1 for right column.
roleis 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 236 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:
column0 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 285 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 306 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::MarkerDisplay, rviz::Display, rviz::DisplayGroup, rviz::TFDisplay, rviz::FailedViewController, rviz::FailedDisplay, rviz::QuaternionProperty, and rviz::VectorProperty.

Definition at line 426 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 449 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 419 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:
painterThe QPainter to use.
optionA 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 394 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_indexThe index of the first child to delete.
countThe 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.

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 405 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 467 of file property.cpp.

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

Set the description.

Parameters:
descriptionthe new description.

Definition at line 164 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 530 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.

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

Definition at line 379 of file property.cpp.

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

Set the name.

Parameters:
namethe new name.

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

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

Definition at line 150 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 231 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_valueThe 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 130 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 174 of file property.cpp.

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 316 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 328 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 457 of file property.h.

Definition at line 467 of file property.h.

QString rviz::Property::description_ [private]

Definition at line 468 of file property.h.

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.

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

Definition at line 466 of file property.h.

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:


rviz
Author(s): Dave Hershberger, David Gossow, Josh Faust
autogenerated on Tue Oct 3 2017 03:19:32