3 files changed, 127 insertions, 1 deletions
diff --git a/examples/webkit/domtraversal/doc/images/webkit-domtraversal.png b/examples/webkit/domtraversal/doc/images/webkit-domtraversal.png
new file mode 100644
index 0000000..8b6f34a
--- /dev/null
+++ b/examples/webkit/domtraversal/doc/images/webkit-domtraversal.png
diff --git a/examples/webkit/domtraversal/doc/src/domtraversal.qdoc b/examples/webkit/domtraversal/doc/src/domtraversal.qdoc
new file mode 100644
index 0000000..9f34290
--- /dev/null
+++ b/examples/webkit/domtraversal/doc/src/domtraversal.qdoc
@@ -0,0 +1,125 @@
+/****************************************************************************
+**
+** 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/domtraversal
+    \title DOM Traversal Example
+
+    The DOM Traversal example shows how to use the QWebElement class to access
+    the structure of a Web page.
+
+    \image webkit-domtraversal.png
+
+    The QWebElement class provides an API that can be used to examine the structure
+    and content of a Web page via a Document Object Model (DOM) interface. It can be
+    used for basic traversal of the document structure, to search for particular
+    elements (see the \l{Simple Selector Example}), and to modify content in-place.
+
+    This example uses a QWebView widget to display the Web page, and a dock widget
+    holds the QTreeWidget that shows the document structure. These widgets are
+    placed in an instance of the \c Window class, which we describe below.
+
+    \section1 Window Class Definition
+
+    The \c Window class is derived from QMainWindow and its user interface is created
+    using \l{Qt Designer}. As a result, the class is also derived from the user
+    interface class created by \l uic:
+
+    \snippet webkit/domtraversal/window.h Window class definition
+
+    Two important functions to note are the \c on_webView_loadFinished() slot and
+    the \c examineChildElements() function. The former is automatically called
+    when the QWebView widget finishes loading a page. See the
+    \l{#Further Reading}{Further Reading} section for more information on this
+    mechanism.
+
+    The \c examineChildElements() function is used to traverse the document structure
+    and add items to the QTreeWidget.
+
+    \section1 Window Class Implementation
+
+    In the \c Window class constructor, we call the \l{QWidget::}{setupUi()} function
+    to set up the user interface described in the \c{window.ui} file:
+
+    \snippet webkit/domtraversal/window.cpp Window constructor
+
+    When the Web page is loaded, the \c on_webView_loadFinished() slot is called. Here,
+    we clear the tree widget and begin inspection of the document by obtaining the
+    document element from the page's main frame:
+
+    \snippet webkit/domtraversal/window.cpp begin document inspection
+
+    At this point, we call the \c examineChildElements() function to traverse the
+    document, starting with the child elements of the document element for which we
+    will create top level items in the tree widget.
+
+    The \c examineChildElements() function accepts a parent element and a parent item.
+    Starting with the first child element, which we obtain with the element's
+    \l{QWebElement::}{firstChild()} function, we examine each child element of the
+    parent item. For each valid (non-null) element, which we check by calling its
+    \l{QWebElement::}{isNull()} function, we create a new QTreeWidgetItem instance with
+    the element name and add it to the parent item.
+
+    \snippet webkit/domtraversal/window.cpp traverse document
+
+    We recursively examine the child elements for each element by calling
+    \c examineChildElements() with the current child element and the newly-created item.
+    To obtain the next element at the same level in the document, we call its
+    \l{QWebElement::}{nextSibling()} function.
+
+    This recursive approach to reading the document makes it easy to create a simple
+    representation of the document structure in a tree widget.
+
+    For completeness, we show the \c setUrl() function, which is provided to allow the
+    document URL to be set from the example's \c main() function.
+
+    \snippet webkit/domtraversal/window.cpp set URL
+
+    \section1 Starting the Example
+
+    We set up the application, create
+    a \c Window instance, set its URL, and show it:
+
+    \snippet webkit/domtraversal/main.cpp main program
+
+    When the application's event loop is run, the Qt home page will load, and the
+    tree widget will be updated to show the document structure. Navigating to another
+    page will cause the tree widget to be updated to show the document structure of
+    the new page.
+
+    \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. The user interface
+    contains a QWebView widget called \c webView whose \l{QWebView::}{loadFinished()}
+    signal is automatically connected to the \c on_webView_loadFinished() slot when
+    we call \l{QWidget::}{setupUi()} in the \c Window constructor.
+*/
diff --git a/examples/webkit/domtraversal/main.cpp b/examples/webkit/domtraversal/main.cpp
index 014086a..d105e47 100644
--- a/examples/webkit/domtraversal/main.cpp
+++ b/examples/webkit/domtraversal/main.cpp
@@ -37,7 +37,7 @@
 ** $QT_END_LICENSE$
 **
 ****************************************************************************/
-
+//! [main program]
 #include <QApplication>
 #include "window.h"
 
@@ -49,3 +49,4 @@ int main(int argc, char *argv[])
     window.setUrl(QUrl("http://qt-project.org/"));
     return app.exec();
 }
+//! [main program]