/****************************************************************************

**

** Copyright (C) 2010 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/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.

*/