1 files changed, 164 insertions, 0 deletions
diff --git a/doc/src/examples/recipes.qdoc b/doc/src/examples/recipes.qdoc
new file mode 100644
index 0000000..ba06b7e
--- /dev/null
+++ b/doc/src/examples/recipes.qdoc
@@ -0,0 +1,164 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 qt-sales@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.
+
+*/