doc/src/examples/recipes.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29   \example xmlpatterns/recipes
  30   \title Recipes Example
  31
  32   The Recipes example shows how to use Qt XML Patterns to query XML data
  33   loaded from a file.
  34
  35   \tableofcontents
  36
  37   \section1 Introduction
  38
  39   In this case, the XML data represents a cookbook, \c{cookbook.xml},
  40   which contains \c{<cookbook>} as its document element, which in turn
  41   contains a sequence of \c{<recipe>} elements. This XML data is
  42   searched using queries stored in XQuery files (\c{*.xq}).
  43
  44   \section2 The User Interface
  45
  46   The UI for this example was created using \l{Qt Designer Manual} {Qt
  47   Designer}:
  48
  49   \image recipes-example.png
  50
  51   The UI consists of three \l{QGroupBox} {group boxes} arranged
  52   vertically. The top one contains a \l{QTextEdit} {text viewer} that
  53   displays the XML text from the cookbook file. The middle group box
  54   contains a \l{QComboBox} {combo box} for choosing the \l{A Short
  55   Path to XQuery} {XQuery} to run and a \l{QTextEdit} {text viewer}
  56   for displaying the text of the selected XQuery. The \c{.xq} files in
  57   the file list above are shown in the combo box menu. Choosing an
  58   XQuery loads, parses, and runs the selected XQuery. The query result
  59   is shown in the bottom group box's \l{QTextEdit} {text viewer}.
  60
  61   \section2 Running your own XQueries
  62
  63   You can write your own XQuery files and run them in the example
  64   program. The file \c{xmlpatterns/recipes/recipes.qrc} is the \l{The
  65   Qt Resource System} {resource file} for this example. It is used in
  66   \c{main.cpp} (\c{Q_INIT_RESOURCE(recipes);}). It lists the XQuery
  67   files (\c{.xq}) that can be selected in the combobox.
  68
  69   \quotefromfile xmlpatterns/recipes/recipes.qrc
  70   \printuntil
  71
  72   To add your own queries to the example's combobox, store your
  73   \c{.xq} files in the \c{examples/xmlpatterns/recipes/files}
  74   directory and add them to \c{recipes.qrc} as shown above.
  75
  76   \section1 Code Walk-Through
  77
  78   The example's main() function creates the standard instance of
  79   QApplication. Then it creates an instance of the UI class, shows it,
  80   and starts the Qt event loop:
  81
  82   \snippet xmlpatterns/recipes/main.cpp 0
  83
  84   \section2 The UI Class: QueryMainWindow
  85
  86   The example's UI is a conventional Qt GUI application inheriting
  87   QMainWindow and the class generated by \l{Qt Designer Manual} {Qt
  88   Designer}:
  89
  90   \snippet xmlpatterns/recipes/querymainwindow.h 0
  91
  92   The constructor finds the window's \l{QComboBox} {combo box} child
  93   widget and connects its \l{QComboBox::currentIndexChanged()}
  94   {currentIndexChanged()} signal to the window's \c{displayQuery()}
  95   slot. It then calls \c{loadInputFile()} to load \c{cookbook.xml} and
  96   display its contents in the top group box's \l{QTextEdit} {text
  97   viewer} . Finally, it finds the XQuery files (\c{.xq}) and adds each
  98   one to the \l{QComboBox} {combo box} menu.
  99
 100   \snippet xmlpatterns/recipes/querymainwindow.cpp 0
 101
 102   The work is done in the \l{displayQuery() slot} {displayQuery()}
 103   slot and the \l{evaluate() function} {evaluate()} function it
 104   calls. \l{displayQuery() slot} {displayQuery()} loads and displays
 105   the selected query file and passes the XQuery text to \l{evaluate()
 106   function} {evaluate()}.
 107
 108   \target displayQuery() slot
 109   \snippet xmlpatterns/recipes/querymainwindow.cpp 1
 110
 111   \l{evaluate() function} {evaluate()} demonstrates the standard
 112   Qt XML Patterns usage pattern. First, an instance of QXmlQuery is
 113   created (\c{query}). The \c{query's} \l{QXmlQuery::bindVariable()}
 114   {bindVariable()} function is then called to bind the \c cookbook.xml
 115   file to the XQuery variable \c inputDocument. \e{After} the variable
 116   is bound, \l{QXmlQuery::setQuery()} {setQuery()} is called to pass
 117   the XQuery text to the \c query.
 118
 119   \note \l{QXmlQuery::setQuery()} {setQuery()} must be called
 120   \e{after} \l{QXmlQuery::bindVariable()} {bindVariable()}.
 121
 122   Passing the XQuery to \l{QXmlQuery::setQuery()} {setQuery()} causes
 123   Qt XML Patterns to parse the XQuery. \l{QXmlQuery::isValid()} is
 124   called to ensure that the XQuery was correctly parsed.
 125
 126   \target evaluate() function
 127   \snippet xmlpatterns/recipes/querymainwindow.cpp 2
 128
 129   If the XQuery is valid, an instance of QXmlFormatter is created to
 130   format the query result as XML into a QBuffer. To evaluate the
 131   XQuery, an overload of \l{QXmlQuery::evaluateTo()} {evaluateTo()} is
 132   called that takes a QAbstractXmlReceiver for its output
 133   (QXmlFormatter inherits QAbstractXmlReceiver). Finally, the
 134   formatted XML result is displayed in the UI's bottom text view.
 135
 136   \note Each XQuery \c{.xq} file must declare the \c{$inputDocument}
 137   variable to represent the \c cookbook.xml document:
 138
 139   \code
 140   (: All ingredients for Mushroom Soup. :)
 141   declare variable $inputDocument external;
 142
 143   doc($inputDocument)/cookbook/recipe[@xml:id = "MushroomSoup"]/ingredient/
 144   <p>{@name, @quantity}</p>
 145   \endcode
 146
 147   \note If you add add your own query.xq files, you must declare the
 148   \c{$inputDocument} and use it as shown above.
 149
 150 */