diff options
author | Milian Wolff <milian.wolff@kdab.com> | 2014-01-31 18:24:23 +0100 |
---|---|---|
committer | The Qt Project <gerrit-noreply@qt-project.org> | 2014-02-06 13:23:01 +0100 |
commit | 05bafd509ca302fc63465fece7cd0c33ec602e31 (patch) | |
tree | 08922a3a4ada3ad859cad4436f8f009245cef810 /README.md | |
parent | a32631c5e2136dd93ada9a0a98b5bf458acfb44d (diff) | |
download | qtwebchannel-05bafd509ca302fc63465fece7cd0c33ec602e31.tar.gz |
Update README and use markdown for nicer display on gitorious.
This text can then be used in the future for proper qdoc integration.
Change-Id: If75b98c0aa1aa131b52542c97a5c2bf382171729
Reviewed-by: Simon Hausmann <simon.hausmann@digia.com>
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 90 |
1 files changed, 90 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..185c4fd --- /dev/null +++ b/README.md @@ -0,0 +1,90 @@ +### 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. + +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. + +### 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. + +### Building + + qmake-qt5 + make + make install + +### Usage from C++ + +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: + + 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: + + <script type="text/javascript" src="path/to/qwebchannel.js"></script> + <script type="text/javascript"> + // note: baseUrl must be known + new QWebChannel(baseUrl, function(channel) { + foo.doStuff(); // calls doStuff slot or invokable method on myFooObj on the C++ side + }); + </script> + +An example which shows all this can be found in `examples/standalone`. + +### Usage from QtQuick + +For QML applications, use the following import: + + import QtWebChannel 1.0 + +Then setup the WebChannel and register objects to it: + + 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 + } + +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: + + <script type="text/javascript" src="qrc:///qwebchannel/qwebchannel.js"></script> + <script type="text/javascript"> + new QWebChannel(navigator.qt, function(channel) { + // do stuff with published objects + }); + </script> + +To see this in action, take a look at `examples/qml` and run the `example.qml` in `qmlscene`. |