diff options
author | Venugopal Shivashankar <venugopal.shivashankar@digia.com> | 2012-12-11 18:15:48 +0100 |
---|---|---|
committer | The Qt Project <gerrit-noreply@qt-project.org> | 2012-12-12 18:26:45 +0100 |
commit | a2d8aa1b462b709c9a18292eb57971eaaeb18dbe (patch) | |
tree | a7f8941dc990f712e54750ff14d73cff2b2b32a5 /examples/webkitwidgets | |
parent | e88665589b06aa0d87a5185cc780ed767cff0f70 (diff) | |
download | qtwebkit-examples-a2d8aa1b462b709c9a18292eb57971eaaeb18dbe.tar.gz |
Doc: Added documentation for the WebKit Widget examples
- Moved the qdoc files from the qtdoc repository
- Added group pages for QML and QWidget-based examples
- Added an index page
- Updated the qhp details in the qdocconf
Change-Id: I5f79fb1aedbfc3bcb42c84ac774ea1c4bd3a9036
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>
Diffstat (limited to 'examples/webkitwidgets')
17 files changed, 825 insertions, 0 deletions
diff --git a/examples/webkitwidgets/browser/doc/images/browser-demo.png b/examples/webkitwidgets/browser/doc/images/browser-demo.png Binary files differnew file mode 100644 index 0000000..09d0650 --- /dev/null +++ b/examples/webkitwidgets/browser/doc/images/browser-demo.png diff --git a/examples/webkitwidgets/browser/doc/src/browser.qdoc b/examples/webkitwidgets/browser/doc/src/browser.qdoc new file mode 100644 index 0000000..bdb004c --- /dev/null +++ b/examples/webkitwidgets/browser/doc/src/browser.qdoc @@ -0,0 +1,41 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example browser + \title Tab Browser + \brief Demonstrates a complete web browsing experience + \ingroup webkit-widgetexamples + + The Tab Browser example shows \l{Qt WebKit} module in action, + providing a little Web browser application with support for tabs. + + \image browser-demo.png + + This browser is the foundation for the \l{Arora Browser}, a simple cross-platform + Web browser. +*/ diff --git a/examples/webkitwidgets/domtraversal/doc/src/domtraversal.qdoc b/examples/webkitwidgets/domtraversal/doc/src/domtraversal.qdoc index 52764f3..86b1616 100644 --- a/examples/webkitwidgets/domtraversal/doc/src/domtraversal.qdoc +++ b/examples/webkitwidgets/domtraversal/doc/src/domtraversal.qdoc @@ -28,6 +28,8 @@ /*! \example domtraversal \title DOM Traversal Example + \brief Demonstrates how to traverse the DOM tree + \ingroup webkit-widgetexamples \brief The DOM Traversal example shows how to use the QWebElement class to access the structure of a Web page. diff --git a/examples/webkitwidgets/fancybrowser/doc/src/fancybrowser.qdoc b/examples/webkitwidgets/fancybrowser/doc/src/fancybrowser.qdoc index 7734478..0c6f417 100644 --- a/examples/webkitwidgets/fancybrowser/doc/src/fancybrowser.qdoc +++ b/examples/webkitwidgets/fancybrowser/doc/src/fancybrowser.qdoc @@ -28,6 +28,8 @@ /*! \example fancybrowser \title Fancy Browser Example + \brief Demonstrates how to use browse web and manipulate content + \ingroup webkit-widgetexamples \brief The Fancy Browser example shows how to use JQuery with QtWebKit to create a web browser with special effects and content diff --git a/examples/webkitwidgets/formextractor/doc/src/formextractor.qdoc b/examples/webkitwidgets/formextractor/doc/src/formextractor.qdoc index 5b27054..b8d2755 100644 --- a/examples/webkitwidgets/formextractor/doc/src/formextractor.qdoc +++ b/examples/webkitwidgets/formextractor/doc/src/formextractor.qdoc @@ -28,6 +28,8 @@ /*! \example formextractor \title Form Extractor Example + \brief Demonstrates how to read form data using JavaScript + \ingroup webkit-widgetexamples \brief The Form Extractor example shows how to use QWebFrame with JavaScript to extract form data. diff --git a/examples/webkitwidgets/framecapture/doc/images/framecapture-example.png b/examples/webkitwidgets/framecapture/doc/images/framecapture-example.png Binary files differnew file mode 100644 index 0000000..edccf6b --- /dev/null +++ b/examples/webkitwidgets/framecapture/doc/images/framecapture-example.png diff --git a/examples/webkitwidgets/framecapture/doc/src/webkit-framecapture.qdoc b/examples/webkitwidgets/framecapture/doc/src/webkit-framecapture.qdoc new file mode 100644 index 0000000..b616011 --- /dev/null +++ b/examples/webkitwidgets/framecapture/doc/src/webkit-framecapture.qdoc @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example webkit/framecapture + \title WebKit Frame Capture Example + \brief Demonstrates how to capture frame in the web page + \ingroup webkit-widgetexamples + + The Frame Capture example shows how to use the WebKit browser engine to + obtain images of frames in a Web page. + + This example is designed to be run from the command-line. Run the + example with a URL and the output file name as arguments. The application + captures the frame contents in a PNG image with the file name your + specified. + + The following output image is generated by the application, if you pass the + URL, www.qt-project.org. + + \image framecapture-example.png +*/ diff --git a/examples/webkitwidgets/imageanalyzer/doc/images/webkit-imageanalyzer-progress.png b/examples/webkitwidgets/imageanalyzer/doc/images/webkit-imageanalyzer-progress.png Binary files differnew file mode 100644 index 0000000..530effb --- /dev/null +++ b/examples/webkitwidgets/imageanalyzer/doc/images/webkit-imageanalyzer-progress.png diff --git a/examples/webkitwidgets/imageanalyzer/doc/images/webkit-imageanalyzer-screenshot.png b/examples/webkitwidgets/imageanalyzer/doc/images/webkit-imageanalyzer-screenshot.png Binary files differnew file mode 100644 index 0000000..cb0c42c --- /dev/null +++ b/examples/webkitwidgets/imageanalyzer/doc/images/webkit-imageanalyzer-screenshot.png diff --git a/examples/webkitwidgets/imageanalyzer/doc/images/wekit-imageanalyzer-complete.png b/examples/webkitwidgets/imageanalyzer/doc/images/wekit-imageanalyzer-complete.png Binary files differnew file mode 100644 index 0000000..83bfb26 --- /dev/null +++ b/examples/webkitwidgets/imageanalyzer/doc/images/wekit-imageanalyzer-complete.png diff --git a/examples/webkitwidgets/imageanalyzer/doc/src/webkit-bridge-imageanalyzer.qdoc b/examples/webkitwidgets/imageanalyzer/doc/src/webkit-bridge-imageanalyzer.qdoc new file mode 100644 index 0000000..44ce91c --- /dev/null +++ b/examples/webkitwidgets/imageanalyzer/doc/src/webkit-bridge-imageanalyzer.qdoc @@ -0,0 +1,162 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example webkit/imageanalyzer + \title The Webkit Bridge Tutorial - Hybrid Client Application + \brief Demonstrates how to integrate web functionality with other core + functionality. + \ingroup webkit-widgetexamples + + 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. + +For the full reference documentation of QtWebKit hybrid development, see +\l{qtwebkit-bridge.html}{The QtWebKit Bridge}. + +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 \b 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 \l QNetworkDiskCache and a +\l QWebView, and tells the \l QWebView to load the starting page, providing us +with a user interface for the client. + + \snippet 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 \l{QWebFrame::}{javaScriptWindowObjectCleared()} signal to a slot +which does the object creation and handoff to JavaScript. + + \snippet 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 webkit/imageanalyzer/resources/index.html sample images + +Clicking an image adds it to an images list. + + \snippet webkit/imageanalyzer/resources/index.html addImage + +The \b {Analyze} button at the bottom of the image list is clicked when we +want to start the analysis: + + \snippet webkit/imageanalyzer/resources/index.html images list + +When the user clicks the \b {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, \l{QWebFrame::}{javaScriptWindowObjectCleared()}. + + \snippet 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 \{The Meta-Object System}{Qt's MetaObject} +system: \l{The Property System}{property} getter/setter methods, +\c public \l {Signals & Slots}{signals and slots}, and other +\l{Q_INVOKABLE}{Q_INVOKABLE} functions. + +\snippet webkit/imageanalyzer/imageanalyzer.h ImageAnalyzer - public interface +\dots +\snippet webkit/imageanalyzer/imageanalyzer.h ImageAnalyzer - private members + +Most of the members are set up in the constructor: + +\snippet 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 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 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 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 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 \l QFutureWatcher, which will distribute the +processing across multiple threads and cores, depending on how many are available. + +\snippet webkit/imageanalyzer/imageanalyzer.cpp ImageAnalyzer - queueImage + +The function that gets performed on each image is \c averageRGB(), +as specified in argument 2 to the \l{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 webkit/imageanalyzer/imageanalyzer.cpp ImageAnalyzer - averageRGB + +*/ + diff --git a/examples/webkitwidgets/previewer/doc/src/previewer.qdoc b/examples/webkitwidgets/previewer/doc/src/previewer.qdoc index 5a3bdc3..e45dc17 100644 --- a/examples/webkitwidgets/previewer/doc/src/previewer.qdoc +++ b/examples/webkitwidgets/previewer/doc/src/previewer.qdoc @@ -28,6 +28,8 @@ /*! \example previewer \title Previewer Example + \brief Demonstrates how to preview HTML data + \ingroup webkit-widgetexamples \brief The Previewer example shows how to use QtWebKit's QWebView to preview HTML data written in a QPlainTextEdit. diff --git a/examples/webkitwidgets/scroller/wheel/doc/src/wheel.qdoc b/examples/webkitwidgets/scroller/wheel/doc/src/wheel.qdoc new file mode 100644 index 0000000..779f3ca --- /dev/null +++ b/examples/webkitwidgets/scroller/wheel/doc/src/wheel.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example scroller/wheel + \title Wheel Scroller Example + \brief Demonstrates how scrolling is handled in Qt. + \ingroup webkit-widgetexamples + + The Wheel Scroller Example shows how to use QScroller, QScrollEvent + and QScrollPrepareEvent to implement smooth scrolling for a + custom Widget. + + \section1 Basics + + The QScroller class is the main part of the smooth scrolling + mechanism in Qt. It keeps track of the current scroll position and + speed and updates the object through events. + QScroller will get touch events via the QFlickGesture. + It will query the target object through a QScrollPrepareEvent for + the scroll area and other information. + QScroller will send QScrollEvents to inform the target object about + the current scroll position. + The target object (usually a QWidget or a QGraphicsObject) will + then need to update it's graphical representation to reflect the + new scroll position. + + \section1 The Wheel Widget class + + To demonstrate how to use the QScroller we implement a QWidget that + looks and works like the wheel of a slot machine. + The wheel can be started via touch events and will continue getting + slower. + Additionally the wheel should appear as if no border exists (which + would seem unnatural) and the scrolling should snap to center one + item. + + In the widget we need to grab the QFlickGesture. The gesture itself + will setAcceptTouchEvents for us, so we don't need to do that here. + + \snippet scroller/wheel/wheelwidget.cpp 0 + + The widget will get gesture events but in addition we also will + get the events from QScroller. + We will need to accept the QScrollPrepareEvent to indicate that + a scrolling should really be started from the given position. + + \snippet scroller/wheel/wheelwidget.cpp 1 + + We should call all three set functions form QScrollPrepareEvent. + + \list + \li \c setViewportSize to indicate our viewport size. Actually the + given code could be improved by giving our size minus the borders. + \li \c setMaxContentPos to indicate the maximum values for the scroll + position. The minimum values are implicitely set to 0. + In our example we give a very high number here and hope that the user + is not patient enough to scroll until the very end. + \li \c setContentPos to indicate the current scroll position. + We give a position in the middle of the huge scroll area. + Actually we give this position every time a new scroll is started so + the user will only reach the end if he continuously scrolls in one + direction which is not very likely. + \endlist + + The handling of the QScrollEvent is a lengthly code not fully shown here. + \snippet scroller/wheel/wheelwidget.cpp 2 + + In principle it does three steps. + \list + \li It calculates and updates the current scroll position as given by + QScroller. + \li It repaints the widget so that the new position is shown. + \li It centers the item as soon as the scrolling stopps. + \endlist + + The following code does the centering. + \snippet scroller/wheel/wheelwidget.cpp 3 + + We check if the scrolling is finished which is indicated in the + QScrollEvent by the \c isLast flag. + We then check if the item is not already centered and if not start a new + scroll by calling QScroller::scrollTo. + + As you can see the QScroller can be used for other things besides simple + scroll areas. +*/ diff --git a/examples/webkitwidgets/simpleselector/doc/images/webkit-simpleselector.png b/examples/webkitwidgets/simpleselector/doc/images/webkit-simpleselector.png Binary files differnew file mode 100644 index 0000000..a0aa28a --- /dev/null +++ b/examples/webkitwidgets/simpleselector/doc/images/webkit-simpleselector.png diff --git a/examples/webkitwidgets/simpleselector/doc/src/simpleselector.qdoc b/examples/webkitwidgets/simpleselector/doc/src/simpleselector.qdoc new file mode 100644 index 0000000..f42824a --- /dev/null +++ b/examples/webkitwidgets/simpleselector/doc/src/simpleselector.qdoc @@ -0,0 +1,116 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example webkit/simpleselector + \title Simple Selector Example + \brief Demonstrates how to identify HTML elements in a web page + \ingroup webkit-widgetexamples + + The Simple Selector example shows how to use QWebElement to access the + Document Object Model (DOM) in a Web page. + + \image webkit-simpleselector.png + + The QWebElement class enables access to the document structure and content in a Web page, + as represented by a QWebFrame instance. It can be used for basic traversal of the document + structure (see the \l{DOM Traversal Example}), to search for particular elements, and to + modify any elements found. + + This example uses a QWebView widget to display a Web page. A QLineEdit widget and QPushButton + allow the user to enter a query and highlight the results in the page. These widgets are + contained in an instance of the \c Window class, which we described below. + + \section1 Window Class Definition + + The \c Window class describes the example's user interface and this is partially described + by the \c window.ui file, created using \l{Qt Designer}: + + \snippet webkit/simpleselector/window.h Window class definition + + We use \l{Using a Designer UI File in Your Application#The Multiple Inheritance Approach} + {multiple inheritance} to include the user interface description. We define slots that + will automatically respond to signals emitted by certain user interface controls. + + \section1 Window Class Implementation + + Since the layout of the user interface is provided by the \c{window.ui} user interface file, + we only need to call the \l{QWidget::}{setupUi()} in the constructor: + + \snippet webkit/simpleselector/window.cpp Window class constructor + + This adds all the controls to the window and sets up connections between their signals + and suitably-named slots in the \c Window class. The QLineEdit instance was given a name of + \c elementLineEdit in Qt Designer, so the \c{on_elementLineEdit_returnPressed()} slot is + automatically connected to its \l{QLineEdit::}{returnPressed()} signal. + + This slot performs the main work of this example. We begin by obtaining a QWebFrame + instance for the current page shown in the QWebView widget. Each QWebFrame contains + a QWebElement instance that represents the document, and we obtain this in order to + examine its contents: + + \snippet webkit/simpleselector/window.cpp return pressed + + Taking the contents of the QLineEdit as the query text, we call the element's + \l{QWebElement::}{findAll()} function to obtain a list of elements that match the + query. + + For each element obtained, we modify its style by setting its \c style attribute + to give it a yellow background color. + + Since we also want the query to be performed when the user clicks the \gui Highlight + button, we also implement the \c{on_highlightButton_clicked()} slot to simply call + the \c{on_elementLineEdit_returnPressed()} slot when it is invoked: + + \snippet webkit/simpleselector/window.cpp button clicked + + For completeness, we also implement a \c setUrl() function which simply passes on + a QUrl instance to the equivalent function in the QWebView widget: + + \snippet webkit/simpleselector/window.cpp set URL + + \section1 Starting the Example + + The main function implementation is simple. We set up the application, create + a \c Window instance, set its URL, and show it: + + \snippet webkit/simpleselector/main.cpp main program + + When the application's event loop is run, the WebKit home page will load, and the + user can then begin to start running queries against the contents of the page. + The highlighting can only be removed by reloading the page. To do this, open a + context menu over the page and select the \gui Reload menu item. + + \section1 Further Reading + + The QWebElement documentation contains more information about DOM access for the + QtWebKit classes. + + In this example, we take advantage of Qt's + \l{Using a Designer UI File in Your Application#Automatic Connections}{auto-connection} + feature to avoid explicitly connecting signals to slots. +*/ diff --git a/examples/webkitwidgets/xmlpatterns/doc/images/qobjectxmlmodel-example.png b/examples/webkitwidgets/xmlpatterns/doc/images/qobjectxmlmodel-example.png Binary files differnew file mode 100644 index 0000000..e40ba15 --- /dev/null +++ b/examples/webkitwidgets/xmlpatterns/doc/images/qobjectxmlmodel-example.png diff --git a/examples/webkitwidgets/xmlpatterns/doc/src/qobjectxmlmodel.qdoc b/examples/webkitwidgets/xmlpatterns/doc/src/qobjectxmlmodel.qdoc new file mode 100644 index 0000000..f386df3 --- /dev/null +++ b/examples/webkitwidgets/xmlpatterns/doc/src/qobjectxmlmodel.qdoc @@ -0,0 +1,341 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xmlpatterns/qobjectxmlmodel + \title QObject XML Model Example + \brief Demonstrates how to present XML-like data structure in the web view + \ingroup webkit-widgetexamples + + This example shows how to use QtXmlPatterns to query QObject trees + by modeling the non-XML data structure of a QObject tree to look + like XML. + + \tableofcontents + + \section1 Introduction + + This example illustrates two important points about using XQuery to + query non-XML data modeled to look like XML. The first point is that + a custom node model class doesn't always have to actually build the + node model. Sometimes the node model can be an already existing data + structure, like the QObject tree used in this example. The second + point is to explain what is required to make non-XML data look like + XML. + + In this example, we want to model a QObject tree to look like + XML. That is easy to do because a QObject tree maps to the XML tree + structure in a staightforward way. Each QObject node is modeled as + an XML element node. However, when we want to add the QMetaObject tree + to the QObject tree node model, we are trying to add a second tree to + the node model. The QMetaObject tree exists \e{behind} the QObject + tree. Adding the QMetaObject tree to the node model changes the two + dimensional tree into a three dimensional tree. + + The query engine can only traverse two dimensional trees, because an + XML document is always a two dimensional tree. If we want to add the + QMetaObject tree to the node model, we have to somehow flatten it + into the same plane as the QObject tree. This requires that the + node model class must build an auxiliary data structure and make it + part of the two dimensional QObject node model. How to do this is + explained in \l{Including The QMetaObject Tree}. + + \section2 The User Interface + + The UI for this example was created using Qt Designer: + + \image qobjectxmlmodel-example.png + + \section1 Code Walk-Through + + The strategy for this example is different from the strategy for the + \l{File System Example}{file system example}. In the file system + example, the node model class had to actually build a node model + because the non-XML data to be traversed was the computer's file + system, a structure stored on disk in a form that the query engine + couldn't use. The node model class had to build an analog of the + computer's file system in memory. + + For this example, the data structure to be traversed already exists + in memory in a usable form. It is the QObject tree of the example + application itself. All we need is the pointer to the root of the + QObject tree. + + \note When we add the QMetaObject tree to the node model, the node + model class will have to build an auxiliary data structure to move + the QMetaObject tree into the same plane as the QObject tree. This + is explained later in \l{Including The QMetaObject Tree}. + + \section2 The Custom Node Model Class: QObjextXmlModel + + The node model class for this example is QObjextXmlModel, which is + derived from QSimpleXmlNodeModel. QObjextXmlModel implements the + callback interface functions that don't have implementations in + QSimpleXmlNodeModel: + + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.h 0 + + The node model class declares three data members: + + \target Three Data Members + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.h 2 + + The constructor sets \c m_baseURI to the QUrl constructed from the + \l{QCoreApplication::applicationFilePath()}{file path} of the + application executable. This is the value returned by + \l{QAbstractXmlNodeModel::documentUri()}{documentUri()}. The + constructor sets \c{m_root} to point to the QObject tree for the + example application. This is the node model that the query engine + will use. And the constructor calls a local function to build the + auxiliary data structure (\c{m_allMetaObjects}) for including the + QMetaObject tree in the node model. How this auxiliary data + structure is incorporated into the QObject node model is discussed + in \l{Including The QMetaObject Tree}. + + \section3 Accessing The Node Model + + Since the query engine knows nothing about QObject trees, it can + only access them by calling functions in the node model callback + interface. The query engine passes a QXmlNodeModelIndex to uniquely + identify a node in the node model. The QXmlNodeModelIndex is + constructed from a pointer to the QObject that represents the node. + \l{QAbstractXmlNodeModel::createIndex()}{createIndex()} creates the + QXmlNodeModelIndex, as in the local \c{root()} function, for example: + + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 0 + + A QObject represents an element node in the node model, but we also + need to represent attribute nodes. For example, the class name of a + QObject is an attribute of the QObject, so it should be an attribute + node in the node model. A QObject's class name is obtained from the + QObject. (Actually, it is in the QMetaObject, which is obtained from + the QObject). This means that a single QObject logically represents + multiple nodes in the node model: the element node and potentially + many attribute nodes. + + To uniquely identify an attribute node, we need the pointer to the + QObject containing the attribute, and an additional value that + identifies the attribute in the QObject. For this \e{additional + data} value, we use \c{enum QObjectNodeType}: + + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.h 3 + + Ignore the \c{MetaObjectXXX} values for now. They will be explained + in \l{Including The QMetaObject Tree}. Here we are interested in the + three node types for QObject nodes: \c{IsQObject}, which represents + the element node type for a QObject, and \c{QObjectProperty} and + \c{QObjectClassName}, which represent the attribute node types for + the attributes of a QObject. + + The \l{QAbstractXmlNodeModel::createIndex()}{createIndex()} + function called in the \c{root()} snippet above is the overload that + accepts a \c{void*} pointer and a second parameter, + \c{additionalData}, with default value 0 (\c{IsQObject}). Wherever + you see a call to \l{QAbstractXmlNodeModel::createIndex()} + {createIndex()} that only passes the QObject pointer, it is creating + the node index for a QObject element node. To create the node index + for the class name attribute, for example, the \l{QObject + attributes} {attributes()} function uses + \c{createIndex(object,QObjectClassName)}. + + \target QObject attributes + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 6 + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 8 + + \l{QObject attributes} {attributes()} is one of the callback + functions you have to implement in your custom node model class. It + returns a QVector of \l{QXmlNodeModelIndex} {node indexes} for all + the attribute nodes for QObject \c{n}. It calls + \l{QAbstractXmlNodeModel::createIndex()} {createIndex()} in two places. + Both calls use the QObject pointer from the current node \c{n} (the + element node), and just add a different value for the \e{additional data} + parameter. This makes sense because, in XML, the attributes of an + element are part of that element. + + \section3 Traversing The Node Model + + The query engine traverses the QObject tree by calling back to the + node model class's implementation of \l{QObject nextFromSimpleAxis} + {nextFromSimpleAxis()}. This function is the heart of the callback + interface, and it will probably be the most complex to implement in + your custom node model class. Below is a partial listing of the + implementation for this example. The full listing will be shown in + \l{Including The QMetaObject Tree}, where we discuss traversing the + QMetaObject tree. + + \target QObject nextFromSimpleAxis + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 2 + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 4 + + The main switch uses \c toNodeType(), which obtains the node + type from \l{QXmlNodeModelIndex::additionalData()}: + + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 1 + + \c{case IsObject} case is the most interesting. It switches again on + the value of the \c{axis} parameter, which specifies the direction + the query engine wants to take from the current node. It is one of + the four enum values of \l{QAbstractXmlNodeModel::SimpleAxis}. The + \l{QAbstractXmlNodeModel::Parent} {Parent} and + \l{QAbstractXmlNodeModel::FirstChild} {FirstChild} cases reduce to + calls to QObject::parent() and QObject::children() + respectively. Note that a default constructed QXmlNodeModelIndex is + returned in the \l{QAbstractXmlNodeModel::Parent} {Parent} case if + the current node is the root, and in the + \l{QAbstractXmlNodeModel::FirstChild} {FirstChild} case if the + current node has no children. + + For the \l{QAbstractXmlNodeModel::NextSibling} {NextSibling} and + \l{QAbstractXmlNodeModel::PreviousSibling} {PreviousSibling} axes, + the helper function \c{qObjectSibling()} is called, with +1 to + traverse to the \l{QAbstractXmlNodeModel::NextSibling} {NextSibling} + and -1 to traverse to the + \l{QAbstractXmlNodeModel::PreviousSibling} {PreviousSibling}. + + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 5 + + \c{qObjectSibling()} determines whether or not the node has any + siblings. It is called with \c{n}, the index of the current node. + If the current node is a child, then it has a parent with children + (the current node one of these). + So, we get the \l{QObject::parent()}{parent}, obtain the parent's + \l{QObject::children()} {child list}, find the current node in the + list, and construct the node index for the next or previous child + (sibling) and return it. + + \note In \l{QObject nextFromSimpleAxis} {nextFromSimpleAxis()}, the + special case of asking for the + \l{QAbstractXmlNodeModel::PreviousSibling} {PreviousSibling} of the + root node is discussed in \l{Including The QMetaObject Tree}. + + Traversing away from a \c{QObjectClassName} attribute node or a + \c{QObjectProperty} attribute node might seem a bit confusing at + first glance. The only move allowed from an attribute node is to the + \l{QAbstractXmlNodeModel::Parent} {Parent}, because attribute nodes + don't have children. But these two cases simply return the + \l{QXmlNodeModelIndex} {node index} of the current node. + + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 7 + + Since \c n is the QXmlNodeModelIndex of the current node, all this + does is create another QXmlNodeModelIndex for the current node and + return it. This was explained above in \l{Accessing The Node Model}, + where we saw that each QObject in the node model actually represents + an element node and potentially many attribute nodes. Traversing to + the parent node of an attribute simply creates a node index for the + same QObject, but with an \e{additional data} value of 0 + (\c{IsQObject}). + + If we only wanted to traverse the QObject tree with XQuery, we could + just implement the rest of the virtual callback functions listed + earlier and we would be done. The implementations for the remaining + functions are straightforward. But if we also want to use XQuery to + traverse the QMetaObject tree, we must include the QMetaObject tree + in the custom node model. + + \section3 Including The QMetaObject Tree + + The \l{Meta-Object System} {metaobject system} not only enables Qt's + \l{Signals and Slots} {signals and slots}, it also provides type + information that is useful at run-time; e.g., getting and setting + properties without knowing the property names at compile time. Each + QObject has an associated QMetaObject tree which contains all this + useful type information. Given a QObject, its QMetaObject is + obtained with QObject::metaObject(). Then QMetaObject::superClass() + can be called repeatedly to get the QMetaObject for each class in the + class hierarchy for the original QObject. + + However, the QMetaObject hierarchy is a second tree in a plan that + exists logically behind the plane of the QObject tree. The QtXmlPatterns + query engine can only traverse a two dimensional node model that + represents an XML tree. If we want to include the QMetaObject in the + same node model that represents the QObject tree, we must find a way + to flatten the QMetaObject tree into the same plane as the QObject + tree. + + The node model class declares \l{All MetaObjects}{m_allMetaObjects} + as a vector of pointers to QMetaObject: + + \target All MetaObjects + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.h 1 + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.h 4 + + This vector gets populated by the QObjectXmlModel constructor by + calling the private allMetaObjects() function: + + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 9 + + The first half of the function is an example of the standard code + pattern for using QtXmlPatterns to run an XQuery. First it creates an + instance of QXmlQuery. Then it \l{QXmlQuery::bindVariable()}{binds} + the XQuery variable \c{$root} to the root node of the of the node + model; i.e., the root of the QObject tree. Then it + \l{QXmlQuery::setQuery()} {sets the query} to be an XQuery that + returns all the QObjects in the node model. Finally, the query is + evaluated into a \l{QXmlResultItems} {result item list}. + + \note \l{QXmlQuery::bindVariable()} must be called before + \l{QXmlQuery::setQuery()}, because setting the query causes + QtXmlPatterns to \e compile the XQuery, which requires knowledge of + the variable bindings. + + The second half of the function traverses the \l{QXmlResultItems} + {result item list}, getting the QMetaObject hierarchy for each + QObject and appending it to \l{All MetaObjects} {m_allMetaObjects}, + if it isn't already there. But how do we include this vector of + pointers to QMetaObjects in the node model? The key insight is + shown in the full listing of \l{Full Listing of nextFromSimpleAxis} + {nextFromSimpleAxis()}, where we are interested now in the + \c{MetaObjectXXX} cases: + + \target Full Listing of nextFromSimpleAxis + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 2 + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 3 + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 4 + + But first, revisit the \c{PreviousSibling} case for the + \c{IsQObject} case: + + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 10 + + When asking for the previous sibling of the root of the QObject + tree, it creates a node model index with a null QObject pointer and + an \c{additionalData} value of \c{MetaObjects}. This effectively + allows the query engine to jump from the QObject tree to the + QMetaObject tree. + + The query engine can jump from the QMetaObject tree back to the + QObject tree in the \c{NextSibling} case of case \c{MetaObjects}, + where the \c{root()} function is called: + + \snippet xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 11 + + Having jumped from the QObject tree to the QMetaObject tree, the + query engine will use the \c{MetaObject}, \c{MetaObjectClassName}, + and \c{MetaObjectSuperClass} cases, which are similar to the cases + for \c{IsQObject}, \c{QObjectProperty}, and \c{QObjectClassName}. +*/ |