diff options
Diffstat (limited to 'doc/html/properties.html')
| -rw-r--r-- | doc/html/properties.html | 221 |
1 files changed, 221 insertions, 0 deletions
diff --git a/doc/html/properties.html b/doc/html/properties.html new file mode 100644 index 0000000..2eaf0b3 --- /dev/null +++ b/doc/html/properties.html @@ -0,0 +1,221 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/object.doc:210 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Properties</title> +<style type="text/css"><!-- +fn { margin-left: 1cm; text-indent: -1cm; } +a:link { color: #004faf; text-decoration: none } +a:visited { color: #672967; text-decoration: none } +body { background: #ffffff; color: black; } +--></style> +</head> +<body> + +<table border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr bgcolor="#E5E5E5"> +<td valign=center> + <a href="index.html"> +<font color="#004faf">Home</font></a> + | <a href="classes.html"> +<font color="#004faf">All Classes</font></a> + | <a href="mainclasses.html"> +<font color="#004faf">Main Classes</font></a> + | <a href="annotated.html"> +<font color="#004faf">Annotated</font></a> + | <a href="groups.html"> +<font color="#004faf">Grouped Classes</font></a> + | <a href="functions.html"> +<font color="#004faf">Functions</font></a> +</td> +<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> + + + +<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 +<em>any</em> standard C++ compiler on every platform we support. It's based +on the meta-object system that also provides object communication +through <a href="signalsandslots.html">signals and slots</a>. +<p> The <tt>Q_PROPERTY</tt> macro in a class declaration declares a +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 +aspects of an inherited property in a subclass. (See <a href="#override">Q_OVERRIDE</a>.) +<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 always exists. +<p> <li> A write function. This is optional: read-only properties like <a href="qwidget.html#isDesktop">QWidget::isDesktop</a>() do not have one. +<p> <li> An attribute "stored" that indicates persistence. Most properties +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 +<a href="qwidget.html#minimumSize">QWidget::minimumSize</a>(), and has no data of its own. +<p> <li> A reset function to set a property back to its context specific +default value. This is very rare, but for example, <a href="qwidget.html#font">QWidget::font</a>() +needs this, since no call to <a href="qwidget.html#setFont">QWidget::setFont</a>() can mean 'reset to +the context specific font'. +<p> <li> An attribute "designable" that indicates whether it makes sense to +make the property available in a GUI builder (e.g. <a href="designer-manual.html">Qt Designer</a>). For most properties this +makes sense, but not for all, e.g. <a href="qbutton.html#isDown">QButton::isDown</a>(). 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. +<p> </ul> +<p> The read, write, and reset functions must be public member functions +from the class in which the property is defined. +<p> Properties can be read and written through generic functions in +<a href="qobject.html">QObject</a> without knowing anything about the class in use. These two +function calls are equivalent: +<p> <pre> + // QButton *b and QObject *o point to the same button + b->setDown( TRUE ); + o->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 QObject through its <a href="qmetaobject.html">QMetaObject</a>, <a href="qobject.html#setProperty">QObject::setProperty</a>() +can give you control over classes that weren't available at compile +time. +<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 +the names of all available properties. <a href="qmetaobject.html#property">QMetaObject::property</a>() +returns the property data for a named property: a <a href="qmetaproperty.html">QMetaProperty</a> +object. +<p> Here's a simple example that shows the most important property +functions in use: +<p> <pre> + class MyClass : public <a href="qobject.html">QObject</a> + { + <a href="metaobjects.html#Q_OBJECT">Q_OBJECT</a> + public: + MyClass( <a href="qobject.html">QObject</a> * parent=0, const char * name=0 ); + ~MyClass(); + + enum Priority { High, Low, VeryHigh, VeryLow }; + void setPriority( Priority ); + Priority priority() const; + }; +</pre> + +<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 +declare it with the <tt>Q_PROPERTY</tt> 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> The type of a property can be any <a href="qvariant.html">QVariant</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> There are two exceptions to the above: The type of a property can also +be either <a href="qvaluelist.html">QValueList<QVariant></a> or <a href="qmap.html">QMap<QString,QVariant></a>. In +these cases the type must be specified as <a href="qvaluelist.html">QValueList</a> or as <a href="qmap.html">QMap</a> +(i.e. without their template parameters). +<p> It is possible to set a value by name, like this: +<pre> + obj->setProperty( "priority", "VeryHigh" ); +</pre> + +In the case of <a href="qvaluelist.html">QValueList</a> and <a href="qmap.html">QMap</a> properties the value passes +is a <a href="qvariant.html">QVariant</a> whose value is the entire list or map. +<p> Enumeration types are registered with the <tt>Q_ENUMS</tt> macro. Here's the +final class declaration including the property related declarations: +<p> <pre> + class MyClass : public <a href="qobject.html">QObject</a> + { + Q_OBJECT + Q_PROPERTY( Priority priority READ priority WRITE setPriority ) + Q_ENUMS( Priority ) + public: + MyClass( <a href="qobject.html">QObject</a> * parent=0, const char * name=0 ); + ~MyClass(); + + enum Priority { High, Low, VeryHigh, VeryLow }; + void setPriority( Priority ); + Priority priority() const; + }; +</pre> + +<p> Another similar macro is <tt>Q_SETS</tt>. Like <tt>Q_ENUMS</tt>, it registers an +enumeration type but marks it in addition as a "set", i.e. the +enumeration values can be OR-ed together. An I/O class might have +enumeration values "Read" and "Write" and accept "Read|Write": such an +enum is best handled with <tt>Q_SETS</tt>, rather than <tt>Q_ENUMS</tt>. +<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>. +<p> <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. +<p> <tt>DESIGNABLE</tt> declares whether this property is suitable for +modification by a GUI design tool. The default is <tt>TRUE</tt> for +writable properties; otherwise <tt>FALSE</tt>. Instead of <tt>TRUE</tt> or <tt>FALSE</tt>, you can specify a boolean member function. +<p> <tt>SCRIPTABLE</tt> declares whether this property is suited for access by a +scripting engine. The default is <tt>TRUE</tt>. Instead of <tt>TRUE</tt> or <tt>FALSE</tt>, +you can specify a boolean member function. +<p> <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 <tt>TRUE</tt>. Technically superfluous +properties (like <a href="qpoint.html">QPoint</a> pos if <a href="qrect.html">QRect</a> geometry is already a property) +define this to be <tt>FALSE</tt>. +<p> Connected to the property system is an additional macro, "Q_CLASSINFO", +that can be used to attach additional name/value-pairs to a class' +meta object, for example: +<p> <pre> + Q_CLASSINFO( "Version", "3.0.0" ) +</pre> + +<p> Like other meta data, class information is accessible at runtime +through the meta object, see <a href="qmetaobject.html#classInfo">QMetaObject::classInfo</a>() for details. +<p> <a name="override"></a> +<h2> Q_OVERRIDE +</h2> +<a name="1"></a><p> When you inherit a <a href="qobject.html">QObject</a> subclass you may wish to override some +aspects of some of the class's properties. +<p> For example, in <a href="qwidget.html">QWidget</a> we have the autoMask property defined like +this: +<pre> + Q_PROPERTY( bool autoMask READ autoMask WRITE setAutoMask DESIGNABLE false SCRIPTABLE false ) +</pre> + +<p> But we need to make the auto mask property designable in some QWidget +subclasses. Similarly some classes will need this property to be +scriptable (e.g. for QSA). This is achieved by overriding these +features of the property in a subclass. In <a href="qcheckbox.html">QCheckBox</a>, for example, we +achieve this using the following code: +<pre> + Q_OVERRIDE( bool autoMask DESIGNABLE true SCRIPTABLE true ) +</pre> + +<p> Another example is <a href="qtoolbutton.html">QToolButton</a>. By default QToolButton has a read-only +"toggleButton" property, because that's what it inherits from QButton: +<pre> + Q_PROPERTY( bool toggleButton READ isToggleButton ) +</pre> + +<p> But we want to make our tool buttons able to be toggled, so we write a +WRITE function in QToolButton, and use the following property override +to make it acessible: +<pre> + Q_OVERRIDE( bool toggleButton WRITE setToggleButton ) +</pre> + +The result is read-write (and scriptable and designable, since we now +have a WRITE function) boolean property "toggleButton" for tool +buttons. +<p> +<!-- eof --> +<p><address><hr><div align=center> +<table width=100% cellspacing=0 border=0><tr> +<td>Copyright © 2007 +<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a> +<td align=right><div align=right>Qt 3.3.8</div> +</table></div></address></body> +</html> |