2 Copyright (c) 2009 Kevin Ottens <ervin@kde.org>
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or
7 (at your option) any later version.
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU General Public License for more details.
14 You should have received a copy of the GNU General Public License
15 along with this program; if not, write to the Free Software
16 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19 #ifndef __MESSAGELIST_WIDGET_H__
20 #define __MESSAGELIST_WIDGET_H__
22 #include <messagelist/core/widgetbase.h>
23 #include <messagelist/core/view.h>
24 #include <akonadi/item.h>
26 #include <kmime/kmime_message.h>
28 #include <messagelist/messagelist_export.h>
37 * The Akonadi specific implementation of the Core::Widget.
39 * When a KXmlGuiWindow is passed to setXmlGuiClient, the XMLGUI
40 * defined context menu @c akonadi_messagelist_contextmenu is
44 class MESSAGELIST_EXPORT Widget
: public MessageList::Core::Widget
50 * Create a new message list widget.
52 explicit Widget( QWidget
*parent
);
56 * Sets the XML GUI client which the view is used in.
58 * This is needed if you want to use the built-in context menu.
59 * Passing 0 is ok and will disable the builtin context menu.
61 * @param xmlGuiClient The KXMLGUIClient the view is used in.
63 void setXmlGuiClient( KXMLGUIClient
*xmlGuiClient
);
66 * Returns the current message for the list as Akonadi::Item.
67 * May return an invalid Item if there is no current message or no current folder.
69 Akonadi::Item
currentItem() const;
72 * Returns the current message for the list as KMime::Message::Ptr.
73 * May return 0 if there is no current message or no current folder.
75 KMime::Message::Ptr
currentMessage() const;
79 * Returns true if this drag can be accepted by the underlying view
81 bool canAcceptDrag( const QDropEvent
*e
);
84 * Selects the next message item in the view.
86 * messageTypeFilter can be used to restrict the selection to only certain message types.
88 * existingSelectionBehaviour specifies how the existing selection
89 * is manipulated. It may be cleared, expanded or grown/shrinked.
91 * If centerItem is true then the specified item will be positioned
92 * at the center of the view, if possible.
93 * If loop is true then the "next" algorithm will restart from the beginning
94 * of the list if the end is reached, otherwise it will just stop returning false.
96 bool selectNextMessageItem( MessageList::Core::MessageTypeFilter messageTypeFilter
,
97 MessageList::Core::ExistingSelectionBehaviour existingSelectionBehaviour
,
102 * Selects the previous message item in the view.
103 * If centerItem is true then the specified item will be positioned
104 * at the center of the view, if possible.
106 * messageTypeFilter can be used to restrict the selection to only certain message types.
108 * existingSelectionBehaviour specifies how the existing selection
109 * is manipulated. It may be cleared, expanded or grown/shrinked.
111 * If loop is true then the "previous" algorithm will restart from the end
112 * of the list if the beginning is reached, otherwise it will just stop returning false.
114 bool selectPreviousMessageItem( MessageList::Core::MessageTypeFilter messageTypeFilter
,
115 MessageList::Core::ExistingSelectionBehaviour existingSelectionBehaviour
,
120 * Focuses the next message item in the view without actually selecting it.
122 * messageTypeFilter can be used to restrict the selection to only certain message types.
124 * If centerItem is true then the specified item will be positioned
125 * at the center of the view, if possible.
126 * If loop is true then the "next" algorithm will restart from the beginning
127 * of the list if the end is reached, otherwise it will just stop returning false.
129 bool focusNextMessageItem( MessageList::Core::MessageTypeFilter messageTypeFilter
, bool centerItem
, bool loop
);
132 * Focuses the previous message item in the view without actually selecting it.
134 * messageTypeFilter can be used to restrict the selection to only certain message types.
136 * If centerItem is true then the specified item will be positioned
137 * at the center of the view, if possible.
138 * If loop is true then the "previous" algorithm will restart from the end
139 * of the list if the beginning is reached, otherwise it will just stop returning false.
141 bool focusPreviousMessageItem( MessageList::Core::MessageTypeFilter messageTypeFilter
, bool centerItem
, bool loop
);
144 * Selects the currently focused message item. May do nothing if the
145 * focused message item is already selected (which is very likely).
146 * If centerItem is true then the specified item will be positioned
147 * at the center of the view, if possible.
149 void selectFocusedMessageItem( bool centerItem
);
152 * Selects the first message item in the view that matches the specified Core::MessageTypeFilter.
153 * If centerItem is true then the specified item will be positioned
154 * at the center of the view, if possible.
156 * If the current view is already loaded then the request will
157 * be satisfied immediately (well... if an unread message exists at all).
158 * If the current view is still loading then the selection of the first
159 * message will be scheduled to be executed when loading terminates.
161 * So this function doesn't actually guarantee that an unread or new message
162 * was selected when the call returns. Take care :)
164 * The function returns true if a message was selected and false otherwise.
166 bool selectFirstMessageItem( MessageList::Core::MessageTypeFilter messageTypeFilter
, bool centerItem
);
169 * Selects all the items in the current folder.
173 * If expand is true then it expands the current thread, otherwise
176 void setCurrentThreadExpanded( bool expand
);
179 * If expand is true then it expands all the threads, otherwise
182 void setAllThreadsExpanded( bool expand
);
185 * If expand is true then it expands all the groups (only the toplevel
186 * group item: inner threads are NOT expanded). If expand is false
187 * then it collapses all the groups. If no grouping is in effect
188 * then this function does nothing.
190 void setAllGroupsExpanded( bool expand
);
193 * Sets the focus on the quick search line of the currently active tab.
195 void focusQuickSearch();
198 * Returns the currently selected KMime::Message::Ptr (bound to current StorageModel).
199 * The list may be empty if there are no selected messages or no StorageModel.
201 * If includeCollapsedChildren is true then the children of the selected but
202 * collapsed items are also added to the list.
204 * The returned list is guaranteed to be valid only until you return control
205 * to the main even loop. Don't store it for any longer. If you need to reference
206 * this set of messages at a later stage then take a look at createPersistentSet().
208 QList
<KMime::Message::Ptr
> selectionAsMessageList( bool includeCollapsedChildren
= true ) const;
211 * Returns the currently selected Items (bound to current StorageModel).
212 * The list may be empty if there are no selected messages or no StorageModel.
214 * If includeCollapsedChildren is true then the children of the selected but
215 * collapsed items are also added to the list.
217 * The returned list is guaranteed to be valid only until you return control
218 * to the main even loop. Don't store it for any longer. If you need to reference
219 * this set of messages at a later stage then take a look at createPersistentSet().
221 QList
<Akonadi::Item
> selectionAsMessageItemList( bool includeCollapsedChildren
= true ) const;
224 * Returns the currently selected Items id (bound to current StorageModel).
225 * The list may be empty if there are no selected messages or no StorageModel.
227 * If includeCollapsedChildren is true then the children of the selected but
228 * collapsed items are also added to the list.
230 * The returned list is guaranteed to be valid only until you return control
231 * to the main even loop. Don't store it for any longer. If you need to reference
232 * this set of messages at a later stage then take a look at createPersistentSet().
235 QVector
<qlonglong
> selectionAsMessageItemListId( bool includeCollapsedChildren
) const;
238 * Returns the Akonadi::Item bound to the current StorageModel that
239 * are part of the current thread. The current thread is the thread
240 * that contains currentMessageItem().
241 * The list may be empty if there is no currentMessageItem() or no StorageModel.
243 * The returned list is guaranteed to be valid only until you return control
244 * to the main even loop. Don't store it for any longer. If you need to reference
245 * this set of messages at a later stage then take a look at createPersistentSet().
247 QList
<Akonadi::Item
> currentThreadAsMessageList() const;
250 * Returns the Akonadi::MessageStatus in the current quicksearch field.
252 Akonadi::MessageStatus
currentFilterStatus() const;
255 * Returns the search term in the current quicksearch field.
257 QString
currentFilterSearchString() const;
260 * Returns true if the current Aggregation is threaded, false otherwise
261 * (or if there is no current Aggregation).
263 bool isThreaded() const;
266 * Fast function that determines if the selection is empty
268 bool selectionEmpty() const;
271 * Fills the lists of the selected message serial numbers and of the selected+visible ones.
272 * Returns true if the returned stats are valid (there is a current folder after all)
273 * and false otherwise. This is called by KMMainWidget in a single place so we optimize by
274 * making it a single sweep on the selection.
276 * If includeCollapsedChildren is true then the children of the selected but
277 * collapsed items are also included in the stats
280 bool getSelectionStats( Akonadi::Item::List
&selectedSernums
,
281 Akonadi::Item::List
&selectedVisibleSernums
,
282 bool * allSelectedBelongToSameThread
,
283 bool includeCollapsedChildren
= true ) const;
285 * Deletes the persistent set pointed by the specified reference.
286 * If the set does not exist anymore, nothing happens.
288 void deletePersistentSet( MessageList::Core::MessageItemSetReference ref
);
291 * If bMark is true this function marks the messages as "about to be removed"
292 * so they appear dimmer and aren't selectable in the view.
293 * If bMark is false then this function clears the "about to be removed" state
294 * for the specified MessageItems.
296 void markMessageItemsAsAboutToBeRemoved( MessageList::Core::MessageItemSetReference ref
, bool bMark
);
299 * Return Akonadi::Item from messageItemReference
301 QList
<Akonadi::Item
> itemListFromPersistentSet( MessageList::Core::MessageItemSetReference ref
);
304 * Return a persistent set from current selection
306 MessageList::Core::MessageItemSetReference
selectionAsPersistentSet( bool includeCollapsedChildren
= true ) const;
309 * Return a persistent set from current thread
311 MessageList::Core::MessageItemSetReference
currentThreadAsPersistentSet() const;
312 Akonadi::Collection
currentCollection() const;
317 * Reimplemented from MessageList::Core::Widget
319 virtual void fillMessageTagCombo( KComboBox
* combo
);
322 * Reimplemented from MessageList::Core::Widget
324 virtual void viewMessageSelected( MessageList::Core::MessageItem
*msg
);
327 * Reimplemented from MessageList::Core::Widget
329 virtual void viewMessageActivated( MessageList::Core::MessageItem
*msg
);
332 * Reimplemented from MessageList::Core::Widget
334 virtual void viewSelectionChanged();
337 * Reimplemented from MessageList::Core::Widget
339 virtual void viewMessageListContextPopupRequest( const QList
< MessageList::Core::MessageItem
* > &selectedItems
, const QPoint
&globalPos
);
342 * Reimplemented from MessageList::Core::Widget
344 virtual void viewGroupHeaderContextPopupRequest( MessageList::Core::GroupHeaderItem
*group
, const QPoint
&globalPos
);
347 * Reimplemented from MessageList::Core::Widget
349 virtual void viewDragEnterEvent( QDragEnterEvent
* e
);
352 * Reimplemented from MessageList::Core::Widget
354 virtual void viewDragMoveEvent( QDragMoveEvent
* e
);
357 * Reimplemented from MessageList::Core::Widget
359 virtual void viewDropEvent( QDropEvent
* e
);
362 * Reimplemented from MessageList::Core::Widget
364 virtual void viewStartDragRequest();
367 * Reimplemented from MessageList::Core::Widget
369 virtual void viewMessageStatusChangeRequest( MessageList::Core::MessageItem
*msg
, const Akonadi::MessageStatus
&set
, const Akonadi::MessageStatus
&clear
);
376 * Emitted when a message is selected (that is, single clicked and thus made current in the view)
377 * Note that this message CAN be 0 (when the current item is cleared, for example).
379 * This signal is emitted when a SINGLE message is selected in the view, probably
380 * by clicking on it or by simple keyboard navigation. When multiple items
381 * are selected at once (by shift+clicking, for example) then you will get
382 * this signal only for the last clicked message (or at all, if the last shift+clicked
383 * thing is a group header...). You should handle selection changed in this case.
385 void messageSelected( const Akonadi::Item
&item
);
388 * Emitted when a message is doubleclicked or activated by other input means
390 void messageActivated( const Akonadi::Item
&item
);
393 * Emitted when the selection in the view changes.
395 void selectionChanged();
398 * Emitted when a message wants its status to be changed
400 void messageStatusChangeRequest( const Akonadi::Item
&item
, const Akonadi::MessageStatus
&set
, const Akonadi::MessageStatus
&clear
);
407 } // namespace MessageList
409 #endif //!__MESSAGELIST_WIDGET_H__