1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
10 ** GNU Free Documentation License
11 ** Alternatively, this file may be used under the terms of the GNU Free
12 ** Documentation License version 1.3 as published by the Free Software
13 ** Foundation and appearing in the file included in the packaging of
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \page qml-extending-tutorial-index.html
30 \title Tutorial: Writing QML Extensions with C++
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.
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.
40 You can find the source code for this tutorial in \c Qt's
41 examples/declarative/tutorials/extending directory.
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}
58 \title Chapter 1: Creating a New Type
60 \example declarative/tutorials/extending/chapter1-basics
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.
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.
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.
77 We want this \c PieChart type to be usable from QML like this:
83 width: 100; height: 100
84 name: "A simple pie chart"
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},
94 \o Inherit from QObject
95 \o Declare its properties using the Q_PROPERTY macro
98 Here is our \c PieChart class, defined in \c piechart.h:
100 \snippet declarative/tutorials/extending/chapter1-basics/piechart.h 0
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.
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:
114 \snippet declarative/tutorials/extending/chapter1-basics/piechart.cpp 0
116 \snippet declarative/tutorials/extending/chapter1-basics/piechart.cpp 1
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:
122 \snippet declarative/tutorials/extending/chapter1-basics/app.qml 0
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.
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.
134 Here is the application \c main.cpp:
136 \snippet declarative/tutorials/extending/chapter1-basics/main.cpp 0
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.
141 Lastly, we write a \c .pro project file that includes the files and the \c declarative library:
143 \quotefile declarative/tutorials/extending/chapter1-basics/chapter1-basics.pro
145 Now we can build and run the application:
147 \image extending-tutorial-chapter1.png
149 Try it yourself with the code in Qt's \c examples/tutorials/extending/chapter1-basics directory.
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.
160 \title Chapter 2: Connecting to C++ Methods and Signals
162 \example declarative/tutorials/extending/chapter2-methods
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:
168 \snippet declarative/tutorials/extending/chapter2-methods/app.qml 0
170 \image extending-tutorial-chapter2.png
172 To do this, we add a \c clearChart() method and a \c chartCleared() signal
175 \snippet declarative/tutorials/extending/chapter2-methods/piechart.h 0
177 \snippet declarative/tutorials/extending/chapter2-methods/piechart.h 1
179 \snippet declarative/tutorials/extending/chapter2-methods/piechart.h 2
181 \snippet declarative/tutorials/extending/chapter2-methods/piechart.h 3
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.
188 The \c clearChart() method simply changes the color to Qt::transparent,
189 repaints the chart, then emits the \c chartCleared() signal:
191 \snippet declarative/tutorials/extending/chapter2-methods/piechart.cpp 0
193 Now when we run the application and click the window, the pie chart
194 disappears, and the application outputs:
197 The chart has been cleared
200 Try out the example yourself with the updated code in Qt's \c examples/tutorials/extending/chapter2-methods directory.
205 \title Chapter 3: Adding Property Bindings
207 \example declarative/tutorials/extending/chapter3-bindings
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.
213 Let's enable property bindings for the \c color property. That means
214 if we have code like this:
216 \snippet declarative/tutorials/extending/chapter3-bindings/app.qml 0
218 \image extending-tutorial-chapter3.png
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.
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.
231 \snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 0
233 \snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 1
235 \snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 2
237 \snippet declarative/tutorials/extending/chapter3-bindings/piechart.h 3
239 Then, we emit this signal in \c setPieSlice():
241 \snippet declarative/tutorials/extending/chapter3-bindings/piechart.cpp 0
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.
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.
257 \title Chapter 4: Using Custom Property Types
259 \example declarative/tutorials/extending/chapter4-customPropertyTypes
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:
267 class PieChart : public QDeclarativeItem
269 Q_PROPERTY(int chartId READ chartId WRITE setChartId NOTIFY chartIdChanged)
273 void setChartId(int chartId);
278 void chartIdChanged();
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:
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
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.
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:
306 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/app.qml 0
308 Like \c PieChart, this new \c PieSlice type inherits from QDeclarativeItem and declares
309 its properties with Q_PROPERTY():
311 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/pieslice.h 0
313 To use it in \c PieChart, we modify the \c color property declaration
314 and associated method signatures:
316 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 0
318 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 1
320 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 2
322 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.h 3
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:
329 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/piechart.cpp 0
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:
336 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/main.cpp 0
338 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/main.cpp 1
340 \snippet declarative/tutorials/extending/chapter4-customPropertyTypes/main.cpp 2
342 Try it out with the code in Qt's \c examples/tutorials/extending/chapter4-customPropertyTypes directory.
348 \title Chapter 5: Using List Property Types
350 \example declarative/tutorials/extending/chapter5-listproperties
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:
356 \snippet declarative/tutorials/extending/chapter5-listproperties/app.qml 0
358 \image extending-tutorial-chapter5.png
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:
367 \snippet declarative/tutorials/extending/chapter5-listproperties/piechart.h 0
369 \snippet declarative/tutorials/extending/chapter5-listproperties/piechart.h 1
371 \snippet declarative/tutorials/extending/chapter5-listproperties/piechart.h 2
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:
380 \snippet declarative/tutorials/extending/chapter5-listproperties/piechart.cpp 0
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.
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.
391 The complete code can be seen in the updated \c examples/tutorials/extending/chapter5-listproperties directory.
397 \title Chapter 6: Writing an Extension Plugin
399 \example declarative/tutorials/extending/chapter6-plugins
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.
408 To create a plugin library, we need:
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
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}.
420 Here is the \c ChartsPlugin definition in \c chartsplugin.h:
422 \snippet declarative/tutorials/extending/chapter6-plugins/chartsplugin.h 0
424 And its implementation in \c chartsplugin.cpp:
426 \snippet declarative/tutorials/extending/chapter6-plugins/chartsplugin.cpp 0
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:
431 \quotefile declarative/tutorials/extending/chapter6-plugins/chapter6-plugins.pro
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:
437 \quotefile declarative/tutorials/extending/chapter6-plugins/qmldir
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}:
446 (On Mac OS X, you can launch the "QMLViewer" application instead.)
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.
456 \page qml-extending-tutorial7.html
457 \title Chapter 7: In Summary
459 In this tutorial, we've shown the basic steps for creating a QML extension:
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
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:
484 Or randomly add and remove slices from time to time using \l{Property Value Sources}{property value sources}:
488 PieSliceRandomizer on slices {}
493 See the \l{Extending QML Functionalities using C++} reference documentation
494 for more information.