Messagelib

widget.h
1/*
2 SPDX-FileCopyrightText: 2009 Kevin Ottens <ervin@kde.org>
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/Message>
16
17#include "messagelist_export.h"
18#include <QList>
19class KXMLGUIClient;
20class QWidget;
21class KJob;
22namespace 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 */
32class MESSAGELIST_EXPORT Widget : public MessageList::Core::Widget
33{
34 Q_OBJECT
35
36public:
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 [[nodiscard]] 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 [[nodiscard]] KMime::Message::Ptr currentMessage() const;
64
65 /**
66 * Returns true if this drag can be accepted by the underlying view
67 */
68 [[nodiscard]] 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 [[nodiscard]] 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 */
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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] QList<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 [[nodiscard]] 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 [[nodiscard]] QList<qlonglong> selectionAsMessageItemListId(bool includeCollapsedChildren) const;
232 [[nodiscard]] QList<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 */
245
246 /**
247 * Returns the Akonadi::MessageStatus in the current quicksearch field.
248 */
250
251 /**
252 * Returns the search term in the current quicksearch field.
253 */
254 [[nodiscard]] 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 [[nodiscard]] bool isThreaded() const;
261
262 /**
263 * Fast function that determines if the selection is empty
264 */
265 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] Akonadi::Item::List itemListFromPersistentSet(MessageList::Core::MessageItemSetReference ref);
299
300 /**
301 * Return a persistent set from current selection
302 */
303 [[nodiscard]] MessageList::Core::MessageItemSetReference selectionAsPersistentSet(bool includeCollapsedChildren = true) const;
304
305 /**
306 * Return a persistent set from current thread
307 */
308 [[nodiscard]] MessageList::Core::MessageItemSetReference currentThreadAsPersistentSet() const;
309 [[nodiscard]] Akonadi::Collection currentCollection() const;
310
311 void setQuickSearchClickMessage(const QString &msg);
312 [[nodiscard]] MessageList::Core::SearchMessageByButtons::SearchOptions currentOptions() const;
313
314protected:
315 /**
316 * Reimplemented from MessageList::Core::Widget
317 */
318 void fillMessageTagCombo() override;
319
320 /**
321 * Reimplemented from MessageList::Core::Widget
322 */
324
325 /**
326 * Reimplemented from MessageList::Core::Widget
327 */
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 QList<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 */
349
350 /**
351 * Reimplemented from MessageList::Core::Widget
352 */
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 */
369
370private:
371 MESSAGELIST_NO_EXPORT void slotCollapseItem();
372 MESSAGELIST_NO_EXPORT void slotExpandItem();
373 MESSAGELIST_NO_EXPORT void slotTagsFetched(KJob *job);
374
375Q_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 */
387
388 /**
389 * Emitted when a message is doubleclicked or activated by other input means
390 */
392
393 /**
394 * Emitted when the selection in the view changes.
395 */
397
398 /**
399 * Emitted when a message wants its status to be changed
400 */
402
403private:
404 class WidgetPrivate;
405 std::unique_ptr<WidgetPrivate> const d;
406};
407} // namespace MessageList
The MessageItem class.
Definition messageitem.h:35
Provides a widget which has the messagelist and the most important helper widgets,...
Definition widgetbase.h:41
The Akonadi specific implementation of the Core::Widget.
Definition widget.h:33
void setAllThreadsExpanded(bool expand)
If expand is true then it expands all the threads, otherwise collapses them.
QString currentFilterSearchString() const
Returns the search term in the current quicksearch field.
bool selectionEmpty() const
Fast function that determines if the selection is empty.
void selectAll()
Selects all the items in the current folder.
bool selectLastMessageItem(MessageList::Core::MessageTypeFilter messageTypeFilter, bool centerItem)
Selects the last message item in the view that matches the specified Core::MessageTypeFilter.
void viewDropEvent(QDropEvent *e) override
Reimplemented from MessageList::Core::Widget.
MessageList::Core::MessageItemSetReference currentThreadAsPersistentSet() const
Return a persistent set from current thread.
void messageSelected(const Akonadi::Item &item)
Emitted when a message is selected (that is, single clicked and thus made current in the view) Note t...
QList< qlonglong > selectionAsMessageItemListId(bool includeCollapsedChildren) const
Returns the currently selected Items id (bound to current StorageModel).
bool focusNextMessageItem(MessageList::Core::MessageTypeFilter messageTypeFilter, bool centerItem, bool loop)
Focuses the next message item in the view without actually selecting it.
void deletePersistentSet(MessageList::Core::MessageItemSetReference ref)
Deletes the persistent set pointed by the specified reference.
bool canAcceptDrag(const QDropEvent *e)
Returns true if this drag can be accepted by the underlying view.
bool focusPreviousMessageItem(MessageList::Core::MessageTypeFilter messageTypeFilter, bool centerItem, bool loop)
Focuses the previous message item in the view without actually selecting it.
void messageStatusChangeRequest(const Akonadi::Item &item, const Akonadi::MessageStatus &set, const Akonadi::MessageStatus &clear)
Emitted when a message wants its status to be changed.
QList< Akonadi::MessageStatus > currentFilterStatus() const
Returns the Akonadi::MessageStatus in the current quicksearch field.
MessageList::Core::MessageItemSetReference selectionAsPersistentSet(bool includeCollapsedChildren=true) const
Return a persistent set from current selection.
bool getSelectionStats(Akonadi::Item::List &selectedSernums, Akonadi::Item::List &selectedVisibleSernums, bool *allSelectedBelongToSameThread, bool includeCollapsedChildren=true) const
Fills the lists of the selected message serial numbers and of the selected+visible ones.
void selectFocusedMessageItem(bool centerItem)
Selects the currently focused message item.
void viewGroupHeaderContextPopupRequest(MessageList::Core::GroupHeaderItem *group, const QPoint &globalPos) override
Reimplemented from MessageList::Core::Widget.
void focusQuickSearch(const QString &selectedText)
Sets the focus on the quick search line of the currently active tab.
Akonadi::Item::List selectionAsMessageItemList(bool includeCollapsedChildren=true) const
Returns the currently selected Items (bound to current StorageModel).
void viewDragMoveEvent(QDragMoveEvent *e) override
Reimplemented from MessageList::Core::Widget.
void selectionChanged()
Emitted when the selection in the view changes.
void setCurrentThreadExpanded(bool expand)
If expand is true then it expands the current thread, otherwise collapses it.
Akonadi::Item currentItem() const
Returns the current message for the list as Akonadi::Item.
void viewStartDragRequest() override
Reimplemented from MessageList::Core::Widget.
bool isThreaded() const
Returns true if the current Aggregation is threaded, false otherwise (or if there is no current Aggre...
void markMessageItemsAsAboutToBeRemoved(MessageList::Core::MessageItemSetReference ref, bool bMark)
If bMark is true this function marks the messages as "about to be removed" so they appear dimmer and ...
bool selectNextMessageItem(MessageList::Core::MessageTypeFilter messageTypeFilter, MessageList::Core::ExistingSelectionBehaviour existingSelectionBehaviour, bool centerItem, bool loop)
Selects the next message item in the view.
void viewMessageSelected(MessageList::Core::MessageItem *msg) override
Reimplemented from MessageList::Core::Widget.
void setXmlGuiClient(KXMLGUIClient *xmlGuiClient)
Sets the XML GUI client which the view is used in.
void viewMessageStatusChangeRequest(MessageList::Core::MessageItem *msg, Akonadi::MessageStatus set, Akonadi::MessageStatus clear) override
Reimplemented from MessageList::Core::Widget.
Akonadi::Item::List itemListFromPersistentSet(MessageList::Core::MessageItemSetReference ref)
Return Akonadi::Item from messageItemReference.
KMime::Message::Ptr currentMessage() const
Returns the current message for the list as KMime::Message::Ptr.
void messageActivated(const Akonadi::Item &item)
Emitted when a message is doubleclicked or activated by other input means.
void fillMessageTagCombo() override
Reimplemented from MessageList::Core::Widget.
void viewDragEnterEvent(QDragEnterEvent *e) override
Reimplemented from MessageList::Core::Widget.
void viewSelectionChanged() override
Reimplemented from MessageList::Core::Widget.
void setAllGroupsExpanded(bool expand)
If expand is true then it expands all the groups (only the toplevel group item: inner threads are NOT...
QList< KMime::Message::Ptr > selectionAsMessageList(bool includeCollapsedChildren=true) const
Returns the currently selected KMime::Message::Ptr (bound to current StorageModel).
bool selectFirstMessageItem(MessageList::Core::MessageTypeFilter messageTypeFilter, bool centerItem)
Selects the first message item in the view that matches the specified Core::MessageTypeFilter.
void viewMessageListContextPopupRequest(const QList< Core::MessageItem * > &selectedItems, const QPoint &globalPos) override
Reimplemented from MessageList::Core::Widget.
Akonadi::Item::List currentThreadAsMessageList() const
Returns the Akonadi::Item bound to the current StorageModel that are part of the current thread.
Widget(QWidget *parent)
Create a new message list widget.
void viewMessageActivated(MessageList::Core::MessageItem *msg) override
Reimplemented from MessageList::Core::Widget.
bool selectPreviousMessageItem(MessageList::Core::MessageTypeFilter messageTypeFilter, MessageList::Core::ExistingSelectionBehaviour existingSelectionBehaviour, bool centerItem, bool loop)
Selects the previous message item in the view.
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-2024 The KDE developers.
Generated on Fri Jul 19 2024 11:56:56 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.