diff options
Diffstat (limited to 'src/qml/doc/src/cppintegration/topic.qdoc')
| -rw-r--r-- | src/qml/doc/src/cppintegration/topic.qdoc | 111 |
1 files changed, 15 insertions, 96 deletions
diff --git a/src/qml/doc/src/cppintegration/topic.qdoc b/src/qml/doc/src/cppintegration/topic.qdoc index 14a27c9a3f..b14c54a24e 100644 --- a/src/qml/doc/src/cppintegration/topic.qdoc +++ b/src/qml/doc/src/cppintegration/topic.qdoc @@ -1,99 +1,13 @@ -/**************************************************************************** -** -** 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: - -\badcode -CONFIG += qmltypes -QML_IMPORT_NAME = io.qt.examples.backend -QML_IMPORT_MAJOR_VERSION = 1 -\endcode -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}. -*/ +// Copyright (C) 2017 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtqml-cppintegration-overview.html \title Overview - QML and C++ Integration \brief Highlights important points about integrating C++ with QML. +\ingroup explanations-programminglanguages -QML is designed to be easily extensible through C++ code. The classes in the \l {Qt QML} module +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 @@ -107,7 +21,7 @@ with QML and JavaScript within \l{qtqml-documents-topic.html}{QML documents}, an 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 +\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 @@ -135,11 +49,15 @@ methods and signals to be accessed from QML 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 +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. +It is often desirable to expose some state as global properties to QML. +\l{qtqml-cppintegration-exposecppstate.html}{Exposing State from C++ to QML} +describes how to do this. + 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 @@ -151,7 +69,7 @@ information. To quickly determine which integration method is appropriate for your situation, the following flowchart can be used: -\image cpp-qml-integration-flowchart +\image cpp-qml-integration-flowchart.png For a description of the macros in the flowchart, see the \l {qtqml-cppintegration-definetypes.html}{Defining QML Types from C++} documentation. @@ -177,7 +95,7 @@ registered for other purposes: for example, it could be registered as a \e {Sing 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 +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 @@ -188,7 +106,7 @@ For more information on registering and creating custom QML types from C++, see 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 +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 @@ -205,7 +123,8 @@ 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++}. +\l{qtqml-cppintegration-interactqmlfromcpp.html}{Interacting with QML Objects from C++}, +and the \l {Exposing Data from C++ to QML} section of the Best Practices page. \section1 Data Type Conversion Between QML and C++ |