fc924ae47e
Widget examples were moved into a widgets subfolder, but qdoc references were not updated. Change-Id: Id2a4573e723745b9827c664c852807d6116f8f6d Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com>
342 lines
15 KiB
Plaintext
342 lines
15 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** 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 widgets/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} 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 Programming#Models}{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 \li \inlineimage treemodel-structure.png
|
|
\li \b{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 widgets/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
|
|
\li The \c appendChildItem() is used to add data when the model is first
|
|
constructed and is not used during normal use.
|
|
\li The \c child() and \c childCount() functions allow the model to obtain
|
|
information about any child items.
|
|
\li 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.
|
|
\li 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 widgets/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 widgets/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 widgets/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 widgets/itemviews/simpletreemodel/treeitem.cpp 3
|
|
|
|
The number of child items held can be found with \c childCount():
|
|
|
|
\snippet widgets/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 widgets/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 widgets/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 widgets/itemviews/simpletreemodel/treeitem.cpp 6
|
|
|
|
The item's parent is found with \c parent():
|
|
|
|
\snippet widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/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 widgets/itemviews/simpletreemodel/treemodel.cpp 4
|
|
|
|
The \c headerData() function returns data that we conveniently stored
|
|
in the root item:
|
|
|
|
\snippet widgets/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:
|
|
|
|
\code
|
|
Getting Started How to familiarize yourself with Qt Designer
|
|
Launching Designer Running the Qt Designer application
|
|
The User Interface How to interact with Qt Designer
|
|
\endcode
|
|
\dots
|
|
\code
|
|
Connection Editing Mode Connecting widgets together with signals and slots
|
|
Connecting Objects Making connections in Qt Designer
|
|
Editing Connections Changing existing connections
|
|
\endcode
|
|
|
|
We process the text file with the following two rules:
|
|
|
|
\list
|
|
\li 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.
|
|
\li 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.
|
|
*/
|