messagelist/widget.h

   1 /*
   2     Copyright (c) 2009 Kevin Ottens <ervin@kde.org>
   3
   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.
   8
   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.
  13
  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.
  17 */
  18
  19 #ifndef __MESSAGELIST_WIDGET_H__
  20 #define __MESSAGELIST_WIDGET_H__
  21
  22 #include <messagelist/core/widgetbase.h>
  23 #include <messagelist/core/view.h>
  24 #include <akonadi/item.h>
  25
  26 #include <kmime/kmime_message.h>
  27
  28 #include <messagelist/messagelist_export.h>
  29
  30 class KXMLGUIClient;
  31 class QWidget;
  32
  33 namespace MessageList
  34 {
  35
  36 /**
  37  * The Akonadi specific implementation of the Core::Widget.
  38  *
  39  * When a KXmlGuiWindow is passed to setXmlGuiClient, the XMLGUI
  40  * defined context menu @c akonadi_messagelist_contextmenu is
  41  * used if available.
  42  *
  43  */
  44 class MESSAGELIST_EXPORT Widget : public MessageList::Core::Widget
  45 {
  46   Q_OBJECT
  47
  48 public:
  49   /**
  50    * Create a new message list widget.
  51    */
  52   explicit Widget( QWidget *parent );
  53   ~Widget();
  54
  55   /**
  56    * Sets the XML GUI client which the view is used in.
  57    *
  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.
  60    *
  61    * @param xmlGuiClient The KXMLGUIClient the view is used in.
  62    */
  63   void setXmlGuiClient( KXMLGUIClient *xmlGuiClient );
  64
  65   /**
  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.
  68    */
  69   Akonadi::Item currentItem() const;
  70
  71   /**
  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.
  74    */
  75   KMime::Message::Ptr currentMessage() const;
  76
  77
  78   /**
  79    * Returns true if this drag can be accepted by the underlying view
  80    */
  81   bool canAcceptDrag( const QDropEvent *e );
  82
  83   /**
  84    * Selects the next message item in the view.
  85    *
  86    * messageTypeFilter can be used to restrict the selection to only certain message types.
  87    *
  88    * existingSelectionBehaviour specifies how the existing selection
  89    * is manipulated. It may be cleared, expanded or grown/shrinked.
  90    *
  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.
  95    */
  96   bool selectNextMessageItem( MessageList::Core::MessageTypeFilter messageTypeFilter,
  97                               MessageList::Core::ExistingSelectionBehaviour existingSelectionBehaviour,
  98                               bool centerItem,
  99                               bool loop );
 100
 101   /**
 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.
 105    *
 106    * messageTypeFilter can be used to restrict the selection to only certain message types.
 107    *
 108    * existingSelectionBehaviour specifies how the existing selection
 109    * is manipulated. It may be cleared, expanded or grown/shrinked.
 110    *
 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.
 113    */
 114   bool selectPreviousMessageItem( MessageList::Core::MessageTypeFilter messageTypeFilter,
 115                                   MessageList::Core::ExistingSelectionBehaviour existingSelectionBehaviour,
 116                                   bool centerItem,
 117                                   bool loop );
 118
 119   /**
 120    * Focuses the next message item in the view without actually selecting it.
 121    *
 122    * messageTypeFilter can be used to restrict the selection to only certain message types.
 123    *
 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.
 128    */
 129   bool focusNextMessageItem( MessageList::Core::MessageTypeFilter messageTypeFilter, bool centerItem, bool loop );
 130
 131   /**
 132    * Focuses the previous message item in the view without actually selecting it.
 133    *
 134    * messageTypeFilter can be used to restrict the selection to only certain message types.
 135    *
 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.
 140    */
 141   bool focusPreviousMessageItem( MessageList::Core::MessageTypeFilter messageTypeFilter, bool centerItem, bool loop );
 142
 143   /**
 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.
 148    */
 149   void selectFocusedMessageItem( bool centerItem );
 150
 151   /**
 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.
 155    *
 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.
 160    *
 161    * So this function doesn't actually guarantee that an unread or new message
 162    * was selected when the call returns. Take care :)
 163    *
 164    * The function returns true if a message was selected and false otherwise.
 165    */
 166   bool selectFirstMessageItem( MessageList::Core::MessageTypeFilter messageTypeFilter, bool centerItem );
 167
 168   /**
 169    * Selects all the items in the current folder.
 170    */
 171   void selectAll();
 172   /**
 173    * If expand is true then it expands the current thread, otherwise
 174    * collapses it.
 175    */
 176   void setCurrentThreadExpanded( bool expand );
 177
 178   /**
 179    * If expand is true then it expands all the threads, otherwise
 180    * collapses them.
 181    */
 182   void setAllThreadsExpanded( bool expand );
 183
 184   /**
 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.
 189    */
 190   void setAllGroupsExpanded( bool expand );
 191
 192   /**
 193    * Sets the focus on the quick search line of the currently active tab.
 194    */
 195   void focusQuickSearch();
 196
 197   /**
 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.
 200    *
 201    * If includeCollapsedChildren is true then the children of the selected but
 202    * collapsed items are also added to the list.
 203    *
 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().
 207    */
 208   QList<KMime::Message::Ptr > selectionAsMessageList( bool includeCollapsedChildren = true ) const;
 209
 210   /**
 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.
 213    *
 214    * If includeCollapsedChildren is true then the children of the selected but
 215    * collapsed items are also added to the list.
 216    *
 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().
 220    */
 221   QList<Akonadi::Item> selectionAsMessageItemList( bool includeCollapsedChildren = true ) const;
 222
 223   /**
 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.
 226    *
 227    * If includeCollapsedChildren is true then the children of the selected but
 228    * collapsed items are also added to the list.
 229    *
 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().
 233    */
 234
 235   QVector<qlonglong> selectionAsMessageItemListId( bool includeCollapsedChildren ) const;
 236
 237   /**
 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.
 242    *
 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().
 246    */
 247   QList<Akonadi::Item> currentThreadAsMessageList() const;
 248
 249   /**
 250    * Returns the Akonadi::MessageStatus in the current quicksearch field.
 251    */
 252   Akonadi::MessageStatus currentFilterStatus() const;
 253
 254   /**
 255    * Returns the search term in the current quicksearch field.
 256    */
 257   QString currentFilterSearchString() const;
 258
 259   /**
 260    * Returns true if the current Aggregation is threaded, false otherwise
 261    * (or if there is no current Aggregation).
 262    */
 263   bool isThreaded() const;
 264
 265   /**
 266    * Fast function that determines if the selection is empty
 267    */
 268   bool selectionEmpty() const;
 269
 270   /**
 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.
 275    *
 276    * If includeCollapsedChildren is true then the children of the selected but
 277    * collapsed items are also included in the stats
 278    */
 279
 280   bool getSelectionStats( Akonadi::Item::List &selectedSernums,
 281                           Akonadi::Item::List &selectedVisibleSernums,
 282                           bool * allSelectedBelongToSameThread,
 283                           bool includeCollapsedChildren = true ) const;
 284   /**
 285    * Deletes the persistent set pointed by the specified reference.
 286    * If the set does not exist anymore, nothing happens.
 287    */
 288   void deletePersistentSet( MessageList::Core::MessageItemSetReference ref );
 289
 290   /**
 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.
 295    */
 296   void markMessageItemsAsAboutToBeRemoved( MessageList::Core::MessageItemSetReference ref, bool bMark );
 297
 298   /**
 299    * Return Akonadi::Item from messageItemReference
 300    */
 301   QList<Akonadi::Item> itemListFromPersistentSet( MessageList::Core::MessageItemSetReference ref );
 302
 303   /**
 304    * Return a persistent set from current selection
 305    */
 306   MessageList::Core::MessageItemSetReference selectionAsPersistentSet( bool includeCollapsedChildren = true ) const;
 307
 308   /**
 309    * Return a persistent set from current thread
 310    */
 311   MessageList::Core::MessageItemSetReference currentThreadAsPersistentSet() const;
 312   Akonadi::Collection currentCollection() const;
 313
 314 protected:
 315
 316   /**
 317    * Reimplemented from MessageList::Core::Widget
 318    */
 319   virtual void fillMessageTagCombo( KComboBox * combo );
 320
 321   /**
 322    * Reimplemented from MessageList::Core::Widget
 323    */
 324   virtual void viewMessageSelected( MessageList::Core::MessageItem *msg );
 325
 326   /**
 327    * Reimplemented from MessageList::Core::Widget
 328    */
 329   virtual void viewMessageActivated( MessageList::Core::MessageItem *msg );
 330
 331   /**
 332    * Reimplemented from MessageList::Core::Widget
 333    */
 334   virtual void viewSelectionChanged();
 335
 336   /**
 337    * Reimplemented from MessageList::Core::Widget
 338    */
 339   virtual void viewMessageListContextPopupRequest( const QList< MessageList::Core::MessageItem * > &selectedItems, const QPoint &globalPos );
 340
 341   /**
 342    * Reimplemented from MessageList::Core::Widget
 343    */
 344   virtual void viewGroupHeaderContextPopupRequest( MessageList::Core::GroupHeaderItem *group, const QPoint &globalPos );
 345
 346   /**
 347    * Reimplemented from MessageList::Core::Widget
 348    */
 349   virtual void viewDragEnterEvent( QDragEnterEvent * e );
 350
 351   /**
 352    * Reimplemented from MessageList::Core::Widget
 353    */
 354   virtual void viewDragMoveEvent( QDragMoveEvent * e );
 355
 356   /**
 357    * Reimplemented from MessageList::Core::Widget
 358    */
 359   virtual void viewDropEvent( QDropEvent * e );
 360
 361   /**
 362    * Reimplemented from MessageList::Core::Widget
 363    */
 364   virtual void viewStartDragRequest();
 365
 366   /**
 367    * Reimplemented from MessageList::Core::Widget
 368    */
 369   virtual void viewMessageStatusChangeRequest( MessageList::Core::MessageItem *msg, const Akonadi::MessageStatus &set, const Akonadi::MessageStatus &clear );
 370
 371
 372
 373
 374 signals:
 375   /**
 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).
 378    *
 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.
 384    */
 385   void messageSelected( const Akonadi::Item &item );
 386
 387   /**
 388    * Emitted when a message is doubleclicked or activated by other input means
 389    */
 390   void messageActivated( const Akonadi::Item &item );
 391
 392   /**
 393    * Emitted when the selection in the view changes.
 394    */
 395   void selectionChanged();
 396
 397   /**
 398    * Emitted when a message wants its status to be changed
 399    */
 400   void messageStatusChangeRequest( const Akonadi::Item &item, const Akonadi::MessageStatus &set, const Akonadi::MessageStatus &clear );
 401
 402 private:
 403   class Private;
 404   Private * const d;
 405 };
 406
 407 } // namespace MessageList
 408
 409 #endif //!__MESSAGELIST_WIDGET_H__