--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/recipes.qdoc Thu Apr 08 14:19:33 2010 +0300
@@ -0,0 +1,164 @@
+/****************************************************************************
+**
+** 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: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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $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{<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.
+
+*/