kopete/libkopete/kopetestatusmessage.h

   1 /*
   2     kopetestatusmessage.h - Describle a status message and it's metadata.
   3
   4     Copyright (c) 2006  by Michaël Larouche          <larouche@kde.org>
   5
   6     Kopete    (c) 2002-2006 by the Kopete developers <kopete-devel@kde.org>
   7
   8     *************************************************************************
   9     *                                                                       *
  10     * This library is free software; you can redistribute it and/or         *
  11     * modify it under the terms of the GNU Lesser General Public            *
  12     * License as published by the Free Software Foundation; either          *
  13     * version 2 of the License, or (at your option) any later version.      *
  14     *                                                                       *
  15     *************************************************************************
  16 */
  17 #ifndef KOPETESTATUSMESSAGE_H
  18 #define KOPETESTATUSMESSAGE_H
  19
  20 #include <QtCore/QVariant>
  21
  22 #include <ksharedptr.h>
  23 #include "kopete_export.h"
  24
  25 namespace Kopete
  26 {
  27
  28 /**
  29  * @brief This class encapsulate a status message.
  30  * A status message to today(as 2006) standards is more than a simple text.
  31  * It can be used to show the current listening song, current playing game, show our mood etc..
  32  * So this class allows to add metadata to the status message where protocols will be able to use properly.
  33  *
  34  * @code
  35  * // Create a new status message.
  36  * Kopete::StatusMessage message;
  37  * message.setMessage( QString("Writing APIDOX") );
  38  * message.addMetaData( "musicPlayer", "amaroK" );
  39  * message.addMetaData( "artist", "Liquid Tension Experiment" );
  40  * message.addMetaData( "title", "Acid Rain" );
  41  * message.addMetaData( "album", "Liquid Tension Experiment 2" );
  42  *
  43  * account->setStatusMessage(message);
  44  * @endcode
  45  * This class is implicit shared.
  46  * @author Michaël Larouche
  47  */
  48 class KOPETE_EXPORT StatusMessage
  49 {
  50 public:
  51         /**
  52          * Create a empty status message.
  53          */
  54         StatusMessage();
  55         /**
  56          * Create a new status message with the specified status message.
  57          * This constructor is not explicit so it's allow implicit QString
  58          * conversation to this class.
  59          * @param statusMessage the status message.
  60          */
  61         StatusMessage(const QString &statusMessage); /* implicit */
  62         /**
  63          * Create a new status message with the specified status message and title.
  64          * @param statusTitle the status title.
  65          * @param statusMessage the status message.
  66          */
  67         StatusMessage(const QString &statusTitle, const QString &statusMessage);
  68         /**
  69          * StatusMessage copy constructor.
  70          * Very cheap because the class is implicit shared.
  71          */
  72         StatusMessage(const StatusMessage &copy);
  73         /**
  74          * StatusMessage destructor
  75          */
  76         ~StatusMessage();
  77         /**
  78          * StatusMessage copy-assignment operator.
  79          * Very cheap because the class is implicit shared.
  80          */
  81         StatusMessage &operator=(const StatusMessage &other);
  82
  83         /**
  84          * Verify if the status message is empty.
  85          * @return true if the status message is empty.
  86          */
  87         bool isEmpty() const;
  88
  89         /**
  90          * Add a metadata to the status message.
  91          * @param key Key to identity the metadata.
  92          * @param value Value for the metadata.
  93          */
  94         void addMetaData(const QString &key, const QVariant &value);
  95         /**
  96          * Add a hash of metadata to the status message.
  97          * If a key already exists, it gets replaced (it doesn't use QHash::unite).;
  98          * @param otherHash The hash to add.
  99          */
 100         void addMetaData(const QHash<QString,QVariant> &otherHash);
 101
 102         /**
 103          * Check if the status message has the specified metadata.
 104          * @param key Key of the metadata.
 105          * @return true if the metadata is present.
 106          */
 107         bool hasMetaData(const QString &key) const;
 108         /**
 109          * Retrieve the specified metadata.
 110          * @param key Key of the metadata
 111          * @return The medata value
 112          */
 113         QVariant metaData(const QString &key) const;
 114
 115         /**
 116          * Set a new status message.
 117          * @param message New status message.
 118          */
 119         void setMessage(const QString &message);
 120         /**
 121          * Return the current status message.
 122          * @return The current status message.
 123          */
 124         QString message() const;
 125
 126         /**
 127          * Set a new status title.
 128          * @param title New status title.
 129          */
 130         void setTitle(const QString &title);
 131
 132         /**
 133          * Return the current status title.
 134          * @return The current status title.
 135          */
 136         QString title() const;
 137
 138 private:
 139         class Private;
 140         KSharedPtr<Private> d;
 141 };
 142
 143 }
 144
 145 #endif