Messagelib

model.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 <QAbstractItemModel>
12 #include <QHash>
13 #include <QList>
14 #include <QMultiHash>
15 #include <QVector>
16 
17 #include <core/enums.h>
18 
19 #include <ctime> // time_t
20 #include <memory>
21 
22 namespace MessageList
23 {
24 namespace Core
25 {
26 using MessageItemSetReference = long;
27 
28 class Filter;
29 class GroupHeaderItem;
30 class Item;
31 class MessageItem;
32 class Theme;
33 class StorageModel;
34 class View;
35 class ModelPrivate;
36 class SortOrder;
37 class Aggregation;
38 
39 /**
40  * This class manages the huge tree of displayable objects: GroupHeaderItems and MessageItems.
41  * The tree is exposed via a 'hacked' QAbstractItemModel interface to a QTreeView
42  * subclass (which is MessageList::View).
43  *
44  * The keypoint in this class is that it has to be non-blocking in manipulating the tree:
45  * fill, cleanup and update operations are performed in timed chunks. Perfect non-blocking
46  * behaviour is not possible since there are some small operations that basically can't be
47  * split in chunks. However, these exceptions apply to a minority of tasks and in the
48  * average case the user will not notice.
49  *
50  * The data for building the tree is obtained from a subclass of StorageModel. The
51  * StorageModel must offer a consistent rappresentation of a "flat" folder containing
52  * messages.
53  */
54 class Model : public QAbstractItemModel
55 {
56  friend class Item;
57  friend class ItemPrivate;
58 
59  Q_OBJECT
60 public:
61  /**
62  * Creates the mighty Model attached to the specified View.
63  */
64  explicit Model(View *pParent);
65 
66  /**
67  * Destroys the mighty model along with the tree of items it manages.
68  */
69  ~Model() override;
70 
71  /**
72  * Returns the StorageModel currently set.
73  */
74  StorageModel *storageModel() const;
75 
76  /**
77  * Sets the storage model from that the messages to be displayed should be fetched.
78  * The model is then reset and a new fill operation is started. The fill operation may
79  * or may not complete before setStorageModel() returns. This depends on the fill
80  * strategy and the size of the folder. You can check if the fill operation has
81  * completed by looking at the return value of isLoading().
82  *
83  * Pre-selection is the action of automatically selecting a message just after the folder
84  * has finished loading. We may want to select the message that was selected the last
85  * time this folder has been open, or we may want to select the first unread message.
86  * We also may want to do no pre-selection at all (for example, when the user
87  * starts navigating the view before the pre-selection could actually be made
88  * and pre-selecting would confuse him). The pre-selection is applied once
89  * loading is complete.
90  */
91  void setStorageModel(StorageModel *storageModel, PreSelectionMode preSelectionMode = PreSelectLastSelected);
92 
93  /**
94  * Sets the pre-selection mode.
95  *
96  * Called with PreSelectNone to abort any pending message pre-selection. This may be done if the user
97  * starts navigating the view and selecting items before we actually could
98  * apply the pre-selection.
99  */
100  void setPreSelectionMode(PreSelectionMode preSelect);
101 
102  /**
103  * Returns the hidden root item that all the messages are (or will be) attached to.
104  * The returned value is never 0.
105  */
106  Item *rootItem() const;
107 
108  /**
109  * Returns true if the view is currently loading, that is
110  * it's in the first (possibly lengthy) job batch after attaching to a StorageModel.
111  */
112  Q_REQUIRED_RESULT bool isLoading() const;
113 
114  /**
115  * Returns the message item that is at the _current_ storage row index
116  * or zero if no such storage item is found. Please note that this may return 0
117  * also if the specified storage row hasn't been actually read yet. This may happen
118  * if isLoading() returns true. In this case the only thing you can do is to retry in a while.
119  */
120  MessageItem *messageItemByStorageRow(int row) const;
121 
122  /**
123  * Sets the Aggregation mode.
124  * Does not reload the model in any way: you need to call setStorageModel( storageModel() ) for this to happen.
125  * The pointer ownership remains of the caller which must ensure its validity until the next
126  * call to setAggretation() or until this Model dies. The caller, in fact, is Widget which
127  * takes care of meeting the above conditions. The aggregation pointer must not be null.
128  */
129  void setAggregation(const Aggregation *aggregation);
130 
131  /**
132  * Sets the Theme.
133  * Does not reload the model in any way: you need to call setStorageModel( storageModel() ) for this to happen.
134  * The pointer ownership remains of the caller which must ensure its validity until the next
135  * call to setTheme() or until this Model dies. The caller, in fact, is Widget which
136  * takes care of meeting the above conditions. The theme pointer must not be null.
137  */
138  void setTheme(const Theme *theme);
139 
140  /**
141  * Sets the sort order. As with setTheme() and setAggregation(), this does not reload the
142  * model in any way.
143  */
144  void setSortOrder(const SortOrder *sortOrder);
145 
146  /**
147  * Returns the sort order
148  */
149  const SortOrder *sortOrder() const;
150 
151  /**
152  * Sets the Filter to be applied on messages. filter may be null (no filter is applied).
153  * The pointer ownership remains of the caller which must ensure its validity until the next
154  * call to setFilter() or until this Model dies. The caller, in fact, is Widget which
155  * takes care of meeting the above conditions. The Filter pointer may be null.
156  */
157  void setFilter(const Filter *filter);
158 
159  /**
160  * Creates a persistent set for the specified MessageItems and
161  * returns its reference. Later you can use this reference
162  * to retrieve the list of MessageItems that are still valid.
163  * See persistentSetActualMessageList() for that.
164  *
165  * Persistent sets consume resources (both memory and CPU time
166  * while manipulating the view) so be sure to call deletePersistentSet()
167  * when you no longer need it.
168  */
169  Q_REQUIRED_RESULT MessageItemSetReference createPersistentSet(const QVector<MessageItem *> &items);
170 
171  /**
172  * Returns the list of MessageItems that are still existing in the
173  * set pointed by the specified reference. This list will contain
174  * at most the messages that you have passed to createPersistentSet()
175  * but may contain less (even 0) if these MessageItem object were removed
176  * from the view for some reason.
177  */
178  Q_REQUIRED_RESULT QList<MessageItem *> persistentSetCurrentMessageItemList(MessageItemSetReference ref);
179 
180  /**
181  * Deletes the persistent set pointed by the specified reference.
182  * If the set does not exist anymore, nothing happens.
183  */
184  void deletePersistentSet(MessageItemSetReference ref);
185 
186  // Mandatory QAbstractItemModel interface.
187 
188  int columnCount(const QModelIndex &parent = QModelIndex()) const override;
189  QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;
190  QVariant headerData(int section, Qt::Orientation orientation, int role) const override;
191  QModelIndex index(int row, int column, const QModelIndex &parent = QModelIndex()) const override;
192  QModelIndex index(Item *item, int column) const;
193  QModelIndex parent(const QModelIndex &index) const override;
194  int rowCount(const QModelIndex &parent = QModelIndex()) const override;
195  Qt::ItemFlags flags(const QModelIndex &index) const override;
196 
197  /// Called when user initiates a drag from the messagelist
198  QMimeData *mimeData(const QModelIndexList &indexes) const override;
199 
200 Q_SIGNALS:
201  /**
202  * Notify the outside when updating the status bar with a message
203  * could be useful
204  */
205  void statusMessage(const QString &message);
206 
207 private:
208  friend class ModelPrivate;
209  std::unique_ptr<ModelPrivate> const d;
210 };
211 } // namespace Core
212 } // namespace MessageList
Q_OBJECTQ_OBJECT
const SortOrder * sortOrder() const
Returns the sort order.
Definition: model.cpp:384
The MessageItem class.
Definition: messageitem.h:34
DisplayRole
void setStorageModel(StorageModel *storageModel, PreSelectionMode preSelectionMode=PreSelectLastSelected)
Sets the storage model from that the messages to be displayed should be fetched.
Definition: model.cpp:740
Item * rootItem() const
Returns the hidden root item that all the messages are (or will be) attached to.
Definition: model.cpp:4521
Model(View *pParent)
Creates the mighty Model attached to the specified View.
Definition: model.cpp:304
void deletePersistentSet(MessageItemSetReference ref)
Deletes the persistent set pointed by the specified reference.
Definition: model.cpp:4566
Model
Definition: item.h:49
void setSortOrder(const SortOrder *sortOrder)
Sets the sort order.
Definition: model.cpp:379
typedef ItemFlags
Orientation
StorageModel * storageModel() const
Returns the StorageModel currently set.
Definition: model.cpp:690
MessageItem * messageItemByStorageRow(int row) const
Returns the message item that is at the current storage row index or zero if no such storage item is ...
Definition: model.cpp:4531
PreSelectionMode
Pre-selection is the action of automatically selecting a message just after the folder has finished l...
A class which holds information about sorting, e.g.
Definition: sortorder.h:34
QMimeData * mimeData(const QModelIndexList &indexes) const override
Called when user initiates a drag from the messagelist.
Definition: model.cpp:4507
void setAggregation(const Aggregation *aggregation)
Sets the Aggregation mode.
Definition: model.cpp:368
Q_SIGNALSQ_SIGNALS
QVariant data(const QModelIndex &index, int role=Qt::DisplayRole) const override
Definition: model.cpp:485
The Theme class defines the visual appearance of the MessageList.
Definition: theme.h:48
void setPreSelectionMode(PreSelectionMode preSelect)
Sets the pre-selection mode.
Definition: model.cpp:1001
The QAbstractItemModel based interface that you need to provide for your storage to work with Message...
void statusMessage(const QString &message)
Notify the outside when updating the status bar with a message could be useful.
This class is responsible of matching messages that should be displayed in the View.
Definition: filter.h:44
~Model() override
Destroys the mighty model along with the tree of items it manages.
Definition: model.cpp:350
A single item of the MessageList tree managed by MessageList::Model.
Definition: item.h:47
void setFilter(const Filter *filter)
Sets the Filter to be applied on messages.
Definition: model.cpp:389
void setTheme(const Theme *theme)
Sets the Theme.
Definition: model.cpp:374
QList< MessageItem * > persistentSetCurrentMessageItemList(MessageItemSetReference ref)
Returns the list of MessageItems that are still existing in the set pointed by the specified referenc...
Definition: model.cpp:4558
A set of aggregation options that can be applied to the MessageList::Model in a single shot.
Definition: aggregation.h:28
QObject * parent() const const
QString message
MessageItemSetReference createPersistentSet(const QVector< MessageItem * > &items)
Creates a persistent set for the specified MessageItems and returns its reference.
Definition: model.cpp:4544
bool isLoading() const
Returns true if the view is currently loading, that is it's in the first (possibly lengthy) job batch...
Definition: model.cpp:4526
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Mar 27 2023 04:08:18 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.