/****************************************************************************
**
** 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 webkitwidgets/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.

    \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 webkitwidgets/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 webkitwidgets/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 webkitwidgets/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 webkitwidgets/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 webkitwidgets/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 webkitwidgets/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.
*/
