src/qml/doc/src/cppintegration/functions.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   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
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27 /*!
  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
  31
  32
  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.
  36
  37
  38
  39 \section1 Properties of Types Defined in C++
  40
  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:
  45
  46 \table
  47 \row
  48 \li \snippet qml/qtbinding/properties-cpp/applicationdata.h 0
  49 \li \snippet qml/qtbinding/properties-cpp/MyItem.qml 0
  50 \endtable
  51
  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.
  57
  58 \section1 Signals and Slots
  59
  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++.
  64
  65 \section1 Method Invocation
  66
  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.
  71
  72
  73
  74
  75 \section2 Property Signals
  76
  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.
  82
  83     Here is the \c host property declaration:
  84
  85     \snippet examples/qml/cppextensions/referenceexamples/binding/birthdayparty.h 0
  86
  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
  90     not important to QML.
  91
  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.
  97
  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
 101     scenario.
 102
 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.
 106
 107     \code
 108     TestElement {
 109         // This is OK
 110         a: b
 111     }
 112     TestElement {
 113         // Will NOT work
 114         b: a
 115     }
 116     \endcode
 117
 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
 124     signal.
 125
 126     \snippet examples/qml/cppextensions/referenceexamples/binding/person.h 0
 127
 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.
 132
 133     \l {Extending QML -  Binding Example} shows the BirthdayParty example updated to
 134     include NOTIFY signals for use in binding.
 135
 136 \section1 Signals Support
 137
 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.
 144
 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
 149
 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.
 153
 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.
 158
 159     To use signals from items not created in QML, access their signals with the
 160     \l {Connections} element.
 161
 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.
 167
 168     The \l {Extending QML - Signal Support Example}{Signal Support Example}
 169     shows an example application exposing signals to a QML component.
 170
 171 \section1 Exposing Methods
 172
 173     The Q_INVOKABLE macro exposes any Qt C++ method as a QML method.
 174
 175     \snippet examples/qml/cppextensions/referenceexamples/methods/birthdayparty.h 0
 176
 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
 180
 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
 183     an application.
 184
 185     An alternative to the Q_INVOKABLE macro is to declare the C++ method as a
 186     \l{signals and slot}{slot}.
 187
 188     \code
 189     slots:
 190         void invite(const QString &name);
 191     \endcode
 192
 193
 194
 195
 196 \section1 Module API Functionality
 197
 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.
 206
 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.
 210
 211 */