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 --- README.md | 76 ++++++++++++++++++--------------------------------------------- 1 file changed, 22 insertions(+), 54 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 185c4fd..111c76f 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,22 @@ ### Introduction -The `QtWebChannel` module offers Qt applications a seamless way to publish `QObjects` for interaction -from HTML/JavaScript clients. These clients can either be inside local Qt `WebView`s or any other, -potentially remote, client which supports JavaScript and WebSockets. +The Qt WebChannel module offers Qt applications a seamless way to publish `QObjects` for interaction +with HTML/JavaScript clients. These clients can either be inside local Qt `WebView`s or any other, +potentially remote, client which supports JavaScript, as long as a communication channel such +as WebSockets is available. -It uses introspection on the `QObject`s and sends this serialized data to the clients. There, with -the help of a small JavaScript library, an object is created which simulates the API of the `QObject`. -Any invokable methods, including slots, can be called as well as properties read and written. -Additionally you can connect to signals and register JavaScript callbacks as handlers. +Qt WebChannel uses introspection on the `QObject`s and sends this serialized data to the clients. +There, with the help of a small JavaScript library, an object is created which simulates the API of +the `QObject`. Any invokable methods, including slots, can be called as well as properties read and +written. Additionally you can connect to signals and register JavaScript callbacks as handlers. ### Dependencies -This module depends on `QtBase` and `QtWebSockets`. Optionally, an additional module for QtQuick is -build which makes it easy to use the `QWebChannel` from QML. Furthermore, you can decide to use the -native IPC mechanism of `QtWebKit` for efficient message passing to QtQuick `WebView`'s. +This module depends on Qt Core only. Optionally, an additional plugin for Qt Quick is build, which +makes it easy to use a `QWebChannel` from QML. Note that this module alone is not functional. It +is being used in e.g. Qt WebKit to provide a seamless integration of QML/C++ QObjects into JavaScript +clients. You can integrate it in your projects as well, by providing an implementation of the +`QWebChannelAbstractTransport` class, see the `standalone` example for how to do this. ### Building @@ -27,64 +30,29 @@ To use the Qt/C++ library, add the following to your `QMake` project: QT += webchannel -Then, in your C++ code, construct a websocket transport and webchannel, then publish your `QObject`s: +Then, in your C++ code, construct a a webchannel, then publish your `QObject`s: - QWebSocketTransport transport; QWebChannel channel; - channel.connectTo(&transport); - channel.registerObject(QStringLiteral("foo"), myFooObj); .... -On the HTML/JavaScript client side, you need to embed `src/webchannel/qwebchannel.js` and setup -the connection to the WebSocket transport. The base URL for that can be found from C++ via -`transport.baseUrl()` after the transport was initialized, and must be passed to HTML clients: - - - +Additionally, you need to provide a communication channel to the HTML client. One way is to +use the Qt WebSockets module. On the HTML/JavaScript client side, you need to embed +`src/webchannel/qwebchannel.js` and setup the connection to a client-side transport. An example +which shows all this in action can be found in `examples/standalone`. -An example which shows all this can be found in `examples/standalone`. - -### Usage from QtQuick +### Usage from Qt Quick For QML applications, use the following import: import QtWebChannel 1.0 -Then setup the WebChannel and register objects to it: +Then setup the WebChannel, register objects to it and connect to transport objects: WebChannel { registeredObjects: [foo, bar, ...] - connections: WebViewTransport { - webViewExperimental: yourWebView.experimental - onMessageReceived: { - textEdit.text += "Received message: " + message + "\n"; - } - } - } - -The above uses a `WebViewTransport` for efficient message passing between the server QML application -and HTML clients in a `WebView`, which must be setup as follows: - - WebView { - id: yourWebView - experimental.preferences.navigatorQtObjectEnabled: true + transports: [yourTransport] } -The HTML client finally uses a similar setup as above, but can make use of the embedded resource -for `qwebchannel.js` and the `navigator.qt` object: - - - - -To see this in action, take a look at `examples/qml` and run the `example.qml` in `qmlscene`. +To see this in action, take a look at the test code in `tests/auto/qml`. -- cgit v1.2.1