MCL/sf/mw/qt: comparison doc/src/examples/editabletreemodel.qdoc

equal deleted inserted replaced

--1:000000000000
+:1918ee327afb
+/****************************************************************************
+**
+** Copyright (C) 2009 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/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()}, 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::}{headerData()}, 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 \o \inlineimage itemviews-editabletreemodel-items.png
+\o \bold{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, \bold{A} and
+\bold{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 \bold{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 \o \inlineimage itemviews-editabletreemodel-model.png
+\o \bold{Accessing data via the model}
+In the case shown in the diagram, the piece of information represented
+by \bold{a} can be obtained using the standard model/view API:
+\snippet doc/src/snippets/code/doc_src_examples_editabletreemodel.qdoc 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 \bold{b} can be obtained
+using the following code:
+\snippet doc/src/snippets/code/doc_src_examples_editabletreemodel.qdoc 1
+The same underlying \c TreeItem would be accessed to obtain information
+for the other model indexes in the same row as \bold{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 \o \bold{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 \bold{a}, \bold{b} and \bold{c} in the
+previous two diagrams, are stored in items \bold{A}, \bold{B} and
+\bold{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.
+\o \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
+\o \inlineimage itemviews-editabletreemodel-indexes.png
+\o \bold{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 \bold{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 \bold{B}. The parent model index is
+created using the QAbstractItemModel::createIndex() function, passing
+the pointer to item \bold{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 examples/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 examples/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 examples/itemviews/editabletreemodel/treeitem.cpp 1
+\target TreeItem::parent
+Since each item stores a pointer to its parent, the \c parent() function
+is trivial:
+\snippet examples/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 examples/itemviews/editabletreemodel/treeitem.cpp 2
+The \c childCount() function returns the total number of children:
+\snippet examples/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 examples/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 examples/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 examples/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 examples/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 examples/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 examples/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 examples/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 examples/itemviews/editabletreemodel/treemodel.h 0
+The constructor and destructor are specific to this model.
+\snippet examples/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 examples/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 examples/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 examples/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 examples/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 examples/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 examples/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 examples/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 examples/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 examples/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 examples/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
+*/