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
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at qt-sales@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page cppitem.html
\target cppitem
\title C++ Components for QML
\section1 Making a C++ object available in QML
In QML, the item types and properties correspond to Qt objects and properties. Thus, any Qt object
can potentially be used as an item in QML. More specifically, to make an object available in QML,
it should:
\list
\o Be a subclass of QObject.
\o Provide a default constructor.
\o Declare Q_PROPERTYs.
\o Be registered via the QML_DECLARE_TYPE and QML_DEFINE_TYPE macros.
\endlist
\section2 Declaring Q_PROPERTYs
\target properties
Properties of QObject subclasses are available as properties in QML.
Like any QObject, these properties are defined by the Q_PROPERTY
macro in the header file.
Properties should have a NOTIFY function if they can change dynamically and
if any useful response could be made to them changing in another object. Almost
all properties will thus need a NOTIFY function.
\code
Q_PROPERTY(qreal scale READ scale WRITE setScale NOTIFY scaleChanged);
qreal scale() const;
void setScale(qreal);
...
signals: void scaleChanged();
\endcode
The property types currently supported by QML are:
\list
\o int
\o qreal
\o QString
\o QColor
\o QDate, QTime, and QDateTime
\o QSize and QSizeF
\o QPoint and QPointF
\o QRect and QRectF
\o QPixmap
\o QIcon
\o enums registered with Q_ENUMS
\o flags registered with Q_FLAGS
\o QVariant
\o QObject* (or subclass)
\endlist
Custom property types that provide string-to-type conversion can be used as well, by:
\list
\o Registering them as a metatype (Q_DECLARE_METATYPE() and qRegisterMetaType())
\o Registering a string-to-type convertor function (QML::addCustomStringConvertor()).
\endlist
\section2 Registering your type
\target register
In order for your type to be usable in QML, you must register it:
\code
QML_DECLARE_TYPE(TypeName);
QML_DEFINE_TYPE(ModuleUri,ModuleMajorVersion,ModuleMinorVersionFrom,ModuleMinorVersionTo,QmlName,TypeName);
\endcode
These macros make the C++ \e TypeName available from the declarative markup language under the name \e QmlName.
Of course there's nothing stopping you using the same name for both the C++ and the QML name!
For example:
\code
QML_DECLARE_TYPE(MyCircle);
QML_DEFINE_TYPE(MyLib,1,0,5,Circle,MyCircle);
\endcode
would make the \e MyCircle class accessable though the \c Circle type in QML whenever MyLib 1.0 to 1.5 is imported.
\section1 Creating a new type of QML item in C++
You can create a new type of QML item by:
\list 1
\o Creating a subclass of QFxItem,
\o Adding Q_PROPERTYs appropriate for your item (see \l {properties}{Properties}),
\o Reimplementing the relevant paint functions,
\o Registering the type with the QML_DECLARE_TYPE and QML_DEFINE_TYPE macros (see \l {register}{Register}).
\endlist
\section2 Creating a subclass of QFxItem
To add a new type, you first must add a new C++ class derived from QFxItem.
You may of course extend existing QFxItem subclasses.
One existing subclass is QFxPaintedItem, which provides
a simple cached-image painting model.
\section2 Reimplementing paint functions
\warning This section is out of date. Use the normal QGraphicsItem::paint function.
Two alternative painters are available, offering
different levels of performance and functionality:
QPainter, GLPainter.
You can choose to subclass QFxPaintedItem rather than QFxItem,
and then implement the virtual method:
\code
void drawContents(QPainter *painter, const QRect &rect);
\endcode
This paints into an offscreen pixmap which is then painted to the display (transformed,
etc. as needed). The cost of this offscreen pixmap should be carefully considered, as
should the specific performance of the painting done in the paint function.
If you require more control, subclass QFxItem instead.
QFxItem subclasses must implement both simple software canvas painting
and GL painting:
\list
\o \c QFxItem::paintContents(QPainter &) for the simple software canvas,
\o \c QFxItem::paintGLContents(GLPainter &) for OpenGL.
\endlist
See the documentation of those functions for detailed subclassing notes.
*/
|
