diff options
author | Milian Wolff <milian.wolff@kdab.com> | 2014-07-16 17:39:31 +0200 |
---|---|---|
committer | Sumedha Widyadharma <sumedha.widyadharma@basyskom.com> | 2014-08-01 09:16:16 +0200 |
commit | b84e46090b5230d7ebcdbdabd8c03a9ae5d2f860 (patch) | |
tree | 9687c3b47f4e77e931916a8afe1d516d3b280101 /examples | |
parent | 5051411b92b4aca4ed5ec462e7b0e52af4d3951e (diff) | |
download | qtwebchannel-b84e46090b5230d7ebcdbdabd8c03a9ae5d2f860.tar.gz |
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 <jerome.pasion@digia.com>
Diffstat (limited to 'examples')
-rw-r--r-- | examples/examples.pro | 4 | ||||
-rw-r--r-- | examples/qwebchannel/doc/examples.qdoc | 49 | ||||
-rw-r--r-- | examples/qwebchannel/doc/standalone-screenshot.png | bin | 0 -> 30363 bytes | |||
-rw-r--r-- | examples/qwebchannel/doc/standalone.qdoc | 64 | ||||
-rw-r--r-- | examples/qwebchannel/qwebchannel.pro | 5 | ||||
-rw-r--r-- | examples/qwebchannel/standalone/dialog.ui (renamed from examples/standalone/dialog.ui) | 0 | ||||
-rw-r--r-- | examples/qwebchannel/standalone/index.html (renamed from examples/standalone/index.html) | 0 | ||||
-rw-r--r-- | examples/qwebchannel/standalone/main.cpp (renamed from examples/standalone/main.cpp) | 21 | ||||
-rw-r--r-- | examples/qwebchannel/standalone/standalone.pro (renamed from examples/standalone/standalone.pro) | 0 | ||||
-rw-r--r-- | examples/qwebchannel/standalone/websocketclientwrapper.cpp (renamed from examples/standalone/websocketclientwrapper.cpp) | 9 | ||||
-rw-r--r-- | examples/qwebchannel/standalone/websocketclientwrapper.h (renamed from examples/standalone/websocketclientwrapper.h) | 0 | ||||
-rw-r--r-- | examples/qwebchannel/standalone/websockettransport.cpp (renamed from examples/standalone/websockettransport.cpp) | 14 | ||||
-rw-r--r-- | examples/qwebchannel/standalone/websockettransport.h (renamed from examples/standalone/websockettransport.h) | 0 |
13 files changed, 161 insertions, 5 deletions
diff --git a/examples/examples.pro b/examples/examples.pro index 63677f5..1cb6c9f 100644 --- a/examples/examples.pro +++ b/examples/examples.pro @@ -1,5 +1,3 @@ TEMPLATE = subdirs -qtHaveModule(widgets):qtHaveModule(websockets) { - SUBDIRS += standalone -} +SUBDIRS += qwebchannel diff --git a/examples/qwebchannel/doc/examples.qdoc b/examples/qwebchannel/doc/examples.qdoc new file mode 100644 index 0000000..613d760 --- /dev/null +++ b/examples/qwebchannel/doc/examples.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Milian Wolff <milian.wolff@kdab.com> +** Contact: http://www.qt-project.org/legal +** +** This file is part of the QtWebChannel module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Digia gives you certain additional +** rights. These rights are described in the Digia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Qt WebChannel Examples + \group qtwebchannel-examples + \brief List of Qt WebChannel examples. + + The examples show how to use the QWebChannel C++ and WebChannel QML API. + +*/ diff --git a/examples/qwebchannel/doc/standalone-screenshot.png b/examples/qwebchannel/doc/standalone-screenshot.png Binary files differnew file mode 100644 index 0000000..3c55e19 --- /dev/null +++ b/examples/qwebchannel/doc/standalone-screenshot.png diff --git a/examples/qwebchannel/doc/standalone.qdoc b/examples/qwebchannel/doc/standalone.qdoc new file mode 100644 index 0000000..1d81dad --- /dev/null +++ b/examples/qwebchannel/doc/standalone.qdoc @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Milian Wolff <milian.wolff@kdab.com> +** Contact: http://www.qt-project.org/legal +** +** This file is part of the QtWebChannel module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Digia gives you certain additional +** rights. These rights are described in the Digia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example standalone + \title Standalone Example + \ingroup qtwebchannel-examples + \image standalone-screenshot.png + \brief Shows how to use the QWebChannel C++ API to communicate with an external client. + + The standalone example is a simple chat between a pure C++/Qt application and a remote HTML + client running in your default browser. + + The C++ app sets up a QWebChannel and publishes a Dialog object over it. + For the remote client side, \c index.html is opened. Both show a dialog with the list of + received messages and an input box to send messages to the other end. + + The Dialog emits the Dialog::sendText() signal when the user sents a message. The signal + automatically gets propagated to the HTML client. When the user enters a message on the HTML + side, Dialog::receiveText() is called. + + All communication between the HTML client and the C++/Qt server is done over a WebSocket. + The C++ side instantiates a QWebSocketServer and wraps incoming QWebSocket connections + in WebSocketTransport objects, which implement QWebChannelAbstractTransport. These objects are + then connected to the QWebChannel instance. +*/ diff --git a/examples/qwebchannel/qwebchannel.pro b/examples/qwebchannel/qwebchannel.pro new file mode 100644 index 0000000..63677f5 --- /dev/null +++ b/examples/qwebchannel/qwebchannel.pro @@ -0,0 +1,5 @@ +TEMPLATE = subdirs + +qtHaveModule(widgets):qtHaveModule(websockets) { + SUBDIRS += standalone +} diff --git a/examples/standalone/dialog.ui b/examples/qwebchannel/standalone/dialog.ui index 056a3f5..056a3f5 100644 --- a/examples/standalone/dialog.ui +++ b/examples/qwebchannel/standalone/dialog.ui diff --git a/examples/standalone/index.html b/examples/qwebchannel/standalone/index.html index 3cce3ec..3cce3ec 100644 --- a/examples/standalone/index.html +++ b/examples/qwebchannel/standalone/index.html diff --git a/examples/standalone/main.cpp b/examples/qwebchannel/standalone/main.cpp index f407da6..cc22ed3 100644 --- a/examples/standalone/main.cpp +++ b/examples/qwebchannel/standalone/main.cpp @@ -55,6 +55,9 @@ #include "ui_dialog.h" +/*! + An instance of this class gets published over the WebChannel and is then accessible to HTML clients. +*/ class Dialog : public QObject { Q_OBJECT @@ -75,15 +78,24 @@ public: } signals: + /*! + This signal is emitted from the C++ side and the text displayed on the HTML client side. + */ void sendText(const QString &text); public slots: + /*! + This slot is invoked from the HTML client side and the text displayed on the server side. + */ void receiveText(const QString &text) { displayMessage(tr("Received message: %1").arg(text)); } private slots: + /*! + Note that this slot is private and thus not accessible to HTML clients. + */ void clicked() { const QString text = ui.input->text(); @@ -107,21 +119,26 @@ int main(int argc, char** argv) { QApplication app(argc, argv); - QWebChannel channel; + // setup the QWebSocketServer QWebSocketServer server(QStringLiteral("QWebChannel Standalone Example Server"), QWebSocketServer::NonSecureMode); if (!server.listen(QHostAddress::LocalHost)) { qFatal("Failed to open web socket server."); return 1; } + // wrap WebSocket clients in QWebChannelAbstractTransport objects WebSocketClientWrapper clientWrapper(&server); + + // setup the channel + QWebChannel channel; QObject::connect(&clientWrapper, &WebSocketClientWrapper::clientConnected, &channel, &QWebChannel::connectTo); + // setup the dialog and publish it to the QWebChannel Dialog dialog; - channel.registerObject(QStringLiteral("dialog"), &dialog); + // open a browser window with the client HTML page QUrl url = QUrl::fromLocalFile(SOURCE_DIR "/index.html"); url.setQuery(QStringLiteral("webChannelBaseUrl=") + server.serverUrl().toString()); QDesktopServices::openUrl(url); diff --git a/examples/standalone/standalone.pro b/examples/qwebchannel/standalone/standalone.pro index 37b6de3..37b6de3 100644 --- a/examples/standalone/standalone.pro +++ b/examples/qwebchannel/standalone/standalone.pro diff --git a/examples/standalone/websocketclientwrapper.cpp b/examples/qwebchannel/standalone/websocketclientwrapper.cpp index 219050d..0e776e1 100644 --- a/examples/standalone/websocketclientwrapper.cpp +++ b/examples/qwebchannel/standalone/websocketclientwrapper.cpp @@ -55,6 +55,12 @@ QT_BEGIN_NAMESPACE +/*! + Construct the client wrapper with the given parent. + + All clients connecting to the QWebSocketServer will be automatically wrapped + in WebSocketTransport objects. +*/ WebSocketClientWrapper::WebSocketClientWrapper(QWebSocketServer *server, QObject *parent) : QObject(parent) , m_server(server) @@ -63,6 +69,9 @@ WebSocketClientWrapper::WebSocketClientWrapper(QWebSocketServer *server, QObject this, &WebSocketClientWrapper::handleNewConnection); } +/*! + Wrap an incoming WebSocket connection in a WebSocketTransport object. +*/ void WebSocketClientWrapper::handleNewConnection() { emit clientConnected(new WebSocketTransport(m_server->nextPendingConnection())); diff --git a/examples/standalone/websocketclientwrapper.h b/examples/qwebchannel/standalone/websocketclientwrapper.h index 1f742f7..1f742f7 100644 --- a/examples/standalone/websocketclientwrapper.h +++ b/examples/qwebchannel/standalone/websocketclientwrapper.h diff --git a/examples/standalone/websockettransport.cpp b/examples/qwebchannel/standalone/websockettransport.cpp index f1ecee2..5714463 100644 --- a/examples/standalone/websockettransport.cpp +++ b/examples/qwebchannel/standalone/websockettransport.cpp @@ -57,6 +57,11 @@ QT_BEGIN_NAMESPACE +/*! + Construct the transport object and wrap the given socket. + + The socket is also set as the parent of the transport object. +*/ WebSocketTransport::WebSocketTransport(QWebSocket *socket) : QWebChannelAbstractTransport(socket) , m_socket(socket) @@ -65,17 +70,26 @@ WebSocketTransport::WebSocketTransport(QWebSocket *socket) this, &WebSocketTransport::textMessageReceived); } +/*! + Destroys the WebSocketTransport. +*/ WebSocketTransport::~WebSocketTransport() { } +/*! + Serialize the JSON message and send it as a text message via the WebSocket to the client. +*/ void WebSocketTransport::sendMessage(const QJsonObject &message) { QJsonDocument doc(message); m_socket->sendTextMessage(QString::fromUtf8(doc.toJson(QJsonDocument::Compact))); } +/*! + Deserialize the stringified JSON messageData and emit messageReceived. +*/ void WebSocketTransport::textMessageReceived(const QString &messageData) { QJsonParseError error; diff --git a/examples/standalone/websockettransport.h b/examples/qwebchannel/standalone/websockettransport.h index 828ac00..828ac00 100644 --- a/examples/standalone/websockettransport.h +++ b/examples/qwebchannel/standalone/websockettransport.h |