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
|
/****************************************************************************
**
** Copyright (C) 2010 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.
*/
|
