summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLeena Miettinen <riitta-leena.miettinen@qt.io>2016-05-31 15:34:32 +0200
committerJani Heikkinen <jani.heikkinen@qt.io>2016-06-02 09:51:29 +0000
commit18d8ca185819d6d81a9f21858ff2d60bf6fd05f8 (patch)
treeadd5531b4e3cd6b77f8bfbc9c515268631336e9f
parent4fda82b66e17cc03e6b08f1afd135069cfef09b7 (diff)
downloadqtwebchannel-18d8ca185819d6d81a9f21858ff2d60bf6fd05f8.tar.gz
Doc: Edit example documentation
- Add images to the examples. - Add instructions for running the examples - Edit for grammar and style - Add dependencies to Qt WebEngine and Qt WebSockets modules - Add a workaround for preventing autolinking of WebChannel, WebEngine and WebSockets to the wrong targets - Use explicit linking where necessary Change-Id: Ia4025284063fa09c9e2a0b2c347ee682bba8a615 Reviewed-by: Topi Reiniƶ <topi.reinio@theqtcompany.com> (cherry picked from commit 01ea92c7c8d77d3d3c10ab1cc4bf4f214aa07126)
-rw-r--r--examples/webchannel/chatclient-html/doc/images/chatclient-html.pngbin0 -> 7284 bytes
-rw-r--r--examples/webchannel/chatclient-html/doc/src/chatclient-html.qdoc31
-rw-r--r--examples/webchannel/chatclient-qml/doc/images/chatclient-qml.pngbin0 -> 5018 bytes
-rw-r--r--examples/webchannel/chatclient-qml/doc/src/chatclient-qml.qdoc32
-rw-r--r--examples/webchannel/chatserver-cpp/doc/images/chatserver-cpp.pngbin0 -> 6829 bytes
-rw-r--r--examples/webchannel/chatserver-cpp/doc/src/chatserver-cpp.qdoc32
-rw-r--r--examples/webchannel/standalone/doc/src/standalone.qdoc18
-rw-r--r--src/webchannel/doc/qtwebchannel.qdocconf3
-rw-r--r--src/webchannel/doc/src/examples.qdoc3
-rw-r--r--src/webchannel/doc/src/external-resources.qdoc57
10 files changed, 128 insertions, 48 deletions
diff --git a/examples/webchannel/chatclient-html/doc/images/chatclient-html.png b/examples/webchannel/chatclient-html/doc/images/chatclient-html.png
new file mode 100644
index 0000000..f61c9ec
--- /dev/null
+++ b/examples/webchannel/chatclient-html/doc/images/chatclient-html.png
Binary files differ
diff --git a/examples/webchannel/chatclient-html/doc/src/chatclient-html.qdoc b/examples/webchannel/chatclient-html/doc/src/chatclient-html.qdoc
index 497c63f..0a3efb6 100644
--- a/examples/webchannel/chatclient-html/doc/src/chatclient-html.qdoc
+++ b/examples/webchannel/chatclient-html/doc/src/chatclient-html.qdoc
@@ -50,31 +50,36 @@
/*!
\example chatclient-html
- \title Qt WebChannel Chatclient HTML Example
+ \title Qt WebChannel ChatClient HTML Example
\ingroup qtwebchannel-examples
\brief A HTML/JavaScript client that communicates over a WebSocket with a QWebChannel server.
- The chatclient-html example provides a simple QWebChannel client implemented using JavaScript and HTML.
+ \image chatclient-html.png
- \section1 Overview
+ \e{ChatClient HTML} provides a simple QWebChannel client implemented using JavaScript and HTML.
+
+ \section1 Running the Example
+
+ To run the example, open the \c chatclient.html file in a browser.
+
+ \section1 Implementing a Web Channel Client
The client initializes a WebSocket connection to the chat server and receives an object
- containing all neccessarry signals, slots and properties for implementing a chat client.
+ containing all the necessary signals, slots, and properties for implementing a chat client.
- After login the client can invoke the method \c sendMessage and receive the signal \c newMessage
- to send and receive messages. Furthermore there is a \c userList property which provides the
- names of all other connected clients. It is automatically updated when its contents change.
- Also, the client responds to the servers keep alive signal which is needed to detect disconnected
- clients and remove them from the \c userlist property.
+ After login, the client can invoke the method \c sendMessage and receive the signal \c newMessage
+ to send and receive messages. Furthermore, a \c userList property provides the names of
+ all other connected clients. The list is automatically updated when its contents change.
+ Also, the client responds to the server's keep alive signal which is needed to detect disconnected
+ clients and remove them from the \c userList property.
The example shows how basic elements can be used with the client JavaScript implementation of
- QWebChannel, like connecting to signals (\c newMessage), calling slots (\c sendMessage) and handle
+ QWebChannel, like connecting to signals (\c newMessage), calling slots (\c sendMessage), and handling
property changes (\c userList).
- The client is able to work with the chatserver-cpp example.
+ The client is able to work with \l{Qt WebChannel ChatServer Example}.
- To run the example, open the \c chatclient.html in a browser.
- \sa {chatserver-cpp}, {chatclient-qml}
+ \sa {Qt WebChannel ChatServer Example}, {Qt WebChannel ChatClient QML Example}
*/
diff --git a/examples/webchannel/chatclient-qml/doc/images/chatclient-qml.png b/examples/webchannel/chatclient-qml/doc/images/chatclient-qml.png
new file mode 100644
index 0000000..7f96e26
--- /dev/null
+++ b/examples/webchannel/chatclient-qml/doc/images/chatclient-qml.png
Binary files differ
diff --git a/examples/webchannel/chatclient-qml/doc/src/chatclient-qml.qdoc b/examples/webchannel/chatclient-qml/doc/src/chatclient-qml.qdoc
index cd029e0..c6e0f32 100644
--- a/examples/webchannel/chatclient-qml/doc/src/chatclient-qml.qdoc
+++ b/examples/webchannel/chatclient-qml/doc/src/chatclient-qml.qdoc
@@ -50,32 +50,38 @@
/*!
\example chatclient-qml
- \title Qt WebChannel Chatclient QML Example
+ \title Qt WebChannel ChatClient QML Example
\ingroup qtwebchannel-examples
\brief A QML client that communicates over a WebSocket with a QWebChannel server.
- The chatclient-html example provides a simple QWebChannel client implemented using JavaScript and QML.
+ \image chatclient-qml.png
- \section1 Overview
+ \e{ChatClient QML} provides a simple QWebChannel client implemented using JavaScript and QML.
- The client initializes a WebSocket connection to the chat server and receives an object
- containing all neccessarry signals, slots and properties for implementing a chat client.
+ \section1 Running the Example
+
+ To run the example, enter the following command in the client source
+ directory:
+
+ \c {path/to/qmlscene qmlchatclient.qml}
+
+ \section1 Implementing a Web Channel Client
+
+ The client initializes a \l [QML] WebSocket connection to the chat server and receives an object
+ containing all the necessary signals, slots, and properties for implementing a chat client.
After login, the client can invoke the method \c sendMessage and receive the signal \c newMessage
- to send and receive messages. Furthermore, there is a \c userList property which provides the
+ to send and receive messages. Furthermore, a \c userList property provides the
names of all other connected clients. It is automatically updated when its contents change.
- Also, the client responds to the servers keep alive signal which is needed to detect disconnected
+ Also, the client responds to the server's keep alive signal which is needed to detect disconnected
clients and remove them from the \c userList property.
The example shows how basic elements can be used with the client JavaScript implementation of
- QWebChannel, like connecting to signals (\c newMessage), calling slots (\c sendMessage) and handle
+ QWebChannel, like connecting to signals (\c newMessage), calling slots (\c sendMessage), and handling
property changes (\c userList).
- The client is able to work with the chatserver-cpp as server application
-
-
- The example can be run by invoking \c {path/to/qmlscene qmlchatclient.qml}.
+ The client is able to work with the \l{Qt WebChannel ChatServer Example}.
- \sa {chatserver-cpp}, {chatclient-html}
+ \sa {Qt WebChannel ChatServer Example}, {Qt WebChannel ChatClient HTML Example}
*/
diff --git a/examples/webchannel/chatserver-cpp/doc/images/chatserver-cpp.png b/examples/webchannel/chatserver-cpp/doc/images/chatserver-cpp.png
new file mode 100644
index 0000000..b0f484a
--- /dev/null
+++ b/examples/webchannel/chatserver-cpp/doc/images/chatserver-cpp.png
Binary files differ
diff --git a/examples/webchannel/chatserver-cpp/doc/src/chatserver-cpp.qdoc b/examples/webchannel/chatserver-cpp/doc/src/chatserver-cpp.qdoc
index 06d5b2e..0b198d2 100644
--- a/examples/webchannel/chatserver-cpp/doc/src/chatserver-cpp.qdoc
+++ b/examples/webchannel/chatserver-cpp/doc/src/chatserver-cpp.qdoc
@@ -50,31 +50,39 @@
/*!
\example chatserver-cpp
- \title Qt WebChannel Chatserver Example
+ \title Qt WebChannel ChatServer Example
\ingroup qtwebchannel-examples
- \brief Shows how to use the QWebChannel C++ API to implement a simple chat server
+ \brief A simple chat server implemented using the QWebChannel C++ API.
- The chatserver examples provides a chat service that client examples can connect to.
+ \image chatserver-cpp.png
- \section1 Overview
+ \e{ChatServer} provides a chat service that the
+ \l{Qt WebChannel ChatClient QML Example} and
+ \l{Qt WebChannel ChatClient HTML Example} can connect to.
+
+ \include examples-run.qdocinc
+
+ \section1 Implementing a Chat Server
The C++ application implements a QObject which provides all mechanisms required for
a chat service.
- This object is published through a QWebChannel which uses a WebSocket as transport.
+ This object is published through a QWebChannel which uses a \l{Qt WebSockets}
+ {WebSocket} as transport.
The server provides a basic \c login method (username only, no passwords), which must be
successfully invoked before a client is able to chat.
- After login a client can invoke the method \c sendMessage and receive the signal \c newMessage
- to write and receive messages. Furthermore there is a \c userList property which provides
+ After login, a client can invoke the method \c sendMessage and receive the signal \c newMessage
+ to write and receive messages. Furthermore, there is a \c userList property which provides
the names of all other connected clients.
- Additionally the server sends a keepAlive signal periodically to all clients. The clients
+ Additionally the server sends a \c keepAlive signal periodically to all clients. The clients
have to respond to this signal, otherwise the client will be removed from the \c userList property.
- The example shows how basic QObject elements can be used with QWebChannel, i.e. signals
- (\c newMessage), slots (\c sendMessage) and properties (\c userList).
+ The example shows how basic QObject elements can be used with QWebChannel, that is signals
+ (\c newMessage), slots (\c sendMessage), and properties (\c userList).
- Because this is a plain server application, there are separated clients needed to interact
- with the server. Both examples chatclient-qml and chatclient-html show a client implementation
+ Because this is a plain server application, separate clients are needed to
+ interact with it. \l{Qt WebChannel ChatClient QML Example} and
+ \l{Qt WebChannel ChatClient HTML Example} are client implementations
compatible with this server.
*/
diff --git a/examples/webchannel/standalone/doc/src/standalone.qdoc b/examples/webchannel/standalone/doc/src/standalone.qdoc
index 28c67a2..0d030bf 100644
--- a/examples/webchannel/standalone/doc/src/standalone.qdoc
+++ b/examples/webchannel/standalone/doc/src/standalone.qdoc
@@ -53,26 +53,28 @@
\title Qt WebChannel Standalone Example
\ingroup qtwebchannel-examples
\image standalone-screenshot.png
- \brief Shows how to use the QWebChannel C++ API to communicate with an external client.
+ \brief A simple chat between a server and a remote client running in a
+ browser.
- The standalone example is a simple chat between a C++ application and a remote HTML
- client running in your default browser.
+ \e{Standalone} demonstrates how to use the QWebChannel C++ API to
+ communicate with an external client. It is a simple chat between a C++
+ application and a remote HTML client running in your default browser.
\include examples-run.qdocinc
- \section1 Overview
+ \section1 Communicating with a Remote Client
- The C++ application sets up a QWebChannel instance and publishes a Dialog object over it.
+ The C++ application sets up a QWebChannel instance and publishes a \c Dialog object over it.
For the remote client side, \l {standalone/index.html}{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 sends a message. The signal
+ The \c Dialog emits the \c Dialog::sendText() signal when the user sends 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.
+ side, \c Dialog::receiveText() is called.
All communication between the HTML client and the C++ 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
+ in QWebChannelAbstractTransport objects. These objects are
then connected to the QWebChannel instance.
\sa {Qt WebChannel JavaScript API}
diff --git a/src/webchannel/doc/qtwebchannel.qdocconf b/src/webchannel/doc/qtwebchannel.qdocconf
index cfb47e4..4026379 100644
--- a/src/webchannel/doc/qtwebchannel.qdocconf
+++ b/src/webchannel/doc/qtwebchannel.qdocconf
@@ -40,7 +40,7 @@ qhp.QtWebChannel.subprojects.javascript.indexTitle = Qt WebChannel JavaScript
tagfile = ../../../doc/qtwebchannel/qtwebchannel.tags
-depends += qtcore qtquick qtqml qmake qtdoc
+depends += qtcore qtquick qtqml qmake qtdoc qtwebengine qtwebsockets
headerdirs += .. \
../../imports
@@ -48,6 +48,7 @@ headerdirs += .. \
sourcedirs += .. \
../../imports
+imagedirs += images
exampledirs += ../../../examples/webchannel
examples.fileextensions += "*.html *.json"
diff --git a/src/webchannel/doc/src/examples.qdoc b/src/webchannel/doc/src/examples.qdoc
index b304ac6..83e614e 100644
--- a/src/webchannel/doc/src/examples.qdoc
+++ b/src/webchannel/doc/src/examples.qdoc
@@ -42,6 +42,7 @@
\group qtwebchannel-examples
\brief List of Qt WebChannel examples.
- The examples show how to use the QWebChannel C++ and WebChannel QML API.
+ The examples show how to use the QWebChannel C++ and \l [QML] WebChannel QML
+ API.
*/
diff --git a/src/webchannel/doc/src/external-resources.qdoc b/src/webchannel/doc/src/external-resources.qdoc
new file mode 100644
index 0000000..0002ec1
--- /dev/null
+++ b/src/webchannel/doc/src/external-resources.qdoc
@@ -0,0 +1,57 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://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 http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*
+ The nolink entries prevent autolinking of each occurrence of 'WebChannel'
+ 'WebEngine' or 'WebSocket' to the QML type.
+ To link to the QML type, use explicit linking. For example:
+ \l [QML] WebChannel
+ \sa {QtWebChannel::}{WebChannel}
+*/
+/*!
+ \externalpage nolink
+ \title WebChannel
+ \internal
+*/
+
+/*!
+ \externalpage nolink
+ \title WebEngine
+ \internal
+*/
+
+/*!
+ \externalpage nolink
+ \title WebSockets
+ \internal
+*/
+
+/*!
+ \externalpage nolink
+ \title WebSocket
+ \internal
+*/