Update copyright headers
[qt:qt.git] / doc / src / declarative / extending-tutorial.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29 \page qml-extending-tutorial-index.html
30 \title Tutorial: Writing QML Extensions with C++
31
32 The Qt Declarative module provides a set of APIs for extending QML through
33 C++ extensions. You can write extensions to add your own QML types, extend existing
34 Qt types, or call C/C++ functions that are not accessible from ordinary QML code.
35
36 This tutorial shows how to write a QML extension using C++ that includes
37 core QML features, including properties, signals and bindings. It also shows how
38 extensions can be deployed through plugins.
39
40 You can find the source code for this tutorial in \c Qt's
41 examples/declarative/tutorials/extending directory.
42
43 Tutorial chapters:
44
45 \list 1
46 \o \l{declarative/tutorials/extending/chapter1-basics}{Creating a New Type}
47 \o \l{declarative/tutorials/extending/chapter2-methods}{Connecting to C++ Methods and Signals}
48 \o \l{declarative/tutorials/extending/chapter3-bindings}{Property Binding}
49 \o \l{declarative/tutorials/extending/chapter4-customPropertyTypes}{Using Custom Property Types}
50 \o \l{declarative/tutorials/extending/chapter5-listproperties}{Using List Property Types}
51 \o \l{declarative/tutorials/extending/chapter6-plugins}{Writing an Extension Plugin}
52 \o \l{qml-extending-tutorial7.html}{In Summary}
53 \endlist
54
55 */
56
57 /*!
58 \title Chapter 1: Creating a New Type
59
60 \example declarative/tutorials/extending/chapter1-basics
61
62 A common task when extending QML is to provide a new QML type that supports some
63  custom functionality beyond what is provided by the built-in \l {QML Elements}.
64 For example, this could be done to implement particular data models, or provide
65 elements with custom painting and drawing capabilities, or access system features
66 like network programming that are not accessible through built-in QML features.
67
68 In this tutorial, we will show how to use the C++ classes in the Qt Declarative
69 module to extend QML. The end result will be a simple Pie Chart display implemented by
70 several custom QML types connected together through QML features like bindings and
71 signals, and made available to the QML runtime through a plugin.
72
73 To begin with, let's create a new QML type called "PieChart" that has two properties: a name
74 and a color.  We will make it available in a \l {Modules}{module} called "Charts", with
75 a module version of 1.0.
76
77 We want this \c PieChart type to be usable from QML like this:
78
79 \code
80     import Charts 1.0
81
82     PieChart {
83         width: 100; height: 100
84         name: "A simple pie chart"
85         color: "red"
86     }
87 \endcode
88
89 To do this, we need a C++ class that encapsulates this \c PieChart type and its two
90 properties. Since QML makes extensive use of Qt's \l{Meta-Object System}{meta object system},
91 this new class must:
92
93 \list
94 \o Inherit from QObject
95 \o Declare its properties using the Q_PROPERTY macro
96 \endlist
97
98 Here is our \c PieChart class, defined in \c piechart.h:
99
100 \snippet declarative/tutorials/extending/chapter1-basics/piechart.h 0
101
102 The class inherits from QDeclarativeItem because we want to override
103 QDeclarativeItem::paint() in order to draw. If the class just represented some
104 data type and was not an item that actually needed to be displayed, it could simply inherit
105 from QObject. Or, if we want to extend the functionality of an existing QObject-based
106 class, it could inherit from that class instead.
107
108 The \c PieChart class defines the two properties, \c name and \c color, with the Q_PROPERTY macro,
109 and overrides QDeclarativeItem::paint(). The class implementation in \c piechart.cpp
110 simply sets and returns the \c m_name and \c m_color values as appropriate, and
111 implements \c paint() to draw a simple pie chart. It also turns off the
112 QGraphicsItem::ItemHasNoContents flag to enable painting:
113
114 \snippet declarative/tutorials/extending/chapter1-basics/piechart.cpp 0
115 \dots 0
116 \snippet declarative/tutorials/extending/chapter1-basics/piechart.cpp 1
117
118 Now that we have defined the \c PieChart type, we will use it from QML. The \c app.qml
119 file creates a \c PieChart item and display the pie chart's details
120 using a standard QML \l Text item:
121
122 \snippet declarative/tutorials/extending/chapter1-basics/app.qml 0
123
124 Notice that although the color is specified as a string in QML, it is automatically
125 converted to a QColor object for the PieChart \c color property. Automatic conversions are
126 provided for various other \l {QML Basic Types}{basic types}; for example, a string
127 like "640x480" can be automatically converted to a QSize value.
128
129 We'll also create a C++ application that uses a QDeclarativeView to run and
130 display \c app.qml. The application must register the \c PieChart type
131 using the qmlRegisterType() function, to allow it to be used from QML. If
132 you don't register the type, \c app.qml won't be able to create a \c PieChart.
133
134 Here is the application \c main.cpp:
135
136 \snippet declarative/tutorials/extending/chapter1-basics/main.cpp 0
137
138 This call to qmlRegisterType() registers the \c PieChart type as a type called "PieChart", in a module named "Charts",
139 with a module version of 1.0.
140
141 Lastly, we write a \c .pro project file that includes the files and the \c declarative library:
142
143 \quotefile declarative/tutorials/extending/chapter1-basics/chapter1-basics.pro
144
145 Now we can build and run the application:
146
147 \image extending-tutorial-chapter1.png
148
149 Try it yourself with the code in Qt's \c examples/tutorials/extending/chapter1-basics directory.
150
151 At the moment, the \c app.qml is run from within a C++ application.
152 This may seem odd if you're used to running QML files with the \l {QML Viewer}.
153 Later on, we'll show how to create a plugin so that you can run \c app.qml using the
154 \l {QML Viewer} instead.
155
156 */
157
158
159 /*!
160 \title Chapter 2: Connecting to C++ Methods and Signals
161
162 \example declarative/tutorials/extending/chapter2-methods
163
164 Suppose we want \c PieChart to have a "clearChart()" method that erases the
165 chart and then emits a "chartCleared" signal. Our \c app.qml would be able
166 to call \c clearChart() and receive \c chartCleared() signals like this:
167
168 \snippet declarative/tutorials/extending/chapter2-methods/app.qml 0
169
170 \image extending-tutorial-chapter2.png
171
172 To do this, we add a \c clearChart() method and a \c chartCleared() signal
173 to our C++ class:
174
175 \snippet declarative/tutorials/extending/chapter2-methods/piechart.h 0
176 \dots
177 \snippet declarative/tutorials/extending/chapter2-methods/piechart.h 1
178 \dots
179 \snippet declarative/tutorials/extending/chapter2-methods/piechart.h 2
180 \dots
181 \snippet declarative/tutorials/extending/chapter2-methods/piechart.h 3
182
183 The use of Q_INVOKABLE makes the \c clearChart() method available to the
184 Qt Meta-Object system, and in turn, to QML. Note that it could have
185 been declared as as a Qt slot instead of using Q_INVOKABLE, as
186 slots are also callable from QML. Both of these approaches are valid.
187
188 The \c clearChart() method simply changes the color to Qt::transparent,
189 repaints the chart, then emits the \c chartCleared() signal:
190
191 \snippet declarative/tutorials/extending/chapter2-methods/piechart.cpp 0
192
193 Now when we run the application and click the window, the pie chart
194 disappears, and the application outputs:
195
196 \code
197     The chart has been cleared
198 \endcode
199
200 Try out the example yourself with the updated code in Qt's \c examples/tutorials/extending/chapter2-methods directory.
201
202 */
203
204 /*!
205 \title Chapter 3: Adding Property Bindings
206
207 \example declarative/tutorials/extending/chapter3-bindings
208
209 Property bindings is a powerful feature of QML that allows values of different
210 elements to be synchronized automatically. It uses signals to notify and update
211 other elements' values when property values are changed.
212
213 Let's enable property bindings for the \c color property. That means
214 if we have code like this:
215
216 \snippet declarative/tutorials/extending/chapter3-bindings/app.qml 0
217
218 \image extending-tutorial-chapter3.png
219
220 The "color: chartA.color" statement binds the \c color value of
221 \c chartB to the \c color of \c chartA.
222 Whenever \c chartA's \c color value changes, \c chartB's \c color value
223 updates to the same value. When the window is clicked, the \c onClicked
224 handler in the MouseArea changes the color of \c chartA, thereby changing
225 both charts to the color blue.
226
227 It's easy to enable property binding for the \c color property.
228 We add a \l{Qt's Property System}{NOTIFY} feature to its Q_PROPERTY() declaration to indicate that a "colorChanged" signal
229 is emitted whenever the value changes.
230
231 \snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 0
232 \dots
233 \snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 1
234 \dots
235 \snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 2
236 \dots
237 \snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 3
238
239 Then, we emit this signal in \c setPieSlice():
240
241 \snippet declarative/tutorials/extending/chapter3-bindings/piechart.cpp 0
242
243 It's important for \c setColor() to check that the color value has actually changed
244 before emitting \c colorChanged(). This ensures the signal is not emitted unnecessarily and
245 also prevents loops when other elements respond to the value change.
246
247 The use of bindings is essential to QML. You should always add NOTIFY
248 signals for properties if they are able to be implemented, so that your
249 properties can be used in bindings. Properties that cannot be bound cannot be
250 automatically updated and cannot be used as flexibly in QML. Also, since
251 bindings are invoked so often and relied upon in QML usage, users of your
252 custom QML types may see unexpected behavior if bindings are not implemented.
253
254 */
255
256 /*!
257 \title Chapter 4: Using Custom Property Types
258
259 \example declarative/tutorials/extending/chapter4-customPropertyTypes
260
261 The \c PieChart type currently has a string-type property and a color-type property.
262 It could have many other types of properties. For example, it could have an
263 int-type property to store an identifier for each chart:
264
265 \code
266     // C++
267     class PieChart : public QDeclarativeItem
268     {
269         Q_PROPERTY(int chartId READ chartId WRITE setChartId NOTIFY chartIdChanged)
270         ...
271
272     public:
273         void setChartId(int chartId);
274         int chartId() const;
275         ...
276
277     signals:
278         void chartIdChanged();
279     };
280
281     // QML
282     PieChart {
283         ...
284         chartId: 100
285     }
286 \endcode
287
288 We can also use various other property types. QML has built-in support for the types
289 listed in the \l{QML Basic Types} documentation, which includes the following:
290
291 \list
292 \o bool, unsigned int, int, float, double, qreal
293 \o QString, QUrl, QColor
294 \o QDate, QTime, QDateTime
295 \o QPoint, QPointF, QSize, QSizeF, QRect, QRectF
296 \o QVariant
297 \endlist
298
299 If we want to create a property whose type is not supported by QML by default,
300 we need to register the type with QML.
301
302 For example, let's replace the use of the \c property with a type called
303 "PieSlice" that has a \c color property. Instead of assigning a color,
304 we assign an \c PieSlice value which itself contains a \c color:
305
306 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/app.qml 0
307
308 Like \c PieChart, this new \c PieSlice type inherits from QDeclarativeItem and declares
309 its properties with Q_PROPERTY():
310
311 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/pieslice.h 0
312
313 To use it in \c PieChart, we modify the \c color property declaration
314 and associated method signatures:
315
316 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 0
317 \dots
318 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 1
319 \dots
320 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 2
321 \dots
322 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 3
323
324 There is one thing to be aware of when implementing \c setPieSlice(). The \c PieSlice
325 is a visual item, so it must be set as a child of the \c PieChart using
326 QDeclarativeItem::setParentItem() so that the \c PieChart knows to paint this child
327 item when its contents are drawn:
328
329 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.cpp 0
330
331
332 Like the \c PieChart type, the \c PieSlice type has to be registered
333 using qmlRegisterType() to be used from QML. As with \c PieChart, we'll add the
334 type to the "Charts" module, version 1.0:
335
336 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/main.cpp 0
337 \dots
338 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/main.cpp 1
339 \dots
340 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/main.cpp 2
341
342 Try it out with the code in Qt's \c examples/tutorials/extending/chapter4-customPropertyTypes directory.
343
344 */
345
346
347 /*!
348 \title Chapter 5: Using List Property Types
349
350 \example declarative/tutorials/extending/chapter5-listproperties
351
352 Right now, a \c PieChart can only have one \c PieSlice. Ideally a chart would
353 have multiple slices, with different colors and sizes. To do this, we could
354 have a \c slices property that accepts a list of \c PieSlice items:
355
356 \snippet declarative/tutorials/extending/chapter5-listproperties/app.qml 0
357
358 \image extending-tutorial-chapter5.png
359
360 To do this, we replace the \c pieSlice property in \c PieChart with a \c slices property,
361 declared as a QDeclarativeListProperty type. The QDeclarativeListProperty class enables the
362 creation of list properties in QML extensions. We replace the \c pieSlice()
363 function with a \c slices() function that returns a list of slices, and add
364 an internal \c append_slice() function (discussed below). We also use a QList to
365 store the internal list of slices as \c m_slices:
366
367 \snippet declarative/tutorials/extending/chapter5-listproperties/piechart.h 0
368 \dots
369 \snippet declarative/tutorials/extending/chapter5-listproperties/piechart.h 1
370 \dots
371 \snippet declarative/tutorials/extending/chapter5-listproperties/piechart.h 2
372
373 Although the \c slices property does not have an associated \c WRITE function,
374 it is still modifiable because of the way QDeclarativeListProperty works.
375 In the \c PieChart implementation, we implement \c PieChart::slices() to
376 return a QDeclarativeListProperty value and indicate that the internal
377 \c PieChart::append_slice() function is to be called whenever a request is made from QML
378 to add items to the list:
379
380 \snippet declarative/tutorials/extending/chapter5-listproperties/piechart.cpp 0
381
382 The \c append_slice() function simply sets the parent item as before,
383 and adds the new item to the \c m_slices list. As you can see, the append function for a
384 QDeclarativeListProperty is called with two arguments: the list property, and
385 the item that is to be appended.
386
387 The \c PieSlice class has also been modified to include \c fromAngle and \c angleSpan
388 properties and to draw the slice according to these values. This is a straightforward
389 modification if you have read the previous pages in this tutorial, so the code is not shown here.
390
391 The complete code can be seen in the updated \c examples/tutorials/extending/chapter5-listproperties directory.
392
393 */
394
395
396 /*!
397 \title Chapter 6: Writing an Extension Plugin
398
399 \example declarative/tutorials/extending/chapter6-plugins
400
401 Currently the \c PieChart and \c PieSlice types are used by \c app.qml,
402 which is displayed using a QDeclarativeView in a C++ application. An alternative
403 way to use our QML extension is to create a plugin library to make it available
404 to the QML engine. This allows \c app.qml to be loaded with the \l {QML Viewer}
405 (or some other QML \l{Qt Declarative UI Runtime}{runtime} application) instead of writing a \c main.cpp file and
406 loading our own C++ application.
407
408 To create a plugin library, we need:
409
410 \list
411 \o A plugin class that registers our QML types
412 \o A project file that describes the plugin
413 \o A \l{Writing a qmldir file}{qmldir} file that tells the QML engine to load the plugin
414 \endlist
415
416 First, we create a plugin class named \c ChartsPlugin. It subclasses QDeclarativeExtensionPlugin
417 and registers our QML types in the inherited \l{QDeclarativeExtensionPlugin::}{registerTypes()} method. It also calls
418 Q_EXPORT_PLUGIN2 for Qt's \l{How to Create Qt Plugins}{plugin system}.
419
420 Here is the \c ChartsPlugin definition in \c chartsplugin.h:
421
422 \snippet declarative/tutorials/extending/chapter6-plugins/chartsplugin.h 0
423
424 And its implementation in \c chartsplugin.cpp:
425
426 \snippet declarative/tutorials/extending/chapter6-plugins/chartsplugin.cpp 0
427
428 Then, we write a \c .pro project file that defines the project as a plugin library
429 and specifies with DESTDIR that library files should be built into a "lib" subdirectory:
430
431 \quotefile declarative/tutorials/extending/chapter6-plugins/chapter6-plugins.pro
432
433 Finally, we add a \l{Writing a qmldir file}{qmldir} file that is automatically parsed by the QML engine.
434 In this file, we specify that a plugin named "chapter6-plugin" (the name
435 of the example project) can be found in the "lib" subdirectory:
436
437 \quotefile declarative/tutorials/extending/chapter6-plugins/qmldir
438
439 Now we have a plugin, and instead of having a main.cpp and an executable, we can build
440 the project and then load the QML file in the \l {QML Viewer}:
441
442 \code
443     qmlviewer app.qml
444 \endcode
445
446 (On Mac OS X, you can launch the "QMLViewer" application instead.)
447
448 Notice the "import Charts 1.0" statement has disappeared from \c app.qml. This is
449 because the \c qmldir file is in the same directory as \c app.qml: this is equivalent to
450 having PieChart.qml and PieSlice.qml files inside the project directory, which could both
451 be used by \c app.qml without import statements.
452 */
453
454
455 /*!
456 \page qml-extending-tutorial7.html
457 \title Chapter 7: In Summary
458
459 In this tutorial, we've shown the basic steps for creating a QML extension:
460
461 \list
462 \o Define new QML types by subclassing QObject and registering them with qmlRegisterType()
463 \o Add callable methods using Q_INVOKABLE or Qt slots, and connect to Qt signals with an \c onSignal syntax
464 \o Add property bindings by defining \l{Qt's Property System}{NOTIFY} signals
465 \o Define custom property types if the built-in types are not sufficient
466 \o Define list property types using QDeclarativeListProperty
467 \o Create a plugin library by defining a Qt plugin and writing a \c qmldir file
468 \endlist
469
470
471 The \l {Extending QML Functionalities using C++} reference documentation shows
472 other useful features that can be added to QML extensions. For example, we
473 could use \l{Default Property}{default properties} to allow
474 slices to be added without using the \c slices property:
475
476 \code
477     PieChart {
478         PieSlice { ... }
479         PieSlice { ... }
480         PieSlice { ... }
481     }
482 \endcode
483
484 Or randomly add and remove slices from time to time using \l{Property Value Sources}{property value sources}:
485
486 \code
487     PieChart {
488         PieSliceRandomizer on slices {}
489     }
490 \endcode
491
492
493 See the \l{Extending QML Functionalities using C++} reference documentation
494 for more information.
495
496 */
497