From b84e46090b5230d7ebcdbdabd8c03a9ae5d2f860 Mon Sep 17 00:00:00 2001 From: Milian Wolff Date: Wed, 16 Jul 2014 17:39:31 +0200 Subject: Add documentation for the QtWebChannel module. Please proof-read it and tell me what needs to be improved. I assume most people will probably not use the QWebChannel directly. Rather, they will only consume its features indirectly through the integration in QtWebKit/QtWebEngine. Thus the documentation here is for QWebChannel as a library. User-end documentation should be added to QtWebKit, I think. Change-Id: I259c204e24331271b8dc74ea11695988234a79d3 Reviewed-by: Jerome Pasion --- src/webchannel/doc/qtwebchannel.qdocconf | 56 +++++++++++++++++ src/webchannel/doc/src/index.qdoc | 47 +++++++++++++++ src/webchannel/doc/src/javascript.qdoc | 100 +++++++++++++++++++++++++++++++ src/webchannel/doc/src/module.qdoc | 60 +++++++++++++++++++ 4 files changed, 263 insertions(+) create mode 100644 src/webchannel/doc/qtwebchannel.qdocconf create mode 100644 src/webchannel/doc/src/index.qdoc create mode 100644 src/webchannel/doc/src/javascript.qdoc create mode 100644 src/webchannel/doc/src/module.qdoc (limited to 'src/webchannel/doc') diff --git a/src/webchannel/doc/qtwebchannel.qdocconf b/src/webchannel/doc/qtwebchannel.qdocconf new file mode 100644 index 0000000..e2ed336 --- /dev/null +++ b/src/webchannel/doc/qtwebchannel.qdocconf @@ -0,0 +1,56 @@ +include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) + +project = QtWebChannel +description = Qt WebChannel Reference Documentation +version = $QT_VERSION + +examplesinstallpath = webchannel + +qhp.projects = QtWebChannel + +qhp.QtWebChannel.file = qtwebchannel.qhp +qhp.QtWebChannel.namespace = org.qt-project.qtwebchannel.$QT_VERSION_TAG +qhp.QtWebChannel.virtualFolder = qtwebchannel +qhp.QtWebChannel.indexTitle = Qt WebChannel +qhp.QtWebChannel.indexRoot = + +qhp.QtWebChannel.filterAttributes = qtwebchannel $QT_VERSION qtrefdoc +qhp.QtWebChannel.customFilters.Qt.name = QtWebChannel $QT_VERSION +qhp.QtWebChannel.customFilters.Qt.filterAttributes = qtwebchannel $QT_VERSION + +qhp.QtWebChannel.subprojects = classes qml examples javascript + +qhp.QtWebChannel.subprojects.classes.title = C++ Classes +qhp.QtWebChannel.subprojects.classes.indexTitle = Qt WebChannel C++ Classes +qhp.QtWebChannel.subprojects.classes.selectors = class fake:headerfile +qhp.QtWebChannel.subprojects.classes.sortPages = true + +qhp.QtWebChannel.subprojects.qml.title = QML Types +qhp.QtWebChannel.subprojects.qml.indexTitle = Qt WebChannel QML Types +qhp.QtWebChannel.subprojects.qml.selectors = qmlclass +qhp.QtWebChannel.subprojects.qml.sortPages = true + +qhp.QtWebChannel.subprojects.examples.title = Examples +qhp.QtWebChannel.subprojects.examples.indexTitle = Qt WebChannel Examples +qhp.QtWebChannel.subprojects.examples.selectors = fake:example +qhp.QtWebChannel.subprojects.examples.sortPages = true + +qhp.QtWebChannel.subprojects.javascript.title = JavaScript API +qhp.QtWebChannel.subprojects.javascript.indexTitle = Qt WebChannel JavaScript API + +tagfile = ../../../doc/qtwebchannel/qtwebchannel.tags + +depends += qtcore qtquick qtqml qmake + +headerdirs += .. \ + ../../imports + +sourcedirs += .. \ + ../../imports + + +exampledirs += ../../../examples/webchannel + +navigation.landingpage = "Qt WebChannel" +navigation.cppclassespage = "Qt WebChannel C++ Classes" +navigation.qmltypespage = "Qt WebChannel QML Types" diff --git a/src/webchannel/doc/src/index.qdoc b/src/webchannel/doc/src/index.qdoc new file mode 100644 index 0000000..635c8bd --- /dev/null +++ b/src/webchannel/doc/src/index.qdoc @@ -0,0 +1,47 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Milian Wolff +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qtwebchannel-index.html + \since 5.4 + \title Qt WebChannel + \brief Bridges the gap between C++/QML and HTML/JavaScript. + + The Qt WebChannel module provides a library for seamless integration of C++/QML applications + with HTML/JavaScript clients. Any QObject can be published to remote clients, where its public + API becomes available. + + \section1 Related Information + + For more information on how to use this module, please refer to the following pages: + + \list + \li \l{Qt WebChannel C++ Classes} explains QWebChannel C++ API. + \li \l{Qt WebChannel QML Types} explains the WebChannel QML API. + \li The \l{Qt WebChannel Examples} show how use the API in practice. + \endlist +*/ diff --git a/src/webchannel/doc/src/javascript.qdoc b/src/webchannel/doc/src/javascript.qdoc new file mode 100644 index 0000000..36bc4ab --- /dev/null +++ b/src/webchannel/doc/src/javascript.qdoc @@ -0,0 +1,100 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Milian Wolff +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Qt WebChannel JavaScript API + \page qtwebchannel-javascript.html + + \brief This page explains how to use the JavaScript QWebChannel API in HTML clients. + + \section1 Setup + + To communicate with a QWebChannel or WebChannel, any HTML client must use and setup the + JavaScript API provided by \c qwebchannel.js. For HTML clients run inside QtWebKit, you + can load the file via \c qrc:///qtwebchannel/qwebchannel.js. For external clients you will + need to copy the file to your webserver. Then instantiate a QWebChannel object and pass + it a transport object and a callback function, which will be invoked once the + initialization of the channel finished and published objects become available. + + The transport object implements a minimal message passing interface. It should be an object + with a \c send() function, which takes a stringified JSON message and transmits it to the + server-side QWebChannelAbstractTransport object. Furthermore, its \c onmessage property should + be called when a message from the server was received. This interface is implemented internally + by the QtWebKit navigator.qtWebChannelTransport object. Alternatively, you can also use a + WebSocket, which also implements this interface. + + Note that the JavaScript QWebChannel object should be constructed once the transport object is + fully operational. In case of a WebSocket, that means you should create the QWebChannel in the + socket's \c onopen handler. Take a look at the \l{Standalone Example} to see how this is done. + + \section1 Interacting with QObjects + + Once the callback passed to the QWebChannel object is invoked, the channel has finished + initialization and all published objects are accessible to the HTML client via the \c channel.objects + property. Thus, assuming an object was published with the identifier "foo", then we can interact with it + as shown in the example below. Note that all communication between the HTML client and + the QML/C++ server is asynchronous. Properties are cached on the HTML side. Furthermore + keep in mind that only QML/C++ data types which can be converted to JSON will be (de-)serialized + properly and thus accessible to HTML clients. + + \code +new QWebChannel(yourTransport, function(channel) { + + // Connect to a signal: + channel.objects.foo.mySignal.connect(function() { + // This callback will be invoked whenever the signal is emitted on the C++/QML side. + console.log(arguments); + }); + + // To make the object known globally, assign it to the window object, i.e.: + window.foo = channel.objects.foo; + + // Invoke a method: + foo.myMethod(arg1, arg2, function(returnValue) { + // This callback will be invoked when myMethod has a return value. Keep in mind that + // the communication is asynchronous, hence the need for this callback. + console.log(returnValue); + }); + + // Read a property value, which is cached on the client side: + console.log(foo.myProperty); + + // Writing a property will instantly update the client side cache. + // The remote end will be notified about the change asynchronously + foo.myProperty = "Hello World!"; + + // To get notified about remote property changes, + // simply connect to the corresponding notify signal: + foo.onMyPropertyChanged.connect(function(newValue) { + console.log(newValue); + }); + + // One can also access enums that are marked with Q_ENUM: + console.log(foo.MyEnum.MyEnumerator); +}); + \endcode +*/ diff --git a/src/webchannel/doc/src/module.qdoc b/src/webchannel/doc/src/module.qdoc new file mode 100644 index 0000000..345485e --- /dev/null +++ b/src/webchannel/doc/src/module.qdoc @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Milian Wolff +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module QtWebChannel + \title Qt WebChannel C++ Classes + \ingroup modules + \qtvariable webchannel + \since 5.4 + \brief List of C++ classes that provide the QtWebChannel functionality. + + To use these classes in your application, use the following include + statement: + + \code + #include + \endcode + + To link against the module, add this line to your \l qmake \c .pro file: + + \code + QT += webchannel + \endcode +*/ + +/*! + \qmlmodule QtWebChannel 1.0 + \title Qt WebChannel QML Types + \since 5.4 + \brief List of QML types that provide WebChannel functionality. + + The QML types are accessed by using: + \badcode + import QtWebChannel 1.0 + \endcode +*/ -- cgit v1.2.1