1 | /* |
2 | kopeteonlinestatus.h - Kopete Online Status |
3 | |
4 | Copyright (c) 2003 by Martijn Klingens <klingens@kde.org> |
5 | Copyright (c) 2003 by Duncan Mac-Vicar Prett <duncan@kde.org> |
6 | Copyright (c) 2003 by Will Stephenson <wstephenson@kde.org> |
7 | Copyright (c) 2004 by Olivier Goffart <ogoffart@kde.org> |
8 | |
9 | Kopete (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org> |
10 | |
11 | ************************************************************************* |
12 | * * |
13 | * This library is free software; you can redistribute it and/or * |
14 | * modify it under the terms of the GNU Lesser General Public * |
15 | * License as published by the Free Software Foundation; either * |
16 | * version 2 of the License, or (at your option) any later version. * |
17 | * * |
18 | ************************************************************************* |
19 | */ |
20 | |
21 | #ifndef kopeteonlinestatus_h |
22 | #define kopeteonlinestatus_h |
23 | |
24 | #include "kopete_export.h" |
25 | |
26 | #include <kdemacros.h> |
27 | #include <ksharedptr.h> |
28 | #include <kiconloader.h> |
29 | |
30 | #include <QtCore/QObject> |
31 | #include <QtCore/QFlags> |
32 | #include <QtGui/QIcon> |
33 | |
34 | #include "kopeteonlinestatusmanager.h" |
35 | |
36 | class QString; |
37 | class QPixmap; |
38 | class QColor; |
39 | |
40 | namespace Kopete |
41 | { |
42 | class OnlineStatusManager; |
43 | |
44 | class Identity; |
45 | class Protocol; |
46 | class Account; |
47 | class Contact; |
48 | |
49 | /** |
50 | * @author Martijn Klingens <klingens@kde.org> |
51 | * @author Will Stephenson (icon generating code) |
52 | * |
53 | * OnlineStatus is a class that encapsulates all information about the |
54 | * various online states that a protocol can be in in a single class. The |
55 | * online status consists of both a 'global' status as it's known to libkopete |
56 | * and used for going online or away, which non-protocol plugins can use, |
57 | * and the 'private' status, which is simply an unsigned int and is only |
58 | * useful for the actual protocol plugin that uses the status. |
59 | * |
60 | * This class is passed around by value, but is refcounted to cut down on the |
61 | * amount of overhead. All in all it should be more than fast enough for |
62 | * general use. |
63 | * |
64 | * Note that ONLY the constructor can set the data, the object is considered |
65 | * to be const after creation as there really shouldn't be a need to change |
66 | * a status' characteristics during runtime! |
67 | */ |
68 | class KOPETE_EXPORT OnlineStatus |
69 | { |
70 | public: |
71 | /** |
72 | * The available global states. It is possible that multiple internal |
73 | * states map to the same global states. For example ICQ's 'Do not disturb' |
74 | * is handled just like 'Away' by libkopete. Only ICQ itself makes (and |
75 | * should make) a distinction. |
76 | * The order is important and is used in the < or > operator |
77 | */ |
78 | enum StatusType |
79 | { |
80 | /** |
81 | * Refers to protocols where state cannot be determined. This |
82 | * applies to SMS contacts (text messages via mobile phones), |
83 | * since there's no presence information over SMS, but also |
84 | * to e.g. MSN contacts that are not on your contact list, |
85 | * since MSN only allows a user to query online state for |
86 | * users that are formally on the contact list. Lastly, libkopete |
87 | * itself uses the Unknown state in @ref MetaContact for |
88 | * meta contacts that have no child contacts at all. |
89 | */ |
90 | Unknown=0, |
91 | /** |
92 | * State where you really cannot be contacted. Although |
93 | * Kopete doesn't oppose any technical limitations it really |
94 | * doesn't make sense to have more than one status per protocol |
95 | * that maps to 'Offline', since you're supposed to be |
96 | * disconnected from the network in this state. |
97 | */ |
98 | Offline=10, |
99 | /** |
100 | * State where the user is not available on the network yet |
101 | * but trying to get onto. Most useful to yourself contact, because |
102 | * this state means not visible but with network access |
103 | */ |
104 | Connecting=20, |
105 | /** |
106 | * State where you are online but none of your contacts can |
107 | * see that you're online. Useful for all the protocols that support |
108 | * being invisible. |
109 | */ |
110 | Invisible=30, |
111 | /** |
112 | * Refers to a state where you can be technically reached, but |
113 | * for one reason or another it is often not useful to do so. |
114 | * This will be because you are not in front of the computer |
115 | * or because the client detected you don't interact. |
116 | */ |
117 | Away=40, |
118 | /** |
119 | * Means that you have other things to do |
120 | * and don't want to get involved in messaging ('Busy' or 'Do |
121 | * not Disturb' for example). |
122 | */ |
123 | Busy=45, |
124 | /** |
125 | * Refers to a true online state, i.e. you can be contacted by |
126 | * others both technically and practically. This also applies |
127 | * to e.g. ICQ's 'Free for Chat' status. |
128 | */ |
129 | Online=50 |
130 | }; |
131 | // note than Unknown is first, because the metacontact algorithm to detect |
132 | // the metacontact status from the contact status starts from Unknown, and |
133 | // takes a contact only if its status is greater |
134 | |
135 | /** |
136 | * Reserved internal status values |
137 | * |
138 | * Any internal status value > 0x80000000 is reserved for internal |
139 | * libkopete use. This enumeration lists the currently known values. |
140 | */ |
141 | enum ReservedInternalStatus |
142 | { |
143 | /** |
144 | * The account this contact belongs to is offline. Used with |
145 | * the Unknown StatusType. |
146 | */ |
147 | AccountOffline = 0x80000001 |
148 | }; |
149 | |
150 | |
151 | /** |
152 | * Constructor. |
153 | * |
154 | * Creates an empty OnlineStatus object. Since you cannot change |
155 | * OnlineStatus objects that are already created other than by their |
156 | * assignment operator, this constructor is only a convenience method |
157 | * for use in e.g. class members and local variables. |
158 | */ |
159 | OnlineStatus(); |
160 | |
161 | |
162 | /** |
163 | * Constructor. |
164 | * |
165 | * Creates a new OnlineStatus object. All fields are mandatory; there |
166 | * are no default values. Also, you cannot change the object after creation. |
167 | * |
168 | * @param status is the global online status as used by libkopete |
169 | * @param weight is the 'weight' of this status. The contact list is |
170 | * sorted by status, and by weight within a status. It's not possible to |
171 | * 'promote' an Away item to a level above Online, since the status field |
172 | * always takes precedence. Weight is used when the same status is used |
173 | * more than once. Weight is also used for picking the most important |
174 | * 'Away' status for a protocol when going Away. |
175 | * @param protocol is a pointer to the protocol used. This is used when |
176 | * comparing two online status objects. |
177 | * @param internalStatus is the status as used internally by the protocol. |
178 | * This status is usually a lot more fine-grained than the status as used |
179 | * by libkopete and should be unique per protocol. |
180 | * @param overlayIcons is a list of QStrings which are the name of status |
181 | * icons to be used by the KDE icon loader. (Statuses which don't have icons |
182 | * to overlay like Online and Offline should use QString() as icon |
183 | * name ). NOTE if the string is a movie ( *.mng ) it must be the first string in the list. |
184 | * TODO: KDE4 sort out movies and overlay icons. |
185 | * @param description is a description in e.g. tooltips. |
186 | */ |
187 | OnlineStatus( StatusType status, unsigned weight, Protocol *protocol, |
188 | unsigned internalStatus, const QStringList &overlayIcons, const QString &description ); |
189 | |
190 | /** |
191 | * Constructor. |
192 | * |
193 | * @p Creates a new OnlineStatus object and registers it with the @ref Kopete::OnlineStatusManager. |
194 | * Registration allows you to generate a KActionMenu filled with KActions for changing to this OnlineStatus, |
195 | * using Kopete::Account::accountMenu(). |
196 | * |
197 | * @p Note that weight has an additional significance for registered protocols when used for menu generation. |
198 | * |
199 | * All fields are mandatory; there |
200 | * are no default values. Also, you cannot change the object after creation. |
201 | * |
202 | * @param status is the global online status as used by libkopete |
203 | * @param weight is the 'weight' of this status. The contact list is |
204 | * sorted by status, and by weight within a status. It's not possible to |
205 | * 'promote' an Away item to a level above Online, since the status field |
206 | * always takes precedence. Weight is used when the same status is used |
207 | * more than once. Weight is also used for picking the most important |
208 | * 'Away' status for a protocol when going Away. Additionally, Weight determinesis also |
209 | * @param protocol is a pointer to the protocol used. This is used when |
210 | * comparing two online status objects. |
211 | * @param internalStatus is the status as used internally by the protocol. |
212 | * This status is usually a lot more fine-grained than the status as used |
213 | * by libkopete and should be unique per protocol. |
214 | * @param overlayIcon is a string returning the name of the status icon to be |
215 | * used by the KDE icon loader. (Status whiwh doesn't have icon to overlay like |
216 | * Online and Offline should use QString() as icon string) |
217 | * @param description is a description in e.g. tooltips. |
218 | * @param caption is the text of the action in the menu |
219 | * @param categories the categories this online status is in |
220 | * @param options the options of this online status |
221 | * @see Kopete::OnlineStatusManager for more info about the categories and options parameters |
222 | * |
223 | * You can set the status to be in the predefined categories. |
224 | * Ideally, each category should own one status. |
225 | * A status may be in several categories, or in none. |
226 | * There shouldn't be more than one status per protocol per categories. |
227 | */ |
228 | OnlineStatus( StatusType status, unsigned weight, Protocol *protocol, unsigned internalStatus, const QStringList &overlayIcon, |
229 | const QString &description, const QString& caption, OnlineStatusManager::Categories categories = 0x0 , OnlineStatusManager::Options options = 0x0 ); |
230 | |
231 | |
232 | /** |
233 | * Constructor. |
234 | * |
235 | * Creates a libkopete builtin status object. Weight, protocol and internal |
236 | * status are set to zero, the strings and icons are set to the meta contact |
237 | * strings. |
238 | */ |
239 | OnlineStatus( StatusType status ); /* implicit */ |
240 | |
241 | /** |
242 | * Copy constructor. |
243 | * |
244 | * Just adds a reference to the refcount. Used to copy around the status |
245 | * objects with very little overhead. |
246 | */ |
247 | OnlineStatus( const OnlineStatus &other ); |
248 | |
249 | /** |
250 | * Destructor. |
251 | */ |
252 | ~OnlineStatus(); |
253 | |
254 | /** |
255 | * \brief Return the status |
256 | */ |
257 | StatusType status() const; |
258 | |
259 | /** |
260 | * \brief Return the internal status |
261 | */ |
262 | unsigned internalStatus() const; |
263 | |
264 | /** |
265 | * \brief Return the weight |
266 | */ |
267 | unsigned weight() const; |
268 | |
269 | /** |
270 | * \brief Return the list of overlay icons |
271 | */ |
272 | QStringList overlayIcons() const; |
273 | |
274 | /** |
275 | * \brief Return the description |
276 | */ |
277 | QString description() const; |
278 | |
279 | /** |
280 | * \brief Return the protocol this applies to |
281 | */ |
282 | Protocol* protocol() const; |
283 | |
284 | /** |
285 | * \brief Return the text for the action in the menu |
286 | */ |
287 | QString caption() const; |
288 | |
289 | /** |
290 | * \brief Return the categories this online status is in |
291 | * |
292 | * @see Kopete::OnlineStatusManager for more info about the categories |
293 | */ |
294 | OnlineStatusManager::Categories categories() const; |
295 | |
296 | /** |
297 | * \brief Return the options of this online status |
298 | * |
299 | * @see Kopete::OnlineStatusManager for more info about the options parameters |
300 | */ |
301 | OnlineStatusManager::Options options() const; |
302 | |
303 | /** |
304 | * @return @c true if this a contact with this status is definitely online, |
305 | * @c false if the contact is Offline, Connecting or Unknown. |
306 | */ |
307 | bool isDefinitelyOnline() const; |
308 | |
309 | |
310 | |
311 | |
312 | /** |
313 | * \brief Return a status icon generated for the given Contact |
314 | * |
315 | * This will draw an overlay representing the online status |
316 | * of the contact the OnlineStatus applies to |
317 | * over the base icon. |
318 | * A cache is employed to reduce CPU and memory usage. |
319 | * @param contact is the contact the icon should apply to. |
320 | */ |
321 | QIcon iconFor( const Contact *contact ) const; |
322 | |
323 | /** |
324 | * \brief Return a status icon generated for the given Contact |
325 | * \overload |
326 | * \deprecated Use the one that return a QIcon |
327 | * @param contact is the contact the icon should apply to. |
328 | * @param size is the size we the icon should be scaled to |
329 | */ |
330 | KDE_DEPRECATED QPixmap iconFor( const Contact *contact, int size ) const |
331 | { return iconFor(contact).pixmap(size); } |
332 | |
333 | /** |
334 | * \brief Return the mime source for a status icon generated for the given Contact |
335 | * |
336 | * This behaves essentially like the method above, except for that |
337 | * it returns a mime source string that can be used to render the |
338 | * image in richtext components and the like. The returned key |
339 | * is only valid until the cache is cleared for the next time, |
340 | * so no assumptions should be made about long-time availability |
341 | * of the referenced data. |
342 | * @param contact is the contact the icon should apply to. |
343 | * @param size is the size we the icon should be scaled to - 16 is default and so costs nothing |
344 | */ |
345 | QString mimeSourceFor( const Contact *contact, int size = 16 ) const; |
346 | |
347 | /** |
348 | * \brief Return a status icon generated for the given Account |
349 | * |
350 | * This will draw an overlay representing the online status |
351 | * of the account the OnlineStatus applies to |
352 | * over the base icon. |
353 | * A cache is employed to reduce CPU and memory usage. |
354 | * @param account is the account the icon should apply to. |
355 | * The account's color causes tinting, if it's plain QColor(), no tinting takes place. |
356 | * @param size is the size we the icon should be scaled to - 16 is default and so costs nothing |
357 | */ |
358 | QIcon iconFor( const Account *account ) const; |
359 | |
360 | /** |
361 | * \brief Return a status icon generated for the given Account |
362 | * \overload |
363 | * \deprecated Use the varient which return a QIcon |
364 | * |
365 | * @param account is the account the icon should apply to. |
366 | * The account's color causes tinting, if it's plain QColor(), no tinting takes place. |
367 | * @param size is the size we the icon should be scaled to - 16 is default and so costs nothing |
368 | */ |
369 | KDE_DEPRECATED QPixmap iconFor( const Account *account, int size ) const |
370 | { return iconFor(account).pixmap(size); } |
371 | |
372 | /** |
373 | * \brief Return the mime source for a status icon generated for the given Account |
374 | * |
375 | * This behaves essentially like the method above, except for that |
376 | * it returns a mime source string that can be used to render the |
377 | * image in richtext components and the like. The returned key |
378 | * is only valid until the cache is cleared for the next time, |
379 | * so no assumptions should be made about long-time availability |
380 | * of the referenced data. |
381 | * @param account is the account the icon should apply to. |
382 | * The account's color causes tinting, if it's plain QColor(), no tinting takes place. |
383 | * @param size is the size we the icon should be scaled to - 16 is default and so costs nothing |
384 | */ |
385 | QString mimeSourceFor( const Account *account, int size = 16 ) const; |
386 | |
387 | /** |
388 | * \brief Return a previously rendered status icon for a mime source key |
389 | * |
390 | * You can access icons with this method that have previously been rendered |
391 | * using mimeSourceFor(). Note that only a cache lookup will be done, so |
392 | * if the cache has been invalidated due to a change of icon sets between |
393 | * requesting the key (thus rendering the icon) and trying to access the |
394 | * icon by key, an invalid pixmap will be returned. |
395 | */ |
396 | QPixmap iconFor( const QString &mimeSource ) const; |
397 | |
398 | /** |
399 | * \brief Returns the status icon for the protocol. |
400 | * |
401 | * A cache is employed to reduce CPU and memory usage. |
402 | */ |
403 | QPixmap protocolIcon(const KIconLoader::StdSizes size) const; |
404 | |
405 | /** |
406 | * \brief Returns the status icon for the protocol. |
407 | * |
408 | * A cache is employed to reduce CPU and memory usage. |
409 | */ |
410 | KDE_DEPRECATED QPixmap protocolIcon() const; |
411 | |
412 | /** |
413 | * Assignment operator |
414 | */ |
415 | OnlineStatus & operator=( const OnlineStatus &other ); |
416 | |
417 | /** |
418 | * Comparison operator |
419 | * |
420 | * Returns true if both the protocol and the internal status are |
421 | * identical. |
422 | */ |
423 | bool operator==( const OnlineStatus &other ) const; |
424 | |
425 | /** |
426 | * Comparison operator |
427 | * |
428 | * This operator works exactly opposite of @ref operator==() |
429 | */ |
430 | bool operator!=( const OnlineStatus &other ) const; |
431 | |
432 | /** |
433 | * Comparison operator |
434 | * |
435 | * Returns true if the status() of this contact is of higher value than the other |
436 | * contact or if both statuses are equal and weight() is higher for this contact. |
437 | */ |
438 | bool operator>( const OnlineStatus &other ) const; |
439 | |
440 | /** |
441 | * Comparison operator |
442 | * |
443 | * This operator works exactly opposite of @ref operator>() |
444 | */ |
445 | bool operator<( const OnlineStatus &other ) const; |
446 | |
447 | /** |
448 | * \brief returns a QString from a StatusType |
449 | * |
450 | * Static method to convert a Kopete::OnlineStatus::StatusType to a string to avoid |
451 | * many issues when saving StatusType to disk |
452 | */ |
453 | static QString statusTypeToString(OnlineStatus::StatusType status); |
454 | |
455 | /** |
456 | * \brief returns a StatusType from a QString |
457 | * |
458 | * Static method to convert a QString representing a StatusType to a StatusType to avoid |
459 | * many issues when saving StatusType to disk |
460 | */ |
461 | static OnlineStatus::StatusType statusStringToType(const QString& string); |
462 | |
463 | |
464 | |
465 | private: |
466 | |
467 | class Private; |
468 | KSharedPtr<Private> d; |
469 | |
470 | QString mimeSource( const QString& icon, int size, QColor color, bool idle) const; |
471 | |
472 | |
473 | }; |
474 | |
475 | } //END namespace Kopete |
476 | |
477 | #endif |
478 | |
479 | |
480 | |