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
25namespace 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 */
48class KOPETE_EXPORT StatusMessage
49{
50public:
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
138private:
139 class Private;
140 KSharedPtr<Private> d;
141};
142
143}
144
145#endif
146