Long live Qt 4.5!

1 files changed, 353 insertions, 0 deletions

diff --git a/doc/src/examples/qobjectxmlmodel.qdoc b/doc/src/examples/qobjectxmlmodel.qdoc
new file mode 100644
index 0000000..ce1dab6
--- /dev/null
+++ b/doc/src/examples/qobjectxmlmodel.qdoc
@@ -0,0 +1,353 @@
+/****************************************************************************
+**
+** 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$
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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/qobjectxmlmodel
+  \title QObject XML Model Example
+
+  This example shows how to use QtXmlPatterns to query QObject trees
+  by modeling the non-XML data structure of a QObject tree to look
+  like XML.
+
+  \tableofcontents
+
+  \section1 Introduction
+
+  This example illustrates two important points about using XQuery to
+  query non-XML data modeled to look like XML. The first point is that
+  a custom node model class doesn't always have to actually build the
+  node model. Sometimes the node model can be an already existing data
+  structure, like the QObject tree used in this example. The second
+  point is to explain what is required to make non-XML data look like
+  XML.
+
+  In this example, we want to model a QObject tree to look like
+  XML. That is easy to do because a QObject tree maps to the XML tree
+  structure in a staightforward way. Each QObject node is modeled as
+  an XML element node. However, when we want to add the QMetaObject tree
+  to the QObject tree node model, we are trying to add a second tree to
+  the node model. The QMetaObject tree exists \e{behind} the QObject
+  tree. Adding the QMetaObject tree to the node model changes the two
+  dimensional tree into a three dimensional tree.
+
+  The query engine can only traverse two dimensional trees, because an
+  XML document is always a two dimensional tree. If we want to add the
+  QMetaObject tree to the node model, we have to somehow flatten it
+  into the the same plane as the QObject tree. This requires that the
+  node model class must build an auxiliary data structure and make it
+  part of the two dimensional QObject node model. How to do this is
+  explained in \l{Including The QMetaObject Tree}.
+
+  \section2 The User Interface
+
+  The UI for this example was created using Qt Designer:
+
+  \image qobjectxmlmodel-example.png
+
+  \section1 Code Walk-Through
+
+  The strategy for this example is different from the strategy for the
+  \l{File System Example}{file system example}. In the file system
+  example, the node model class had to actually build a node model
+  because the non-XML data to be traversed was the computer's file
+  system, a structure stored on disk in a form that the query engine
+  couldn't use. The node model class had to build an analog of the
+  computer's file system in memory.
+
+  For this example, the data structure to be traversed already exists
+  in memory in a usable form. It is the QObject tree of the example
+  application itself. All we need is the pointer to the root of the
+  QObject tree.
+
+  \note When we add the QMetaObject tree to the node model, the node
+  model class will have to build an auxiliary data structure to move
+  the QMetaObject tree into the same plane as the QObject tree. This
+  is explained later in \l{Including The QMetaObject Tree}.
+
+  \section2 The Custom Node Model Class: QObjextXmlModel
+
+  The node model class for this example is QObjextXmlModel, which is
+  derived from QSimpleXmlNodeModel. QObjextXmlModel implements the
+  callback interface functions that don't have implementations in
+  QSimpleXmlNodeModel: 
+
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.h 0
+
+  The node model class declares three data members:
+
+  \target Three Data Members
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.h 2
+
+  The constructor sets \c m_baseURI to the QUrl constructed from the
+  \l{QCoreApplication::applicationFilePath()}{file path} of the
+  application executable.  This is the value returned by
+  \l{QAbstractXmlNodeModel::documentUri()}{documentUri()}. The
+  constructor sets \c{m_root} to point to the QObject tree for the
+  example application. This is the node model that the query engine
+  will use. And the constructor calls a local function to build the
+  auxiliary data structure (\c{m_allMetaObjects}) for including the
+  QMetaObject tree in the node model. How this auxiliary data
+  structure is incorporated into the QObject node model is discussed
+  in \l{Including The QMetaObject Tree}.
+
+  \section3 Accessing The Node Model
+
+  Since the query engine knows nothing about QObject trees, it can
+  only access them by calling functions in the node model callback
+  interface. The query engine passes a QXmlNodeModelIndex to uniquely
+  identify a node in the node model. The QXmlNodeModelIndex is
+  constructed from a pointer to the QObject that represents the node.
+  \l{QAbstractXmlNodeModel::createIndex()}{createIndex()} creates the
+  QXmlNodeModelIndex, as in the local \c{root()} function, for example:
+
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 0
+
+  A QObject represents an element node in the node model, but we also
+  need to represent attribute nodes. For example, the class name of a
+  QObject is an attribute of the QObject, so it should be an attribute
+  node in the node model. A QObject's class name is obtained from the
+  QObject. (Actually, it is in the QMetaObject, which is obtained from
+  the QObject). This means that a single QObject logically represents
+  multiple nodes in the node model: the element node and potentially
+  many attribute nodes.
+
+  To uniquely identify an attribute node, we need the pointer to the
+  QObject containing the attribute, and an additional value that
+  identifies the attribute in the QObject. For this \e{additional
+  data} value, we use \c{enum QObjectNodeType}:
+
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.h 3
+
+  Ignore the \c{MetaObjectXXX} values for now. They will be explained
+  in \l{Including The QMetaObject Tree}. Here we are interested in the
+  three node types for QObject nodes: \c{IsQObject}, which represents
+  the element node type for a QObject, and \c{QObjectProperty} and
+  \c{QObjectClassName}, which represent the attribute node types for
+  the attributes of a QObject.
+
+  The \l{QAbstractXmlNodeModel::createIndex()}{createIndex()}
+  function called in the \c{root()} snippet above is the overload that
+  accepts a \c{void*} pointer and a second parameter,
+  \c{additionalData}, with default value 0 (\c{IsQObject}). Wherever
+  you see a call to \l{QAbstractXmlNodeModel::createIndex()}
+  {createIndex()} that only passes the QObject pointer, it is creating
+  the node index for a QObject element node. To create the node index
+  for the class name attribute, for example, the \l{QObject
+  attributes} {attributes()} function uses
+  \c{createIndex(object,QObjectClassName)}.
+
+  \target QObject attributes
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 6
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 8
+
+  \l{QObject attributes} {attributes()} is one of the callback
+  functions you have to implement in your custom node model class. It
+  returns a QVector of \l{QXmlNodeModelIndex} {node indexes} for all
+  the attribute nodes for QObject \c{n}. It calls
+  \l{QAbstractXmlNodeModel::createIndex()} {createIndex()} in two places.
+  Both calls use the QObject pointer from the current node \c{n} (the
+  element node), and just add a different value for the \e{additional data}
+  parameter. This makes sense because, in XML, the attributes of an
+  element are part of that element. 
+
+  \section3 Traversing The Node Model
+
+  The query engine traverses the QObject tree by calling back to the
+  node model class's implementation of \l{QObject nextFromSimpleAxis}
+  {nextFromSimpleAxis()}. This function is the heart of the callback
+  interface, and it will probably be the most complex to implement in
+  your custom node model class. Below is a partial listing of the
+  implementation for this example. The full listing will be shown in
+  \l{Including The QMetaObject Tree}, where we discuss traversing the
+  QMetaObject tree.
+
+  \target QObject nextFromSimpleAxis
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 2
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 4
+
+  The main switch uses \c toNodeType(), which obtains the node
+  type from \l{QXmlNodeModelIndex::additionalData()}:
+
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 1
+
+  \c{case IsObject} case is the most interesting. It switches again on
+  the value of the \c{axis} parameter, which specifies the direction
+  the query engine wants to take from the current node. It is one of
+  the four enum values of \l{QAbstractXmlNodeModel::SimpleAxis}.  The
+  \l{QAbstractXmlNodeModel::Parent} {Parent} and
+  \l{QAbstractXmlNodeModel::FirstChild} {FirstChild} cases reduce to
+  calls to QObject::parent() and QObject::children()
+  respectively. Note that a default constructed QXmlNodeModelIndex is
+  returned in the \l{QAbstractXmlNodeModel::Parent} {Parent} case if
+  the current node is the root, and in the
+  \l{QAbstractXmlNodeModel::FirstChild} {FirstChild} case if the
+  current node has no children.
+
+  For the \l{QAbstractXmlNodeModel::NextSibling} {NextSibling} and
+  \l{QAbstractXmlNodeModel::PreviousSibling} {PreviousSibling} axes,
+  the helper function \c{qObjectSibling()} is called, with +1 to
+  traverse to the \l{QAbstractXmlNodeModel::NextSibling} {NextSibling}
+  and -1 to traverse to the
+  \l{QAbstractXmlNodeModel::PreviousSibling} {PreviousSibling}.
+
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 5
+
+  \c{qObjectSibling()} determines whether or not the node has any
+  siblings. It is called with \c{n}, the index of the current node.
+  If the current node is a child, then it has a parent with children
+  (the current node one of these).
+  So, we get the \l{QObject::parent()}{parent}, obtain the parent's
+  \l{QObject::children()} {child list}, find the current node in the
+  list, and construct the node index for the next or previous child
+  (sibling) and return it.
+
+  \note In \l{QObject nextFromSimpleAxis} {nextFromSimpleAxis()}, the
+  special case of asking for the
+  \l{QAbstractXmlNodeModel::PreviousSibling} {PreviousSibling} of the
+  root node is discussed in \l{Including The QMetaObject Tree}.
+
+  Traversing away from a \c{QObjectClassName} attribute node or a
+  \c{QObjectProperty} attribute node might seem a bit confusing at
+  first glance. The only move allowed from an attribute node is to the
+  \l{QAbstractXmlNodeModel::Parent} {Parent}, because attribute nodes
+  don't have children. But these two cases simply return the 
+  \l{QXmlNodeModelIndex} {node index} of the current node.
+
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 7
+
+  Since \c n is the QXmlNodeModelIndex of the current node, all this
+  does is create another QXmlNodeModelIndex for the current node and
+  return it. This was explained above in \l{Accessing The Node Model},
+  where we saw that each QObject in the node model actually represents
+  an element node and potentially many attribute nodes. Traversing to
+  the parent node of an attribute simply creates a node index for the
+  same QObject, but with an \e{additional data} value of 0
+  (\c{IsQObject}).
+
+  If we only wanted to traverse the QObject tree with XQuery, we could
+  just implement the rest of the virtual callback functions listed
+  earlier and we would be done. The implementations for the remaining
+  functions are straightforward. But if we also want to use XQuery to
+  traverse the QMetaObject tree, we must include the QMetaObject tree
+  in the custom node model.
+
+  \section3 Including The QMetaObject Tree
+
+  The \l{Meta-Object System} {metaobject system} not only enables Qt's
+  \l{Signals and Slots} {signals and slots}, it also provides type
+  information that is useful at run-time; e.g., getting and setting
+  properties without knowing the property names at compile time. Each
+  QObject has an associated QMetaObject tree which contains all this
+  useful type information. Given a QObject, its QMetaObject is
+  obtained with QObject::metaObject(). Then QMetaObject::superClass()
+  can be called repeatedly to get the QMetaObject for each class in the 
+  class hierarchy for the original QObject.
+
+  However, the QMetaObject hierarchy is a second tree in a plan that
+  exists logically behind the plane of the QObject tree. The QtXmlPatterns
+  query engine can only traverse a two dimensional node model that
+  represents an XML tree. If we want to include the QMetaObject in the
+  same node model that represents the QObject tree, we must find a way
+  to flatten the QMetaObject tree into the same plane as the QObject
+  tree.
+
+  The node model class declares \l{All MetaObjects}{m_allMetaObjects}
+  as a vector of pointers to QMetaObject:
+
+  \target All MetaObjects
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.h 1
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.h 4
+
+  This vector gets populated by the QObjectXmlModel constructor by
+  calling the private allMetaObjects() function:
+
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 9
+
+  The first half of the function is an example of the standard code
+  pattern for using QtXmlPatterns to run an XQuery. First it creates an
+  instance of QXmlQuery. Then it \l{QXmlQuery::bindVariable()}{binds}
+  the XQuery variable \c{$root} to the root node of the of the node
+  model; i.e., the root of the QObject tree. Then it
+  \l{QXmlQuery::setQuery()} {sets the query} to be an XQuery that
+  returns all the QObjects in the node model. Finally, the query is
+  evaluated into a \l{QXmlResultItems} {result item list}.
+
+  \note \l{QXmlQuery::bindVariable()} must be called before
+  \l{QXmlQuery::setQuery()}, because setting the query causes
+  QtXmlPatterns to \e compile the XQuery, which requires knowledge of
+  the variable bindings.
+
+  The second half of the function traverses the \l{QXmlResultItems}
+  {result item list}, getting the QMetaObject hierarchy for each
+  QObject and appending it to \l{All MetaObjects} {m_allMetaObjects},
+  if it isn't already there. But how do we include this vector of
+  pointers to QMetaObjects in the node model? The key insight is
+  shown in the full listing of \l{Full Listing of nextFromSimpleAxis}
+  {nextFromSimpleAxis()}, where we are interested now in the 
+  \c{MetaObjectXXX} cases:
+
+  \target Full Listing of nextFromSimpleAxis
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 2
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 3
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 4
+
+  But first, revisit the \c{PreviousSibling} case for the
+  \c{IsQObject} case:
+
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 10
+
+  When asking for the previous sibling of the root of the QObject
+  tree, it creates a node model index with a null QObject pointer and
+  an \c{additionalData} value of \c{MetaObjects}. This effectively
+  allows the query engine to jump from the QObject tree to the
+  QMetaObject tree.
+
+  The query engine can jump from the QMetaObject tree back to the
+  QObject tree in the \c{NextSibling} case of case \c{MetaObjects},
+  where the \c{root()} function is called:
+
+  \snippet examples/xmlpatterns/qobjectxmlmodel/qobjectxmlmodel.cpp 11
+
+  Having jumped from the QObject tree to the QMetaObject tree, the
+  query engine will use the \c{MetaObject}, \c{MetaObjectClassName},
+  and \c{MetaObjectSuperClass} cases, which are similar to the cases
+  for \c{IsQObject}, \c{QObjectProperty}, and \c{QObjectClassName}.  
+*/