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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
/****************************************************************************
**
** 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 xmlpatterns/recipes
\title Recipes Example
\brief The Recipes example shows how to use QtXmlPatterns to query XML data
loaded from a file.
\tableofcontents
\section1 Introduction
In this case, the XML data represents a cookbook, \c{cookbook.xml},
which contains \c{<cookbook>} as its document element, which in turn
contains a sequence of \c{<recipe>} elements. This XML data is
searched using queries stored in XQuery files (\c{*.xq}).
\section2 The User Interface
The UI for this example was created using \l{Qt Designer Manual} {Qt
Designer}:
\image recipes-example.png
The UI consists of three \l{QGroupBox} {group boxes} arranged
vertically. The top one contains a \l{QTextEdit} {text viewer} that
displays the XML text from the cookbook file. The middle group box
contains a \l{QComboBox} {combo box} for choosing the \l{A Short
Path to XQuery} {XQuery} to run and a \l{QTextEdit} {text viewer}
for displaying the text of the selected XQuery. The \c{.xq} files in
the file list above are shown in the combo box menu. Choosing an
XQuery loads, parses, and runs the selected XQuery. The query result
is shown in the bottom group box's \l{QTextEdit} {text viewer}.
\section2 Running your own XQueries
You can write your own XQuery files and run them in the example
program. The file \c{xmlpatterns/recipes/recipes.qrc} is the \l{The
Qt Resource System} {resource file} for this example. It is used in
\c{main.cpp} (\c{Q_INIT_RESOURCE(recipes);}). It lists the XQuery
files (\c{.xq}) that can be selected in the combobox.
\quotefromfile examples/xmlpatterns/recipes/recipes.qrc
\printuntil
To add your own queries to the example's combobox, store your
\c{.xq} files in the \c{examples/xmlpatterns/recipes/files}
directory and add them to \c{recipes.qrc} as shown above.
\section1 Code Walk-Through
The example's main() function creates the standard instance of
QApplication. Then it creates an instance of the UI class, shows it,
and starts the Qt event loop:
\snippet examples/xmlpatterns/recipes/main.cpp 0
\section2 The UI Class: QueryMainWindow
The example's UI is a conventional Qt GUI application inheriting
QMainWindow and the class generated by \l{Qt Designer Manual} {Qt
Designer}:
\snippet examples/xmlpatterns/recipes/querymainwindow.h 0
The constructor finds the window's \l{QComboBox} {combo box} child
widget and connects its \l{QComboBox::currentIndexChanged()}
{currentIndexChanged()} signal to the window's \c{displayQuery()}
slot. It then calls \c{loadInputFile()} to load \c{cookbook.xml} and
display its contents in the top group box's \l{QTextEdit} {text
viewer} . Finally, it finds the XQuery files (\c{.xq}) and adds each
one to the \l{QComboBox} {combo box} menu.
\snippet examples/xmlpatterns/recipes/querymainwindow.cpp 0
The work is done in the \l{displayQuery() slot} {displayQuery()}
slot and the \l{evaluate() function} {evaluate()} function it
calls. \l{displayQuery() slot} {displayQuery()} loads and displays
the selected query file and passes the XQuery text to \l{evaluate()
function} {evaluate()}.
\target displayQuery() slot
\snippet examples/xmlpatterns/recipes/querymainwindow.cpp 1
\l{evaluate() function} {evaluate()} demonstrates the standard
QtXmlPatterns usage pattern. First, an instance of QXmlQuery is
created (\c{query}). The \c{query's} \l{QXmlQuery::bindVariable()}
{bindVariable()} function is then called to bind the \c cookbook.xml
file to the XQuery variable \c inputDocument. \e{After} the variable
is bound, \l{QXmlQuery::setQuery()} {setQuery()} is called to pass
the XQuery text to the \c query.
\note \l{QXmlQuery::setQuery()} {setQuery()} must be called
\e{after} \l{QXmlQuery::bindVariable()} {bindVariable()}.
Passing the XQuery to \l{QXmlQuery::setQuery()} {setQuery()} causes
QtXmlPatterns to parse the XQuery. \l{QXmlQuery::isValid()} is
called to ensure that the XQuery was correctly parsed.
\target evaluate() function
\snippet examples/xmlpatterns/recipes/querymainwindow.cpp 2
If the XQuery is valid, an instance of QXmlFormatter is created to
format the query result as XML into a QBuffer. To evaluate the
XQuery, an overload of \l{QXmlQuery::evaluateTo()} {evaluateTo()} is
called that takes a QAbstractXmlReceiver for its output
(QXmlFormatter inherits QAbstractXmlReceiver). Finally, the
formatted XML result is displayed in the UI's bottom text view.
\note Each XQuery \c{.xq} file must declare the \c{$inputDocument}
variable to represent the \c cookbook.xml document:
\code
(: All ingredients for Mushroom Soup. :)
declare variable $inputDocument external;
doc($inputDocument)/cookbook/recipe[@xml:id = "MushroomSoup"]/ingredient/
<p>{@name, @quantity}</p>
\endcode
\note If you add add your own query.xq files, you must declare the
\c{$inputDocument} and use it as shown above.
*/
|
