summaryrefslogtreecommitdiffstats
path: root/examples/qml/doc/src/qml-extending.qdoc
blob: 30c074d765a2d5bba5b053af1d4b3684d49a3cb3 (plain)
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
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\example referenceexamples/adding
\title Extending QML - Adding Types Example
\brief Exporting C++ Classes
\ingroup qmlextendingexamples

The Adding Types Example shows how to add a new object type, \c Person, to QML.
The \c Person type can be used from QML like this:

\snippet referenceexamples/adding/example.qml 0

\section1 Declare the Person Class

All QML types map to C++ types.  Here we declare a basic C++ Person class
with the two properties we want accessible on the QML type - name and shoeSize.
Although in this example we use the same name for the C++ class as the QML
type, the C++ class can be named differently, or appear in a namespace.

\snippet referenceexamples/adding/person.h 0

\section1 Define the Person Class

\snippet referenceexamples/adding/person.cpp 0

The Person class implementation is quite basic.  The property accessors simply
return members of the object instance.

The \c main.cpp file also calls the \c qmlRegisterType() function to
register the \c Person type with QML as a type in the People library version 1.0,
and defines the mapping between the C++ and QML class names.

\section1 Running the Example

The main.cpp file in the example includes a simple shell application that
loads and runs the QML snippet shown at the beginning of this page.
*/

/*!
\example referenceexamples/extended
\title Extending QML - Extension Objects Example
\brief Extension Objects
\ingroup qmlextendingexamples

This example builds on:
\list
\li \l {Extending QML - Adding Types Example}
\endlist

Shows how to use \l {QQmlEngine::}{qmlRegisterExtendedType()} to provide an
\l {Registering Extension Objects}{extension object} to a \l QLineEdit without modifying or
subclassing it.

Firstly, the LineEditExtension class is registered with the QML system as an extension of QLineEdit:

\snippet referenceexamples/extended/main.cpp 0

The QML engine then instantiates a \l QLineEdit:

\snippet referenceexamples/extended/main.cpp 1

In QML, a property is set on the line edit that only exists in the LineEditExtension class:

\snippet referenceexamples/extended/example.qml 0

The extension type performs calls on the \l QLineEdit that otherwise will
not be accessible to the QML engine.
*/

/*!
\example referenceexamples/properties
\title Extending QML - Object and List Property Types Example
\brief Exporting C++ Properties
\ingroup qmlextendingexamples

This example builds on:
\list
\li \l {Extending QML - Adding Types Example}
\endlist

The Object and List Property Types example shows how to add object and list
properties in QML.  This example adds a BirthdayParty type that specifies
a birthday party, consisting of a celebrant and a list of guests.  People are
specified using the People QML type built in the previous example.

\snippet referenceexamples/properties/example.qml 0

\section1 Declare the BirthdayParty

The BirthdayParty class is declared like this:

\snippet referenceexamples/properties/birthdayparty.h 0
\snippet referenceexamples/properties/birthdayparty.h 1
\snippet referenceexamples/properties/birthdayparty.h 2
\snippet referenceexamples/properties/birthdayparty.h 3

The class contains a member to store the celebrant object, and also a
QList<Person *> member.

In QML, the type of a list properties - and the guests property is a list of
people - are all of type QQmlListProperty<T>.  QQmlListProperty is simple value
type that contains a set of function pointers.  QML calls these function
pointers whenever it needs to read from, write to or otherwise interact with
the list.  In addition to concrete lists like the people list used in this
example, the use of QQmlListProperty allows for "virtual lists" and other advanced
scenarios.

\section2 Define the BirthdayParty

The implementation of BirthdayParty property accessors is straight forward.

\snippet referenceexamples/properties/birthdayparty.cpp 0

\section1 Running the Example

The main.cpp file in the example includes a simple shell application that
loads and runs the QML snippet shown at the beginning of this page.
*/

/*!
\example referenceexamples/coercion
\title Extending QML - Inheritance and Coercion Example
\brief C++ Inheritance and Coercion
\ingroup qmlextendingexamples

This example builds on:
\list
\li \l {Extending QML - Object and List Property Types Example}
\li \l {Extending QML - Adding Types Example}
\endlist

The Inheritance and Coercion Example shows how to use base classes to assign
types of more than one type to a property.  It specializes the Person type
developed in the previous examples into two types - a \c Boy and a \c Girl.

\snippet referenceexamples/coercion/example.qml 0

\section1 Declare Boy and Girl

\snippet referenceexamples/coercion/person.h 0

The Person class remains unaltered in this example and the Boy and Girl C++
classes are trivial extensions of it.  As an example, the inheritance used here
is a little contrived, but in real applications it is likely that the two
extensions would add additional properties or modify the Person classes
behavior.

\section2 Define People as a Base Class

The implementation of the People class itself has not changed since the
previous example.  However, as we have repurposed the People class as a common
base for Boy and Girl, we want to prevent it from being instantiated from QML
directly - an explicit Boy or Girl should be instantiated instead.

\snippet referenceexamples/coercion/main.cpp 0

While we want to disallow instantiating Person from within QML, it still needs
to be registered with the QML engine, so that it can be used as a property type
and other types can be coerced to it.

\section2 Define Boy and Girl

The implementation of Boy and Girl is trivial.

\snippet referenceexamples/coercion/person.cpp 1

All that is necessary is to implement the constructor, and to register the types
and their QML name with the QML engine.

\section1 Running the Example

The BirthdayParty type has not changed since the previous example.  The
celebrant and guests property still use the People type.

\snippet referenceexamples/coercion/birthdayparty.h 0

However, as all three types, Person, Boy and Girl, have been registered with the
QML system, on assignment QML automatically (and type-safely) converts the Boy
and Girl objects into a Person.

The main.cpp file in the example includes a simple shell application that
loads and runs the QML snippet shown at the beginning of this page.
*/

/*!
\example referenceexamples/default
\title Extending QML - Default Property Example
\brief Default Property
\ingroup qmlextendingexamples

This example builds on:
\list
\li \l {Extending QML - Inheritance and Coercion Example}
\li \l {Extending QML - Object and List Property Types Example}
\li \l {Extending QML - Adding Types Example}
\endlist

The Default Property Example is a minor modification of the
\l {Extending QML - Inheritance and Coercion Example} that simplifies the
specification of a BirthdayParty through the use of a default property.

\snippet referenceexamples/default/example.qml 0

\section1 Declaring the BirthdayParty Class

The only difference between this example and the last, is the addition of the
\c DefaultProperty class info annotation.

\snippet referenceexamples/default/birthdayparty.h 0

The default property specifies the property to assign to whenever an explicit
property is not specified, in the case of the BirthdayParty type the guest
property.  It is purely a syntactic simplification, the behavior is identical
to specifying the property by name, but it can add a more natural feel in many
situations.  The default property must be either an object or list property.

\section1 Running the Example

The main.cpp file in the example includes a simple shell application that
loads and runs the QML snippet shown at the beginning of this page.
*/

/*!
\example referenceexamples/grouped
\title Extending QML - Grouped Properties Example
\brief Grouped Properties
\ingroup qmlextendingexamples

This example builds on:
\list
\li \l {Extending QML - Default Property Example}
\li \l {Extending QML - Inheritance and Coercion Example}
\li \l {Extending QML - Object and List Property Types Example}
\li \l {Extending QML - Adding Types Example}
\endlist

*/

/*!
\example referenceexamples/attached
\title Extending QML - Attached Properties Example
\brief Attached Properties
\ingroup qmlextendingexamples

This example builds on:
\list
\li \l {Extending QML - Grouped Properties Example}
\li \l {Extending QML - Default Property Example}
\li \l {Extending QML - Inheritance and Coercion Example}
\li \l {Extending QML - Object and List Property Types Example}
\li \l {Extending QML - Adding Types Example}
\endlist

*/

/*!
\example referenceexamples/signal
\title Extending QML - Signal Support Example
\brief Signal Support
\ingroup qmlextendingexamples

This example builds on:
\list
\li \l {Extending QML - Attached Properties Example}
\li \l {Extending QML - Grouped Properties Example}
\li \l {Extending QML - Default Property Example}
\li \l {Extending QML - Inheritance and Coercion Example}
\li \l {Extending QML - Object and List Property Types Example}
\li \l {Extending QML - Adding Types Example}
\endlist

*/

/*!
\example referenceexamples/methods
\title Extending QML - Methods Example
\brief Methods Support
\ingroup qmlextendingexamples

This example builds on:
\list
\li \l {Extending QML - Inheritance and Coercion Example}
\li \l {Extending QML - Object and List Property Types Example}
\li \l {Extending QML - Adding Types Example}
\endlist

The Methods Example has an additional method in the \c BirthdayParty class: \c invite().
\c invite() is declared with \l Q_INVOKABLE so that it can be
called from QML.

\snippet referenceexamples/methods/birthdayparty.h 0

In \c example.qml, the \c invite() method is called in the \l [QML]{QtQml::Component::completed()}{Component.onCompleted} signal handler:

\snippet referenceexamples/methods/example.qml 0
*/

/*!
\example referenceexamples/valuesource
\title Extending QML - Property Value Source Example
\brief Property Value Source
\ingroup qmlextendingexamples

This example builds on:
\list
\li \l {Extending QML - Signal Support Example}
\li \l {Extending QML - Attached Properties Example}
\li \l {Extending QML - Grouped Properties Example}
\li \l {Extending QML - Default Property Example}
\li \l {Extending QML - Inheritance and Coercion Example}
\li \l {Extending QML - Object and List Property Types Example}
\li \l {Extending QML - Adding Types Example}
\endlist

*/

/*!
\example referenceexamples/binding
\title Extending QML - Binding Example
\brief Binding
\ingroup qmlextendingexamples

This example builds on:
\list
\li \l {Extending QML - Property Value Source Example}
\li \l {Extending QML - Signal Support Example}
\li \l {Extending QML - Attached Properties Example}
\li \l {Extending QML - Grouped Properties Example}
\li \l {Extending QML - Default Property Example}
\li \l {Extending QML - Inheritance and Coercion Example}
\li \l {Extending QML - Object and List Property Types Example}
\li \l {Extending QML - Adding Types Example}
\endlist

*/