src/qml/doc/src/cppintegration/topic.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-topic.html
  29 \title Integrating QML and C++
  30 \brief Description of how to integrate QML and C++ code
  31
  32 QML was designed to allow tight integration with C++ code.  This allows hybrid
  33 applications to be developed where the user-interface (and perhaps some small
  34 amount of application logic) is specified in QML documents with QML and
  35 JavaScript, but the bulk of the application logic is implemented in C++.
  36
  37 Applications with a C++ entry-point can instantiate a QQmlEngine directly,
  38 can use the QML type registration functions, and access the properties of the
  39 root QQmlContext directly.  Applications which utilize a QML entry point (that
  40 is, they are loaded via \l{qtquick-qmlscene.html}{qmlscene} or some other tool)
  41 can provide \l{qtqml-modules-cppplugins.html}{C++ plugins} which can register
  42 types and provide functionality.
  43
  44 You may want to mix QML and C++ for a number of reasons. For example:
  45
  46 \list
  47 \li To use functionality defined in a C++ source (for example, when using a C++ Qt-based data model, or
  48 calling functions in a third-party C++ library)
  49 \li To access functionality in the QtQml or QtQuick modules (for example, to dynamically generate
  50 images using QQuickImageProvider)
  51 \li To write your own QML object types (whether for your applications, or for distribution to others)
  52 \endlist
  53
  54 There are a number of ways to extend your QML application through C++. For example, you could:
  55
  56 \list
  57 \li Load a QML component and manipulate it (or its children) from C++
  58 \li Embed a C++ object and its properties directly into a QML component (for example, to make a
  59 particular C++ object callable from QML, or to replace a dummy list model with a real data set)
  60 \li Define new QML object types (through QObject-based C++ classes) and create them directly from your
  61 QML code
  62 \endlist
  63
  64
  65 \section1 Exposing C++ Types to QML
  66
  67 QML types may be implemented in C++ and then exposed to the QML type system via
  68 plugins or type registration.  This is covered in more detail elsewhere in the
  69 documentation; see the documentation regarding
  70 \l{qtqml-cppintegration-registercpptypes.html}
  71 {Registering C++ Types with the QML Type System} for more information on that
  72 topic.
  73
  74 For more information on the specifics of how to define C++ types for use in QML
  75 (not merely how to expose types to the QML type system), see the documentation
  76 about defining \l{qtqml-modules-cppplugins.html#creating-a-plugin}
  77 {C++ types for use in QML}.
  78
  79 \section1 Exposing C++ Data to QML
  80
  81 Data from C++ may be exposed to QML via context properties, instance
  82 properties, or by returning data from Q_INVOKABLE methods.  For more
  83 information about each of these approaches, and the ownership semantics
  84 applicable to each, see the documentation on \l{qtqml-cppintegration-data.html}
  85 {Exposing C++ Data to QML}.
  86
  87 \section1 Exposing C++ Functions to QML
  88
  89 Functions from C++ may be exposed to QML via signals and slots, by tagging a
  90 function declaration with the Q_INVOKABLE macro, or by registering the C++ type
  91 as a module API and installing that module API into a particular namespace.
  92 For more information about these approaches, see the documentation on
  93 \l{qtqml-cppintegration-functions.html}{Exposing C++ Functionality to QML}.
  94
  95 \section1 Interacting with Objects Defined in QML from C++
  96
  97 Most properties of an object defined in QML may be accessed via
  98 QQmlProperty::read() or QObject::property().  If the property is a list
  99 property, QQmlListReference may be used instead.
 100
 101 All methods of an object defined in QML may be invoked using the
 102 QMetaObject::invokeMethod() function.  This includes dynamic methods and signal
 103 handlers.
 104
 105 For more information about accessing QML objects from C++, see the
 106 documentation on \l{qtqml-cppintegration-reverse.html}
 107 {Interacting with Objects Defined in QML from C++}.
 108
 109 */