Added the QtWebKit bridge Image Analyzer example.

Originally written by Jervey Kong.

Task-number: QTBUG-14154
Reviewed-by: David Boddie

1 files changed, 155 insertions, 0 deletions

diff --git a/doc/src/examples/webkit-bridge-imageanalyzer.qdoc b/doc/src/examples/webkit-bridge-imageanalyzer.qdoc
new file mode 100644
index 0000000..efc5623
--- /dev/null
+++ b/doc/src/examples/webkit-bridge-imageanalyzer.qdoc
@@ -0,0 +1,155 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Free Documentation License
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+    \example webkit/imageanalyzer
+    \startpage {index.html} {Qt Reference Documentation}
+    \title The Webkit Bridge Tutorial - Hybrid Client Application
+
+    In this example, we will show how to write a hybrid application using
+\l{The QtWebKit Bridge}{QtWebKit Bridge}, which distinguishes itself from a
+thin client in that it performs heavy calculations on the client side in C++,
+like a native application, but presents nothing more than a \c QWebView for its
+user interface, displaying web content written in HTML/JavaScript. The
+application uses QtConcurrent to distribute its work across as many CPU cores as
+are available from the system, so it can process each image in parallel.
+
+Initially, you will see a user interface with an empty list of images. Clicking
+on some of the images in the lower pane below adds them to the list view above,
+as shown in the screenshot below.
+
+    \image webkit-imageanalyzer-screenshot.png
+
+Now, we can click on \bold Analyze, and each image is analyzed using some
+computationally intensive C++ function, in parallel and on different cores.
+Progress is shown while the analysis is proceeding.
+
+    \image webkit-imageanalyzer-progress.png
+
+and in the end, we will see something like this, where the average RGB values of
+each image are shown.
+
+    \image webkit-imageanalyzer-complete.png
+
+The MainWindow is defined in C++, and creates a \c QNetworkCache and a
+\c QWebView, and tells the \c QWebView to load the starting page, providing us
+with a user interface for the client.
+
+  \snippet examples/webkit/imageanalyzer/mainwindow.cpp MainWindow - constructor
+
+In this example, the sample content is addressed with the \tt qrc:/index.html
+URL. \tt qrc:/ indicates that the file is stored as a Qt resource (attached to
+the executable). In a real-world application, the content and images would
+likely be retrieved from the network rather than from resources.
+
+We wish to initialize an object reference in the JavaScript web page to point
+to our \tt ImageAnalyzer before any other scripts are run. To do this, we
+connect the \c javaScriptWindowObjectCleared() signal to a slot which does the
+object creation and handoff to JavaScript.
+
+  \snippet examples/webkit/imageanalyzer/mainwindow.cpp MainWindow - addJSObject
+
+The ImageAnalyzer object is created and added to a JavaScript object on the web
+page's mainFrame with \c addToJavaScriptWindowObject().
+
+    The start page is resources/index.html.
+    In one of its <div> regions, we have images, each
+    with an \c onClick() handler that calls \c addImage().
+
+    \snippet examples/webkit/imageanalyzer/resources/index.html sample images
+
+    Clicking an image adds it to an images list.
+
+    \snippet examples/webkit/imageanalyzer/resources/index.html addImage
+
+The \bold {Analyze} button at the bottom of the image list is clicked when we
+want to start the analysis:
+
+    \snippet examples/webkit/imageanalyzer/resources/index.html images list
+
+When the user clicks the \bold {Analyze} button, \c analyzeImages() is called,
+another regular JavaScript method, shown below.
+Notice it assumes the \c imageAnalyzer object is already defined and initialized
+in JavaScript space, but we guaranteed that by connecting our setup slot to the
+appropriate signal, \c javaScriptWindowObjectCleared().
+
+    \snippet examples/webkit/imageanalyzer/resources/index.html analyzeImages
+
+The only methods on \c ImageAnalyzer that we can or do call from JavaScript are
+those which are exposed through Qt's MetaObject system: property getter/setter
+methods,
+\c public \c slots, \c signals, and other \c Q_INVOKABLE functions.
+
+\snippet examples/webkit/imageanalyzer/imageanalyzer.h ImageAnalyzer - public interface
+\dots
+\snippet examples/webkit/imageanalyzer/imageanalyzer.h ImageAnalyzer - private members
+
+Most of the members are set up in the constructor:
+
+\snippet examples/webkit/imageanalyzer/imageanalyzer.cpp ImageAnalyzer - Constructor
+
+Back on the JavaScript side, we want to connect signals from this object to
+JavaScript functions on our web page, after the web page is loaded, but before
+the images are analyzed.
+
+From \c connectSlots(), we can see how to connect signals from the imageAnalyzer
+object to regular JavaScript functions, which can also behave like slots. We use
+this to monitor and display progress from the C++ side.
+
+    \snippet examples/webkit/imageanalyzer/resources/index.html connect slots
+
+The only public slot is \c startAnalysis(), called to place
+a list of URLs into the image analyzer's QtConcurrent processing queue
+from JavaScript space.
+
+\snippet examples/webkit/imageanalyzer/imageanalyzer.cpp ImageAnalyzer - startAnalysis
+
+The images need to be loaded again now, which is why fetchURLs first checks the
+cache to see if we can save an extra network get.
+
+\snippet examples/webkit/imageanalyzer/imageanalyzer.cpp ImageAnalyzer - fetchURLs
+
+For the images that were not in the cache, \c handleReply()
+will load them into a QImage when the data is ready.
+
+\snippet examples/webkit/imageanalyzer/imageanalyzer.cpp ImageAnalyzer - handleReply
+
+After the images are loaded, they are queued up in preparation to be
+sent in a batch for analysis to a \c QFutureWatcher, which will distribute the
+processing across multiple threads and cores, depending on how many are available.
+
+\snippet examples/webkit/imageanalyzer/imageanalyzer.cpp ImageAnalyzer - queueImage
+
+The function that gets performed on each image is \c averageRGB(),
+as specified in argument 2 to the \c QtConcurrent::mapped() function.
+Notice it repeats the same calculations 100 times on each pixel to keep the CPU
+very busy. This is done only for the purposes of the demo so that the analysis
+takes a noticeable time to complete.
+
+\snippet examples/webkit/imageanalyzer/imageanalyzer.cpp ImageAnalyzer - averageRGB
+
+*/
+