1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
/****************************************************************************
**
** Copyright (C) 2013 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.
*/
|
