path: root/src/qml/doc/src/cppintegration/topic.qdoc

/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtqml-cppintegration-topic.html
\title Integrating QML and C++
\brief Provides instruction to integrate QML and C++

QML applications often need to handle more advanced and performance-intensive
tasks in C++. The most common and quickest way to do this is to expose the C++
class to the QML runtime, provided the C++ implementation is derived from
QObject. Assuming that you have Qt 5.7 or later installed, the following
step-by-step instructions guide you through the process of using the C++ class,
BackEnd, in a QML application:

\list 1

\li Create a new project using the "Qt Quick Application" template in Qt Creator

\note Uncheck the \uicontrol {With ui.qml file} option in the
\uicontrol {Define Project Details} section of \uicontrol {New Project Wizard}.

\li Add a new C++ class called \c BackEnd to the project and replace its header
file contents with:

\snippet code/backend/backend.h backend_header

The \c Q_PROPERTY macro declares a property that could be accessed from QML.
The \c QML_ELEMENT macro makes the BackEnd class available in QML.

\li Add the following lines to your project file:

\snippet code/backend/backend.pro registration

The BackEnd class is automatically registered as a type, which is accessible
from QML by importing the URL, "\c{io.qt.examples.backend 1.0}".

\li Replace the contents of \c{backend.cpp} with:

\snippet code/backend/backend.cpp backend_cpp

The \c setUserName function emits the \c userNameChanged signal every time
\c m_userName value changes. The signal can be handled from QML using the
\c onUserNameChanged handler.

\li Replace the contents of \c main.qml with the following code:

\snippet code/backend/main.qml main_qml

The \c BackEnd instance lets you access the \c userName property, which
is updated when the TextField's \c text property changes.

\endlist

Now the application can be run.

\borderedimage cppintegration-ex.png
\caption Application running on Ubuntu

Qt offers several methods to integrate C++ with QML, and the method discussed
in this tutorial is just one of them. For more details about these methods,
refer to \l{Overview - QML and C++ Integration}.
*/

/*!
\page qtqml-cppintegration-overview.html
\title Overview - QML and C++ Integration
\brief Highlights important points about integrating C++ with QML.

QML is designed to be easily extensible through C++ code. The classes in the \l {Qt QML} module
enable QML objects to be loaded and manipulated from C++, and the nature of QML engine's
integration with Qt's \l{Meta Object System}{meta object system} enables C++ functionality to be
invoked directly from QML. This allows the development of hybrid applications which are implemented
with a mixture of QML, JavaScript and C++ code.

Integrating QML and C++ provides a variety of opportunities, including the ability to:

\list
\li Separate the user interface code from the application logic code, by implementing the former
with QML and JavaScript within \l{qtqml-documents-topic.html}{QML documents}, and the latter with
C++
\li Use and invoke some C++ functionality from QML (for example, to invoke your application logic,
use a data model implemented in C++, or call some functions in a third-party C++ library)
\li Access functionality in the \l {Qt QML} or \l {Qt Quick} C++ API (for example, to dynamically generate
images using QQuickImageProvider)
\li Implement your own \l{qtqml-typesystem-objecttypes.html}{QML object types} from C++
\unicode{0x2014} whether for use within your own specific application, or for distribution to others
\endlist

To provide some C++ data or functionality to QML, it must be made available from a QObject-derived
class. Due to the QML engine's integration with the meta object system, the properties, methods and
signals of any QObject-derived class are accessible from QML, as described in
\l{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ Types to QML}. Once the
required functionality is provided by such a class, it can be exposed to QML in a variety of ways:

\list
\li The class can be
\l{qtqml-cppintegration-definetypes.html#registering-an-instantiable-object-type}{
registered as an instantiable QML type}, so that it can be instantiated and used like any ordinary
\l{qtqml-typesystem-objecttypes.html}{QML object type} from QML code
\li The class can be registered as a
\l{qtqml-cppintegration-definetypes.html#registering-singleton-objects-with-a-singleton-type}
{Singleton Type} so that a single instance of the class may be imported from QML code, allowing the
instance's properties, methods and signals to be accessed from QML
\li An instance of the class can be \l{qtqml-cppintegration-contextproperties.html}{embedded into
QML code} as a \e {context property} or \e {context object}, allowing the instance's properties,
methods and signals to be accessed from QML
\endlist

These are the most common methods of accessing C++ functionality from QML code; for more options and
details, see the main documentation pages that are described in the sections further below.
Additionally, aside from the ability to access C++ functionality from QML, the \l {Qt QML} module also
provides ways to do the reverse and manipulate QML objects from C++ code. See
\l{qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++} for more
details.

Finally, the C++ code may be integrated into either a C++ application or a C++ plugin depending on
whether it is to be distributed as a standalone application or a library. A plugin can be integrated
with a QML module that can then be imported and used by QML code in other applications; see
\l{qtqml-modules-cppplugins.html}{Providing Types and Functionality in a C++ Plugin} for more
information.

\section1 Choosing the Correct Integration Method Between C++ and QML

To quickly determine which integration method is appropriate for your situation, the following
flowchart can be used:

\image cpp-qml-integration-flowchart

For a description of the macros in the flowchart, see the
\l {qtqml-cppintegration-definetypes.html}{Defining QML Types from C++} documentation.

\section1 Exposing Attributes of C++ Classes to QML

QML can easily be extended from C++ due to the QML engine's integration with the Qt meta object
system. This integration allows the properties, methods and signals of any QObject-derived class to
be accessible from QML: properties can be read and modified, methods can be invoked from JavaScript
expressions and signal handlers are automatically created for signals as necessary. Additionally,
enumeration values of a QObject-derived class are accessible from QML.

See \l{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ Types to QML} for
more information.


\section1 Defining QML Types from C++

QML types can be defined in C++ and then registered with the \l{qtqml-typesystem-topic.html}{QML
type system}. This allows a C++ class to be instantiated as a \l {QML Object Types}{QML object type}, enabling custom
object types to be implemented in C++ and integrated into existing QML code. A C++ class may be also
registered for other purposes: for example, it could be registered as a \e {Singleton Type} to enable a
single class instance to be imported by QML code, or it could be registered to enable the
enumeration values of a non-instantiable class to be accessible from QML.

Additionally, the \l {Qt QML} module provides mechanisms to define QML types that integrate with QML
concepts like attached properties and default properties.

For more information on registering and creating custom QML types from C++, see the \l
{qtqml-cppintegration-definetypes.html}{Defining QML Types from C++} documentation.


\section1 Embedding C++ Objects into QML with Context Properties

C++ objects and values can be embedded directly into the context (or \e scope) of loaded QML objects
using \e {context properties} and \e {context objects}. This is achieved through the QQmlContext
class provided by the \l {Qt QML} module, which exposes data to the context of a QML component, allowing
data to be injected from C++ into QML.

See \l{qtqml-cppintegration-contextproperties.html}{Embedding C++ Objects into QML with Context
Properties} for more information.


\section1 Interacting with QML Objects from C++

QML object types can be instantiated from C++ and inspected in order to access their properties,
invoke their methods and receive their signal notifications. This is possible due to the fact that
all QML object types are implemented using QObject-derived classes, enabling the QML engine to
dynamically load and introspect objects through the Qt meta object system.

\include warning.qdocinc

For more information on accessing QML objects from C++, see the documentation on
\l{qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++}.


\section1 Data Type Conversion Between QML and C++

When data values are exchanged between QML and C++, they are converted by the QML engine to have the
correct data types as appropriate for use from QML or C++, providing the data types involved are
known to the engine.

See \l{qtqml-cppintegration-data.html}{Data Type Conversion Between QML and C++} for information on
the built-in types supported by the engine and how these types are converted for use when exchanged
between QML and C++.

*/