diff options
-rw-r--r-- | README | 60 | ||||
-rw-r--r-- | README.md | 90 |
2 files changed, 90 insertions, 60 deletions
@@ -1,60 +0,0 @@ -Qt Web Channel is a labs project that enables the creation of a WebSocket based channel between a web view and its QML/C++ container. - -To build: -cd src -qmake -make -sudo make install - -This would enable a QML import, which can be imported as such: -import Qt.labs.WebChannel 1.0 - -and then instantiated: - WebChannel { - id: webChannel - - onExecute: { - } - } - -A new WebChannel then generates a secret URL, that can be used from within an HTML page as a loaded script. - -QML: -WebView { - id: webView - url: "index.html?webChannelBaseUrl=" + webChannel.baseUrl; -} - -HTML: -<script type="text/javascript" src="qrc:///qwebchannel/webchannel.js"></script> -<script type="text/javascript" src="qrc:///qwebchannel/qobject.js"></script> -<script type="text/javascript"> - var baseUrl = (/[?&]webChannelBaseUrl=([A-Za-z0-9\-:/\.]+)/.exec(location.search)[1]); - var webChannel = new QWebChannel(baseUrl, function(channel) { - // channel is connected, send data! - }); -</script> - -This would invoke a function named createWebChannel (or any other name passed in the URL), that would receieve as a parameter the web channel object. -That object can be used to execute commands: - -HTML -webChannel.exec("command", function(result) { ... }); - -QML -WebChannel { - onRawMessageReceived { - if (requestData == "command") { sendRawMessage("..."); } - } -} - -or subscribe to events: - -HTML -webChannel.subscribe("myEvent", function(eventData) { ... }); - -QML -webChannel.sendMessage("myEvent", "..."); - -See examples for further details. - 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`. |