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

**

** Copyright (C) 2009 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/filetree

  \title File System Example

  This example shows how to use QtXmlPatterns for querying non-XML

  data that is modeled to look like XML. 

  \tableofcontents

  \section1 Introduction

  The example models your computer's file system to look like XML and

  allows you to query the file system with XQuery. Suppose we want to

  find all the \c{cpp} files in the subtree beginning at

  \c{/filetree}:

  \image filetree_1-example.png

  \section2 The User Inteface

  The example is shown below. First, we use \c{File->Open Directory}

  (not shown) to select the \c{/filetree} directory. Then we use the

  combobox on the right to select the XQuery that searches for \c{cpp}

  files (\c{listCPPFiles.xq}).  Selecting an XQuery runs the query,

  which in this case traverses the model looking for all the \c{cpp}

  files. The XQuery text and the query results are shown on the right:

  \image filetree_2-example.png

  Don't be mislead by the XML representation of the \c{/filetree}

  directory shown on the left. This is not the node model itself but

  the XML obtained by traversing the node model and outputting it as

  XML. Constructing and using the custom node model is explained in

  the code walk-through.

  \section2 Running your own XQueries

  You can write your own XQuery files and run them in the example

  program. The file \c{xmlpatterns/filetree/queries.qrc} is the \l{The

  Qt Resource System} {resource file} for this example. It is used in

  \c{main.cpp} (\c{Q_INIT_RESOURCE(queries);}). It lists the XQuery

  files (\c{.xq}) that can be selected in the combobox.

  \quotefromfile examples/xmlpatterns/filetree/queries.qrc

  \printuntil

  To add your own queries to the example's combobox, store your

  \c{.xq} files in the \c{examples/xmlpatterns/filetree/queries}

  directory and add them to \c{queries.qrc} as shown above.

  \section1 Code Walk-Through

  The strategy is to create a custom node model that represents the

  directory tree of the computer's file system. That tree structure is

  non-XML data. The custom node model must have the same callback

  interface as the XML node models that the QtXmlPatterns query engine

  uses to execute queries. The query engine can then traverse the

  custom node model as if it were traversing the node model built from

  an XML document.

  The required callback interface is in QAbstractXmlNodeModel, so we

  create a custom node model by subclassing QAbstractXmlNodeModel and

  providing implementations for its pure virtual functions. For many

  cases, the implementations of several of the virtual functions are

  always the same, so QtXmlPatterns also provides QSimpleXmlNodeModel,

  which subclasses QAbstractXmlNodeModel and provides implementations

  for the callback functions that you can ignore. By subclassing

  QSimpleXmlNodeModel instead of QAbstractXmlNodeModel, you can reduce

  development time.

  \section2 The Custom Node Model Class: FileTree

  The custom node model for this example is class \c{FileTree}, which

  is derived from QSimpleXmlNodeModel. \c{FileTree} implements all the

  callback functions that don't have standard implementations in

  QSimpleXmlNodeModel. When you implement your own custom node model,

  you must provide implementations for these callback functions:

  \snippet examples/xmlpatterns/filetree/filetree.h 0

  \snippet examples/xmlpatterns/filetree/filetree.h 1

  The \c{FileTree} class declares four data members:

  \snippet examples/xmlpatterns/filetree/filetree.h 2

  The QVector \c{m_fileInfos} will contain the node model. Each

  QFileInfo in the vector will represent a file or a directory in the

  file system. At this point it is instructive to note that although

  the node model class for this example (\c{FileTree}) actually builds

  and contains the custom node model, building the custom node model

  isn't always required. The node model class for the \l{QObject XML

  Model Example} {QObject node model example} does not build its node

  model but instead uses an already existing QObject tree as its node

  model and just implements the callback interface for that already

  existing data structure. In this file system example, however,

  although we have an already existing data structure, i.e. the file

  system, that data structure is not in memory and is not in a form we

  can use. So we must build an analog of the file system in memory

  from instances of QFileInfo, and we use that analog as the custom

  node model.

  The two sets of flags, \c{m_filterAllowAll} and \c{m_sortFlags},

  contain OR'ed flags from QDir::Filters and QDir::SortFlags

  respectively. They are set by the \c{FileTree} constructor and used

  in calls to QDir::entryInfoList() for getting the child list for a

  directory node, i.e. a QFileInfoList containing the file and

  directory nodes for all the immediate children of a directory.

  The QVector \c{m_names} is an auxiliary component of the node

  model. It holds the XML element and attribute names (QXmlName) for

  all the node types that will be found in the node model. \c{m_names}

  is indexed by the enum \c{FileTree::Type}, which specifies the node

  types:

  \target Node_Type

  \snippet examples/xmlpatterns/filetree/filetree.h 4

  \c{Directory} and \c{File} will represent the XML element nodes for

  directories and files respectively, and the other enum values will

  represent the XML attribute nodes for a file's path, name, suffix,

  its size in bytes, and its mime type. The \c{FileTree} constructor

  initializes \c{m_names} with an appropriate QXmlName for each

  element and attribute type:

  \snippet examples/xmlpatterns/filetree/filetree.cpp 2

  Note that the constructor does \e{not} pre-build the entire node

  model. Instead, the node model is built \e{incrementally} as the

  query engine evaluates a query. To see how the query engine causes

  the node model to be built incrementally, see \l{Building And

  Traversing The Node Model}. To see how the query engine accesses the

  node model, see \l{Accessing the node model}. See also: \l{Node

  Model Building Strategy}.

  \section3 Accessing The Node Model

  Since the node model is stored outside the query engine in the

  \c{FileTree} class, the query engine knows nothing about it and can

  only access it by calling functions in the callback interface. When

  the query engine calls any callback function to access data in the

  node model, it passes a QXmlNodeModelIndex to identify the node in

  the node model that it wants to access.  Hence all the virtual

  functions in the callback interface use a QXmlNodeModelIndex to

  uniquely identify a node in the model.

  We use the index of a QFileInfo in \c{m_fileInfos} to uniquely

  identify a node in the node model. To get the QXmlNodeModelIndex for

  a QFileInfo, the class uses the private function \c{toNodeIndex()}:

  \target main toNodeIndex

  \snippet examples/xmlpatterns/filetree/filetree.cpp 1

  It searches the \c{m_fileInfos} vector for a QFileInfo that matches

  \c{fileInfo}. If a match is found, its array index is passed to

  QAbstractXmlNodeModel::createIndex() as the \c data value for the

  QXmlNodeIndex. If no match is found, the unmatched QFileInfo is

  appended to the vector, so this function is also doing the actual

  incremental model building (see \l{Building And Traversing The Node

  Model}).

  Note that \c{toNodeIndex()} gets a \l{Node_Type} {node type} as the

  second parameter, which it just passes on to

  \l{QAbstractXmlNodeModel::createIndex()} {createIndex()} as the

  \c{additionalData} value. Logically, this second parameter

  represents a second dimension in the node model, where the first

  dimension represents the \e element nodes, and the second dimension

  represents each element's attribute nodes. The meaning is that each

  QFileInfo in the \c{m_fileInfos} vector can represent an \e{element}

  node \e{and} one or more \e{attribute} nodes. In particular, the

  QFileInfo for a file will contain the values for the attribute nodes

  path, name, suffix, size, and mime type (see

  \c{FileTree::attributes()}). Since the attributes are contained in

  the QFileInfo of the file element, there aren't actually any

  attribute nodes in the node model. Hence, we can use a QVector for

  \c{m_fileInfos}.

  A convenience overloading of \l{toNodeIndex of convenience}

  {toNodeIndex()} is also called in several places, wherever it is

  known that the QXmlNodeModelIndex being requested is for a directory

  or a file and not for an attribute. The convenience function takes

  only the QFileInfo parameter and calls the other \l{main toNodeIndex}

  {toNodeIndex()}, after obtaining either the Directory or File node

  type directly from the QFileInfo:

  \target toNodeIndex of convenience

  \snippet examples/xmlpatterns/filetree/filetree.cpp 0

  Note that the auxiliary vector \c{m_names} is accessed using the

  \l{Node_Type} {node type}, for example:

  \snippet examples/xmlpatterns/filetree/filetree.cpp 3

  Most of the virtual functions in the callback interface are as

  simple as the ones described so far, but the callback function used

  for traversing (and building) the node model is more complex.

  \section3 Building And Traversing The Node Model 

  The node model in \c{FileTree} is not fully built before the query

  engine begins evaluating the query. In fact, when the query engine

  begins evaluating its first query, the only node in the node model

  is the one representing the root directory for the selected part of

  the file system. See \l{The UI Class: MainWindow} below for details

  about how the UI triggers creation of the model.

  The query engine builds the node model incrementally each time it

  calls the \l{next node on axis} {nextFromSimpleAxis()} callback

  function, as it traverses the node model to evaluate a query. Thus

  the query engine only builds the region of the node model that it

  needs for evaluating the query.

  \l{next node on axis} {nextFromSimpleAxis()} takes an

  \l{QAbstractXmlNodeModel::SimpleAxis} {axis identifier} and a

  \l{QXmlNodeModelIndex} {node identifier} as parameters. The

  \l{QXmlNodeModelIndex} {node identifier} represents the \e{context

  node} (i.e. the query engine's current location in the model), and

  the \l{QAbstractXmlNodeModel::SimpleAxis} {axis identifier}

  represents the direction we want to move from the context node. The

  function finds the appropriate next node and returns its

  QXmlNodeModelIndex.

  \l{next node on axis} {nextFromSimpleAxis()} is where most of the

  work of implementing a custom node model will be required. The

  obvious way to do it is to use a switch statement with a case for

  each \l{QAbstractXmlNodeModel::SimpleAxis} {axis}.

  \target next node on axis

  \snippet examples/xmlpatterns/filetree/filetree.cpp 4

  The first thing this function does is call \l{to file info}

  {toFileInfo()} to get the QFileInfo of the context node. The use of

  QVector::at() here is guaranteed to succeed because the context node

  must already be in the node model, and hence must have a QFileInfo

  in \c{m_fileInfos}.

  \target to file info

  \snippet examples/xmlpatterns/filetree/filetree.cpp 6

  The \l{QAbstractXmlNodeModel::Parent} {Parent} case looks up the

  context node's parent by constructing a QFileInfo from the context

  node's \l{QFileInfo::absoluteFilePath()} {path} and passing it to

  \l{main toNodeIndex} {toNodeIndex()} to find the QFileInfo in

  \c{m_fileInfos}.

  The \l{QAbstractXmlNodeModel::FirstChild} {FirstChild} case requires

  that the context node must be a directory, because a file doesn't

  have children. If the context node is not a directory, a default

  constructed QXmlNodeModelIndex is returned. Otherwise,

  QDir::entryInfoList() constructs a QFileInfoList of the context

  node's children. The first QFileInfo in the list is passed to

  \l{toNodeIndex of convenience} {toNodeIndex()} to get its

  QXmlNodeModelIndex. Note that this will add the child to the node

  model, if it isn't in the model yet.

  The \l{QAbstractXmlNodeModel::PreviousSibling} {PreviousSibling} and

  \l{QAbstractXmlNodeModel::NextSibling} {NextSibling} cases call the

  \l{nextSibling helper} {nextSibling() helper function}. It takes the

  QXmlNodeModelIndex of the context node, the QFileInfo of the context

  node, and an offest of +1 or -1. The context node is a child of some

  parent, so the function gets the parent and then gets the child list

  for the parent. The child list is searched to find the QFileInfo of

  the context node. It must be there. Then the offset is applied, -1

  for the previous sibling and +1 for the next sibling. The resulting

  index is passed to \l{toNodeIndex of convenience} {toNodeIndex()} to

  get its QXmlNodeModelIndex. Note again that this will add the

  sibling to the node model, if it isn't in the model yet.

  \target nextSibling helper

  \snippet examples/xmlpatterns/filetree/filetree.cpp 5

  \section2 The UI Class: MainWindow

  The example's UI is a conventional Qt GUI application inheriting

  QMainWindow and the Ui_MainWindow base class generated by 

  \l{Qt Designer Manual} {Qt Designer}.

  \snippet examples/xmlpatterns/filetree/mainwindow.h 0

  It contains the custom node model (\c{m_fileTree}) and an instance

  of QXmlNodeModelIndex (\c{m_fileNode}) used for holding the node

  index for the root of the file system subtree. \c{m_fileNode} will

  be bound to a $variable in the XQuery to be evaluated.

  Two actions of interest are handled by slot functions: \l{Selecting

  A Directory To Model} and \l{Selecting And Running An XQuery}.

  \section3 Selecting A Directory To Model

  The user selects \c{File->Open Directory} to choose a directory to

  be loaded into the custom node model. Choosing a directory signals

  the \c{on_actionOpenDirectory_triggered()} slot:

  \snippet examples/xmlpatterns/filetree/mainwindow.cpp 1

  The slot function simply calls the private function

  \c{loadDirectory()} with the path of the chosen directory:

  \target the standard code pattern

  \snippet examples/xmlpatterns/filetree/mainwindow.cpp 4

  \c{loadDirectory()} demonstrates a standard code pattern for using

  QtXmlPatterns programatically. First it gets the node model index

  for the root of the selected directory. Then it creates an instance

  of QXmlQuery and calls QXmlQuery::bindVariable() to bind the node

  index to the XQuery variable \c{$fileTree}. It then calls

  QXmlQuery::setQuery() to load the XQuery text.

  \note QXmlQuery::bindVariable() must be called \e before calling

  QXmlQuery::setQuery(), which loads and parses the XQuery text and

  must have access to the variable binding as the text is parsed.

  The next lines create an output device for outputting the query

  result, which is then used to create a QXmlFormatter to format the

  query result as XML. QXmlQuery::evaluateTo() is called to run the

  query, and the formatted XML output is displayed in the left panel

  of the UI window.

  Finally, the private function \l{Selecting And Running An XQuery}

  {evaluateResult()} is called to run the currently selected XQuery

  over the custom node model.

  \note As described in \l{Building And Traversing The Node Model},

  the \c FileTree class wants to build the custom node model

  incrementally as it evaluates the XQuery. But, because the

  \c{loadDirectory()} function runs the \c{wholeTree.xq} XQuery, it

  actually builds the entire node model anyway. See \l{Node Model

  Building Strategy} for a discussion about building your custom node

  model.

  \section3 Selecting And Running An XQuery

  The user chooses an XQuery from the menu in the combobox on the

  right. Choosing an XQuery signals the

  \c{on_queryBox_currentIndexChanged()} slot:

  \snippet examples/xmlpatterns/filetree/mainwindow.cpp 2

  The slot function opens and loads the query file and then calls the

  private function \c{evaluateResult()} to run the query:

  \snippet examples/xmlpatterns/filetree/mainwindow.cpp 3

  \c{evaluateResult()} is a second example of the same code pattern

  shown in \l{the standard code pattern} {loadDirectory()}. In this

  case, it runs the XQuery currently selected in the combobox instead

  of \c{qrc:/queries/wholeTree.xq}, and it outputs the query result to

  the panel on the lower right of the UI window.

  \section2 Node Model Building Strategy

  We saw that the \l{The Custom Node Model Class: FileTree} {FileTree}

  tries to build its custom node model incrementally, but we also saw

  that the \l{the standard code pattern} {MainWindow::loadDirectory()}

  function in the UI class immediately subverts the incremental build

  by running the \c{wholeTree.xq} XQuery, which traverses the entire

  selected directory, thereby causing the entire node model to be

  built.

  If we want to preserve the incremental build capability of the

  \c{FileTree} class, we can strip the running of \c{wholeTree.xq} out

  of \l{the standard code pattern} {MainWindow::loadDirectory()}:

  \snippet examples/xmlpatterns/filetree/mainwindow.cpp 5

  \snippet examples/xmlpatterns/filetree/mainwindow.cpp 6

  Note, however, that \c{FileTree} doesn't have the capability of

  deleting all or part of the node model. The node model, once built,

  is only deleted when the \c{FileTree} instance goes out of scope.

  In this example, each element node in the node model represents a

  directory or a file in the computer's file system, and each node is

  represented by an instance of QFileInfo. An instance of QFileInfo is

  not costly to produce, but you might imagine a node model where

  building new nodes is very costly. In such cases, the capability to

  build the node model incrementally is important, because it allows

  us to only build the region of the model we need for evaluating the

  query. In other cases, it will be simpler to just build the entire

  node model. 

*/