File: properties.html

package info (click to toggle)
qt-embedded 2.3.2-3
  • links: PTS
  • area: main
  • in suites: woody
  • size: 68,608 kB
  • ctags: 45,998
  • sloc: cpp: 276,654; ansic: 71,987; makefile: 29,074; sh: 12,305; yacc: 2,465; python: 1,863; perl: 481; lex: 480; xml: 68; lisp: 15
file content (155 lines) | stat: -rw-r--r-- 7,657 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Qt Toolkit -  Properties</title><style type="text/css"><!--
h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm; }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }body { background: white; color: black; }
--></style></head><body bgcolor="#ffffff">
<p>
<table width="100%">
<tr><td><a href="index.html">
<img width="100" height="100" src="qtlogo.png"
alt="Home" border="0"><img width="100"
height="100" src="face.png" alt="Home" border="0">
</a><td valign=top><div align=right><img src="dochead.png" width="472" height="27"><br>
<a href="classes.html"><b>Classes</b></a>
-<a href="annotated.html">Annotated</a>
- <a href="hierarchy.html">Tree</a>
-<a href="functions.html">Functions</a>
-<a href="index.html">Home</a>
-<a href="topicals.html"><b>Structure</b></a>
</div>
</table>
<h1 align=center> Properties</h1><br clear="all">
Qt provides a sophisticated property system similar to those shipped
by some compiler vendors. However, as a compiler- and
platform-independent library, Qt cannot rely on non-standard compiler
features like <code>__property</code> or <code>[property].</code> Our solution works with
any standard C++ compiler on every platform we support. It's based on
the <a href="metaobjects.html">Meta Object System</a> that also
provides object communication through signals and slots.
<p>
The <code>Q_PROPERTY</code> 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 - <code>Q_OVERRIDE</code> - can be used to override some
aspects of an inherited property in a subclass.
<p>
To the outer world, a property appears quite similar to a data
member. However, properties have several features that distinguish
them from ordinary data members:
<p>
<ul>
<li> a read method.  This always exists.
<li> a write method.  Optional: read-only properties like <a href="qwidget.html#38c72f">QWidget::isDesktop()</a> do not have this.
<li> an attribute "stored" that indicates persistence.  Most
properties are stored, but a few janus-faced properties like <a href="qwidget.html#3dae47">QWidget::minimumWidth()</a> aren't: That property is just way of looking
at <a href="qwidget.html#b24d94">QWidget::minimumSize()</a>, it has no data of its own.
<li> a reset method to set a property back to its context specific
default value.  Very unusual, but e.g. <a href="qwidget.html#167922">QWidget::font()</a> needs it:
The default is to follow its surroundings, and no call to <a href="qwidget.html#090d60">QWidget::setFont()</a> can mean that.
<li> an attribute "designable" that indicates whether a property is
considered to be designable in a GUI Designer.  Most are, but e.g. <a href="qbutton.html#ea8b93">QButton::isDown()</a> can't be designed.  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>
Properties can be read and written through generic functions in
QObject without knowing anything about class in use.  These two are
equivalent:
<p>
<pre>    //QButton * b and QObject * o point to the same button
    b-&gt;setDown( TRUE );
    o-&gt;setProperty( "down", TRUE );
</pre>
<p>
Equivalent, that is, except that the first is faster, and that the
first gives much better diagnostics at compile time.  When accessible,
the first is preferred.  However, since you can get a list of all
available properties for any QObject through its <a href="qmetaobject.html">metaObject()</a> setProperty() can give you control over classes
that weren't available at compile time.
<p>
As well as QObject::setProperty(), there is a <a href="qobject.html#a110be">QObject::property()</a>.
<a href="qmetaobject.html#8c9b9c">QMetaObject::propertyNames()</a> returns the names of all available
properties.  <a href="qmetaobject.html#843ead">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 QObject
    {
        Q_OBJECT
    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 meta
object system. In order to make the property known, you have to
declare it with the <code>Q_PROPERTY</code> macro. The syntax is as follows:
<p>
<pre>Q_PROPERTY( type name READ getFunction [WRITE setFunction]
            [STORED bool] [DESIGNABLE bool] [RESET resetFunction])
</pre>
<p>
For the declaration to be valid, the get function has to be const and
to return either the type itself, a pointer to it, or a reference to
it. The optional write function has to return void and to 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 everything <a href="qvariant.html">QVariant</a> provides or an
enumeration type declared in the class itself. Since <code>MyClass</code> uses
the enumeration type <code>Priority</code> for the property, this type has to be
registered with the property system as well. This way it will be
possible to set a value by name, like this:
<p>
<pre>   obj-&gt;setProperty( "priority", "VeryHigh" );
</pre>
<p>
Enumeration types are registered with the <code>Q_ENUMS</code> macro.  Here's the
final class declaration including the property declaration:
<p>
<pre>    class MyClass : public QObject
    {
        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 <code>Q_SETS.</code> Like <code>Q_ENUMS,</code> it registers an
enumeration type but marks it in addition as "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 <code>Q_SETS,</code> not <code>Q_ENUMS.</code>
<p>
The remaining keywords in the <code>Q_PROPERTY</code> section are <code>STORED,</code> <code>DESIGNABLE</code> and <code>RESET.</code>
<p>
<code>STORED</code> declares whether the property's value is stored in the
object. Stored makes only sense for writable properties. The default
value is <code>true.</code>
<p>
<code>DESIGNABLE</code> declares whether this property is suited for
modification by a GUI designer program.  The default is <code>true</code> for
writable properties, otherwise <code>false.</code>
<p>
<code>RESET</code> 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><address><hr><div align="center">
<table width="100%" cellspacing="0" border="0"><tr>
<td>Copyright  2001 Trolltech<td><a href="http://www.trolltech.com/trademarks.html">Trademarks</a>
<td align="right"><div align="right">Qt version 2.3.2</div>
</table></div></address></body></html>