Signals | Public Member Functions | Protected Member Functions | Protected Attributes | Private Member Functions | Private Attributes | Static Private Attributes | List of all members
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]

Signals

void aboutToChange ()
 Emitted by setValue() just before the value has changed. More...
 
void changed ()
 Emitted by setValue() just after the value has changed. More...
 
void childListChanged (Property *this_property)
 Emitted after insertions and deletions of child Properties. More...
 

Public Member Functions

virtual void addChild (Property *child, int index=-1)
 Add a child property. More...
 
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. More...
 
virtual PropertychildAtUnchecked (int index) const
 Return the child Property with the given index, without checking whether the index is within bounds. More...
 
virtual void collapse ()
 Collapse (hide the children of) this Property. More...
 
bool contains (Property *possible_child) const
 Return true if the list of children includes possible_child, false if not. More...
 
virtual QWidget * createEditor (QWidget *parent, const QStyleOptionViewItem &option)
 Create an editor widget to edit the value of this property. More...
 
virtual void expand ()
 Expand (show the children of) this Property. More...
 
virtual QString getDescription () const
 Return the description. More...
 
virtual bool getDisableChildren ()
 If true, the children of this property should set their ItemIsEnabled flag to false. More...
 
virtual bool getHidden () const
 Return the hidden/shown state. True means hidden, false means visible. More...
 
virtual QIcon getIcon () const
 
PropertyTreeModelgetModel () const
 Return the model managing this Property and its childrent. More...
 
virtual QString getName () const
 Return the name of this Property as a QString. More...
 
std::string getNameStd () const
 Return the name of this Property as a std::string. More...
 
PropertygetParent () const
 Return the parent Property. More...
 
virtual bool getReadOnly ()
 Return the read-only-ness of this property. More...
 
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. More...
 
virtual QVariant getViewData (int column, int role) const
 Return data appropriate for the given column (0 or 1) and role for this Property. More...
 
virtual Qt::ItemFlags getViewFlags (int column) const
 Return item flags appropriate for the given column (0 or 1) for this Property. More...
 
void hide ()
 Hide this Property in any PropertyTreeWidgets. More...
 
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. More...
 
virtual void load (const Config &config)
 Load the value of this property and/or its children from the given Config reference. More...
 
virtual void moveChild (int from_index, int to_index)
 Move the child at from_index to to_index. More...
 
virtual int numChildren () const
 Return the number of child objects (Property or otherwise). More...
 
virtual bool paint (QPainter *painter, const QStyleOptionViewItem &option) const
 Hook to provide custom painting of the value data (right-hand column) in a subclass. More...
 
 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. More...
 
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. More...
 
int rowNumberInParent () const
 Return the row number of this property within its parent, or -1 if it has no parent. More...
 
virtual void save (Config config) const
 Write the value of this property and/or its children into the given Config reference. More...
 
virtual void setDescription (const QString &description)
 Set the description. More...
 
virtual void setHidden (bool hidden)
 Hide or show this property in any PropertyTreeWidget viewing its parent. More...
 
virtual void setIcon (const QIcon &icon)
 Set the icon to be displayed next to the property. More...
 
void setModel (PropertyTreeModel *model)
 Set the model managing this Property and all its child properties, recursively. More...
 
virtual void setName (const QString &name)
 Set the name. More...
 
void setParent (Property *new_parent)
 Set parent property, without telling the parent. More...
 
virtual void setReadOnly (bool read_only)
 Prevent or allow users to edit this property from a PropertyTreeWidget. More...
 
void setShouldBeSaved (bool save)
 If save is true and getReadOnly() is false, shouldBeSaved will return true; otherwise false. Default is true. More...
 
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. More...
 
bool shouldBeSaved () const
 Returns true if the property is not read-only AND has data worth saving. More...
 
void show ()
 Show this Property in any PropertyTreeWidgets. More...
 
virtual PropertysubProp (const QString &sub_name)
 Return the first child Property with the given name, or the FailureProperty if no child has the name. More...
 
PropertytakeChild (Property *child)
 Remove a given child object and return a pointer to it. More...
 
virtual PropertytakeChildAt (int index)
 Take a child out of the child list, but don't destroy it. More...
 
virtual ~Property ()
 Destructor. Removes this property from its parent's list of children. More...
 

Protected Member Functions

void loadValue (const Config &config)
 Load the value of this property specifically, not including children. More...
 

Protected Attributes

bool child_indexes_valid_
 True if row_number_within_parent_ of all children is valid, false if not. More...
 
QIcon icon_
 
PropertyTreeModelmodel_
 Pointer to the PropertyTreeModel managing this property tree. More...
 
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(). More...
 

Private Member Functions

void reindexChildren ()
 Set row_number_within_parent_ correctly for every child. Sets child_indexes_valid_ to true when done. More...
 

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

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:

{
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() ));
}
{
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.

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

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

virtual bool rviz::Property::getHidden ( ) const
inlinevirtual

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

Definition at line 388 of file property.h.

virtual QIcon rviz::Property::getIcon ( ) const
inlinevirtual

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

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

Return the parent Property.

Definition at line 226 of file property.cpp.

virtual bool rviz::Property::getReadOnly ( )
inlinevirtual

Return the read-only-ness of this property.

See also
setReadOnly()

Definition at line 401 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 371 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
inlinevirtual

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
inlinevirtual

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.

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 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)
inlinevirtual

Set the icon to be displayed next to the property.

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 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)
inlinevirtual

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 397 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 361 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::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 357 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 377 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.

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

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

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

Definition at line 471 of file property.h.

QString rviz::Property::description_
private

Definition at line 472 of file property.h.

Property * rviz::Property::failprop_ = new FailureProperty
staticprivate

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

Definition at line 477 of file property.h.

bool rviz::Property::hidden_
private

Definition at line 473 of file property.h.

QIcon rviz::Property::icon_
protected

Definition at line 463 of file property.h.

bool rviz::Property::is_read_only_
private

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

Property* rviz::Property::parent_
private

Definition at line 470 of file property.h.

int rviz::Property::row_number_within_parent_
private

Definition at line 479 of file property.h.

bool rviz::Property::save_
private

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 440 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 Sat Apr 27 2019 02:33:43