summaryrefslogtreecommitdiffstats
path: root/examples/widgets/doc/src/editabletreemodel.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'examples/widgets/doc/src/editabletreemodel.qdoc')
-rw-r--r--examples/widgets/doc/src/editabletreemodel.qdoc82
1 files changed, 37 insertions, 45 deletions
diff --git a/examples/widgets/doc/src/editabletreemodel.qdoc b/examples/widgets/doc/src/editabletreemodel.qdoc
index 68e10e3e78..15df678c87 100644
--- a/examples/widgets/doc/src/editabletreemodel.qdoc
+++ b/examples/widgets/doc/src/editabletreemodel.qdoc
@@ -1,36 +1,13 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** 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. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// 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 the model/view framework.
+ be used with other classes in the model/view framework.
\image itemviews-editabletreemodel.png
@@ -108,7 +85,7 @@
\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
+ As with other functions in the item, this simplifies the implementation
of the model's \l{QAbstractItemModel::}{data()} and
\l{QAbstractItemModel::}{setData()} functions.
@@ -253,32 +230,30 @@
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 itemviews/editabletreemodel/treeitem.cpp 1
+ 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 9
+ \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 2
+ \snippet itemviews/editabletreemodel/treeitem.cpp 1
The \c childCount() function returns the total number of children:
- \snippet itemviews/editabletreemodel/treeitem.cpp 3
+ \snippet itemviews/editabletreemodel/treeitem.cpp 2
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 itemviews/editabletreemodel/treeitem.cpp 4
+ \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.
@@ -286,20 +261,20 @@
The \c columnCount() function simply returns the number of elements in
the internal \c itemData list of QVariant objects:
- \snippet itemviews/editabletreemodel/treeitem.cpp 5
+ \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 6
+ \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 11
+ \snippet itemviews/editabletreemodel/treeitem.cpp 10
To make implementation of the model easier, we return true to indicate
that the data was set successfully.
@@ -309,20 +284,20 @@
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 7
+ \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 10
+ \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 8
+ \snippet itemviews/editabletreemodel/treeitem.cpp 7
\section1 TreeModel Class Definition
@@ -358,11 +333,12 @@
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.
- The destructor only has to delete the root item, which will cause all child
- items to be recursively deleted.
-
\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,
@@ -443,4 +419,20 @@
\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
*/