| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|---|
| 2 | <!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/object.doc:210 -->
|
|---|
| 3 | <html>
|
|---|
| 4 | <head>
|
|---|
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|---|
| 6 | <title>Properties</title>
|
|---|
| 7 | <style type="text/css"><!--
|
|---|
| 8 | fn { margin-left: 1cm; text-indent: -1cm; }
|
|---|
| 9 | a:link { color: #004faf; text-decoration: none }
|
|---|
| 10 | a:visited { color: #672967; text-decoration: none }
|
|---|
| 11 | body { background: #ffffff; color: black; }
|
|---|
| 12 | --></style>
|
|---|
| 13 | </head>
|
|---|
| 14 | <body>
|
|---|
| 15 |
|
|---|
| 16 | <table border="0" cellpadding="0" cellspacing="0" width="100%">
|
|---|
| 17 | <tr bgcolor="#E5E5E5">
|
|---|
| 18 | <td valign=center>
|
|---|
| 19 | <a href="index.html">
|
|---|
| 20 | <font color="#004faf">Home</font></a>
|
|---|
| 21 | | <a href="classes.html">
|
|---|
| 22 | <font color="#004faf">All Classes</font></a>
|
|---|
| 23 | | <a href="mainclasses.html">
|
|---|
| 24 | <font color="#004faf">Main Classes</font></a>
|
|---|
| 25 | | <a href="annotated.html">
|
|---|
| 26 | <font color="#004faf">Annotated</font></a>
|
|---|
| 27 | | <a href="groups.html">
|
|---|
| 28 | <font color="#004faf">Grouped Classes</font></a>
|
|---|
| 29 | | <a href="functions.html">
|
|---|
| 30 | <font color="#004faf">Functions</font></a>
|
|---|
| 31 | </td>
|
|---|
| 32 | <td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>Properties</h1>
|
|---|
| 33 |
|
|---|
| 34 |
|
|---|
| 35 |
|
|---|
| 36 | <p> Qt provides a sophisticated property system similar to those supplied
|
|---|
| 37 | by some compiler vendors. However, as a compiler- and
|
|---|
| 38 | platform-independent library, Qt cannot rely on non-standard compiler
|
|---|
| 39 | features like <tt>__property</tt> or <tt>[property]</tt>. Our solution works with
|
|---|
| 40 | <em>any</em> standard C++ compiler on every platform we support. It's based
|
|---|
| 41 | on the meta-object system that also provides object communication
|
|---|
| 42 | through <a href="signalsandslots.html">signals and slots</a>.
|
|---|
| 43 | <p> The <tt>Q_PROPERTY</tt> macro in a class declaration declares a
|
|---|
| 44 | property. Properties can only be declared in classes that inherit <a href="qobject.html">QObject</a>. A second macro, <tt>Q_OVERRIDE</tt>, can be used to override some
|
|---|
| 45 | aspects of an inherited property in a subclass. (See <a href="#override">Q_OVERRIDE</a>.)
|
|---|
| 46 | <p> To the outer world, a property appears to be similar to a data member.
|
|---|
| 47 | But properties have several features that distinguish them from
|
|---|
| 48 | ordinary data members:
|
|---|
| 49 | <p> <ul>
|
|---|
| 50 | <li> A read function. This always exists.
|
|---|
| 51 | <p> <li> A write function. This is optional: read-only properties like <a href="qwidget.html#isDesktop">QWidget::isDesktop</a>() do not have one.
|
|---|
| 52 | <p> <li> An attribute "stored" that indicates persistence. Most properties
|
|---|
| 53 | are stored, but a few virtual properties are not. For example, <a href="qwidget.html#minimumWidth">QWidget::minimumWidth</a>() isn't stored, since it's just a view of
|
|---|
| 54 | <a href="qwidget.html#minimumSize">QWidget::minimumSize</a>(), and has no data of its own.
|
|---|
| 55 | <p> <li> A reset function to set a property back to its context specific
|
|---|
| 56 | default value. This is very rare, but for example, <a href="qwidget.html#font">QWidget::font</a>()
|
|---|
| 57 | needs this, since no call to <a href="qwidget.html#setFont">QWidget::setFont</a>() can mean 'reset to
|
|---|
| 58 | the context specific font'.
|
|---|
| 59 | <p> <li> An attribute "designable" that indicates whether it makes sense to
|
|---|
| 60 | make the property available in a GUI builder (e.g. <a href="designer-manual.html">Qt Designer</a>). For most properties this
|
|---|
| 61 | makes sense, but not for all, e.g. <a href="qbutton.html#isDown">QButton::isDown</a>(). The user can
|
|---|
| 62 | press buttons, and the application programmer can make the program
|
|---|
| 63 | press its own buttons, but a GUI design tool can't press buttons.
|
|---|
| 64 | <p> </ul>
|
|---|
| 65 | <p> The read, write, and reset functions must be public member functions
|
|---|
| 66 | from the class in which the property is defined.
|
|---|
| 67 | <p> Properties can be read and written through generic functions in
|
|---|
| 68 | <a href="qobject.html">QObject</a> without knowing anything about the class in use. These two
|
|---|
| 69 | function calls are equivalent:
|
|---|
| 70 | <p> <pre>
|
|---|
| 71 | // QButton *b and QObject *o point to the same button
|
|---|
| 72 | b->setDown( TRUE );
|
|---|
| 73 | o->setProperty( "down", TRUE );
|
|---|
| 74 | </pre>
|
|---|
| 75 |
|
|---|
| 76 | <p> Equivalent, that is, except that the first is faster, and provides
|
|---|
| 77 | much better diagnostics at compile time. When practical, the first is
|
|---|
| 78 | better. However, since you can get a list of all available properties
|
|---|
| 79 | for any QObject through its <a href="qmetaobject.html">QMetaObject</a>, <a href="qobject.html#setProperty">QObject::setProperty</a>()
|
|---|
| 80 | can give you control over classes that weren't available at compile
|
|---|
| 81 | time.
|
|---|
| 82 | <p> As well as <a href="qobject.html#setProperty">QObject::setProperty</a>(), there is a corresponding <a href="qobject.html#property">QObject::property</a>() function. <a href="qmetaobject.html#propertyNames">QMetaObject::propertyNames</a>() returns
|
|---|
| 83 | the names of all available properties. <a href="qmetaobject.html#property">QMetaObject::property</a>()
|
|---|
| 84 | returns the property data for a named property: a <a href="qmetaproperty.html">QMetaProperty</a>
|
|---|
| 85 | object.
|
|---|
| 86 | <p> Here's a simple example that shows the most important property
|
|---|
| 87 | functions in use:
|
|---|
| 88 | <p> <pre>
|
|---|
| 89 | class MyClass : public <a href="qobject.html">QObject</a>
|
|---|
| 90 | {
|
|---|
| 91 | <a href="metaobjects.html#Q_OBJECT">Q_OBJECT</a>
|
|---|
| 92 | public:
|
|---|
| 93 | MyClass( <a href="qobject.html">QObject</a> * parent=0, const char * name=0 );
|
|---|
| 94 | ~MyClass();
|
|---|
| 95 |
|
|---|
| 96 | enum Priority { High, Low, VeryHigh, VeryLow };
|
|---|
| 97 | void setPriority( Priority );
|
|---|
| 98 | Priority priority() const;
|
|---|
| 99 | };
|
|---|
| 100 | </pre>
|
|---|
| 101 |
|
|---|
| 102 | <p> The class has a property "priority" that is not yet known to the <a href="metaobjects.html#meta-object">meta object</a> system. In order to make the property known, you must
|
|---|
| 103 | declare it with the <tt>Q_PROPERTY</tt> macro. The syntax is as follows:
|
|---|
| 104 | <p> <pre>
|
|---|
| 105 | Q_PROPERTY( type name READ getFunction [WRITE setFunction]
|
|---|
| 106 | [RESET resetFunction] [DESIGNABLE bool]
|
|---|
| 107 | [SCRIPTABLE bool] [STORED bool] )
|
|---|
| 108 | </pre>
|
|---|
| 109 |
|
|---|
| 110 | <p> For the declaration to be valid, the get function must be const and
|
|---|
| 111 | to return either the type itself, a pointer to it, or a reference to
|
|---|
| 112 | it. The optional write function must return void and must take exactly
|
|---|
| 113 | one argument, either the type itself, a pointer or a const reference
|
|---|
| 114 | to it. The meta object compiler enforces this.
|
|---|
| 115 | <p> The type of a property can be any <a href="qvariant.html">QVariant</a> supported type or an
|
|---|
| 116 | enumeration type declared in the class itself. Since <tt>MyClass</tt> uses
|
|---|
| 117 | the enumeration type <tt>Priority</tt> for the property, this type must be
|
|---|
| 118 | registered with the property system as well.
|
|---|
| 119 | <p> There are two exceptions to the above: The type of a property can also
|
|---|
| 120 | be either <a href="qvaluelist.html">QValueList<QVariant></a> or <a href="qmap.html">QMap<QString,QVariant></a>. In
|
|---|
| 121 | these cases the type must be specified as <a href="qvaluelist.html">QValueList</a> or as <a href="qmap.html">QMap</a>
|
|---|
| 122 | (i.e. without their template parameters).
|
|---|
| 123 | <p> It is possible to set a value by name, like this:
|
|---|
| 124 | <pre>
|
|---|
| 125 | obj->setProperty( "priority", "VeryHigh" );
|
|---|
| 126 | </pre>
|
|---|
| 127 |
|
|---|
| 128 | In the case of <a href="qvaluelist.html">QValueList</a> and <a href="qmap.html">QMap</a> properties the value passes
|
|---|
| 129 | is a <a href="qvariant.html">QVariant</a> whose value is the entire list or map.
|
|---|
| 130 | <p> Enumeration types are registered with the <tt>Q_ENUMS</tt> macro. Here's the
|
|---|
| 131 | final class declaration including the property related declarations:
|
|---|
| 132 | <p> <pre>
|
|---|
| 133 | class MyClass : public <a href="qobject.html">QObject</a>
|
|---|
| 134 | {
|
|---|
| 135 | Q_OBJECT
|
|---|
| 136 | Q_PROPERTY( Priority priority READ priority WRITE setPriority )
|
|---|
| 137 | Q_ENUMS( Priority )
|
|---|
| 138 | public:
|
|---|
| 139 | MyClass( <a href="qobject.html">QObject</a> * parent=0, const char * name=0 );
|
|---|
| 140 | ~MyClass();
|
|---|
| 141 |
|
|---|
| 142 | enum Priority { High, Low, VeryHigh, VeryLow };
|
|---|
| 143 | void setPriority( Priority );
|
|---|
| 144 | Priority priority() const;
|
|---|
| 145 | };
|
|---|
| 146 | </pre>
|
|---|
| 147 |
|
|---|
| 148 | <p> Another similar macro is <tt>Q_SETS</tt>. Like <tt>Q_ENUMS</tt>, it registers an
|
|---|
| 149 | enumeration type but marks it in addition as a "set", i.e. the
|
|---|
| 150 | enumeration values can be OR-ed together. An I/O class might have
|
|---|
| 151 | enumeration values "Read" and "Write" and accept "Read|Write": such an
|
|---|
| 152 | enum is best handled with <tt>Q_SETS</tt>, rather than <tt>Q_ENUMS</tt>.
|
|---|
| 153 | <p> The remaining keywords in the <tt>Q_PROPERTY</tt> section are <tt>RESET</tt>, <tt>DESIGNABLE</tt>, <tt>SCRIPTABLE</tt> and <tt>STORED</tt>.
|
|---|
| 154 | <p> <tt>RESET</tt> names a function that will set the property to its default
|
|---|
| 155 | state (which may have changed since initialization). The function
|
|---|
| 156 | must return void and take no arguments.
|
|---|
| 157 | <p> <tt>DESIGNABLE</tt> declares whether this property is suitable for
|
|---|
| 158 | modification by a GUI design tool. The default is <tt>TRUE</tt> for
|
|---|
| 159 | writable properties; otherwise <tt>FALSE</tt>. Instead of <tt>TRUE</tt> or <tt>FALSE</tt>, you can specify a boolean member function.
|
|---|
| 160 | <p> <tt>SCRIPTABLE</tt> declares whether this property is suited for access by a
|
|---|
| 161 | scripting engine. The default is <tt>TRUE</tt>. Instead of <tt>TRUE</tt> or <tt>FALSE</tt>,
|
|---|
| 162 | you can specify a boolean member function.
|
|---|
| 163 | <p> <tt>STORED</tt> declares whether the property's value must be remembered
|
|---|
| 164 | when storing an object's state. Stored makes only sense for writable
|
|---|
| 165 | properties. The default value is <tt>TRUE</tt>. Technically superfluous
|
|---|
| 166 | properties (like <a href="qpoint.html">QPoint</a> pos if <a href="qrect.html">QRect</a> geometry is already a property)
|
|---|
| 167 | define this to be <tt>FALSE</tt>.
|
|---|
| 168 | <p> Connected to the property system is an additional macro, "Q_CLASSINFO",
|
|---|
| 169 | that can be used to attach additional name/value-pairs to a class'
|
|---|
| 170 | meta object, for example:
|
|---|
| 171 | <p> <pre>
|
|---|
| 172 | Q_CLASSINFO( "Version", "3.0.0" )
|
|---|
| 173 | </pre>
|
|---|
| 174 |
|
|---|
| 175 | <p> Like other meta data, class information is accessible at runtime
|
|---|
| 176 | through the meta object, see <a href="qmetaobject.html#classInfo">QMetaObject::classInfo</a>() for details.
|
|---|
| 177 | <p> <a name="override"></a>
|
|---|
| 178 | <h2> Q_OVERRIDE
|
|---|
| 179 | </h2>
|
|---|
| 180 | <a name="1"></a><p> When you inherit a <a href="qobject.html">QObject</a> subclass you may wish to override some
|
|---|
| 181 | aspects of some of the class's properties.
|
|---|
| 182 | <p> For example, in <a href="qwidget.html">QWidget</a> we have the autoMask property defined like
|
|---|
| 183 | this:
|
|---|
| 184 | <pre>
|
|---|
| 185 | Q_PROPERTY( bool autoMask READ autoMask WRITE setAutoMask DESIGNABLE false SCRIPTABLE false )
|
|---|
| 186 | </pre>
|
|---|
| 187 |
|
|---|
| 188 | <p> But we need to make the auto mask property designable in some QWidget
|
|---|
| 189 | subclasses. Similarly some classes will need this property to be
|
|---|
| 190 | scriptable (e.g. for QSA). This is achieved by overriding these
|
|---|
| 191 | features of the property in a subclass. In <a href="qcheckbox.html">QCheckBox</a>, for example, we
|
|---|
| 192 | achieve this using the following code:
|
|---|
| 193 | <pre>
|
|---|
| 194 | Q_OVERRIDE( bool autoMask DESIGNABLE true SCRIPTABLE true )
|
|---|
| 195 | </pre>
|
|---|
| 196 |
|
|---|
| 197 | <p> Another example is <a href="qtoolbutton.html">QToolButton</a>. By default QToolButton has a read-only
|
|---|
| 198 | "toggleButton" property, because that's what it inherits from QButton:
|
|---|
| 199 | <pre>
|
|---|
| 200 | Q_PROPERTY( bool toggleButton READ isToggleButton )
|
|---|
| 201 | </pre>
|
|---|
| 202 |
|
|---|
| 203 | <p> But we want to make our tool buttons able to be toggled, so we write a
|
|---|
| 204 | WRITE function in QToolButton, and use the following property override
|
|---|
| 205 | to make it acessible:
|
|---|
| 206 | <pre>
|
|---|
| 207 | Q_OVERRIDE( bool toggleButton WRITE setToggleButton )
|
|---|
| 208 | </pre>
|
|---|
| 209 |
|
|---|
| 210 | The result is read-write (and scriptable and designable, since we now
|
|---|
| 211 | have a WRITE function) boolean property "toggleButton" for tool
|
|---|
| 212 | buttons.
|
|---|
| 213 | <p>
|
|---|
| 214 | <!-- eof -->
|
|---|
| 215 | <p><address><hr><div align=center>
|
|---|
| 216 | <table width=100% cellspacing=0 border=0><tr>
|
|---|
| 217 | <td>Copyright © 2007
|
|---|
| 218 | <a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
|
|---|
| 219 | <td align=right><div align=right>Qt 3.3.8</div>
|
|---|
| 220 | </table></div></address></body>
|
|---|
| 221 | </html>
|
|---|
