messagelist/core/item.h

   1 /******************************************************************************
   2  *
   3  *  Copyright 2008 Szymon Tomasz Stefanek <pragma@kvirc.net>
   4  *
   5  *  This program is free software; you can redistribute it and/or modify
   6  *  it under the terms of the GNU General Public License as published by
   7  *  the Free Software Foundation; either version 2 of the License, or
   8  *  (at your option) any later version.
   9  *
  10  *  This program is distributed in the hope that it will be useful,
  11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  *  GNU General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU General Public License
  16  *  along with this program; if not, write to the Free Software
  17  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  *
  19  *******************************************************************************/
  20
  21 #ifndef __MESSAGELIST_CORE_ITEM_H__
  22 #define __MESSAGELIST_CORE_ITEM_H__
  23
  24 #include <QList>
  25 #include <QString>
  26 #include <QDate>
  27
  28 #include <time.h> // for time_t
  29
  30 #include <kmime/kmime_headers.h>
  31
  32 #include <akonadi/kmime/messagestatus.h>
  33
  34 #include <messagelist/core/model.h>
  35 #include <messagelist/messagelist_export.h>
  36
  37
  38 namespace MessageList
  39 {
  40
  41 namespace Core
  42 {
  43
  44 class ItemPrivate;
  45
  46 /**
  47  * A single item of the MessageList tree managed by MessageList::Model.
  48  *
  49  * This class stores basic information needed in all the subclasses which
  50  * at the moment of writing are MessageItem and GroupHeaderItem.
  51  */
  52 class MESSAGELIST_EXPORT Item
  53 {
  54   friend class Model;
  55   friend class ModelPrivate;
  56
  57 public:
  58   /**
  59    * The type of the Item.
  60    */
  61   enum Type
  62   {
  63     GroupHeader,                              ///< This item is a GroupHeaderItem
  64     Message,                                  ///< This item is a MessageItem
  65     InvisibleRoot                             ///< This item is just Item and it's the only InvisibleRoot per Model.
  66   };
  67
  68   /**
  69    * Specifies the initial expand status for the item that should be applied
  70    * when it's attacched to the viewable tree. Needed as a workaround for
  71    * QTreeView limitations in handling item expansion.
  72    */
  73   enum InitialExpandStatus
  74   {
  75     ExpandNeeded,                             ///< Must expand when this item becomes viewable
  76     NoExpandNeeded,                           ///< No expand needed at all
  77     ExpandExecuted                            ///< Item already expanded
  78   };
  79
  80 protected:
  81   /**
  82    * Creates an Item. Only derived classes and MessageList::Model should access this.
  83    */
  84   Item( Type type );
  85   Item( Type type, ItemPrivate *dd );
  86
  87 public:
  88   /**
  89    * Destroys the Item. Should be protected just like the constructor but the QList<>
  90    * helpers need to access it, so it's public actually.
  91    */
  92   virtual ~Item();
  93
  94   /**
  95    * Returns the type of this item. The Type can be set only in the constructor.
  96    */
  97   Type type() const;
  98
  99   /**
 100    * The initial expand status we have to honor when attacching to the viewable root.
 101    */
 102   InitialExpandStatus initialExpandStatus() const;
 103
 104   /**
 105    * Set the initial expand status we have to honor when attacching to the viewable root.
 106    */
 107   void setInitialExpandStatus( InitialExpandStatus initialExpandStatus );
 108
 109   /**
 110    * Is this item attached to the viewable root ?
 111    */
 112   bool isViewable() const;
 113
 114   /**
 115    * Return true if Item pointed by it is an ancestor of this item (that is,
 116    * if it is it's parent, parent of it's parent, parent of it's parent of it's parent etc...
 117    */
 118   bool hasAncestor( const Item * it ) const;
 119
 120   /**
 121    * Makes this item viewable, that is, notifies it's existence to any listener
 122    * attacched to the "rowsInserted()" signal, most notably QTreeView.
 123    *
 124    * This will also make all the children viewable.
 125    */
 126   void setViewable( Model *model, bool bViewable );
 127
 128   /**
 129    * Return the list of child items. May be null.
 130    */
 131   QList< Item * > * childItems() const;
 132
 133   /**
 134    * Returns the child item at position idx or 0 if idx is out of the allowable range.
 135    */
 136   Item * childItem( int idx ) const;
 137
 138   /**
 139    * Returns the first child item, if any.
 140    */
 141   Item * firstChildItem() const;
 142
 143   /**
 144    * Returns the item that is visually below the specified child if this item.
 145    * Note that the returned item may belong to a completely different subtree.
 146    */
 147   Item * itemBelowChild( Item * child );
 148
 149   /**
 150    * Returns the item that is visually above the specified child if this item.
 151    * Note that the returned item may belong to a completely different subtree.
 152    */
 153   Item * itemAboveChild( Item * child );
 154
 155   /**
 156    * Returns the deepest item in the subtree originating at this item.
 157    */
 158   Item * deepestItem();
 159
 160   /**
 161    * Returns the item that is visually below this item in the tree.
 162    * Note that the returned item may belong to a completely different subtree.
 163    */
 164   Item * itemBelow();
 165
 166   /**
 167    * Returns the item that is visually above this item in the tree.
 168    * Note that the returned item may belong to a completely different subtree.
 169    */
 170   Item * itemAbove();
 171
 172   /**
 173    * Debug helper. Dumps the structure of this subtree.
 174    */
 175   void dump( const QString &prefix );
 176
 177   /**
 178    * Returns the number of children of this Item.
 179    */
 180   int childItemCount() const;
 181
 182   /**
 183    * Convenience function that returns true if this item has children.
 184    */
 185   bool hasChildren() const;
 186
 187   /**
 188    * A structure used with MessageList::Item::childItemStats().
 189    * Contains counts of total and unread messages in a subtree.
 190    */
 191   class ChildItemStats
 192   {
 193   public:
 194     unsigned int mTotalChildCount;   // total
 195     unsigned int mUnreadChildCount;  // unread only
 196   public:
 197     ChildItemStats()
 198       : mTotalChildCount( 0 ), mUnreadChildCount( 0 )
 199       {};
 200   };
 201
 202   /**
 203    * Gathers statistics about child items.
 204    * For performance purposes assumes that this item has children.
 205    * You MUST check it before calling it.
 206    */
 207   void childItemStats( ChildItemStats &stats ) const;
 208
 209   /**
 210    * Returns the actual index of the child Item item or -1 if
 211    * item is not a child of this Item.
 212    */
 213   int indexOfChildItem( Item *item ) const;
 214
 215   /**
 216    * Returns the cached guess for the index of this item in the parent's child list.
 217    *
 218    * This is used to speed up the index lookup with the following algorithm:
 219    * Ask the parent if this item is at the position specified by index guess (this costs ~O(1)).
 220    * If the position matches we have finished, if it doesn't then perform
 221    * a linear search via indexOfChildItem() (which costs ~O(n)).
 222    */
 223   int indexGuess() const;
 224
 225   /**
 226    * Updates the cached guess for the index of this item in the parent's child list.
 227    * See indexGuess() for more information.
 228    */
 229   void setIndexGuess( int index );
 230
 231   /**
 232    * Returns true if the specified Item is a position idx in the list of children.
 233    * See indexGuess() for more information.
 234    */
 235   bool childItemHasIndex( const Item *item, int idx ) const;
 236
 237   /**
 238    * Returns the parent Item in the tree, or 0 if this item isn't attached to the tree.
 239    * Please note that even if this item has a non-zero parent, it can be still non viewable.
 240    * That is: the topmost parent of this item may be not attached to the viewable root.
 241    */
 242   Item * parent() const;
 243
 244   /**
 245    * Sets the parent for this item. You should also take care of inserting
 246    * this item in the parent's child list.
 247    */
 248   void setParent( Item *pParent );
 249
 250   /**
 251    * Returns the topmost parent item that is not a Root item (that is, is a Message or GroupHeader).
 252    */
 253   Item * topmostNonRoot();
 254
 255   /**
 256    * Returns the status associated to this Item.
 257    */
 258   const Akonadi::MessageStatus & status() const;
 259
 260   /**
 261    * Sets the status associated to this Item.
 262    */
 263   void setStatus( const Akonadi::MessageStatus &status );
 264
 265   /**
 266    * Returns a string describing the status e.g: "Read, Forwarded, Important"
 267    */
 268   QString statusDescription() const;
 269
 270   /**
 271    * Returns the size of this item (size of the Message, mainly)
 272    */
 273   size_t size() const;
 274
 275   /**
 276    * Sets the size of this item (size of the Message, mainly)
 277    */
 278   void setSize( size_t size );
 279
 280   /**
 281    * A string with a text rappresentation of size(). This is computed on-the-fly
 282    * and cached until the size() changes.
 283    */
 284   const QString & formattedSize();
 285
 286   /**
 287    * Returns the date of this item
 288    */
 289   time_t date() const;
 290
 291   /**
 292    * Sets the date of this item
 293    */
 294   void setDate( time_t date );
 295
 296   /**
 297    * A string with a text rappresentation of date() obtained via Manager. This is computed on-the-fly
 298    * and cached until the size() changes.
 299    */
 300   const QString & formattedDate();
 301
 302   /**
 303    * Returns the maximum date in the subtree originating from this item.
 304    * This is kept up-to-date by MessageList::Model.
 305    */
 306   time_t maxDate() const;
 307
 308   /**
 309    * Sets the maximum date in the subtree originating from this item.
 310    */
 311   void setMaxDate( time_t date );
 312
 313   /**
 314    * A string with a text rappresentation of maxDate() obtained via Manager. This is computed on-the-fly
 315    * and cached until the size() changes.
 316    */
 317   const QString & formattedMaxDate();
 318
 319   /**
 320    * Recompute the maximum date from the current children list.
 321    * Return true if the current max date changed and false otherwise.
 322    */
 323   bool recomputeMaxDate();
 324
 325   /**
 326    * Returns the sender associated to this item.
 327    */
 328   const QString & sender() const;
 329
 330   /**
 331    * Sets the sender associated to this item.
 332    */
 333   void setSender( const QString &sender );
 334
 335   /**
 336    * Returns the receiver associated to this item.
 337    */
 338   const QString & receiver() const;
 339
 340   /**
 341    * Sets the sender associated to this item.
 342    */
 343   void setReceiver( const QString &receiver );
 344
 345   /**
 346    * Returns the sender or the receiver, depending on the underlying StorageModel settings.
 347    */
 348   const QString & senderOrReceiver() const;
 349
 350   /**
 351    * Sets the sender or the receiver: this should depend on the underlying StorageModel settings.
 352    */
 353   void setSenderOrReceiver( const QString &senderOrReceiver );
 354
 355   /**
 356    * Returns the subject associated to this Item.
 357    */
 358   const QString & subject() const;
 359
 360   /**
 361    * Sets the subject associated to this Item.
 362    */
 363   void setSubject( const QString &subject );
 364
 365   /**
 366    * This is meant to be called right after the constructor.
 367    * It sets up several items at once (so even if not inlined it's still a single call)
 368    * and it skips some calls that can be avoided at constructor time.
 369    */
 370   void initialSetup( time_t date, size_t size,
 371                      const QString &sender,
 372                      const QString &receiver,
 373                      const QString &senderOrReceiver );
 374
 375   /**
 376    * This is meant to be called right after the constructor for MessageItem objects.
 377    * It sets up several items at once (so even if not inlined it's still a single call).
 378    */
 379   void setSubjectAndStatus( const QString &subject,
 380                             const Akonadi::MessageStatus &status );
 381
 382   /**
 383    * Appends an Item to this item's child list.
 384    * The Model is used for beginInsertRows()/endInsertRows() calls.
 385    */
 386   int appendChildItem( Model *model, Item *child );
 387
 388   /**
 389    * Appends a child item without inserting it via the model.
 390    * This is useful in ThemeEditor which doesn't use a custom model for the items.
 391    * You shouldn't need to use this function...
 392    */
 393   void rawAppendChildItem( Item * child );
 394
 395   /**
 396    * Removes a child from this item's child list without deleting it.
 397    * The Model is used for beginRemoveRows()/endRemoveRows() calls.
 398    */
 399   void takeChildItem( Model *model, Item *child );
 400
 401   /**
 402    * Kills all the child items without emitting any signal, recursively.
 403    * It should be used only when MessageList::Model is reset() afterwards.
 404    */
 405   void killAllChildItems();
 406
 407 protected:
 408   ItemPrivate * const d_ptr;
 409   Q_DECLARE_PRIVATE( Item )
 410 };
 411
 412 } // namespace Core
 413
 414 } // namespace MessageList
 415
 416 #endif //!__MESSAGELIST_CORE_ITEM_H__