doc/src/examples/editabletreemodel.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example itemviews/editabletreemodel
  30     \title Editable Tree Model Example
  31
  32     This example shows how to implement a simple item-based tree model that can
  33     be used with other classes the model/view framework.
  34
  35     \image itemviews-editabletreemodel.png
  36
  37     The model supports editable items, custom headers, and the ability to
  38     insert and remove rows and columns. With these features, it is also
  39     possible to insert new child items, and this is shown in the supporting
  40     example code.
  41
  42     \note The model only shows the basic principles used when creating an
  43     editable, hierarchical model. You may wish to use the \l{ModelTest}
  44     project to test production models.
  45
  46     \section1 Overview
  47
  48     As described in the \l{Model Subclassing Reference}, models must
  49     provide implementations for the standard set of model functions:
  50     \l{QAbstractItemModel::}{flags()}, \l{QAbstractItemModel::}{data()},
  51     \l{QAbstractItemModel::}{headerData()}, and
  52     \l{QAbstractItemModel::}{rowCount()}. In addition, hierarchical models,
  53     such as this one, need to provide implementations of
  54     \l{QAbstractItemModel::}{index()} and \l{QAbstractItemModel::}{parent()}.
  55
  56     An editable model needs to provide implementations of
  57     \l{QAbstractItemModel::}{setData()} and
  58     \l{QAbstractItemModel::}{headerData()}, and must return a suitable
  59     combination of flags from its \l{QAbstractItemModel::}{flags()} function.
  60
  61     Since this example allows the dimensions of the model to be changed,
  62     we must also implement \l{QAbstractItemModel::}{insertRows()},
  63     \l{QAbstractItemModel::}{insertColumns()},
  64     \l{QAbstractItemModel::}{removeRows()}, and
  65     \l{QAbstractItemModel::}{removeColumns()}.
  66
  67     \section1 Design
  68
  69     As with the \l{itemviews/simpletreemodel}{Simple Tree Model} example,
  70     the model simply acts as a wrapper around a collection
  71     of instances of a \c TreeItem class. Each \c TreeItem is designed to
  72     hold data for a row of items in a tree view, so it contains a list of
  73     values corresponding to the data shown in each column.
  74
  75     Since QTreeView provides a row-oriented view onto a model, it is
  76     natural to choose a row-oriented design for data structures that
  77     will supply data via a model to this kind of view. Although this makes
  78     the tree model less flexible, and possibly less useful for use with
  79     more sophisticated views, it makes it less complex to design and easier
  80     to implement.
  81
  82     \target Relations-between-internal-items
  83     \table
  84     \row \o \inlineimage itemviews-editabletreemodel-items.png
  85     \o \bold{Relations between internal items}
  86
  87     When designing a data structure for use with a custom model, it is useful
  88     to expose each item's parent via a function like
  89     \l{TreeItem::parent}{TreeItem::parent()} because it will make
  90     writing the model's own \l{QAbstractItemModel::}{parent()} function easier.
  91     Similarly, a function like \l{TreeItem::child}{TreeItem::child()} is
  92     helpful when implementing the model's \l{QAbstractItemModel::}{index()}
  93     function. As a result, each \c TreeItem maintains information about
  94     its parent and children, making it possible for us to traverse the tree
  95     structure.
  96
  97     The diagram shows how \c TreeItem instances are connected via their
  98     \l{TreeItem::parent}{parent()} and \l{TreeItem::child}{child()}
  99     functions.
 100
 101     In the example shown, two top-level items, \bold{A} and
 102     \bold{B}, can be obtained from the root item by calling its child()
 103     function, and each of these items return the root node from their
 104     parent() functions, though this is only shown for item \bold{A}.
 105     \endtable
 106
 107     Each \c TreeItem stores data for each column in the row it represents
 108     in its \c itemData private member (a list of QVariant objects).
 109     Since there is a one-to-one mapping between each column in the view
 110     and each entry in the list, we provide a simple
 111     \l{TreeItem::data}{data()} function to read entries in the \c itemData
 112     list and a \l{TreeItem::setData}{setData()} function to allow them to
 113     be modified.
 114     As with other functions in the item, this simplifies the implemention
 115     of the model's \l{QAbstractItemModel::}{data()} and
 116     \l{QAbstractItemModel::}{setData()} functions.
 117
 118     We place an item at the root of the tree of items. This root item
 119     corresponds to the null model index, \l{QModelIndex::}{QModelIndex()},
 120     that is used to represent the parent of a top-level item when handling
 121     model indexes.
 122     Although the root item does not have a visible representation in any of
 123     the standard views, we use its internal list of QVariant objects to
 124     store a list of strings that will be passed to views for use as
 125     horizontal header titles.
 126
 127     \table
 128     \row \o \inlineimage itemviews-editabletreemodel-model.png
 129     \o \bold{Accessing data via the model}
 130
 131     In the case shown in the diagram, the piece of information represented
 132     by \bold{a} can be obtained using the standard model/view API:
 133
 134     \snippet doc/src/snippets/code/doc_src_examples_editabletreemodel.cpp 0
 135
 136     Since each items holds pieces of data for each column in a given row,
 137     there can be many model indexes that map to the same \c TreeItem object.
 138     For example, the information represented by \bold{b} can be obtained
 139     using the following code:
 140
 141     \snippet doc/src/snippets/code/doc_src_examples_editabletreemodel.cpp 1
 142
 143     The same underlying \c TreeItem would be accessed to obtain information
 144     for the other model indexes in the same row as \bold{b}.
 145     \endtable
 146
 147     In the model class, \c TreeModel, we relate \c TreeItem objects to
 148     model indexes by passing a pointer for each item when we create its
 149     corresponding model index with QAbstractItemModel::createIndex() in
 150     our \l{TreeModel::index}{index()} and \l{TreeModel::parent}{parent()}
 151     implementations.
 152     We can retrieve pointers stored in this way by calling the
 153     \l{QModelIndex::}{internalPointer()} function on the relevant model
 154     index - we create our own \l{TreeModel::getItem}{getItem()} function to
 155     do this work for us, and call it from our \l{TreeModel::data}{data()}
 156     and \l{TreeModel::parent}{parent()} implementations.
 157
 158     Storing pointers to items is convenient when we control how they are
 159     created and destroyed since we can assume that an address obtained from
 160     \l{QModelIndex::}{internalPointer()} is a valid pointer.
 161     However, some models need to handle items that are obtained from other
 162     components in a system, and in many cases it is not possible to fully
 163     control how items are created or destroyed. In such situations, a pure
 164     pointer-based approach needs to be supplemented by safeguards to ensure
 165     that the model does not attempt to access items that have been deleted.
 166
 167     \table
 168     \row \o \bold{Storing information in the underlying data structure}
 169
 170     Several pieces of data are stored as QVariant objects in the \c itemData
 171     member of each \c TreeItem instance
 172
 173     The diagram shows how pieces of information,
 174     represented by the labels \bold{a}, \bold{b} and \bold{c} in the
 175     previous two diagrams, are stored in items \bold{A}, \bold{B} and
 176     \bold{C} in the underlying data structure. Note that pieces of
 177     information from the same row in the model are all obtained from the
 178     same item. Each element in a list corresponds to a piece of information
 179     exposed by each column in a given row in the model.
 180
 181     \o \inlineimage itemviews-editabletreemodel-values.png
 182     \endtable
 183
 184     Since the \c TreeModel implementation has been designed for use with
 185     QTreeView, we have added a restriction on the way it uses \c TreeItem
 186     instances: each item must expose the same number of columns of data.
 187     This makes viewing the model consistent, allowing us to use the root
 188     item to determine the number of columns for any given row, and only
 189     adds the requirement that we create items containing enough data for
 190     the total number of columns. As a result, inserting and removing
 191     columns are time-consuming operations because we need to traverse the
 192     entire tree to modify every item.
 193
 194     An alternative approach would be to design the \c TreeModel class so
 195     that it truncates or expands the list of data in individual \c TreeItem
 196     instances as items of data are modified. However, this "lazy" resizing
 197     approach would only allow us to insert and remove columns at the end of
 198     each row and would not allow columns to be inserted or removed at
 199     arbitrary positions in each row.
 200
 201     \target Relating-items-using-model-indexes
 202     \table
 203     \row
 204     \o \inlineimage itemviews-editabletreemodel-indexes.png
 205     \o \bold{Relating items using model indexes}
 206
 207     As with the \l{itemviews/simpletreemodel}{Simple Tree Model} example,
 208     the \c TreeModel needs to be able to take a model index, find the
 209     corresponding \c TreeItem, and return model indexes that correspond to
 210     its parents and children.
 211
 212     In the diagram, we show how the model's \l{TreeModel::parent}{parent()}
 213     implementation obtains the model index corresponding to the parent of
 214     an item supplied by the caller, using the items shown in a
 215     \l{Relations-between-internal-items}{previous diagram}.
 216
 217     A pointer to item \bold{C} is obtained from the corresponding model index
 218     using the \l{QModelIndex::internalPointer()} function. The pointer was
 219     stored internally in the index when it was created. Since the child
 220     contains a pointer to its parent, we use its \l{TreeItem::parent}{parent()}
 221     function to obtain a pointer to item \bold{B}. The parent model index is
 222     created using the QAbstractItemModel::createIndex() function, passing
 223     the pointer to item \bold{B} as the internal pointer.
 224     \endtable
 225
 226     \section1 TreeItem Class Definition
 227
 228     The \c TreeItem class provides simple items that contain several
 229     pieces of data, and which can provide information about their parent
 230     and child items:
 231
 232     \snippet examples/itemviews/editabletreemodel/treeitem.h 0
 233
 234     We have designed the API to be similar to that provided by
 235     QAbstractItemModel by giving each item functions to return the number
 236     of columns of information, read and write data, and insert and remove
 237     columns. However, we make the relationship between items explicit by
 238     providing functions to deal with "children" rather than "rows".
 239
 240     Each item contains a list of pointers to child items, a pointer to its
 241     parent item, and a list of QVariant objects that correspond to
 242     information held in columns in a given row in the model.
 243
 244     \section1 TreeItem Class Implementation
 245
 246     Each \c TreeItem is constructed with a list of data and an optional
 247     parent item:
 248
 249     \snippet examples/itemviews/editabletreemodel/treeitem.cpp 0
 250
 251     Initially, each item has no children. These are added to the item's
 252     internal \c childItems member using the \c insertChildren() function
 253     described later.
 254
 255     The destructor ensures that each child added to the item is deleted
 256     when the item itself is deleted:
 257
 258     \snippet examples/itemviews/editabletreemodel/treeitem.cpp 1
 259
 260     \target TreeItem::parent
 261     Since each item stores a pointer to its parent, the \c parent() function
 262     is trivial:
 263
 264     \snippet examples/itemviews/editabletreemodel/treeitem.cpp 9
 265
 266     \target TreeItem::child
 267     Three functions provide information about the children of an item.
 268     \c child() returns a specific child from the internal list of children:
 269
 270     \snippet examples/itemviews/editabletreemodel/treeitem.cpp 2
 271
 272     The \c childCount() function returns the total number of children:
 273
 274     \snippet examples/itemviews/editabletreemodel/treeitem.cpp 3
 275
 276     The \c childNumber() function is used to determine the index of the child
 277     in its parent's list of children. It accesses the parent's \c childItems
 278     member directly to obtain this information:
 279
 280     \snippet examples/itemviews/editabletreemodel/treeitem.cpp 4
 281
 282     The root item has no parent item; for this item, we return zero to be
 283     consistent with the other items.
 284
 285     The \c columnCount() function simply returns the number of elements in
 286     the internal \c itemData list of QVariant objects:
 287
 288     \snippet examples/itemviews/editabletreemodel/treeitem.cpp 5
 289
 290     \target TreeItem::data
 291     Data is retrieved using the \c data() function, which accesses the
 292     appropriate element in the \c itemData list:
 293
 294     \snippet examples/itemviews/editabletreemodel/treeitem.cpp 6
 295
 296     \target TreeItem::setData
 297     Data is set using the \c setData() function, which only stores values
 298     in the \c itemData list for valid list indexes, corresponding to column
 299     values in the model:
 300
 301     \snippet examples/itemviews/editabletreemodel/treeitem.cpp 11
 302
 303     To make implementation of the model easier, we return true to indicate
 304     whether the data was set successfully, or false if an invalid column
 305
 306     Editable models often need to be resizable, enabling rows and columns to
 307     be inserted and removed. The insertion of rows beneath a given model index
 308     in the model leads to the insertion of new child items in the corresponding
 309     item, handled by the \c insertChildren() function:
 310
 311     \snippet examples/itemviews/editabletreemodel/treeitem.cpp 7
 312
 313     This ensures that new items are created with the required number of columns
 314     and inserted at a valid position in the internal \c childItems list.
 315     Items are removed with the \c removeChildren() function:
 316
 317     \snippet examples/itemviews/editabletreemodel/treeitem.cpp 10
 318
 319     As discussed above, the functions for inserting and removing columns are
 320     used differently to those for inserting and removing child items because
 321     they are expected to be called on every item in the tree. We do this by
 322     recursively calling this function on each child of the item:
 323
 324     \snippet examples/itemviews/editabletreemodel/treeitem.cpp 8
 325
 326     \section1 TreeModel Class Definition
 327
 328     The \c TreeModel class provides an implementation of the QAbstractItemModel
 329     class, exposing the necessary interface for a model that can be edited and
 330     resized.
 331
 332     \snippet examples/itemviews/editabletreemodel/treemodel.h 0
 333
 334     The constructor and destructor are specific to this model.
 335
 336     \snippet examples/itemviews/editabletreemodel/treemodel.h 1
 337
 338     Read-only tree models only need to provide the above functions. The
 339     following public functions provide support for editing and resizing:
 340
 341     \snippet examples/itemviews/editabletreemodel/treemodel.h 2
 342
 343     To simplify this example, the data exposed by the model is organized into
 344     a data structure by the model's \l{TreeModel::setupModelData}{setupModelData()}
 345     function. Many real world models will not process the raw data at all, but
 346     simply work with an existing data structure or library API.
 347
 348     \section1 TreeModel Class Implementation
 349
 350     The constructor creates a root item and initializes it with the header
 351     data supplied:
 352
 353     \snippet examples/itemviews/editabletreemodel/treemodel.cpp 0
 354
 355     We call the internal \l{TreeModel::setupModelData}{setupModelData()}
 356     function to convert the textual data supplied to a data structure we can
 357     use with the model. Other models may be initialized with a ready-made
 358     data structure, or use an API to a library that maintains its own data.
 359
 360     The destructor only has to delete the root item; all child items will
 361     be recursively deleted by the \c TreeItem destructor.
 362
 363     \snippet examples/itemviews/editabletreemodel/treemodel.cpp 1
 364
 365     \target TreeModel::getItem
 366     Since the model's interface to the other model/view components is based
 367     on model indexes, and the internal data structure is item-based, many of
 368     the functions implemented by the model need to be able to convert any
 369     given model index to its corresponding item. For convenience and
 370     consistency, we have defined a \c getItem() function to perform this
 371     repetitive task:
 372
 373     \snippet examples/itemviews/editabletreemodel/treemodel.cpp 4
 374
 375     This function assumes that each model index it is passed corresponds to
 376     a valid item in memory. If the index is invalid, or its internal pointer
 377     does not refer to a valid item, the root item is returned instead.
 378
 379     The model's \c rowCount() implementation is simple: it first uses the
 380     \c getItem() function to obtain the relevant item, then returns the
 381     number of children it contains:
 382
 383     \snippet examples/itemviews/editabletreemodel/treemodel.cpp 8
 384
 385     By contrast, the \c columnCount() implementation does not need to look
 386     for a particular item because all items are defined to have the same
 387     number of columns associated with them.
 388
 389     \snippet examples/itemviews/editabletreemodel/treemodel.cpp 2
 390
 391     As a result, the number of columns can be obtained directly from the root
 392     item.
 393
 394     To enable items to be edited and selected, the \c flags() function needs
 395     to be implemented so that it returns a combination of flags that includes
 396     the Qt::ItemIsEditable and Qt::ItemIsSelectable flags as well as
 397     Qt::ItemIsEnabled:
 398
 399     \snippet examples/itemviews/editabletreemodel/treemodel.cpp 3
 400
 401     \target TreeModel::index
 402     The model needs to be able to generate model indexes to allow other
 403     components to request data and information about its structure. This task
 404     is performed by the \c index() function, which is used to obtain model
 405     indexes corresponding to children of a given parent item:
 406
 407     \snippet examples/itemviews/editabletreemodel/treemodel.cpp 5
 408
 409     In this model, we only return model indexes for child items if the parent
 410     index is invalid (corresponding to the root item) or if it has a zero
 411     column number.
 412
 413     We use the custom \l{TreeModel::getItem}{getItem()} function to obtain
 414     a \c TreeItem instance that corresponds to the model index supplied, and
 415     request its child item that corresponds to the specified row.
 416
 417     \snippet examples/itemviews/editabletreemodel/treemodel.cpp 6
 418
 419     Since each item contains information for an entire row of data, we create
 420     a model index to uniquely identify it by calling
 421     \l{QAbstractItemModel::}{createIndex()} it with the row and column numbers
 422     and a pointer to the item. In the \l{TreeModel::data}{data()} function,
 423     we will use the item pointer and column number to access the data
 424     associated with the model index; in this model, the row number is not
 425     needed to identify data.
 426
 427     \target TreeModel::parent
 428     The \c parent() function supplies model indexes for parents of items
 429     by finding the corresponding item for a given model index, using its
 430     \l{TreeItem::parent}{parent()} function to obtain its parent item,
 431     then creating a model index to represent the parent. (See
 432     \l{Relating-items-using-model-indexes}{the above diagram}).
 433
 434     \snippet examples/itemviews/editabletreemodel/treemodel.cpp 7
 435
 436     Items without parents, including the root item, are handled by returning
 437     a null model index. Otherwise, a model index is created and returned as
 438     in the \l{TreeModel::index}{index()} function, with a suitable row number,
 439     but with a zero column number to be consistent with the scheme used in
 440     the \l{TreeModel::index}{index()} implementation.
 441
 442     \target TreeModel::data
 443     \target TreeModel::setupModelData
 444
 445 */