FCL/sf/mw/qt: comparison doc/src/examples/filetree.qdoc

equal deleted inserted replaced

-:41300fa6a67c
+:f7bc934e204c
+/****************************************************************************
+**
+** 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/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.
+*/