| /**************************************************************************** |
| ** |
| ** Copyright (C) 2017 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** 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 The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \example recipes |
| \title Recipes Example |
| \ingroup xmlpattern_examples |
| \brief Using Qt XML Patterns to query XML data loaded from a file. |
| |
| The Recipes example shows how to use Qt XML Patterns 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 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 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 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 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 recipes/querymainwindow.cpp 1 |
| |
| \l{evaluate() function} {evaluate()} demonstrates the standard |
| Qt XML Patterns 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 |
| Qt XML Patterns to parse the XQuery. \l{QXmlQuery::isValid()} is |
| called to ensure that the XQuery was correctly parsed. |
| |
| \target evaluate() function |
| \snippet 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: |
| |
| \badcode |
| (: 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. |
| |
| */ |