diff options
Diffstat (limited to 'doc/src/examples/simpletreemodel.qdoc')
| -rw-r--r-- | doc/src/examples/simpletreemodel.qdoc | 346 |
1 files changed, 346 insertions, 0 deletions
diff --git a/doc/src/examples/simpletreemodel.qdoc b/doc/src/examples/simpletreemodel.qdoc new file mode 100644 index 0000000..5ddeb46 --- /dev/null +++ b/doc/src/examples/simpletreemodel.qdoc @@ -0,0 +1,346 @@ +/**************************************************************************** +** +** 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 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. +*/ |