1/*
2 SPDX-FileCopyrightText: 2009 Stephen Kelly <[email protected]>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KDESCENDANTSPROXYMODEL_P_H
8#define KDESCENDANTSPROXYMODEL_P_H
9
10#include <QAbstractProxyModel>
11
12#include "kitemmodels_export.h"
13
14#include <memory>
15
16class KDescendantsProxyModelPrivate;
17
18/*!
19 * \class KDescendantsProxyModel
20 * \inmodule KItemModels
21 * \brief Proxy Model for restructuring a Tree into a list.
22 *
23 * A KDescendantsProxyModel may be used to alter how the items in the tree are presented.
24 *
25 * Given a model which is represented as a tree:
26 *
27 * \image entitytreemodel.png "A plain EntityTreeModel in a view"
28 *
29 * The KDescendantsProxyModel restructures the sourceModel to represent it as a flat list.
30 *
31 * \code
32 * // ... Create an entityTreeModel
33 * KDescendantsProxyModel *descProxy = new KDescendantsProxyModel(this);
34 * descProxy->setSourceModel(entityTree);
35 * view->setModel(descProxy);
36 * \endcode
37 *
38 * \image descendantentitiesproxymodel.png "A KDescendantsProxyModel."
39 *
40 * KDescendantEntitiesProxyModel can also display the ancestors of the index in the source model as part of its display.
41 *
42 * \code
43 * // ... Create an entityTreeModel
44 * KDescendantsProxyModel *descProxy = new KDescendantsProxyModel(this);
45 * descProxy->setSourceModel(entityTree);
46 *
47 * // #### This is new
48 * descProxy->setDisplayAncestorData(true);
49 * descProxy->setAncestorSeparator(QString(" / "));
50 *
51 * view->setModel(descProxy);
52 * \endcode
53 *
54 * \image descendantentitiesproxymodel-withansecnames.png "A KDescendantsProxyModel with ancestor names."
55 *
56 * \since 4.6
57 */
58class KITEMMODELS_EXPORT KDescendantsProxyModel : public QAbstractProxyModel
59{
60 Q_OBJECT
61
62 /*!
63 * \property KDescendantsProxyModel::model
64 * \since 5.62
65 */
66 Q_PROPERTY(QAbstractItemModel *model READ sourceModel WRITE setSourceModel NOTIFY sourceModelChanged)
67 /*!
68 * \property KDescendantsProxyModel::displayAncestorData
69 * \since 5.62
70 */
71 Q_PROPERTY(bool displayAncestorData READ displayAncestorData WRITE setDisplayAncestorData NOTIFY displayAncestorDataChanged)
72 /*!
73 * \property KDescendantsProxyModel::ancestorSeparator
74 * \since 5.62
75 */
76 Q_PROPERTY(QString ancestorSeparator READ ancestorSeparator WRITE setAncestorSeparator NOTIFY ancestorSeparatorChanged)
77
78 /*!
79 * \property KDescendantsProxyModel::expandsByDefault
80 * If true, all the nodes in the whole tree will be expanded upon loading and all items
81 * of the source model will be shown in the proxy.
82 * The default value is true.
83 * \since 5.74
84 */
85 Q_PROPERTY(bool expandsByDefault READ expandsByDefault WRITE setExpandsByDefault NOTIFY expandsByDefaultChanged)
86
87public:
88 enum AdditionalRoles {
89 // Note: use printf "0x%08X\n" $(($RANDOM*$RANDOM))
90 // to define additional roles.
91 LevelRole = 0x14823F9A,
92 ExpandableRole = 0x1CA894AD,
93 ExpandedRole = 0x1E413DA4,
94 HasSiblingsRole = 0x1633CE0C,
95 };
96
97 /*!
98 * Creates a new descendant entities proxy model.
99 *
100 * \a parent The parent object.
101 */
102 explicit KDescendantsProxyModel(QObject *parent = nullptr);
103
104 /*!
105 * Destroys the descendant entities proxy model.
106 */
107 ~KDescendantsProxyModel() override;
108
109 /*!
110 * Sets the source \a model of the proxy.
111 */
112 void setSourceModel(QAbstractItemModel *model) override;
113
114 /*!
115 * Set whether to show ancestor data in the model. If \a display is true, then
116 * a source model which is displayed as
117 *
118 * \code
119 * -> "Item 0-0" (this is row-depth)
120 * -> -> "Item 0-1"
121 * -> -> "Item 1-1"
122 * -> -> -> "Item 0-2"
123 * -> -> -> "Item 1-2"
124 * -> "Item 1-0"
125 * \endcode
126 *
127 * will be displayed as
128 *
129 * \code
130 * -> *Item 0-0"
131 * -> "Item 0-0 / Item 0-1"
132 * -> "Item 0-0 / Item 1-1"
133 * -> "Item 0-0 / Item 1-1 / Item 0-2"
134 * -> "Item 0-0 / Item 1-1 / Item 1-2"
135 * -> "Item 1-0"
136 * \endcode
137 *
138 * If \a display is false, the proxy will show
139 *
140 * \code
141 * -> *Item 0-0"
142 * -> "Item 0-1"
143 * -> "Item 1-1"
144 * -> "Item 0-2"
145 * -> "Item 1-2"
146 * -> "Item 1-0"
147 * \endcode
148 *
149 * Default is false.
150 */
151 void setDisplayAncestorData(bool display);
152
153 /*!
154 * Whether ancestor data will be displayed.
155 */
156 bool displayAncestorData() const;
157
158 /*!
159 * Sets the ancestor \a separator used between data of ancestors.
160 */
161 void setAncestorSeparator(const QString &separator);
162
163 /*!
164 * Separator used between data of ancestors.
165 */
166 QString ancestorSeparator() const;
167
168 QModelIndex mapFromSource(const QModelIndex &sourceIndex) const override;
169 QModelIndex mapToSource(const QModelIndex &proxyIndex) const override;
170
171 Qt::ItemFlags flags(const QModelIndex &index) const override;
172 QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;
173 int rowCount(const QModelIndex &parent = QModelIndex()) const override;
174 QVariant headerData(int section, Qt::Orientation orientation, int role) const override;
175
176 QMimeData *mimeData(const QModelIndexList &indexes) const override;
177 QStringList mimeTypes() const override;
178
179 bool hasChildren(const QModelIndex &parent = QModelIndex()) const override;
180 QModelIndex index(int, int, const QModelIndex &parent = QModelIndex()) const override;
181 QModelIndex parent(const QModelIndex &) const override;
182 int columnCount(const QModelIndex &index = QModelIndex()) const override;
183 QHash<int, QByteArray> roleNames() const override;
184
185 /*!
186 * If true, all the nodes in the whole tree will be expanded upon loading (default)
187 * \a expand whether we want everything expanded upon load
188 * \since 5.74
189 */
190 void setExpandsByDefault(bool expand);
191
192 /*!
193 * Returns true if all the tree nodes are expanded by default upon loading
194 * \since 5.74
195 */
196 bool expandsByDefault() const;
197
198 /*!
199 * Returns true if the source index is mapped in the proxy as expanded, therefore it will show its children
200 * \since 5.74
201 */
202 bool isSourceIndexExpanded(const QModelIndex &sourceIndex) const;
203
204 /*!
205 * Returns true if the source index is visible in the proxy, meaning all its parent hierarchy is expanded.
206 * \since 5.74
207 */
208 bool isSourceIndexVisible(const QModelIndex &sourceIndex) const;
209
210 /*!
211 * Maps a source index as expanded in the proxy, all its children will become visible.
212 * \a sourceIndex an index of the source model.
213 * \since 5.74
214 */
215 void expandSourceIndex(const QModelIndex &sourceIndex);
216
217 /*!
218 * Maps a source index as collapsed in the proxy, all its children will be hidden.
219 * \a sourceIndex an index of the source model.
220 * \since 5.74
221 */
222 void collapseSourceIndex(const QModelIndex &sourceIndex);
223
224 Qt::DropActions supportedDropActions() const override;
225
226 /*!
227 * Reimplemented to match all descendants.
228 */
229 virtual QModelIndexList match(const QModelIndex &start,
230 int role,
231 const QVariant &value,
232 int hits = 1,
233 Qt::MatchFlags flags = Qt::MatchFlags(Qt::MatchStartsWith | Qt::MatchWrap)) const override;
234
235Q_SIGNALS:
236 void sourceModelChanged();
237 void displayAncestorDataChanged();
238 void ancestorSeparatorChanged();
239 void expandsByDefaultChanged(bool expands);
240 void sourceIndexExpanded(const QModelIndex &sourceIndex);
241 void sourceIndexCollapsed(const QModelIndex &sourceIndex);
242
243private:
244 Q_DECLARE_PRIVATE(KDescendantsProxyModel)
245 std::unique_ptr<KDescendantsProxyModelPrivate> const d_ptr;
246
247 Q_PRIVATE_SLOT(d_func(), void sourceRowsAboutToBeInserted(const QModelIndex &, int, int))
248 Q_PRIVATE_SLOT(d_func(), void sourceRowsInserted(const QModelIndex &, int, int))
249 Q_PRIVATE_SLOT(d_func(), void sourceRowsAboutToBeRemoved(const QModelIndex &, int, int))
250 Q_PRIVATE_SLOT(d_func(), void sourceRowsRemoved(const QModelIndex &, int, int))
251 Q_PRIVATE_SLOT(d_func(), void sourceRowsAboutToBeMoved(const QModelIndex &, int, int, const QModelIndex &, int))
252 Q_PRIVATE_SLOT(d_func(), void sourceRowsMoved(const QModelIndex &, int, int, const QModelIndex &, int))
253 Q_PRIVATE_SLOT(d_func(), void sourceModelAboutToBeReset())
254 Q_PRIVATE_SLOT(d_func(), void sourceModelReset())
255 Q_PRIVATE_SLOT(d_func(), void sourceLayoutAboutToBeChanged())
256 Q_PRIVATE_SLOT(d_func(), void sourceLayoutChanged())
257 Q_PRIVATE_SLOT(d_func(), void sourceDataChanged(const QModelIndex &, const QModelIndex &))
258 Q_PRIVATE_SLOT(d_func(), void sourceModelDestroyed())
259
260 Q_PRIVATE_SLOT(d_func(), void processPendingParents())
261
262 // Make these private, they shouldn't be called by applications
263 // virtual bool insertRows(int , int, const QModelIndex & = QModelIndex());
264 // virtual bool insertColumns(int, int, const QModelIndex & = QModelIndex());
265 // virtual bool removeRows(int, int, const QModelIndex & = QModelIndex());
266 // virtual bool removeColumns(int, int, const QModelIndex & = QModelIndex());
267};
268
269#endif
270

source code of kitemmodels/src/core/kdescendantsproxymodel.h