/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
  \example recipes
  \title Recipes Example
  \ingroup xmlpattern_examples
  \brief Using Qt XML Patterns to query XML data loaded from a file.

  The Recipes example shows how to use Qt XML Patterns 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 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 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 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 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 recipes/querymainwindow.cpp 1

  \l{evaluate() function} {evaluate()} demonstrates the standard
  Qt XML Patterns 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
  Qt XML Patterns to parse the XQuery. \l{QXmlQuery::isValid()} is
  called to ensure that the XQuery was correctly parsed.

  \target evaluate() function
  \snippet 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:

  \badcode
  (: 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.

*/