source: trunk/doc/src/examples/domtraversal.qdoc@ 846

/****************************************************************************
**
** Copyright (C) 2011 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$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** 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/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 examples/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 \mdash 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 examples/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 examples/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 examples/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 examples/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 examples/webkit/simpleselector/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.
*/