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>

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`.