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
36class QString;
37class QPixmap;
38class QColor;
39
40namespace 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 */
68class KOPETE_EXPORT OnlineStatus
69{
70public:
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
465private:
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