messagecore/messagestatus.h

   1 /*  -*- mode: C++ -*-
   2     This file is part of KDEPIM.
   3     Copyright (c) 2005 Andreas Gungl <a.gungl@gmx.de>
   4
   5     This library is free software; you can redistribute it and/or
   6     modify it under the terms of the GNU Library General Public
   7     License as published by the Free Software Foundation; either
   8     version 2 of the License, or (at your option) any later version.
   9
  10     This library 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 Library General Public License for more details.
  14
  15     You should have received a copy of the GNU Library General Public License
  16     along with this library; see the file COPYING.LIB.  If not, write to the
  17     Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18     Boston, MA 02110-1301, USA.
  19 */
  20 #ifndef KDEPIM_MESSAGESTATUS_H
  21 #define KDEPIM_MESSAGESTATUS_H
  22
  23 #include <QtCore/QSet>
  24
  25 #include "messagecore_export.h"
  26
  27 class QString;
  28
  29 namespace KPIM {
  30
  31 //---------------------------------------------------------------------------
  32 /**
  33   @short KDEPIM Message Status.
  34   @author Andreas Gungl <a.gungl@gmx.de>
  35
  36   The class encapsulates the handling of the different flags
  37   which describe the status of a message.
  38   The flags itself are not intended to be used outside this class.
  39
  40   In the status pairs Watched/Ignored and Spam/Ham, there both
  41   values can't be set at the same time, however they can
  42   be unset at the same time.
  43
  44   The stati New/Unread/Read/Old are mutually exclusive.
  45 */
  46 class MESSAGECORE_EXPORT MessageStatus
  47 {
  48   public:
  49     /** Constructor - sets status initially to unknown. */
  50     MessageStatus();
  51
  52     /** Assign the status from another instance. The internal
  53         representation is identical afterwards, i.e. a comparison
  54         by operator == will return true.
  55     */
  56     MessageStatus &operator = ( const MessageStatus &other );
  57
  58     /** Compare the status with that from another instance.
  59         @return true if the stati are equal, false if different.
  60     */
  61     bool operator == ( const MessageStatus &other ) const;
  62
  63     /** Compare the status with that from another instance.
  64         @return true if the stati are equal, false if different.
  65     */
  66     bool operator != ( const MessageStatus &other ) const;
  67
  68     /** Check, if some of the flags in the status match
  69         with those flags from another instance.
  70         @return true if at least one flag is set in both stati.
  71     */
  72     bool operator & ( const MessageStatus &other ) const;
  73
  74     /** Clear all status flags, this resets to unknown. */
  75     void clear();
  76
  77     /** Set / add stati described by another MessageStatus object.
  78         This can be used to merge in multiple stati at once without
  79         using the single setter methods.
  80         However, internally the setters are used anyway to ensure the
  81         integrity of the resulting status.
  82     */
  83     void set( const MessageStatus &other );
  84
  85     /** Toggle one or more stati described by another MessageStatus object.
  86         Internally the setters are used to ensure the integrity of the
  87         resulting status.
  88         Toggling of the stati New, Unread, Read and Old is not supported.
  89         These stati are completely ignored.
  90     */
  91     void toggle( const MessageStatus &other );
  92
  93     /* ----- getters ----------------------------------------------------- */
  94
  95     /** Check for Unknown status.
  96         @return true if status is unknown.
  97     */
  98     bool isOfUnknownStatus() const;
  99
 100     /** Check for New status. Ignored messages are not new.
 101         @return true if status is new.
 102     */
 103     bool isNew() const;
 104
 105     /** Check for Unread status. Note that new messages are not unread.
 106         Ignored messages are not unread as well.
 107         @return true if status is unread.
 108     */
 109     bool isUnread() const;
 110
 111     /** Check for Read status. Note that ignored messages are read.
 112         @return true if status is read.
 113     */
 114     bool isRead() const;
 115
 116     /** Check for Old status.
 117         @return true if status is old.
 118     */
 119     bool isOld() const;
 120
 121     /** Check for Deleted status.
 122         @return true if status is deleted.
 123     */
 124     bool isDeleted() const;
 125
 126     /** Check for Replied status.
 127         @return true if status is replied.
 128     */
 129     bool isReplied() const;
 130
 131     /** Check for Forwarded status.
 132         @return true if status is forwarded.
 133     */
 134     bool isForwarded() const;
 135
 136     /** Check for Queued status.
 137         @return true if status is queued.
 138     */
 139     bool isQueued() const;
 140
 141     /** Check for Sent status.
 142         @return true if status is sent.
 143     */
 144     bool isSent() const;
 145
 146     /** Check for Important status.
 147         @return true if status is important.
 148     */
 149     bool isImportant() const;
 150
 151     /** Check for Watched status.
 152         @return true if status is watched.
 153     */
 154     bool isWatched() const;
 155
 156     /** Check for Ignored status.
 157         @return true if status is ignored.
 158     */
 159     bool isIgnored() const;
 160
 161     /** Check for ToAct status.
 162         @return true if status is action item.
 163     */
 164     bool isToAct() const;
 165
 166     /** Check for Spam status.
 167         @return true if status is spam.
 168     */
 169     bool isSpam() const;
 170
 171     /** Check for Ham status.
 172         @return true if status is not spam.
 173     */
 174     bool isHam() const;
 175
 176     /** Check for Attachment status.
 177         @return true if status indicates an attachment.
 178     */
 179     bool hasAttachment() const;
 180
 181     /* ----- setters ----------------------------------------------------- */
 182
 183     /** Set the status to new. */
 184     void setNew();
 185
 186     /** Set the status to unread. */
 187     void setUnread();
 188
 189     /** Set the status to read. */
 190     void setRead();
 191
 192     /** Set the status to old. */
 193     void setOld();
 194
 195     /** Set the status for deleted.
 196         @param deleted Set (true) or unset (false) this status flag.
 197     */
 198     void setDeleted( bool deleted = true );
 199
 200     /** Set the status for replied.
 201         @param replied Set (true) or unset (false) this status flag.
 202     */
 203     void setReplied( bool replied = true );
 204
 205     /** Set the status for forwarded.
 206         @param forwarded Set (true) or unset (false) this status flag.
 207     */
 208     void setForwarded( bool forwarded = true );
 209
 210     /** Set the status for queued.
 211         @param queued Set (true) or unset (false) this status flag.
 212     */
 213     void setQueued( bool queued = true );
 214
 215     /** Set the status for sent.
 216         @param sent Set (true) or unset (false) this status flag.
 217     */
 218     void setSent( bool sent = true );
 219
 220     /** Set the status for important.
 221         @param important Set (true) or unset (false) this status flag.
 222     */
 223     void setImportant( bool important = true );
 224
 225     /** Set the status to watched.
 226         @param watched Set (true) or unset (false) this status flag.
 227     */
 228     void setWatched( bool watched = true );
 229
 230     /** Set the status to ignored.
 231         @param ignored Set (true) or unset (false) this status flag.
 232     */
 233     void setIgnored( bool ignored = true );
 234
 235     /** Set the status to action item.
 236         @param toAct Set (true) or unset (false) this status flag.
 237     */
 238     void setToAct( bool toAct = true );
 239
 240     /** Set the status to spam.
 241         @param spam Set (true) or unset (false) this status flag.
 242     */
 243     void setSpam( bool spam = true );
 244
 245     /** Set the status to not spam.
 246         @param ham Set (true) or unset (false) this status flag.
 247     */
 248     void setHam( bool ham = true );
 249
 250     /** Set the status for an attachment.
 251         @param withAttechment Set (true) or unset (false) this status flag.
 252     */
 253     void setHasAttachment( bool withAttachment = true );
 254
 255     /* ----- state representation  --------------------------------------- */
 256
 257     /** Get the status as a whole e.g. for storage in an index.
 258         Don't manipulte the index via this value, this bypasses
 259         all integrity checks in the setter methods.
 260         @return The status encoded in bits.
 261     */
 262     qint32 toQInt32() const;
 263
 264     /** Set the status as a whole e.g. for reading from an index.
 265         Don't manipulte the index via this value, this bypasses
 266         all integrity checks in the setter methods.
 267         @param status The status encoded in bits to be set in this instance.
 268     */
 269     void fromQInt32( qint32 status );
 270
 271     /** Convert the status to a string representation.
 272         @return A string containing coded uppercase letters
 273                 which describe the status.
 274     */
 275     QString getStatusStr() const;
 276
 277     /** Set the status based on a string representation.
 278         @param aStr The status string to be analyzed.
 279                     Normally it is a string obtained using
 280                     getStatusStr().
 281     */
 282     void setStatusFromStr( const QString &aStr );
 283
 284     /** Convert the status to a string for sorting.
 285         @return A string containing coded lowercase letters
 286                 which allows a predefined sorting by status.
 287     */
 288     QString getSortRank() const;
 289
 290     /** Get the status as a whole e.g. for storage as IMAP flags.
 291         @return The status encoded in flags.
 292     */
 293     QSet<QByteArray> getStatusFlags() const;
 294
 295     /** Set the status as a whole e.g. for reading from IMAP flags.
 296         @param status The status encoded in bits to be set in this instance.
 297     */
 298     void setStatusFromFlags( const QSet<QByteArray> &flags );
 299
 300     /* ----- static accessors to simple states --------------------------- */
 301
 302     /** Return a predefined status initialized as New as is useful
 303         e.g. when providing a state for comparison.
 304         @return A reference to a status instance initialized as New.
 305     */
 306     static MessageStatus statusNew();
 307
 308     /** Return a predefined status initialized as Read as is useful
 309         e.g. when providing a state for comparison.
 310         @return A reference to a status instance initialized as Read.
 311     */
 312     static MessageStatus statusRead();
 313
 314     /** Return a predefined status initialized as Unread as is useful
 315         e.g. when providing a state for comparison.
 316         @return A reference to a status instance initialized as Unread.
 317     */
 318     static MessageStatus statusUnread();
 319
 320     /** Return a predefined status initialized as New and Unread as is
 321         useful e.g. when searching for unread messages.
 322         @return A reference to a status instance initialized as New | Unread.
 323     */
 324     static MessageStatus statusNewAndUnread();
 325
 326     /** Return a predefined status initialized as Old as is useful
 327         e.g. when providing a state for comparison.
 328         @return A reference to a status instance initialized as Old.
 329     */
 330     static MessageStatus statusOld();
 331
 332     /** Return a predefined status initialized as Deleted as is useful
 333         e.g. when providing a state for comparison.
 334         @return A reference to a status instance initialized as Deleted.
 335     */
 336     static MessageStatus statusDeleted();
 337
 338     /** Return a predefined status initialized as Replied as is useful
 339         e.g. when providing a state for comparison.
 340         @return A reference to a status instance initialized as Replied.
 341     */
 342     static MessageStatus statusReplied();
 343
 344     /** Return a predefined status initialized as Forwarded as is useful
 345         e.g. when providing a state for comparison.
 346         @return A reference to a status instance initialized as Forwarded.
 347     */
 348     static MessageStatus statusForwarded();
 349
 350     /** Return a predefined status initialized as Queued as is useful
 351         e.g. when providing a state for comparison.
 352         @return A reference to a status instance initialized as Queued.
 353     */
 354     static MessageStatus statusQueued();
 355
 356     /** Return a predefined status initialized as Sent as is useful
 357         e.g. when providing a state for comparison.
 358         @return A reference to a status instance initialized as Sent.
 359     */
 360     static MessageStatus statusSent();
 361
 362     /** Return a predefined status initialized as Important as is useful
 363         e.g. when providing a state for comparison.
 364         @return A reference to a status instance initialized as Important.
 365     */
 366     static MessageStatus statusImportant();
 367
 368     /** Return a predefined status initialized as Watched as is useful
 369         e.g. when providing a state for comparison.
 370         @return A reference to a status instance initialized as Watched.
 371     */
 372     static MessageStatus statusWatched();
 373
 374     /** Return a predefined status initialized as Ignored as is useful
 375         e.g. when providing a state for comparison.
 376         @return A reference to a status instance initialized as Ignored.
 377     */
 378     static MessageStatus statusIgnored();
 379
 380     /** Return a predefined status initialized as Action Item as is useful
 381         e.g. when providing a state for comparison.
 382         @return A reference to a status instance initialized as ToAct.
 383     */
 384     static MessageStatus statusToAct();
 385
 386     /** Return a predefined status initialized as Spam as is useful
 387         e.g. when providing a state for comparison.
 388         @return A reference to a status instance initialized as Spam.
 389     */
 390     static MessageStatus statusSpam();
 391
 392     /** Return a predefined status initialized as Ham as is useful
 393         e.g. when providing a state for comparison.
 394         @return A reference to a status instance initialized as Ham.
 395     */
 396     static MessageStatus statusHam();
 397
 398     /** Return a predefined status initialized as Attachment as is useful
 399         e.g. when providing a state for comparison.
 400         @return A reference to a status instance initialized as Attachment.
 401     */
 402     static MessageStatus statusHasAttachment();
 403
 404   private:
 405     qint32 mStatus;
 406 };
 407
 408 } // namespace KPIM
 409
 410 #endif /*KMAIL_MESSAGESTATUS_H*/