From 4ea6d985fa76786a965443f814f3f9b59620e056 Mon Sep 17 00:00:00 2001 From: Venugopal Shivashankar Date: Tue, 7 Feb 2017 15:25:08 +0100 Subject: Doc: Simplify documentation about integrating QML and C++ Change-Id: If110d02aad991646054ee6e522549c07f00946e1 Reviewed-by: Mitch Curtis --- src/qml/doc/images/cppintegration-ex.png | Bin 0 -> 1777 bytes src/qml/doc/snippets/code/backend/backend.cpp | 70 +++++++++++++++++++++++ src/qml/doc/snippets/code/backend/backend.h | 75 ++++++++++++++++++++++++ src/qml/doc/snippets/code/backend/main.cpp | 66 +++++++++++++++++++++ src/qml/doc/snippets/code/backend/main.qml | 79 ++++++++++++++++++++++++++ src/qml/doc/src/cppintegration/topic.qdoc | 63 +++++++++++++++++++- 6 files changed, 352 insertions(+), 1 deletion(-) create mode 100644 src/qml/doc/images/cppintegration-ex.png create mode 100644 src/qml/doc/snippets/code/backend/backend.cpp create mode 100644 src/qml/doc/snippets/code/backend/backend.h create mode 100644 src/qml/doc/snippets/code/backend/main.cpp create mode 100644 src/qml/doc/snippets/code/backend/main.qml (limited to 'src/qml/doc') diff --git a/src/qml/doc/images/cppintegration-ex.png b/src/qml/doc/images/cppintegration-ex.png new file mode 100644 index 0000000000..0b476ccb93 Binary files /dev/null and b/src/qml/doc/images/cppintegration-ex.png differ diff --git a/src/qml/doc/snippets/code/backend/backend.cpp b/src/qml/doc/snippets/code/backend/backend.cpp new file mode 100644 index 0000000000..4a7ee89cec --- /dev/null +++ b/src/qml/doc/snippets/code/backend/backend.cpp @@ -0,0 +1,70 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the QtQml module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** 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. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "backend.h" + +BackEnd::BackEnd(QObject *parent) : + QObject(parent) +{ +} + +QString BackEnd::userName() +{ + return m_userName; +} + +void BackEnd::setUserName(const QString &userName) +{ + if (userName == m_userName) + return; + + m_userName = userName; + emit userNameChanged(); +} diff --git a/src/qml/doc/snippets/code/backend/backend.h b/src/qml/doc/snippets/code/backend/backend.h new file mode 100644 index 0000000000..91bb766e1f --- /dev/null +++ b/src/qml/doc/snippets/code/backend/backend.h @@ -0,0 +1,75 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the QtQml module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** 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. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef BACKEND_H +#define BACKEND_H + +#include +#include + +class BackEnd : public QObject +{ + Q_OBJECT + Q_PROPERTY(QString userName READ userName WRITE setUserName NOTIFY userNameChanged) + +public: + explicit BackEnd(QObject *parent = nullptr); + + QString userName(); + void setUserName(const QString &userName); + +signals: + void userNameChanged(); + +private: + QString m_userName; +}; + +#endif // BACKEND_H diff --git a/src/qml/doc/snippets/code/backend/main.cpp b/src/qml/doc/snippets/code/backend/main.cpp new file mode 100644 index 0000000000..d7a1bcbd4f --- /dev/null +++ b/src/qml/doc/snippets/code/backend/main.cpp @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the QtQml module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** 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. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include +#include + +#include "backend.h" + +int main(int argc, char *argv[]) +{ + QGuiApplication app(argc, argv); + + qmlRegisterType("io.qt.examples.backend", 1, 0, "BackEnd"); + + QQmlApplicationEngine engine; + engine.load(QUrl(QStringLiteral("qrc:/main.qml"))); + + return app.exec(); +} diff --git a/src/qml/doc/snippets/code/backend/main.qml b/src/qml/doc/snippets/code/backend/main.qml new file mode 100644 index 0000000000..3720da8412 --- /dev/null +++ b/src/qml/doc/snippets/code/backend/main.qml @@ -0,0 +1,79 @@ +/**************************************************************************** +** +** Copyright (C) 2017 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the QtQml module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** 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. +** +** BSD License Usage +** Alternatively, you may use this file under the terms of the BSD license +** as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of The Qt Company Ltd nor the names of its +** contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +import QtQuick 2.6 +import QtQuick.Controls 2.0 +//![import] +import io.qt.examples.backend 1.0 +//![import] + +ApplicationWindow { + id: root + width: 300 + height: 480 + visible: true + +//![backend] + BackEnd { + id: backend + } +//![backend] + +//![username_input] + TextField { + text: backend.userName + placeholderText: qsTr("User name") + anchors.centerIn: parent + + onTextChanged: backend.userName = text + } +//![username_input] +} + diff --git a/src/qml/doc/src/cppintegration/topic.qdoc b/src/qml/doc/src/cppintegration/topic.qdoc index 1aa3bb6ab5..22115395b1 100644 --- a/src/qml/doc/src/cppintegration/topic.qdoc +++ b/src/qml/doc/src/cppintegration/topic.qdoc @@ -27,7 +27,68 @@ /*! \page qtqml-cppintegration-topic.html \title Integrating QML and C++ -\brief Description of how to integrate QML and C++ code +\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: + +\quotefile code/backend/backend.h + +The \c Q_PROPERTY macro declares a property that could be accessed from QML. + +\li Replace its C++ file contents with: + +\quotefile code/backend/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 Include \c "backend.h" in \c main.cpp and register the class as a QML type +under a import URL as shown below: + +\quotefile code/backend/main.cpp + +The BackEnd class is 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 main.qml with the following code: + +\quotefile code/backend/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 -- cgit v1.2.3