1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** GNU Free Documentation License
10 ** Alternatively, this file may be used under the terms of the GNU Free
11 ** Documentation License version 1.3 as published by the Free Software
12 ** Foundation and appearing in the file included in the packaging of
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
28 \page qtqml-cppintegration-functions.html
29 \title Exposing C++ Functionality to QML
30 \brief Description of how to expose functionality defined in C++ to QML
33 // XXX TODO The content of "Exposing C++ Functionality To QML" and
34 // "Exposing Data From C++ To QML" should probably be grouped together
35 // on the same page, or separated in a more distinct way.
39 \section1 Properties of Types Defined in C++
41 Any \l {The Property System}{Qt properties} - that is, those declared with the Q_PROPERTY()
42 macro - are accessible from QML. Here is a modified version of the \l {Embedding C++ objects into
43 QML components}{earlier example} on this page; here, the \c ApplicationData class has a \c backgroundColor
44 property. This property can be written to and read from QML:
48 \li \snippet qml/qtbinding/properties-cpp/applicationdata.h 0
49 \li \snippet qml/qtbinding/properties-cpp/MyItem.qml 0
52 Notice the \c backgroundColorChanged signal is declared as the NOTIFY signal for the
53 \c backgroundColor property. If a Qt property does not have an associated NOTIFY signal,
54 the property cannot be used for \l{Property Binding}, as the QML engine would not be
55 notified when the value changes. If you are using custom types in QML, make sure their
56 properties have NOTIFY signals so that they can be used in property bindings.
58 \section1 Signals and Slots
60 QML integrates with the normal Qt C++ signals and slots system.
61 Signal handlers may be defined in a QML object, to handle signals
62 emitted by that or other objects. Signals may also be defined
63 and emitted from QML, which can be connected to slots in C++.
65 \section1 Method Invocation
67 Methods of C++ types exposed to QML may be invoked so long as they
68 are flagged with Q_INVOKABLE. As noted above, if the function
69 returns a pointer to a QObject or a QObject-derived type, some care
70 must be taken to avoid unwanted ownership changes occurring.
75 \section2 Property Signals
77 All properties on custom types automatically support property binding.
78 However, for binding to work correctly, QML must be able to reliably
79 determine when a property has changed so that it knows to reevaluate any
80 bindings that depend on the property's value. QML relies on the presence of
81 a \l {Qt's Property System}{NOTIFY signal} for this determination.
83 Here is the \c host property declaration:
85 \snippet examples/qml/cppextensions/referenceexamples/binding/birthdayparty.h 0
87 The NOTIFY attribute is followed by a signal name. It is the responsibility
88 of the class implementer to ensure that whenever the property's value
89 changes, the NOTIFY signal is emitted. The signature of the NOTIFY signal is
92 To prevent loops or excessive evaluation, developers should ensure that the
93 signal is only emitted whenever the property's value is actually changed. If
94 a property, or group of properties, is infrequently used it is permitted to
95 use the same NOTIFY signal for several properties. This should be done with
96 care to ensure that performance doesn't suffer.
98 To keep QML reliable, if a property does not have a NOTIFY signal, it cannot
99 be used in a binding expression. However, the property can still be assigned
100 a binding as QML does not need to monitor the property for change in that
103 Consider a custom type, \c TestElement, that has two properties, \c a and
104 \c b. Property \c a does \e not have a NOTIFY signal, and property \c b does
105 have a NOTIFY signal.
118 The presence of a NOTIFY signal does incur a small overhead. There are cases
119 where a property's value is set at object construction time, and does not
120 subsequently change. The most common case of this is when a type uses \l
121 {Grouped Properties}, and the grouped property object is allocated once, and
122 only freed when the object is deleted. In these cases, the CONSTANT
123 attribute may be added to the property declaration instead of a NOTIFY
126 \snippet examples/qml/cppextensions/referenceexamples/binding/person.h 0
128 Extreme care must be taken here or applications using your type may misbehave.
129 The CONSTANT attribute should only be used for properties whose value is set,
130 and finalized, only in the class constructor. All other properties that want
131 to be used in bindings should have a NOTIFY signal instead.
133 \l {Extending QML - Binding Example} shows the BirthdayParty example updated to
134 include NOTIFY signals for use in binding.
136 \section1 Signals Support
138 A \l{signals and slots}{signal} in Qt C++ is readily available as a
139 \l{Signal and Handler Event System}{QML signal}. A signal will have
140 a corresponding signal \e{handler}, created automatically. The handler
141 name will have \c on prepended at the beginning of the name. The first
142 character of the signal is uppercased for the signal handler. The
143 signal parameter is also availabe to the QML signal.
145 \snippet examples/qml/cppextensions/referenceexamples/signal/birthdayparty.h 0
146 The QML engine will create a handler for the \c partyStarted signal
147 called \c onPartyStarted.
148 \snippet examples/qml/cppextensions/referenceexamples/signal/example.qml 0
150 Classes may have multiple signals with the same name, but only the final
151 signal is accessible as a QML signal. Note that signals with the same name
152 but different parameters cannot be distinguished from one another.
154 Signal parameters are exposed and can be any one of the QML
155 \l{QML Basic Types}{basic types} as well registered object types. Accessing
156 unregistered types will not generate an error, but the parameter value will
157 not be accessible from the handler.
159 To use signals from items not created in QML, access their signals with the
160 \l {Connections} element.
162 Additionally, if a property is added to a C++ class, all QML elements
163 based on that C++ class will have a \e{value-changed} signal handler
164 for that property. The name of the signal handler is
165 \e{on<Property-name>Changed}, with the first letter of the property
166 name being upper case.
168 The \l {Extending QML - Signal Support Example}{Signal Support Example}
169 shows an example application exposing signals to a QML component.
171 \section1 Exposing Methods
173 The Q_INVOKABLE macro exposes any Qt C++ method as a QML method.
175 \snippet examples/qml/cppextensions/referenceexamples/methods/birthdayparty.h 0
177 In a QML file, we can invoke the method as we would a
178 \l{JavaScript Expressions in QML}{JavaScript expression}.
179 \snippet examples/qml/cppextensions/referenceexamples/methods/example.qml 0
181 \l {Extending QML - Methods Example}{Methods example} uses the Q_INVOKABLE
182 method to expose methods and demonstrates some usages of the method in
185 An alternative to the Q_INVOKABLE macro is to declare the C++ method as a
186 \l{signals and slot}{slot}.
190 void invite(const QString &name);
196 \section1 Module API Functionality
198 One of the simplest ways to expose C++ functionality to clients in
199 QML is by registering a QObject module API. This allows functionality
200 and data to be exposed in a namespace which is accessible from QML.
201 See the documentation about
202 \l{Defining QML Object Types from C++#Module-API-Type-Registration}
203 {Module API type registration} for information about module APIs,
204 and see the \l{qmlRegisterModuleApi()} documentation for details on how to
205 register and use a module API.
207 A module API is instantiated and owned by the engine as a singleton.
208 Thus, it is more performant to implement common functionality in a module
209 API than in an instantiable, non-visual element.