/****************************************************************************

**

** 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.

*/