1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: http://www.qt-project.org/
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
10 ** GNU Free Documentation License
11 ** Alternatively, this file may be used under the terms of the GNU Free
12 ** Documentation License version 1.3 as published by the Free Software
13 ** Foundation and appearing in the file included in the packaging of
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \example xmlpatterns/recipes
30 \title Recipes Example
32 The Recipes example shows how to use QtXmlPatterns to query XML data
37 \section1 Introduction
39 In this case, the XML data represents a cookbook, \c{cookbook.xml},
40 which contains \c{<cookbook>} as its document element, which in turn
41 contains a sequence of \c{<recipe>} elements. This XML data is
42 searched using queries stored in XQuery files (\c{*.xq}).
44 \section2 The User Interface
46 The UI for this example was created using \l{Qt Designer Manual} {Qt
49 \image recipes-example.png
51 The UI consists of three \l{QGroupBox} {group boxes} arranged
52 vertically. The top one contains a \l{QTextEdit} {text viewer} that
53 displays the XML text from the cookbook file. The middle group box
54 contains a \l{QComboBox} {combo box} for choosing the \l{A Short
55 Path to XQuery} {XQuery} to run and a \l{QTextEdit} {text viewer}
56 for displaying the text of the selected XQuery. The \c{.xq} files in
57 the file list above are shown in the combo box menu. Choosing an
58 XQuery loads, parses, and runs the selected XQuery. The query result
59 is shown in the bottom group box's \l{QTextEdit} {text viewer}.
61 \section2 Running your own XQueries
63 You can write your own XQuery files and run them in the example
64 program. The file \c{xmlpatterns/recipes/recipes.qrc} is the \l{The
65 Qt Resource System} {resource file} for this example. It is used in
66 \c{main.cpp} (\c{Q_INIT_RESOURCE(recipes);}). It lists the XQuery
67 files (\c{.xq}) that can be selected in the combobox.
69 \quotefromfile examples/xmlpatterns/recipes/recipes.qrc
72 To add your own queries to the example's combobox, store your
73 \c{.xq} files in the \c{examples/xmlpatterns/recipes/files}
74 directory and add them to \c{recipes.qrc} as shown above.
76 \section1 Code Walk-Through
78 The example's main() function creates the standard instance of
79 QApplication. Then it creates an instance of the UI class, shows it,
80 and starts the Qt event loop:
82 \snippet examples/xmlpatterns/recipes/main.cpp 0
84 \section2 The UI Class: QueryMainWindow
86 The example's UI is a conventional Qt GUI application inheriting
87 QMainWindow and the class generated by \l{Qt Designer Manual} {Qt
90 \snippet examples/xmlpatterns/recipes/querymainwindow.h 0
92 The constructor finds the window's \l{QComboBox} {combo box} child
93 widget and connects its \l{QComboBox::currentIndexChanged()}
94 {currentIndexChanged()} signal to the window's \c{displayQuery()}
95 slot. It then calls \c{loadInputFile()} to load \c{cookbook.xml} and
96 display its contents in the top group box's \l{QTextEdit} {text
97 viewer} . Finally, it finds the XQuery files (\c{.xq}) and adds each
98 one to the \l{QComboBox} {combo box} menu.
100 \snippet examples/xmlpatterns/recipes/querymainwindow.cpp 0
102 The work is done in the \l{displayQuery() slot} {displayQuery()}
103 slot and the \l{evaluate() function} {evaluate()} function it
104 calls. \l{displayQuery() slot} {displayQuery()} loads and displays
105 the selected query file and passes the XQuery text to \l{evaluate()
106 function} {evaluate()}.
108 \target displayQuery() slot
109 \snippet examples/xmlpatterns/recipes/querymainwindow.cpp 1
111 \l{evaluate() function} {evaluate()} demonstrates the standard
112 QtXmlPatterns usage pattern. First, an instance of QXmlQuery is
113 created (\c{query}). The \c{query's} \l{QXmlQuery::bindVariable()}
114 {bindVariable()} function is then called to bind the \c cookbook.xml
115 file to the XQuery variable \c inputDocument. \e{After} the variable
116 is bound, \l{QXmlQuery::setQuery()} {setQuery()} is called to pass
117 the XQuery text to the \c query.
119 \note \l{QXmlQuery::setQuery()} {setQuery()} must be called
120 \e{after} \l{QXmlQuery::bindVariable()} {bindVariable()}.
122 Passing the XQuery to \l{QXmlQuery::setQuery()} {setQuery()} causes
123 QtXmlPatterns to parse the XQuery. \l{QXmlQuery::isValid()} is
124 called to ensure that the XQuery was correctly parsed.
126 \target evaluate() function
127 \snippet examples/xmlpatterns/recipes/querymainwindow.cpp 2
129 If the XQuery is valid, an instance of QXmlFormatter is created to
130 format the query result as XML into a QBuffer. To evaluate the
131 XQuery, an overload of \l{QXmlQuery::evaluateTo()} {evaluateTo()} is
132 called that takes a QAbstractXmlReceiver for its output
133 (QXmlFormatter inherits QAbstractXmlReceiver). Finally, the
134 formatted XML result is displayed in the UI's bottom text view.
136 \note Each XQuery \c{.xq} file must declare the \c{$inputDocument}
137 variable to represent the \c cookbook.xml document:
140 (: All ingredients for Mushroom Soup. :)
141 declare variable $inputDocument external;
143 doc($inputDocument)/cookbook/recipe[@xml:id = "MushroomSoup"]/ingredient/
144 <p>{@name, @quantity}</p>
147 \note If you add add your own query.xq files, you must declare the
148 \c{$inputDocument} and use it as shown above.