Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example itemviews/editabletreemodel
++ \title Editable Tree Model Example
++ \examplecategory {User Interface Components}
++ \ingroup examples-itemviews
++ \brief This example shows how to implement a simple item-based tree model that can
++ be used with other classes in the model/view framework.
++
++ \image itemviews-editabletreemodel.png
++ {Application that show editing of a tree model}
++
++ 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.
++
++ \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
++ {Diagram of the relationship among root, parent, and child items}
++ \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 implementation
++ 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
++ {Diagram of the tree model with row and column indexes}
++ \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:
++
++ \code
++ QVariant a = model->index(0, 0, QModelIndex()).data();
++ \endcode
++
++ 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:
++
++ \code
++ QVariant b = model->index(1, 0, QModelIndex()).data();
++ \endcode
++
++ 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 the 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
++ {Diagram of a possible data structure using QVariant}
++ \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
++ {Diagram of accessing the tree model using model indexes}
++ \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, including 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 children are stored in std::unique_ptr to ensures that each child
++ added to the item is deleted when the item itself is deleted.
++
++ \target TreeItem::parent
++ Since each item stores a pointer to its parent, the \c parent() function
++ is trivial:
++
++ \snippet itemviews/editabletreemodel/treeitem.cpp 8
++
++ \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 1
++
++ The \c childCount() function returns the total number of children:
++
++ \snippet itemviews/editabletreemodel/treeitem.cpp 2
++
++ The \c row() 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 3
++
++ 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 4
++
++ \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 5
++
++ \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 10
++
++ To make implementation of the model easier, we return true to indicate
++ that the data was set successfully.
++
++ 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 6
++
++ 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 9
++
++ 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 7
++
++ \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 from a library that maintains its own data.
++
++ \snippet itemviews/editabletreemodel/treemodel.cpp 1
++
++ The destructor only has to delete the root item, which will cause all child
++ items to be recursively deleted. This is done automatically by the default
++ destructor since the root item is stored inside an unique_ptr.
++
++ \target TreeModel::getItem
++ Since the model's interface to the other model/view components is based
++ on model indexes, and since 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
++
++ Each model index passed to this function should correspond 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 it 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
++
++ \section1 Testing the model
++
++ Correctly implementing an item model can be challenging. The class
++ \l [QtTest] QAbstractItemModelTester from the \l [QtTest]{Qt Test} module
++ checks for model consistency, like the model index creation and
++ parent-child relationships.
++
++ You can test your model by just passing a model instance to the class
++ constructor, for instance as part of a Qt unit test:
++
++ \snippet itemviews/editabletreemodel/test.cpp 1
++
++ To create a test which can be run using the \c ctest executable,
++ \c add_test() is used:
++
++ \snippet itemviews/editabletreemodel/CMakeLists.txt 1
++ */