You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
222 lines
11 KiB
222 lines
11 KiB
13 years ago
|
<!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="qobject.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="qwidget.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="qwidget.html#minimumWidth">TQWidget::minimumWidth</a>() isn't stored, since it's just a view of
|
||
|
|
<a href="qwidget.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="qwidget.html#font">TQWidget::font</a>()
|
||
|
|
needs this, since no call to <a href="qwidget.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="qbutton.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="qobject.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="qmetaobject.html">TQMetaObject</a>, <a href="qobject.html#setProperty">TQObject::setProperty</a>()
|
||
|
|
can give you control over classes that weren't available at compile
|
||
|
|
time.
|
||
|
|
<p> As well as <a href="qobject.html#setProperty">TQObject::setProperty</a>(), there is a corresponding <a href="qobject.html#property">TQObject::property</a>() function. <a href="qmetaobject.html#propertyNames">TQMetaObject::propertyNames</a>() returns
|
||
|
|
the names of all available properties. <a href="qmetaobject.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="qobject.html">TQObject</a>
|
||
|
|
{
|
||
|
|
<a href="metaobjects.html#Q_OBJECT">Q_OBJECT</a>
|
||
|
|
public:
|
||
|
|
MyClass( <a href="qobject.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="qvariant.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="qvaluelist.html">TQValueList<TQVariant></a> or <a href="qmap.html">TQMap<TQString,TQVariant></a>. In
|
||
|
|
these cases the type must be specified as <a href="qvaluelist.html">TQValueList</a> or as <a href="qmap.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="qvaluelist.html">TQValueList</a> and <a href="qmap.html">TQMap</a> properties the value passes
|
||
|
|
is a <a href="qvariant.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="qobject.html">TQObject</a>
|
||
|
|
{
|
||
|
|
Q_OBJECT
|
||
|
|
Q_PROPERTY( Priority priority READ priority WRITE setPriority )
|
||
|
|
Q_ENUMS( Priority )
|
||
|
|
public:
|
||
|
|
MyClass( <a href="qobject.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="qpoint.html">TQPoint</a> pos if <a href="qrect.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="qmetaobject.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="qobject.html">TQObject</a> subclass you may wish to override some
|
||
|
|
aspects of some of the class's properties.
|
||
|
|
<p> For example, in <a href="qwidget.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="qcheckbox.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="qtoolbutton.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>
|