libkdepim/maillistdrag.h

   1 /*
   2     This file is part of libkdepim.
   3
   4     Copyright (c) 2003 Don Sanders <sanders@kde.org>
   5     Copyright (c) 2005 George Staikos <staikos@kde.org.
   6     Copyright (c) 2005 Rafal Rzepecki <divide@users.sourceforge.net>
   7     Copyright (c) 2008 Thomas McGuire <mcguire@kde.org>
   8
   9     This library is free software; you can redistribute it and/or
  10     modify it under the terms of the GNU Library General Public
  11     License as published by the Free Software Foundation; either
  12     version 2 of the License, or (at your option) any later version.
  13
  14     This library is distributed in the hope that it will be useful,
  15     but WITHOUT ANY WARRANTY; without even the implied warranty of
  16     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17     Library General Public License for more details.
  18
  19     You should have received a copy of the GNU Library General Public License
  20     along with this library; see the file COPYING.LIB.  If not, write to
  21     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  22     Boston, MA 02110-1301, USA.
  23 */
  24 #ifndef KDEPIM_MAILLISTDRAG_H
  25 #define KDEPIM_MAILLISTDRAG_H
  26
  27 #include "kdepim_export.h"
  28
  29 #include <QList>
  30 #include <QMimeData>
  31 #include <QString>
  32
  33 #include <time.h>
  34
  35 class KUrl;
  36
  37 namespace KPIM {
  38
  39 /**
  40  * @defgroup maildnd Mail drag and drop
  41  *
  42  * KDEPIM classes for drag and drop of mails
  43  *
  44  * \code
  45  * // Code example for drag and drop enabled widget
  46  *
  47  * void SomeWidget::contentsDropEvent(QDropEvent *e)
  48  * {
  49  *    if ( KPIM::MailList::canDecode( e->mimeData() ) ) {
  50  *      MailList mailList = KPIM::MailList::fromMimeData( e->mimeData() );
  51  *      ...
  52  * \endcode
  53  * @{
  54  **/
  55
  56 /**
  57   Represents a single dragged mail.
  58 */
  59 class KDEPIM_EXPORT MailSummary
  60 {
  61 public:
  62     MailSummary( quint32 serialNumber, const QString &messageId, const QString &subject,
  63                  const QString &from, const QString &to, time_t date );
  64     MailSummary() {}
  65     ~MailSummary() {}
  66
  67     /** Set fields for this mail summary  */
  68     void set( quint32, const QString&, const QString&, const QString&, const QString&, time_t );
  69
  70     /** KMail unique identification number */
  71     quint32 serialNumber() const;
  72
  73     /** MD5 checksum of message identification string */
  74     QString messageId() const;
  75
  76     /** Subject of the message including prefixes */
  77     QString subject() const;
  78
  79     /** Simplified from address */
  80     QString from() const;
  81
  82     /** Simplified to address */
  83     QString to() const;
  84
  85     /** Date the message was sent */
  86     time_t date() const;
  87
  88     /** returns kmail:&lt;serial number&gt;/&lt;message id&gt; style uri */
  89 #ifdef Q_CC_MSVC
  90     operator KUrl() const;
  91 #endif
  92
  93     KDE_DUMMY_COMPARISON_OPERATOR(MailSummary)
  94 private:
  95     quint32 mSerialNumber;
  96     QString mMessageId, mSubject, mFrom, mTo;
  97     time_t mDate;
  98 };
  99 #ifdef MAKE_KDEPIM_LIBS
 100 KDE_DUMMY_QHASH_FUNCTION(MailSummary)
 101 #endif
 102
 103 /**
 104   Object for the drag object to call-back for message fulltext.
 105 */
 106 class KDEPIM_EXPORT MailTextSource {
 107 public:
 108     MailTextSource() {}
 109     virtual ~MailTextSource() {}
 110
 111     virtual QByteArray text(quint32 serialNumber) const = 0;
 112 };
 113
 114 /**
 115    List of mail summaries.
 116 */
 117 class KDEPIM_EXPORT MailList : public QList<MailSummary>
 118 {
 119   public:
 120     static QString mimeDataType();
 121     static bool canDecode( const QMimeData*md );
 122     static MailList fromMimeData( const QMimeData*md );
 123     static QByteArray serialsFromMimeData( const QMimeData *md );
 124     static MailList decode( const QByteArray& payload );
 125     void populateMimeData( QMimeData*md );
 126 };
 127
 128 /**
 129  * This special QMimeData has the ability to be associated with a MailTextSource.
 130  * This automatically adds another mimetype, "message/rfc822", which has the
 131  * text of all mails as data.
 132  * The class is needed because the new mimetype is only read on-demand when
 133  * dropped, so no unnecessary mail copying is done when doing drag & drop
 134  * inside of KMail.
 135  *
 136  * For this to work, MailList::populateMimeData() needs to be called for the
 137  * drag object so the mimedata for the MailSummarys is available, which is needed
 138  * to read the serial numbers of the mails.
 139  *
 140  * You only need to use this class when starting a drag with mails.
 141  */
 142 class KDEPIM_EXPORT MailListMimeData : public QMimeData
 143 {
 144   public:
 145
 146     /**
 147      * @param src The callback class for getting the full text of the mail.
 148      *            If not set, the message/rfc822 mimetype is not available.
 149      *            This object takes ownership of src and deletes it in the
 150      *            destructor.
 151      */
 152     MailListMimeData( MailTextSource *src = 0 );
 153
 154     ~MailListMimeData();
 155
 156   protected:
 157
 158     /**
 159      * Reimplemented so that the message/rfc822 mimetype data can be retrieved
 160      * from mMailTextSource.
 161      */
 162     virtual QVariant retrieveData( const QString & mimeType,
 163                                    QVariant::Type type ) const;
 164
 165     virtual bool hasFormat ( const QString & mimeType ) const;
 166
 167     virtual QStringList formats () const;
 168
 169   private:
 170
 171     MailTextSource *mMailTextSource;
 172
 173     // Acts as a cache for the mail text because retrieveData() can be called
 174     // multiple times.
 175     mutable QByteArray mMails;
 176 };
 177
 178 } // namespace KPIM
 179
 180 #endif /*maillistdrag_h*/