/**************************************************************************** ** ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). ** Contact: Nokia Corporation (qt-info@nokia.com) ** ** This file is part of the documentation of the Qt Toolkit. ** ** $QT_BEGIN_LICENSE:LGPL$ ** No Commercial Usage ** This file contains pre-release code and may not be distributed. ** You may use this file in accordance with the terms and conditions ** contained in the either Technology Preview License Agreement or the ** Beta Release License Agreement. ** ** GNU Lesser General Public License Usage ** Alternatively, this file may be used under the terms of the GNU Lesser ** General Public License version 2.1 as published by the Free Software ** Foundation and appearing in the file LICENSE.LGPL included in the ** packaging of this file. Please review the following information to ** ensure the GNU Lesser General Public License version 2.1 requirements ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. ** ** In addition, as a special exception, Nokia gives you certain ** additional rights. These rights are described in the Nokia Qt LGPL ** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this ** package. ** ** GNU General Public License Usage ** Alternatively, this file may be used under the terms of the GNU ** General Public License version 3.0 as published by the Free Software ** Foundation and appearing in the file LICENSE.GPL included in the ** packaging of this file. Please review the following information to ** ensure the GNU General Public License version 3.0 requirements will be ** met: http://www.gnu.org/copyleft/gpl.html. ** ** If you are unsure which license is appropriate for your use, please ** contact the sales department at http://www.qtsoftware.com/contact. ** $QT_END_LICENSE$ ** ****************************************************************************/ /*! \example xmlpatterns/recipes \title Recipes Example 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{} as its document element, which in turn contains a sequence of \c{} 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/

{@name, @quantity}

\endcode \note If you add add your own query.xq files, you must declare the \c{$inputDocument} and use it as shown above. */