<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- /home/gvatteka/dev/qt-4.3/doc/src/properties.qdoc -->
<head>
<title>Qt's Property System</title>
<link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<h1 align="center">Qt's Property System<br /><small></small></h1>
<p>Qt provides a sophisticated property system similar to those supplied by some compiler vendors. However, as a compiler- and platform-independent library, Qt cannot rely on non-standard compiler features like <tt>__property</tt> or <tt>[property]</tt>. Our solution works with <i>any</i> standard C++ compiler on every platform we support. It's based on the meta-object system that also provides object communication through <a href="qtjambi-signalsandslots.html">signals and slots</tt></a>.</p>
<a name="requirements"></a>
<h3>Requirements</h3>
<p>The Q_PROPERTY() macro in a class declaration declares a property. Properties can only be declared in classes that inherit <a href="core/QObject.html"><tt>QObject</tt></a>.</p>
<p>To the outer world, a property appears to be similar to a data member. But properties have several features that distinguish them from ordinary data members:</p>
<ul>
<li>A read function. This must always exist.</li>
<li>A write function. This is optional; read-only properties like QWidget::isDesktop() do not have one.</li>
<li>A "stored" attribute that indicates persistence. Most properties are stored, but a few virtual properties are not. For example, QWidget::minimumWidth() isn't stored, since it's just a view of QWidget::minimumSize(), and has no data of its own.</li>
<li>A reset function to set a property back to its context specific default value. This is very rare, but for example, QWidget::cursor needs this, since no call to QWidget::setCursor() can mean "reset to the context specific cursor".</li>
<li>A "designable" attribute that indicates whether it makes sense to make the property available in a GUI builder (e.g., <a href="qtjambi-designer.html">Qt Designer</tt></a>). For most properties this makes sense, but not for all, e.g. QAbstractButton::down. The user can press buttons, and the application programmer can make the program press its own buttons, but a GUI design tool can't press buttons.</li>
</ul>
<p>The read, write and reset functions can be just about any member functions, inherited or not, virtual or not. The only exception is that member functions must be inherited from the first inherited class in the case of multiple inheritance.</p>
<a name="reading-and-writing-properties"></a>
<h3>Reading and Writing Properties</h3>
<p>Properties can be read and written through generic functions in <a href="core/QObject.html"><tt>QObject</tt></a> without knowing anything about the class in use. In the code snippet below, the QObject::setProperty() call is equivalent to the QAbstractButton::setDown() call:</p>
<pre> QPushButton *button = new QPushButton;
QObject *object = button;
<span class="comment"> // button and object point to the same object</span>
button->setDown(true);
object->setProperty("down", true);</pre>
<p>Equivalent, that is, except that the first is faster and provides much better diagnostics at compile time. When practical, the first is better. However, since you can get a list of all available properties for any <a href="core/QObject.html"><tt>QObject</tt></a> through its QMetaObject, QObject::setProperty() can give you control over classes that weren't available at compile time.</p>
<p>As well as QObject::setProperty(), there is a corresponding QObject::property() function. QMetaObject::propertyCount() returns the number of all available properties. QMetaObject::property() returns the property data for a given property index: a QMetaProperty object.</p>
<a name="a-simple-example"></a>
<h3>A Simple Example</h3>
<p>Here's a simple example that shows the most important property functions in use:</p>
<pre> class MyClass : public QObject
{
Q_OBJECT
public:
MyClass(QObject *parent = 0);
~MyClass();
enum Priority { High, Low, VeryHigh, VeryLow };
void setPriority(Priority priority);
Priority priority() const;
};</pre>
<p>The class has a property <tt>priority</tt> that is not yet known to the meta-object system. In order to make the property known, you must declare it with the Q_PROPERTY() macro. The syntax is as follows:</p>
<pre> Q_PROPERTY(type name
READ getFunction
[WRITE setFunction]
[RESET resetFunction]
[DESIGNABLE bool]
[SCRIPTABLE bool]
[STORED bool])</pre>
<p>For the declaration to be valid, the get function must be const and to return either the type itself, a pointer to it, or a reference to it. The optional write function must return void and must take exactly one argument, either the type itself, a pointer or a const reference to it. The meta-object compiler enforces this.</p>
<p>The type of a property can be any <a href="porting4.html#qvariant"><tt>QVariant</tt></a> supported type or an enumeration type declared in the class itself. Since <tt>MyClass</tt> uses the enumeration type <tt>Priority</tt> for the property, this type must be registered with the property system as well.</p>
<p>It is possible to set a value by name, like this:</p>
<pre> obj->setProperty("priority", "VeryHigh");</pre>
<p>In the case of QList and QMap properties, the value passes is a <a href="porting4.html#qvariant"><tt>QVariant</tt></a> whose value is the entire list or map.</p>
<a name="header-files"></a>
<h3>Header Files</h3>
<p>It is usually necessary to include the header files for each value type that you use in property definitions. For example:</p>
<pre> Q_PROPERTY(QDate date READ getDate WRITE setDate)</pre>
<p>Since the property is based on the <a href="core/QDate.html"><tt>QDate</tt></a> class, the <tt><QDate></tt> header file should be included in the file containing the above property definition.</p>
<a name="using-enums-and-flags-in-properties"></a>
<h4>Using Enums and Flags in Properties</h4>
<p>Enumeration types are registered with the Q_ENUMS() macro. Here's the final class declaration including the property related declarations:</p>
<pre> class MyClass : public QObject
{
Q_OBJECT
Q_PROPERTY(Priority priority READ priority WRITE setPriority)
Q_ENUMS(Priority)
public:
MyClass(QObject *parent = 0);
~MyClass();
enum Priority { High, Low, VeryHigh, VeryLow };
void setPriority(Priority priority);
Priority priority() const;
};</pre>
<p>Note that if you want to register an enum (using Q_ENUMS()) that is declared in another class, the enum must be fully qualified with the name of the class defining it. In addition, the class <i>defining</i> the enum has to inherit <a href="core/QObject.html"><tt>QObject</tt></a> as well as declare the enum using Q_ENUMS().</p>
<p>Another similar macro is Q_FLAGS(). Like Q_ENUMS(), it registers an enumeration type but marks it in addition as a set of "flags", i.e. the enumeration values can be OR'd together. An I/O class might have enumeration values <tt>Read</tt> and <tt>Write</tt> and accept <tt>Read | Write</tt>: such an enum is best handled with Q_FLAGS(), rather than Q_ENUMS().</p>
<a name="property-types"></a>
<h4>Property Types</h4>
<a name="designable"></a><a name="scriptable"></a><p>In addition to the <tt>READ</tt> and <tt>WRITE</tt> keywords, each Q_PROPERTY() declaration can contain additional keywords that supply information about a property:</p>
<ul>
<li><tt>RESET</tt> names a function that will set the property to its default state (which may have changed since initialization). The function must return void and take no arguments.</li>
<li><tt>DESIGNABLE</tt> declares whether this property is suitable for modification by a GUI design tool. The default is true for writable properties; otherwise false. Instead of true or false, you can specify a boolean member function.</li>
<li><tt>NOTIFY</tt> indicates which signal will be emitted when a writable property is changed. Only one signal can be specified per property.</li>
<li><tt>SCRIPTABLE</tt> declares whether this property is suited for access by a scripting engine. The default is true. Instead of true or false, you can specify a boolean member function.</li>
<li><tt>STORED</tt> declares whether the property's value must be remembered when storing an object's state. Stored makes only sense for writable properties. The default value is true. Technically superfluous properties (like <a href="core/QPoint.html"><tt>QPoint</tt></a> pos if <a href="core/QRect.html"><tt>QRect</tt></a> geometry is already a property) define this to be false.</li>
<li><tt>USER</tt> specifies that a particular property in a class (typically a widget) contains user-facing information, and is the main property that a user will modify via the GUI when using instances of the class in an application.</li>
</ul>
<a name="adding-additional-information-to-a-class"></a>
<h3>Adding Additional Information to a Class</h3>
<p>Connected to the property system is an additional macro, Q_CLASSINFO(), that can be used to attach additional <i>name</i>--<i>value</i> pairs to a class's meta-object, for example:</p>
<pre> Q_CLASSINFO("Version", "3.0.0")</pre>
<p>Like other meta-data, class information is accessible at run-time through the meta-object; see QMetaObject::classInfo() for details.</p>
<a name="dynamic-properties"></a>
<h3>Dynamic Properties</h3>
<p>In addition to properties defined using Q_PROPERTY in a class it is possible to dynamically add and remove properties to any <a href="core/QObject.html"><tt>QObject</tt></a> at run-time.</p>
<p>If setProperty is called with a property not statically defined using Q_PROPERTY it is automatically added as dynamic property and its value is stored in the object. The value can be queried using the property() method, just like with static properties.</p>
<dl>
<dt><b>See Also:</b></dt>
<dd><a href="metaobjects.html">Meta-Object System</tt></a>, <a href="qtjambi-signalsandslots.html">Signals and Slots</tt></a></dd>
</dl>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%">Copyright © 2007 <a href="trolltech.html">Trolltech</a></td>
<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt Jambi </div></td>
</tr></table></div></address></body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a6711891ce757817bba854bf3f25205a
>
files
>
1883
