Messagelib

widget.h
1 /*
2  SPDX-FileCopyrightText: 2009 Kevin Ottens <[email protected]>
3 
4  SPDX-License-Identifier: GPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include <MessageList/QuickSearchLine>
10 #include <MessageList/View>
11 #include <MessageList/WidgetBase>
12 
13 #include <Akonadi/Item>
14 
15 #include <KMime/KMimeMessage>
16 
17 #include "messagelist_export.h"
18 #include <QVector>
19 class KXMLGUIClient;
20 class QWidget;
21 class KJob;
22 namespace MessageList
23 {
24 /**
25  * The Akonadi specific implementation of the Core::Widget.
26  *
27  * When a KXmlGuiWindow is passed to setXmlGuiClient, the XMLGUI
28  * defined context menu @c akonadi_messagelist_contextmenu is
29  * used if available.
30  *
31  */
32 class MESSAGELIST_EXPORT Widget : public MessageList::Core::Widget
33 {
34  Q_OBJECT
35 
36 public:
37  /**
38  * Create a new message list widget.
39  */
40  explicit Widget(QWidget *parent);
41  ~Widget() override;
42 
43  /**
44  * Sets the XML GUI client which the view is used in.
45  *
46  * This is needed if you want to use the built-in context menu.
47  * Passing 0 is ok and will disable the builtin context menu.
48  *
49  * @param xmlGuiClient The KXMLGUIClient the view is used in.
50  */
51  void setXmlGuiClient(KXMLGUIClient *xmlGuiClient);
52 
53  /**
54  * Returns the current message for the list as Akonadi::Item.
55  * May return an invalid Item if there is no current message or no current folder.
56  */
57  Q_REQUIRED_RESULT Akonadi::Item currentItem() const;
58 
59  /**
60  * Returns the current message for the list as KMime::Message::Ptr.
61  * May return 0 if there is no current message or no current folder.
62  */
63  Q_REQUIRED_RESULT KMime::Message::Ptr currentMessage() const;
64 
65  /**
66  * Returns true if this drag can be accepted by the underlying view
67  */
68  Q_REQUIRED_RESULT bool canAcceptDrag(const QDropEvent *e);
69 
70  /**
71  * Selects the next message item in the view.
72  *
73  * messageTypeFilter can be used to restrict the selection to only certain message types.
74  *
75  * existingSelectionBehaviour specifies how the existing selection
76  * is manipulated. It may be cleared, expanded or grown/shrunk.
77  *
78  * If centerItem is true then the specified item will be positioned
79  * at the center of the view, if possible.
80  * If loop is true then the "next" algorithm will restart from the beginning
81  * of the list if the end is reached, otherwise it will just stop returning false.
82  */
83  Q_REQUIRED_RESULT bool selectNextMessageItem(MessageList::Core::MessageTypeFilter messageTypeFilter,
84  MessageList::Core::ExistingSelectionBehaviour existingSelectionBehaviour,
85  bool centerItem,
86  bool loop);
87 
88  /**
89  * Selects the previous message item in the view.
90  * If centerItem is true then the specified item will be positioned
91  * at the center of the view, if possible.
92  *
93  * messageTypeFilter can be used to restrict the selection to only certain message types.
94  *
95  * existingSelectionBehaviour specifies how the existing selection
96  * is manipulated. It may be cleared, expanded or grown/shrunk.
97  *
98  * If loop is true then the "previous" algorithm will restart from the end
99  * of the list if the beginning is reached, otherwise it will just stop returning false.
100  */
101  Q_REQUIRED_RESULT bool selectPreviousMessageItem(MessageList::Core::MessageTypeFilter messageTypeFilter,
102  MessageList::Core::ExistingSelectionBehaviour existingSelectionBehaviour,
103  bool centerItem,
104  bool loop);
105 
106  /**
107  * Focuses the next message item in the view without actually selecting it.
108  *
109  * messageTypeFilter can be used to restrict the selection to only certain message types.
110  *
111  * If centerItem is true then the specified item will be positioned
112  * at the center of the view, if possible.
113  * If loop is true then the "next" algorithm will restart from the beginning
114  * of the list if the end is reached, otherwise it will just stop returning false.
115  */
116  Q_REQUIRED_RESULT bool focusNextMessageItem(MessageList::Core::MessageTypeFilter messageTypeFilter, bool centerItem, bool loop);
117 
118  /**
119  * Focuses the previous message item in the view without actually selecting it.
120  *
121  * messageTypeFilter can be used to restrict the selection to only certain message types.
122  *
123  * If centerItem is true then the specified item will be positioned
124  * at the center of the view, if possible.
125  * If loop is true then the "previous" algorithm will restart from the end
126  * of the list if the beginning is reached, otherwise it will just stop returning false.
127  */
128  Q_REQUIRED_RESULT bool focusPreviousMessageItem(MessageList::Core::MessageTypeFilter messageTypeFilter, bool centerItem, bool loop);
129 
130  /**
131  * Selects the currently focused message item. May do nothing if the
132  * focused message item is already selected (which is very likely).
133  * If centerItem is true then the specified item will be positioned
134  * at the center of the view, if possible.
135  */
136  void selectFocusedMessageItem(bool centerItem);
137 
138  /**
139  * Selects the first message item in the view that matches the specified Core::MessageTypeFilter.
140  * If centerItem is true then the specified item will be positioned
141  * at the center of the view, if possible.
142  *
143  * If the current view is already loaded then the request will
144  * be satisfied immediately (well... if an unread message exists at all).
145  * If the current view is still loading then the selection of the first
146  * message will be scheduled to be executed when loading terminates.
147  *
148  * So this function doesn't actually guarantee that an unread or new message
149  * was selected when the call returns. Take care :)
150  *
151  * The function returns true if a message was selected and false otherwise.
152  */
153  Q_REQUIRED_RESULT bool selectFirstMessageItem(MessageList::Core::MessageTypeFilter messageTypeFilter, bool centerItem);
154 
155  /**
156  * Selects the last message item in the view that matches the specified Core::MessageTypeFilter.
157  * If centerItem is true then the specified item will be positioned
158  * at the center of the view, if possible.
159  *
160  * The function returns true if a message was selected and false otherwise.
161  */
162  Q_REQUIRED_RESULT bool selectLastMessageItem(MessageList::Core::MessageTypeFilter messageTypeFilter, bool centerItem);
163 
164  /**
165  * Selects all the items in the current folder.
166  */
167  void selectAll();
168  /**
169  * If expand is true then it expands the current thread, otherwise
170  * collapses it.
171  */
172  void setCurrentThreadExpanded(bool expand);
173 
174  /**
175  * If expand is true then it expands all the threads, otherwise
176  * collapses them.
177  */
178  void setAllThreadsExpanded(bool expand);
179 
180  /**
181  * If expand is true then it expands all the groups (only the toplevel
182  * group item: inner threads are NOT expanded). If expand is false
183  * then it collapses all the groups. If no grouping is in effect
184  * then this function does nothing.
185  */
186  void setAllGroupsExpanded(bool expand);
187 
188  /**
189  * Sets the focus on the quick search line of the currently active tab.
190  */
191  void focusQuickSearch(const QString &selectedText);
192 
193  /**
194  * Returns the currently selected KMime::Message::Ptr (bound to current StorageModel).
195  * The list may be empty if there are no selected messages or no StorageModel.
196  *
197  * If includeCollapsedChildren is true then the children of the selected but
198  * collapsed items are also added to the list.
199  *
200  * The returned list is guaranteed to be valid only until you return control
201  * to the main even loop. Don't store it for any longer. If you need to reference
202  * this set of messages at a later stage then take a look at createPersistentSet().
203  */
204  Q_REQUIRED_RESULT QVector<KMime::Message::Ptr> selectionAsMessageList(bool includeCollapsedChildren = true) const;
205 
206  /**
207  * Returns the currently selected Items (bound to current StorageModel).
208  * The list may be empty if there are no selected messages or no StorageModel.
209  *
210  * If includeCollapsedChildren is true then the children of the selected but
211  * collapsed items are also added to the list.
212  *
213  * The returned list is guaranteed to be valid only until you return control
214  * to the main even loop. Don't store it for any longer. If you need to reference
215  * this set of messages at a later stage then take a look at createPersistentSet().
216  */
217  Q_REQUIRED_RESULT Akonadi::Item::List selectionAsMessageItemList(bool includeCollapsedChildren = true) const;
218 
219  /**
220  * Returns the currently selected Items id (bound to current StorageModel).
221  * The list may be empty if there are no selected messages or no StorageModel.
222  *
223  * If includeCollapsedChildren is true then the children of the selected but
224  * collapsed items are also added to the list.
225  *
226  * The returned list is guaranteed to be valid only until you return control
227  * to the main even loop. Don't store it for any longer. If you need to reference
228  * this set of messages at a later stage then take a look at createPersistentSet().
229  */
230 
231  Q_REQUIRED_RESULT QVector<qlonglong> selectionAsMessageItemListId(bool includeCollapsedChildren) const;
232  Q_REQUIRED_RESULT QVector<Akonadi::Item::Id> selectionAsListMessageId(bool includeCollapsedChildren) const;
233 
234  /**
235  * Returns the Akonadi::Item bound to the current StorageModel that
236  * are part of the current thread. The current thread is the thread
237  * that contains currentMessageItem().
238  * The list may be empty if there is no currentMessageItem() or no StorageModel.
239  *
240  * The returned list is guaranteed to be valid only until you return control
241  * to the main even loop. Don't store it for any longer. If you need to reference
242  * this set of messages at a later stage then take a look at createPersistentSet().
243  */
244  Q_REQUIRED_RESULT Akonadi::Item::List currentThreadAsMessageList() const;
245 
246  /**
247  * Returns the Akonadi::MessageStatus in the current quicksearch field.
248  */
249  Q_REQUIRED_RESULT QVector<Akonadi::MessageStatus> currentFilterStatus() const;
250 
251  /**
252  * Returns the search term in the current quicksearch field.
253  */
254  Q_REQUIRED_RESULT QString currentFilterSearchString() const;
255 
256  /**
257  * Returns true if the current Aggregation is threaded, false otherwise
258  * (or if there is no current Aggregation).
259  */
260  Q_REQUIRED_RESULT bool isThreaded() const;
261 
262  /**
263  * Fast function that determines if the selection is empty
264  */
265  Q_REQUIRED_RESULT bool selectionEmpty() const;
266 
267  /**
268  * Fills the lists of the selected message serial numbers and of the selected+visible ones.
269  * Returns true if the returned stats are valid (there is a current folder after all)
270  * and false otherwise. This is called by KMMainWidget in a single place so we optimize by
271  * making it a single sweep on the selection.
272  *
273  * If includeCollapsedChildren is true then the children of the selected but
274  * collapsed items are also included in the stats
275  */
276 
277  Q_REQUIRED_RESULT bool getSelectionStats(Akonadi::Item::List &selectedSernums,
278  Akonadi::Item::List &selectedVisibleSernums,
279  bool *allSelectedBelongToSameThread,
280  bool includeCollapsedChildren = true) const;
281  /**
282  * Deletes the persistent set pointed by the specified reference.
283  * If the set does not exist anymore, nothing happens.
284  */
285  void deletePersistentSet(MessageList::Core::MessageItemSetReference ref);
286 
287  /**
288  * If bMark is true this function marks the messages as "about to be removed"
289  * so they appear dimmer and aren't selectable in the view.
290  * If bMark is false then this function clears the "about to be removed" state
291  * for the specified MessageItems.
292  */
293  void markMessageItemsAsAboutToBeRemoved(MessageList::Core::MessageItemSetReference ref, bool bMark);
294 
295  /**
296  * Return Akonadi::Item from messageItemReference
297  */
298  Q_REQUIRED_RESULT Akonadi::Item::List itemListFromPersistentSet(MessageList::Core::MessageItemSetReference ref);
299 
300  /**
301  * Return a persistent set from current selection
302  */
303  Q_REQUIRED_RESULT MessageList::Core::MessageItemSetReference selectionAsPersistentSet(bool includeCollapsedChildren = true) const;
304 
305  /**
306  * Return a persistent set from current thread
307  */
308  Q_REQUIRED_RESULT MessageList::Core::MessageItemSetReference currentThreadAsPersistentSet() const;
309  Q_REQUIRED_RESULT Akonadi::Collection currentCollection() const;
310 
311  void setQuickSearchClickMessage(const QString &msg);
313 
314 protected:
315  /**
316  * Reimplemented from MessageList::Core::Widget
317  */
318  void fillMessageTagCombo() override;
319 
320  /**
321  * Reimplemented from MessageList::Core::Widget
322  */
323  void viewMessageSelected(MessageList::Core::MessageItem *msg) override;
324 
325  /**
326  * Reimplemented from MessageList::Core::Widget
327  */
328  void viewMessageActivated(MessageList::Core::MessageItem *msg) override;
329 
330  /**
331  * Reimplemented from MessageList::Core::Widget
332  */
333  void viewSelectionChanged() override;
334 
335  /**
336  * Reimplemented from MessageList::Core::Widget
337  */
338  void viewMessageListContextPopupRequest(const QVector<Core::MessageItem *> &selectedItems, const QPoint &globalPos) override;
339 
340  /**
341  * Reimplemented from MessageList::Core::Widget
342  */
343  void viewGroupHeaderContextPopupRequest(MessageList::Core::GroupHeaderItem *group, const QPoint &globalPos) override;
344 
345  /**
346  * Reimplemented from MessageList::Core::Widget
347  */
348  void viewDragEnterEvent(QDragEnterEvent *e) override;
349 
350  /**
351  * Reimplemented from MessageList::Core::Widget
352  */
353  void viewDragMoveEvent(QDragMoveEvent *e) override;
354 
355  /**
356  * Reimplemented from MessageList::Core::Widget
357  */
358  void viewDropEvent(QDropEvent *e) override;
359 
360  /**
361  * Reimplemented from MessageList::Core::Widget
362  */
363  void viewStartDragRequest() override;
364 
365  /**
366  * Reimplemented from MessageList::Core::Widget
367  */
368  void viewMessageStatusChangeRequest(MessageList::Core::MessageItem *msg, Akonadi::MessageStatus set, Akonadi::MessageStatus clear) override;
369 
370 private Q_SLOTS:
371  void slotCollapseItem();
372  void slotExpandItem();
373  void slotTagsFetched(KJob *job);
374 
375 Q_SIGNALS:
376  /**
377  * Emitted when a message is selected (that is, single clicked and thus made current in the view)
378  * Note that this message CAN be 0 (when the current item is cleared, for example).
379  *
380  * This signal is emitted when a SINGLE message is selected in the view, probably
381  * by clicking on it or by simple keyboard navigation. When multiple items
382  * are selected at once (by shift+clicking, for example) then you will get
383  * this signal only for the last clicked message (or at all, if the last shift+clicked
384  * thing is a group header...). You should handle selection changed in this case.
385  */
386  void messageSelected(const Akonadi::Item &item);
387 
388  /**
389  * Emitted when a message is doubleclicked or activated by other input means
390  */
391  void messageActivated(const Akonadi::Item &item);
392 
393  /**
394  * Emitted when the selection in the view changes.
395  */
396  void selectionChanged();
397 
398  /**
399  * Emitted when a message wants its status to be changed
400  */
401  void messageStatusChangeRequest(const Akonadi::Item &item, const Akonadi::MessageStatus &set, const Akonadi::MessageStatus &clear);
402 
403 private:
404  class WidgetPrivate;
405  std::unique_ptr<WidgetPrivate> const d;
406 };
407 } // namespace MessageList
The MessageItem class.
Definition: messageitem.h:34
Provides a widget which has the messagelist and the most important helper widgets,...
Definition: widgetbase.h:40
The Akonadi specific implementation of the Core::Widget.
Definition: widget.h:32
ExistingSelectionBehaviour
This enum is used in the view message selection functions (for instance View::selectNextMessage())
MessageTypeFilter
This enum is used in the view message selection functions (for instance View::nextMessageItem()).
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Mar 24 2023 04:08:32 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.