<!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> TQt provides a sophisticated property system similar to those supplied
by some compiler vendors. However, as a compiler- and
platform-independent library, TQt 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="ntqobject.html">TQObject</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="ntqwidget.html#isDesktop">TQWidget::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="ntqwidget.html#minimumWidth">TQWidget::minimumWidth</a>() isn't stored, since it's just a view of
<a href="ntqwidget.html#minimumSize">TQWidget::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="ntqwidget.html#font">TQWidget::font</a>()
needs this, since no call to <a href="ntqwidget.html#setFont">TQWidget::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">TQt Designer</a>). For most properties this
makes sense, but not for all, e.g. <a href="ntqbutton.html#isDown">TQButton::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="ntqobject.html">TQObject</a> without knowing anything about the class in use. These two
function calls are equivalent:
<p> <pre>
// TQButton *b and TQObject *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 TQObject through its <a href="ntqmetaobject.html">TQMetaObject</a>, <a href="ntqobject.html#setProperty">TQObject::setProperty</a>()
can give you control over classes that weren't available at compile
time.
<p> As well as <a href="ntqobject.html#setProperty">TQObject::setProperty</a>(), there is a corresponding <a href="ntqobject.html#property">TQObject::property</a>() function. <a href="ntqmetaobject.html#propertyNames">TQMetaObject::propertyNames</a>() returns
the names of all available properties. <a href="ntqmetaobject.html#property">TQMetaObject::property</a>()
returns the property data for a named property: a <a href="qmetaproperty.html">TQMetaProperty</a>
object.
<p> Here's a simple example that shows the most important property
functions in use:
<p> <pre>
class MyClass : public <a href="ntqobject.html">TQObject</a>
{
<a href="metaobjects.html#TQ_OBJECT">TQ_OBJECT</a>
public:
MyClass( <a href="ntqobject.html">TQObject</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="ntqvariant.html">TQVariant</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="ntqvaluelist.html">TQValueList<TQVariant></a> or <a href="ntqmap.html">TQMap<TQString,TQVariant></a>. In
these cases the type must be specified as <a href="ntqvaluelist.html">TQValueList</a> or as <a href="ntqmap.html">TQMap</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="ntqvaluelist.html">TQValueList</a> and <a href="ntqmap.html">TQMap</a> properties the value passes
is a <a href="ntqvariant.html">TQVariant</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="ntqobject.html">TQObject</a>
{
TQ_OBJECT
Q_PROPERTY( Priority priority READ priority WRITE setPriority )
Q_ENUMS( Priority )
public:
MyClass( <a href="ntqobject.html">TQObject</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="ntqpoint.html">TQPoint</a> pos if <a href="ntqrect.html">TQRect</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="ntqmetaobject.html#classInfo">TQMetaObject::classInfo</a>() for details.
<p> <a name="override"></a>
<h2> Q_OVERRIDE
</h2>
<a name="1"></a><p> When you inherit a <a href="ntqobject.html">TQObject</a> subclass you may wish to override some
aspects of some of the class's properties.
<p> For example, in <a href="ntqwidget.html">TQWidget</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 TQWidget
subclasses. Similarly some classes will need this property to be
scriptable (e.g. for TQSA). This is achieved by overriding these
features of the property in a subclass. In <a href="ntqcheckbox.html">TQCheckBox</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="ntqtoolbutton.html">TQToolButton</a>. By default TQToolButton has a read-only
"toggleButton" property, because that's what it inherits from TQButton:
<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 TQToolButton, 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>TQt 3.3.8</div>
</table></div></address></body>
</html>