--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/simpletreemodel.qdoc Wed Mar 31 11:06:36 2010 +0300
@@ -0,0 +1,346 @@
+/****************************************************************************
+**
+** 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 itemviews/simpletreemodel
+ \title Simple Tree Model Example
+
+ The Simple Tree Model example shows how to create a basic, read-only
+ hierarchical model to use with Qt's standard view classes. For a
+ description of simple non-hierarchical list and table models, see the
+ \l{model-view-programming.html}{Model/View Programming} overview.
+
+ \image simpletreemodel-example.png
+
+ Qt's model/view architecture provides a standard way for views to manipulate
+ information in a data source, using an abstract model of the data to
+ simplify and standardize the way it is accessed. Simple models represent
+ data as a table of items, and allow views to access this data via an
+ \l{model-view-model.html}{index-based} system. More generally, models can
+ be used to represent data in the form of a tree structure by allowing each
+ item to act as a parent to a table of child items.
+
+ Before attempting to implement a tree model, it is worth considering whether
+ the data is supplied by an external source, or whether it is going to be
+ maintained within the model itself. In this example, we will implement an
+ internal structure to hold data rather than discuss how to package data from
+ an external source.
+
+ \section1 Design and Concepts
+
+ The data structure that we use to represent the structure of the data takes
+ the form of a tree built from \c TreeItem objects. Each \c TreeItem
+ represents an item in a tree view, and contains several columns of data.
+
+ \target SimpleTreeModelStructure
+ \table
+ \row \i \inlineimage treemodel-structure.png
+ \i \bold{Simple Tree Model Structure}
+
+ The data is stored internally in the model using \c TreeItem objects that
+ are linked together in a pointer-based tree structure. Generally, each
+ \c TreeItem has a parent item, and can have a number of child items.
+ However, the root item in the tree structure has no parent item and it
+ is never referenced outside the model.
+
+ Each \c TreeItem contains information about its place in the tree
+ structure; it can return its parent item and its row number. Having
+ this information readily available makes implementing the model easier.
+
+ Since each item in a tree view usually contains several columns of data
+ (a title and a summary in this example), it is natural to store this
+ information in each item. For simplicity, we will use a list of QVariant
+ objects to store the data for each column in the item.
+ \endtable
+
+ The use of a pointer-based tree structure means that, when passing a
+ model index to a view, we can record the address of the corresponding
+ item in the index (see QAbstractItemModel::createIndex()) and retrieve
+ it later with QModelIndex::internalPointer(). This makes writing the
+ model easier and ensures that all model indexes that refer to the same
+ item have the same internal data pointer.
+
+ With the appropriate data structure in place, we can create a tree model
+ with a minimal amount of extra code to supply model indexes and data to
+ other components.
+
+ \section1 TreeItem Class Definition
+
+ The \c TreeItem class is defined as follows:
+
+ \snippet examples/itemviews/simpletreemodel/treeitem.h 0
+
+ The class is a basic C++ class. It does not inherit from QObject or
+ provide signals and slots. It is used to hold a list of QVariants,
+ containing column data, and information about its position in the tree
+ structure. The functions provide the following features:
+
+ \list
+ \o The \c appendChildItem() is used to add data when the model is first
+ constructed and is not used during normal use.
+ \o The \c child() and \c childCount() functions allow the model to obtain
+ information about any child items.
+ \o Information about the number of columns associated with the item is
+ provided by \c columnCount(), and the data in each column can be
+ obtained with the data() function.
+ \o The \c row() and \c parent() functions are used to obtain the item's
+ row number and parent item.
+ \endlist
+
+ The parent item and column data are stored in the \c parentItem and
+ \c itemData private member variables. The \c childItems variable contains
+ a list of pointers to the item's own child items.
+
+ \section1 TreeItem Class Implementation
+
+ The constructor is only used to record the item's parent and the data
+ associated with each column.
+
+ \snippet examples/itemviews/simpletreemodel/treeitem.cpp 0
+
+ A pointer to each of the child items belonging to this item will be
+ stored in the \c childItems private member variable. When the class's
+ destructor is called, it must delete each of these to ensure that
+ their memory is reused:
+
+ \snippet examples/itemviews/simpletreemodel/treeitem.cpp 1
+
+ Since each of the child items are constructed when the model is initially
+ populated with data, the function to add child items is straightforward:
+
+ \snippet examples/itemviews/simpletreemodel/treeitem.cpp 2
+
+ Each item is able to return any of its child items when given a suitable
+ row number. For example, in the \l{#SimpleTreeModelStructure}{above diagram},
+ the item marked with the letter "A" corresponds to the child of the root item
+ with \c{row = 0}, the "B" item is a child of the "A" item with \c{row = 1},
+ and the "C" item is a child of the root item with \c{row = 1}.
+
+ The \c child() function returns the child that corresponds to
+ the specified row number in the item's list of child items:
+
+ \snippet examples/itemviews/simpletreemodel/treeitem.cpp 3
+
+ The number of child items held can be found with \c childCount():
+
+ \snippet examples/itemviews/simpletreemodel/treeitem.cpp 4
+
+ The \c TreeModel uses this function to determine the number of rows that
+ exist for a given parent item.
+
+ The \c row() function reports the item's location within its parent's
+ list of items:
+
+ \snippet examples/itemviews/simpletreemodel/treeitem.cpp 8
+
+ Note that, although the root item (with no parent item) is automatically
+ assigned a row number of 0, this information is never used by the model.
+
+ The number of columns of data in the item is trivially returned by the
+ \c columnCount() function.
+
+ \snippet examples/itemviews/simpletreemodel/treeitem.cpp 5
+
+ Column data is returned by the \c data() function, taking advantage of
+ QList's ability to provide sensible default values if the column number
+ is out of range:
+
+ \snippet examples/itemviews/simpletreemodel/treeitem.cpp 6
+
+ The item's parent is found with \c parent():
+
+ \snippet examples/itemviews/simpletreemodel/treeitem.cpp 7
+
+ Note that, since the root item in the model will not have a parent, this
+ function will return zero in that case. We need to ensure that the model
+ handles this case correctly when we implement the \c TreeModel::parent()
+ function.
+
+ \section1 TreeModel Class Definition
+
+ The \c TreeModel class is defined as follows:
+
+ \snippet examples/itemviews/simpletreemodel/treemodel.h 0
+
+ This class is similar to most other subclasses of QAbstractItemModel that
+ provide read-only models. Only the form of the constructor and the
+ \c setupModelData() function are specific to this model. In addition, we
+ provide a destructor to clean up when the model is destroyed.
+
+ \section1 TreeModel Class Implementation
+
+ For simplicity, the model does not allow its data to be edited. As a
+ result, the constructor takes an argument containing the data that the
+ model will share with views and delegates:
+
+ \snippet examples/itemviews/simpletreemodel/treemodel.cpp 0
+
+ It is up to the constructor to create a root item for the model. This
+ item only contains vertical header data for convenience. We also use it
+ to reference the internal data structure that contains the model data,
+ and it is used to represent an imaginary parent of top-level items in
+ the model.
+
+ The model's internal data structure is populated with items by the
+ \c setupModelData() function. We will examine this function separately
+ at the end of this document.
+
+ The destructor ensures that the root item and all of its descendants
+ are deleted when the model is destroyed:
+
+ \snippet examples/itemviews/simpletreemodel/treemodel.cpp 1
+
+ Since we cannot add data to the model after it is constructed and set
+ up, this simplifies the way that the internal tree of items is managed.
+
+ Models must implement an \c index() function to provide indexes for
+ views and delegates to use when accessing data. Indexes are created
+ for other components when they are referenced by their row and column
+ numbers, and their parent model index. If an invalid model
+ index is specified as the parent, it is up to the model to return an
+ index that corresponds to a top-level item in the model.
+
+ When supplied with a model index, we first check whether it is valid.
+ If it is not, we assume that a top-level item is being referred to;
+ otherwise, we obtain the data pointer from the model index with its
+ \l{QModelIndex::internalPointer()}{internalPointer()} function and use
+ it to reference a \c TreeItem object. Note that all the model indexes
+ that we construct will contain a pointer to an existing \c TreeItem,
+ so we can guarantee that any valid model indexes that we receive will
+ contain a valid data pointer.
+
+ \snippet examples/itemviews/simpletreemodel/treemodel.cpp 6
+
+ Since the row and column arguments to this function refer to a
+ child item of the corresponding parent item, we obtain the item using
+ the \c TreeItem::child() function. The
+ \l{QAbstractItemModel::createIndex()}{createIndex()} function is used
+ to create a model index to be returned. We specify the row and column
+ numbers, and a pointer to the item itself. The model index can be used
+ later to obtain the item's data.
+
+ The way that the \c TreeItem objects are defined makes writing the
+ \c parent() function easy:
+
+ \snippet examples/itemviews/simpletreemodel/treemodel.cpp 7
+
+ We only need to ensure that we never return a model index corresponding
+ to the root item. To be consistent with the way that the \c index()
+ function is implemented, we return an invalid model index for the
+ parent of any top-level items in the model.
+
+ When creating a model index to return, we must specify the row and
+ column numbers of the parent item within its own parent. We can
+ easily discover the row number with the \c TreeItem::row() function,
+ but we follow a convention of specifying 0 as the column number of
+ the parent. The model index is created with
+ \l{QAbstractItemModel::createIndex()}{createIndex()} in the same way
+ as in the \c index() function.
+
+ The \c rowCount() function simply returns the number of child items
+ for the \c TreeItem that corresponds to a given model index, or the
+ number of top-level items if an invalid index is specified:
+
+ \snippet examples/itemviews/simpletreemodel/treemodel.cpp 8
+
+ Since each item manages its own column data, the \c columnCount()
+ function has to call the item's own \c columnCount() function to
+ determine how many columns are present for a given model index.
+ As with the \c rowCount() function, if an invalid model index is
+ specified, the number of columns returned is determined from the
+ root item:
+
+ \snippet examples/itemviews/simpletreemodel/treemodel.cpp 2
+
+ Data is obtained from the model via \c data(). Since the item manages
+ its own columns, we need to use the column number to retrieve the data
+ with the \c TreeItem::data() function:
+
+ \snippet examples/itemviews/simpletreemodel/treemodel.cpp 3
+
+ Note that we only support the \l{Qt::ItemDataRole}{DisplayRole}
+ in this implementation, and we also return invalid QVariant objects for
+ invalid model indexes.
+
+ We use the \c flags() function to ensure that views know that the
+ model is read-only:
+
+ \snippet examples/itemviews/simpletreemodel/treemodel.cpp 4
+
+ The \c headerData() function returns data that we conveniently stored
+ in the root item:
+
+ \snippet examples/itemviews/simpletreemodel/treemodel.cpp 5
+
+ This information could have been supplied in a different way: either
+ specified in the constructor, or hard coded into the \c headerData()
+ function.
+
+ \section1 Setting Up the Data in the Model
+
+ We use the \c setupModelData() function to set up the initial data in
+ the model. This function parses a text file, extracting strings of
+ text to use in the model, and creates item objects that record both
+ the data and the overall model structure.
+ Naturally, this function works in a way that is very specific to
+ this model. We provide the following description of its behavior,
+ and refer the reader to the example code itself for more information.
+
+ We begin with a text file in the following format:
+
+ \snippet doc/src/snippets/code/doc_src_examples_simpletreemodel.qdoc 0
+ \dots
+ \snippet doc/src/snippets/code/doc_src_examples_simpletreemodel.qdoc 1
+
+ We process the text file with the following two rules:
+
+ \list
+ \o For each pair of strings on each line, create an item (or node)
+ in a tree structure, and place each string in a column of data
+ in the item.
+ \o When the first string on a line is indented with respect to the
+ first string on the previous line, make the item a child of the
+ previous item created.
+ \endlist
+
+ To ensure that the model works correctly, it is only necessary to
+ create instances of \c TreeItem with the correct data and parent item.
+*/