source: trunk/doc/src/examples/recipes.qdoc@ 523

/****************************************************************************
**
** 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$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.

*/