Messagelib

item.h
1 /******************************************************************************
2  *
3  * SPDX-FileCopyrightText: 2008 Szymon Tomasz Stefanek <[email protected]>
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 "messagelist_export.h"
21 #include <core/model.h>
22 
23 namespace MessageList
24 {
25 namespace Core
26 {
27 class 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  */
35 class MESSAGELIST_EXPORT Item
36 {
37  friend class Model;
38  friend class ModelPrivate;
39 
40 public:
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  */
55  enum InitialExpandStatus {
56  ExpandNeeded, ///< Must expand when this item becomes viewable
57  NoExpandNeeded, ///< No expand needed at all
58  ExpandExecuted ///< Item already expanded
59  };
60 
61 protected:
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 
68 public:
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  */
172  class ChildItemStats
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 
405 protected:
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:184
Model
Definition: item.h:49
Q_SCRIPTABLE CaptureState status()
InitialExpandStatus
Specifies the initial expand status for the item that should be applied when it's attached to the vie...
Definition: item.h:67
Type
The type of the Item.
Definition: item.h:56
This class manages the huge tree of displayable objects: GroupHeaderItems and MessageItems.
Definition: model.h:65
A single item of the MessageList tree managed by MessageList::Model.
Definition: item.h:47
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Nov 30 2023 03:56:25 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.