diff options
Diffstat (limited to 'examples/widgets/doc/editabletreemodel.qdoc')
| -rw-r--r-- | examples/widgets/doc/editabletreemodel.qdoc | 446 |
1 files changed, 446 insertions, 0 deletions
diff --git a/examples/widgets/doc/editabletreemodel.qdoc b/examples/widgets/doc/editabletreemodel.qdoc new file mode 100644 index 0000000000..423b9cee94 --- /dev/null +++ b/examples/widgets/doc/editabletreemodel.qdoc @@ -0,0 +1,446 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/editabletreemodel + \title Editable Tree Model Example + + This example shows how to implement a simple item-based tree model that can + be used with other classes the model/view framework. + + \image itemviews-editabletreemodel.png + + The model supports editable items, custom headers, and the ability to + insert and remove rows and columns. With these features, it is also + possible to insert new child items, and this is shown in the supporting + example code. + + \note The model only shows the basic principles used when creating an + editable, hierarchical model. You may wish to use the \l{ModelTest} + project to test production models. + + \section1 Overview + + As described in the \l{Model Subclassing Reference}, models must + provide implementations for the standard set of model functions: + \l{QAbstractItemModel::}{flags()}, \l{QAbstractItemModel::}{data()}, + \l{QAbstractItemModel::}{headerData()}, + \l{QAbstractItemModel::}{columnCount()}, and + \l{QAbstractItemModel::}{rowCount()}. In addition, hierarchical models, + such as this one, need to provide implementations of + \l{QAbstractItemModel::}{index()} and \l{QAbstractItemModel::}{parent()}. + + An editable model needs to provide implementations of + \l{QAbstractItemModel::}{setData()} and + \l{QAbstractItemModel::}{setHeaderData()}, and must return a suitable + combination of flags from its \l{QAbstractItemModel::}{flags()} function. + + Since this example allows the dimensions of the model to be changed, + we must also implement \l{QAbstractItemModel::}{insertRows()}, + \l{QAbstractItemModel::}{insertColumns()}, + \l{QAbstractItemModel::}{removeRows()}, and + \l{QAbstractItemModel::}{removeColumns()}. + + \section1 Design + + As with the \l{itemviews/simpletreemodel}{Simple Tree Model} example, + the model simply acts as a wrapper around a collection + of instances of a \c TreeItem class. Each \c TreeItem is designed to + hold data for a row of items in a tree view, so it contains a list of + values corresponding to the data shown in each column. + + Since QTreeView provides a row-oriented view onto a model, it is + natural to choose a row-oriented design for data structures that + will supply data via a model to this kind of view. Although this makes + the tree model less flexible, and possibly less useful for use with + more sophisticated views, it makes it less complex to design and easier + to implement. + + \target Relations-between-internal-items + \table + \row \li \inlineimage itemviews-editabletreemodel-items.png + \li \b{Relations between internal items} + + When designing a data structure for use with a custom model, it is useful + to expose each item's parent via a function like + \l{TreeItem::parent}{TreeItem::parent()} because it will make + writing the model's own \l{QAbstractItemModel::}{parent()} function easier. + Similarly, a function like \l{TreeItem::child}{TreeItem::child()} is + helpful when implementing the model's \l{QAbstractItemModel::}{index()} + function. As a result, each \c TreeItem maintains information about + its parent and children, making it possible for us to traverse the tree + structure. + + The diagram shows how \c TreeItem instances are connected via their + \l{TreeItem::parent}{parent()} and \l{TreeItem::child}{child()} + functions. + + In the example shown, two top-level items, \b{A} and + \b{B}, can be obtained from the root item by calling its child() + function, and each of these items return the root node from their + parent() functions, though this is only shown for item \b{A}. + \endtable + + Each \c TreeItem stores data for each column in the row it represents + in its \c itemData private member (a list of QVariant objects). + Since there is a one-to-one mapping between each column in the view + and each entry in the list, we provide a simple + \l{TreeItem::data}{data()} function to read entries in the \c itemData + list and a \l{TreeItem::setData}{setData()} function to allow them to + be modified. + As with other functions in the item, this simplifies the implemention + of the model's \l{QAbstractItemModel::}{data()} and + \l{QAbstractItemModel::}{setData()} functions. + + We place an item at the root of the tree of items. This root item + corresponds to the null model index, \l{QModelIndex::}{QModelIndex()}, + that is used to represent the parent of a top-level item when handling + model indexes. + Although the root item does not have a visible representation in any of + the standard views, we use its internal list of QVariant objects to + store a list of strings that will be passed to views for use as + horizontal header titles. + + \table + \row \li \inlineimage itemviews-editabletreemodel-model.png + \li \b{Accessing data via the model} + + In the case shown in the diagram, the piece of information represented + by \b{a} can be obtained using the standard model/view API: + + \snippet doc/src/snippets/code/doc_src_examples_editabletreemodel.cpp 0 + + Since each items holds pieces of data for each column in a given row, + there can be many model indexes that map to the same \c TreeItem object. + For example, the information represented by \b{b} can be obtained + using the following code: + + \snippet doc/src/snippets/code/doc_src_examples_editabletreemodel.cpp 1 + + The same underlying \c TreeItem would be accessed to obtain information + for the other model indexes in the same row as \b{b}. + \endtable + + In the model class, \c TreeModel, we relate \c TreeItem objects to + model indexes by passing a pointer for each item when we create its + corresponding model index with QAbstractItemModel::createIndex() in + our \l{TreeModel::index}{index()} and \l{TreeModel::parent}{parent()} + implementations. + We can retrieve pointers stored in this way by calling the + \l{QModelIndex::}{internalPointer()} function on the relevant model + index - we create our own \l{TreeModel::getItem}{getItem()} function to + do this work for us, and call it from our \l{TreeModel::data}{data()} + and \l{TreeModel::parent}{parent()} implementations. + + Storing pointers to items is convenient when we control how they are + created and destroyed since we can assume that an address obtained from + \l{QModelIndex::}{internalPointer()} is a valid pointer. + However, some models need to handle items that are obtained from other + components in a system, and in many cases it is not possible to fully + control how items are created or destroyed. In such situations, a pure + pointer-based approach needs to be supplemented by safeguards to ensure + that the model does not attempt to access items that have been deleted. + + \table + \row \li \b{Storing information in the underlying data structure} + + Several pieces of data are stored as QVariant objects in the \c itemData + member of each \c TreeItem instance + + The diagram shows how pieces of information, + represented by the labels \b{a}, \b{b} and \b{c} in the + previous two diagrams, are stored in items \b{A}, \b{B} and + \b{C} in the underlying data structure. Note that pieces of + information from the same row in the model are all obtained from the + same item. Each element in a list corresponds to a piece of information + exposed by each column in a given row in the model. + + \li \inlineimage itemviews-editabletreemodel-values.png + \endtable + + Since the \c TreeModel implementation has been designed for use with + QTreeView, we have added a restriction on the way it uses \c TreeItem + instances: each item must expose the same number of columns of data. + This makes viewing the model consistent, allowing us to use the root + item to determine the number of columns for any given row, and only + adds the requirement that we create items containing enough data for + the total number of columns. As a result, inserting and removing + columns are time-consuming operations because we need to traverse the + entire tree to modify every item. + + An alternative approach would be to design the \c TreeModel class so + that it truncates or expands the list of data in individual \c TreeItem + instances as items of data are modified. However, this "lazy" resizing + approach would only allow us to insert and remove columns at the end of + each row and would not allow columns to be inserted or removed at + arbitrary positions in each row. + + \target Relating-items-using-model-indexes + \table + \row + \li \inlineimage itemviews-editabletreemodel-indexes.png + \li \b{Relating items using model indexes} + + As with the \l{itemviews/simpletreemodel}{Simple Tree Model} example, + the \c TreeModel needs to be able to take a model index, find the + corresponding \c TreeItem, and return model indexes that correspond to + its parents and children. + + In the diagram, we show how the model's \l{TreeModel::parent}{parent()} + implementation obtains the model index corresponding to the parent of + an item supplied by the caller, using the items shown in a + \l{Relations-between-internal-items}{previous diagram}. + + A pointer to item \b{C} is obtained from the corresponding model index + using the \l{QModelIndex::internalPointer()} function. The pointer was + stored internally in the index when it was created. Since the child + contains a pointer to its parent, we use its \l{TreeItem::parent}{parent()} + function to obtain a pointer to item \b{B}. The parent model index is + created using the QAbstractItemModel::createIndex() function, passing + the pointer to item \b{B} as the internal pointer. + \endtable + + \section1 TreeItem Class Definition + + The \c TreeItem class provides simple items that contain several + pieces of data, and which can provide information about their parent + and child items: + + \snippet itemviews/editabletreemodel/treeitem.h 0 + + We have designed the API to be similar to that provided by + QAbstractItemModel by giving each item functions to return the number + of columns of information, read and write data, and insert and remove + columns. However, we make the relationship between items explicit by + providing functions to deal with "children" rather than "rows". + + Each item contains a list of pointers to child items, a pointer to its + parent item, and a list of QVariant objects that correspond to + information held in columns in a given row in the model. + + \section1 TreeItem Class Implementation + + Each \c TreeItem is constructed with a list of data and an optional + parent item: + + \snippet itemviews/editabletreemodel/treeitem.cpp 0 + + Initially, each item has no children. These are added to the item's + internal \c childItems member using the \c insertChildren() function + described later. + + The destructor ensures that each child added to the item is deleted + when the item itself is deleted: + + \snippet itemviews/editabletreemodel/treeitem.cpp 1 + + \target TreeItem::parent + Since each item stores a pointer to its parent, the \c parent() function + is trivial: + + \snippet itemviews/editabletreemodel/treeitem.cpp 9 + + \target TreeItem::child + Three functions provide information about the children of an item. + \c child() returns a specific child from the internal list of children: + + \snippet itemviews/editabletreemodel/treeitem.cpp 2 + + The \c childCount() function returns the total number of children: + + \snippet itemviews/editabletreemodel/treeitem.cpp 3 + + The \c childNumber() function is used to determine the index of the child + in its parent's list of children. It accesses the parent's \c childItems + member directly to obtain this information: + + \snippet itemviews/editabletreemodel/treeitem.cpp 4 + + The root item has no parent item; for this item, we return zero to be + consistent with the other items. + + The \c columnCount() function simply returns the number of elements in + the internal \c itemData list of QVariant objects: + + \snippet itemviews/editabletreemodel/treeitem.cpp 5 + + \target TreeItem::data + Data is retrieved using the \c data() function, which accesses the + appropriate element in the \c itemData list: + + \snippet itemviews/editabletreemodel/treeitem.cpp 6 + + \target TreeItem::setData + Data is set using the \c setData() function, which only stores values + in the \c itemData list for valid list indexes, corresponding to column + values in the model: + + \snippet itemviews/editabletreemodel/treeitem.cpp 11 + + To make implementation of the model easier, we return true to indicate + whether the data was set successfully, or false if an invalid column + + Editable models often need to be resizable, enabling rows and columns to + be inserted and removed. The insertion of rows beneath a given model index + in the model leads to the insertion of new child items in the corresponding + item, handled by the \c insertChildren() function: + + \snippet itemviews/editabletreemodel/treeitem.cpp 7 + + This ensures that new items are created with the required number of columns + and inserted at a valid position in the internal \c childItems list. + Items are removed with the \c removeChildren() function: + + \snippet itemviews/editabletreemodel/treeitem.cpp 10 + + As discussed above, the functions for inserting and removing columns are + used differently to those for inserting and removing child items because + they are expected to be called on every item in the tree. We do this by + recursively calling this function on each child of the item: + + \snippet itemviews/editabletreemodel/treeitem.cpp 8 + + \section1 TreeModel Class Definition + + The \c TreeModel class provides an implementation of the QAbstractItemModel + class, exposing the necessary interface for a model that can be edited and + resized. + + \snippet itemviews/editabletreemodel/treemodel.h 0 + + The constructor and destructor are specific to this model. + + \snippet itemviews/editabletreemodel/treemodel.h 1 + + Read-only tree models only need to provide the above functions. The + following public functions provide support for editing and resizing: + + \snippet itemviews/editabletreemodel/treemodel.h 2 + + To simplify this example, the data exposed by the model is organized into + a data structure by the model's \l{TreeModel::setupModelData}{setupModelData()} + function. Many real world models will not process the raw data at all, but + simply work with an existing data structure or library API. + + \section1 TreeModel Class Implementation + + The constructor creates a root item and initializes it with the header + data supplied: + + \snippet itemviews/editabletreemodel/treemodel.cpp 0 + + We call the internal \l{TreeModel::setupModelData}{setupModelData()} + function to convert the textual data supplied to a data structure we can + use with the model. Other models may be initialized with a ready-made + data structure, or use an API to a library that maintains its own data. + + The destructor only has to delete the root item; all child items will + be recursively deleted by the \c TreeItem destructor. + + \snippet itemviews/editabletreemodel/treemodel.cpp 1 + + \target TreeModel::getItem + Since the model's interface to the other model/view components is based + on model indexes, and the internal data structure is item-based, many of + the functions implemented by the model need to be able to convert any + given model index to its corresponding item. For convenience and + consistency, we have defined a \c getItem() function to perform this + repetitive task: + + \snippet itemviews/editabletreemodel/treemodel.cpp 4 + + This function assumes that each model index it is passed corresponds to + a valid item in memory. If the index is invalid, or its internal pointer + does not refer to a valid item, the root item is returned instead. + + The model's \c rowCount() implementation is simple: it first uses the + \c getItem() function to obtain the relevant item, then returns the + number of children it contains: + + \snippet itemviews/editabletreemodel/treemodel.cpp 8 + + By contrast, the \c columnCount() implementation does not need to look + for a particular item because all items are defined to have the same + number of columns associated with them. + + \snippet itemviews/editabletreemodel/treemodel.cpp 2 + + As a result, the number of columns can be obtained directly from the root + item. + + To enable items to be edited and selected, the \c flags() function needs + to be implemented so that it returns a combination of flags that includes + the Qt::ItemIsEditable and Qt::ItemIsSelectable flags as well as + Qt::ItemIsEnabled: + + \snippet itemviews/editabletreemodel/treemodel.cpp 3 + + \target TreeModel::index + The model needs to be able to generate model indexes to allow other + components to request data and information about its structure. This task + is performed by the \c index() function, which is used to obtain model + indexes corresponding to children of a given parent item: + + \snippet itemviews/editabletreemodel/treemodel.cpp 5 + + In this model, we only return model indexes for child items if the parent + index is invalid (corresponding to the root item) or if it has a zero + column number. + + We use the custom \l{TreeModel::getItem}{getItem()} function to obtain + a \c TreeItem instance that corresponds to the model index supplied, and + request its child item that corresponds to the specified row. + + \snippet itemviews/editabletreemodel/treemodel.cpp 6 + + Since each item contains information for an entire row of data, we create + a model index to uniquely identify it by calling + \l{QAbstractItemModel::}{createIndex()} it with the row and column numbers + and a pointer to the item. In the \l{TreeModel::data}{data()} function, + we will use the item pointer and column number to access the data + associated with the model index; in this model, the row number is not + needed to identify data. + + \target TreeModel::parent + The \c parent() function supplies model indexes for parents of items + by finding the corresponding item for a given model index, using its + \l{TreeItem::parent}{parent()} function to obtain its parent item, + then creating a model index to represent the parent. (See + \l{Relating-items-using-model-indexes}{the above diagram}). + + \snippet itemviews/editabletreemodel/treemodel.cpp 7 + + Items without parents, including the root item, are handled by returning + a null model index. Otherwise, a model index is created and returned as + in the \l{TreeModel::index}{index()} function, with a suitable row number, + but with a zero column number to be consistent with the scheme used in + the \l{TreeModel::index}{index()} implementation. + + \target TreeModel::data + \target TreeModel::setupModelData + +*/ |