Messagelib

item.h
1/******************************************************************************
2 *
3 * SPDX-FileCopyrightText: 2008 Szymon Tomasz Stefanek <pragma@kvirc.net>
4 *
5 * SPDX-License-Identifier: GPL-2.0-or-later
6 *
7 *******************************************************************************/
8
9#pragma once
10
11#include <QList>
12#include <QString>
13
14#include <ctime> // for time_t
15
16#include <KMime/Headers>
17
18#include <Akonadi/MessageStatus>
19
20#include "core/model.h"
21#include "messagelist_export.h"
22
23namespace MessageList
24{
25namespace Core
26{
27class ItemPrivate;
28
29/**
30 * A single item of the MessageList tree managed by MessageList::Model.
31 *
32 * This class stores basic information needed in all the subclasses which
33 * at the moment of writing are MessageItem and GroupHeaderItem.
34 */
35class MESSAGELIST_EXPORT Item
36{
37 friend class Model;
38 friend class ModelPrivate;
39
40public:
41 /**
42 * The type of the Item.
43 */
44 enum Type {
45 GroupHeader, ///< This item is a GroupHeaderItem
46 Message, ///< This item is a MessageItem
47 InvisibleRoot ///< This item is just Item and it's the only InvisibleRoot per Model.
48 };
49
50 /**
51 * Specifies the initial expand status for the item that should be applied
52 * when it's attached to the viewable tree. Needed as a workaround for
53 * QTreeView limitations in handling item expansion.
54 */
56 ExpandNeeded, ///< Must expand when this item becomes viewable
57 NoExpandNeeded, ///< No expand needed at all
58 ExpandExecuted ///< Item already expanded
59 };
60
61protected:
62 /**
63 * Creates an Item. Only derived classes and MessageList::Model should access this.
64 */
65 Item(Type type);
66 Item(Type type, ItemPrivate *dd);
67
68public:
69 /**
70 * Destroys the Item. Should be protected just like the constructor but the QList<>
71 * helpers need to access it, so it's public actually.
72 */
73 virtual ~Item();
74
75 /**
76 * Returns the type of this item. The Type can be set only in the constructor.
77 */
78 [[nodiscard]] Type type() const;
79
80 /**
81 * The initial expand status we have to honor when attaching to the viewable root.
82 */
83 [[nodiscard]] InitialExpandStatus initialExpandStatus() const;
84
85 /**
86 * Set the initial expand status we have to honor when attaching to the viewable root.
87 */
88 void setInitialExpandStatus(InitialExpandStatus initialExpandStatus);
89
90 /**
91 * Is this item attached to the viewable root ?
92 */
93 [[nodiscard]] bool isViewable() const;
94
95 /**
96 * Return true if Item pointed by it is an ancestor of this item (that is,
97 * if it is its parent, parent of its parent, parent of its parent of its parent etc...
98 */
99 [[nodiscard]] bool hasAncestor(const Item *it) const;
100
101 /**
102 * Makes this item viewable, that is, notifies its existence to any listener
103 * attached to the "rowsInserted()" signal, most notably QTreeView.
104 *
105 * This will also make all the children viewable.
106 */
107 void setViewable(Model *model, bool bViewable);
108
109 /**
110 * Return the list of child items. May be null.
111 */
112 [[nodiscard]] QList<Item *> *childItems() const;
113
114 /**
115 * Returns the child item at position idx or 0 if idx is out of the allowable range.
116 */
117 [[nodiscard]] Item *childItem(int idx) const;
118
119 /**
120 * Returns the first child item, if any.
121 */
122 [[nodiscard]] Item *firstChildItem() const;
123
124 /**
125 * Returns the item that is visually below the specified child if this item.
126 * Note that the returned item may belong to a completely different subtree.
127 */
128 [[nodiscard]] Item *itemBelowChild(Item *child);
129
130 /**
131 * Returns the item that is visually above the specified child if this item.
132 * Note that the returned item may belong to a completely different subtree.
133 */
134 [[nodiscard]] Item *itemAboveChild(Item *child);
135
136 /**
137 * Returns the deepest item in the subtree originating at this item.
138 */
139 [[nodiscard]] Item *deepestItem();
140
141 /**
142 * Returns the item that is visually below this item in the tree.
143 * Note that the returned item may belong to a completely different subtree.
144 */
145 [[nodiscard]] Item *itemBelow();
146
147 /**
148 * Returns the item that is visually above this item in the tree.
149 * Note that the returned item may belong to a completely different subtree.
150 */
151 [[nodiscard]] Item *itemAbove();
152
153 /**
154 * Debug helper. Dumps the structure of this subtree.
155 */
156 void dump(const QString &prefix);
157
158 /**
159 * Returns the number of children of this Item.
160 */
161 [[nodiscard]] int childItemCount() const;
162
163 /**
164 * Convenience function that returns true if this item has children.
165 */
166 [[nodiscard]] bool hasChildren() const;
167
168 /**
169 * A structure used with MessageList::Item::childItemStats().
170 * Contains counts of total and unread messages in a subtree.
171 */
173 {
174 public:
175 unsigned int mTotalChildCount; // total
176 unsigned int mUnreadChildCount; // unread only
177 public:
179 : mTotalChildCount(0)
180 , mUnreadChildCount(0)
181 {
182 }
183 };
184
185 /**
186 * Gathers statistics about child items.
187 * For performance purposes assumes that this item has children.
188 * You MUST check it before calling it.
189 */
190 void childItemStats(ChildItemStats &stats) const;
191
192 /**
193 * Returns the actual index of the child Item item or -1 if
194 * item is not a child of this Item.
195 */
196 int indexOfChildItem(Item *item) const;
197
198 /**
199 * Sets the cached guess for the index of this item in the parent's child list.
200 *
201 * This is used to speed up the index lookup with the following algorithm:
202 * Ask the parent if this item is at the position specified by index guess (this costs ~O(1)).
203 * If the position matches we have finished, if it doesn't then perform
204 * a linear search via indexOfChildItem() (which costs ~O(n)).
205 */
206 void setIndexGuess(int index);
207
208 /**
209 * Returns the parent Item in the tree, or 0 if this item isn't attached to the tree.
210 * Please note that even if this item has a non-zero parent, it can be still non viewable.
211 * That is: the topmost parent of this item may be not attached to the viewable root.
212 */
213 [[nodiscard]] Item *parent() const;
214
215 /**
216 * Sets the parent for this item. You should also take care of inserting
217 * this item in the parent's child list.
218 */
219 void setParent(Item *pParent);
220
221 /**
222 * Returns the topmost parent item that is not a Root item (that is, is a Message or GroupHeader).
223 */
224 [[nodiscard]] Item *topmostNonRoot();
225
226 /**
227 * Returns the status associated to this Item.
228 */
229 const Akonadi::MessageStatus &status() const;
230
231 /**
232 * Sets the status associated to this Item.
233 */
234 void setStatus(Akonadi::MessageStatus status);
235
236 /**
237 * Returns a string describing the status e.g: "Read, Forwarded, Important"
238 */
239 [[nodiscard]] QString statusDescription() const;
240
241 /**
242 * Returns the size of this item (size of the Message, mainly)
243 */
244 size_t size() const;
245
246 /**
247 * Sets the size of this item (size of the Message, mainly)
248 */
249 void setSize(size_t size);
250
251 /**
252 * A string with a text rappresentation of size(). This is computed on-the-fly
253 * and not cached.
254 */
255 [[nodiscard]] QString formattedSize() const;
256
257 /**
258 * Returns the date of this item
259 */
260 time_t date() const;
261
262 /**
263 * Sets the date of this item
264 */
265 void setDate(time_t date);
266
267 /**
268 * A string with a text rappresentation of date() obtained via Manager. This is computed on-the-fly
269 * and not cached.
270 */
271 [[nodiscard]] QString formattedDate() const;
272
273 /**
274 * Returns the maximum date in the subtree originating from this item.
275 * This is kept up-to-date by MessageList::Model.
276 */
277 time_t maxDate() const;
278
279 /**
280 * Sets the maximum date in the subtree originating from this item.
281 */
282 void setMaxDate(time_t date);
283
284 /**
285 * A string with a text rappresentation of maxDate() obtained via Manager. This is computed on-the-fly
286 * and not cached.
287 */
288 [[nodiscard]] QString formattedMaxDate() const;
289
290 /**
291 * Recompute the maximum date from the current children list.
292 * Return true if the current max date changed and false otherwise.
293 */
294 bool recomputeMaxDate();
295
296 /**
297 * Returns the sender associated to this item.
298 */
299 [[nodiscard]] const QString &sender() const;
300
301 /**
302 * Sets the sender associated to this item.
303 */
304 void setSender(const QString &sender);
305
306 /**
307 * Display sender.
308 */
309 [[nodiscard]] QString displaySender() const;
310
311 /**
312 * Returns the receiver associated to this item.
313 */
314 const QString &receiver() const;
315
316 /**
317 * Sets the sender associated to this item.
318 */
319 void setReceiver(const QString &receiver);
320
321 /**
322 * Display receiver.
323 */
324 [[nodiscard]] QString displayReceiver() const;
325
326 /**
327 * Returns the sender or the receiver, depending on the underlying StorageModel settings.
328 */
329 const QString &senderOrReceiver() const;
330
331 /**
332 * Display sender or receiver.
333 */
334 [[nodiscard]] QString displaySenderOrReceiver() const;
335
336 /**
337 * Returns whether sender or receiver is supposed to be displayed.
338 */
339 bool useReceiver() const;
340
341 /**
342 * Returns the subject associated to this Item.
343 */
344 const QString &subject() const;
345
346 /**
347 * Sets the subject associated to this Item.
348 */
349 void setSubject(const QString &subject);
350
351 /**
352 * Returns the folder associated to this Item.
353 */
354 const QString &folder() const;
355
356 /**
357 * Sets the folder associated to this Item.
358 */
359 void setFolder(const QString &folder);
360
361 /**
362 * This is meant to be called right after the constructor.
363 * It sets up several items at once (so even if not inlined it's still a single call)
364 * and it skips some calls that can be avoided at constructor time.
365 */
366 void initialSetup(time_t date, size_t size, const QString &sender, const QString &receiver, bool useReceiver);
367
368 void setItemId(qint64 id);
369 [[nodiscard]] qint64 itemId() const;
370
371 void setParentCollectionId(qint64 id);
372 [[nodiscard]] qint64 parentCollectionId() const;
373
374 /**
375 * This is meant to be called right after the constructor for MessageItem objects.
376 * It sets up several items at once (so even if not inlined it's still a single call).
377 */
378 void setSubjectAndStatus(const QString &subject, Akonadi::MessageStatus status);
379
380 /**
381 * Appends an Item to this item's child list.
382 * The Model is used for beginInsertRows()/endInsertRows() calls.
383 */
384 int appendChildItem(Model *model, Item *child);
385
386 /**
387 * Appends a child item without inserting it via the model.
388 * This is useful in ThemeEditor which doesn't use a custom model for the items.
389 * You shouldn't need to use this function...
390 */
391 void rawAppendChildItem(Item *child);
392
393 /**
394 * Removes a child from this item's child list without deleting it.
395 * The Model is used for beginRemoveRows()/endRemoveRows() calls.
396 */
397 void takeChildItem(Model *model, Item *child);
398
399 /**
400 * Kills all the child items without emitting any signal, recursively.
401 * It should be used only when MessageList::Model is reset() afterwards.
402 */
403 void killAllChildItems();
404
405protected:
406 ItemPrivate *const d_ptr;
407 Q_DECLARE_PRIVATE(Item)
408};
409} // namespace Core
410} // namespace MessageList
A structure used with MessageList::Item::childItemStats().
Definition item.h:173
A single item of the MessageList tree managed by MessageList::Model.
Definition item.h:36
InitialExpandStatus
Specifies the initial expand status for the item that should be applied when it's attached to the vie...
Definition item.h:55
@ ExpandNeeded
Must expand when this item becomes viewable.
Definition item.h:56
@ NoExpandNeeded
No expand needed at all.
Definition item.h:57
Type
The type of the Item.
Definition item.h:44
@ Message
This item is a MessageItem.
Definition item.h:46
@ GroupHeader
This item is a GroupHeaderItem.
Definition item.h:45
This class manages the huge tree of displayable objects: GroupHeaderItems and MessageItems.
Definition model.h:54
Q_SCRIPTABLE CaptureState status()
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 17 2024 11:53:08 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.