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 ©); |
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 |
146 | |