summaryrefslogtreecommitdiffstats
path: root/kopete/libkopete/kopeteonlinestatus.h
blob: a1296f17a9297f373b11cd001bef4344eee012d7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
/*
    kopeteonlinestatus.h - Kopete Online tqStatus

    Copyright (c) 2003 by Martijn Klingens <klingens@kde.org>
    Copyright (c) 2003 by Duncan Mac-Vicar Prett <duncan@kde.org>
    Copyright (c) 2003 by Will Stephenson <lists@stevello.free-online.co.uk>
    Copyright (c) 2004 by Olivier Goffart <ogoffart @ tiscalinet.be>

    Kopete    (c) 2002-2004 by the Kopete developers  <kopete-devel@kde.org>

    *************************************************************************
    *                                                                       *
    * This library is free software; you can redistribute it and/or         *
    * modify it under the terms of the GNU Lesser General Public            *
    * License as published by the Free Software Foundation; either          *
    * version 2 of the License, or (at your option) any later version.      *
    *                                                                       *
    *************************************************************************
*/

#ifndef kopeteonlinestatus_h
#define kopeteonlinestatus_h

#include "kopete_export.h"

#include <kdemacros.h>
#include <ksharedptr.h>

#include <tqobject.h>

class TQString;
class TQPixmap;
class TQColor;

namespace Kopete
{

	class OnlineStatusManager;
	class Protocol;
	class Account;
	class Contact;

/**
 * @author Martijn Klingens <klingens@kde.org>
 * @author Will Stephenson (icon generating code)
 *
 * OnlineStatus is a class that encapsulates all information about the
 * various online states that a protocol can be in in a single class. The
 * online status consists of both a 'global' status as it's known to libkopete
 * and used for going online or away, which non-protocol plugins can use,
 * and the 'private' status, which is simply an unsigned int and is only
 * useful for the actual protocol plugin that uses the status.
 *
 * This class is passed around by value, but is refcounted to cut down on the
 * amount of overhead. All in all it should be more than fast enough for
 * general use.
 *
 * Note that ONLY the constructor can set the data, the object is considered
 * to be const after creation as there really shouldn't be a need to change
 * a status' characteristics during runtime!
 */
class KOPETE_EXPORT OnlineStatus
{
public:
	/**
	 * The available global states. It is possible that multiple internal
	 * states map to the same global states. For example ICQ's 'Do not disturb'
	 * is handled just like 'Away' by libkopete. Only ICQ itself makes (and
	 * should make) a distinction.
	 * The order is important and is used in the < or > operator
	 */
	enum StatusType
	{
		/**
		 * Refers to protocols where state cannot be determined. This
		 * applies to SMS contacts (text messages via mobile phones),
		 * since there's no presence information over SMS, but also
		 * to e.g. MSN contacts that are not on your contact list,
		 * since MSN only allows a user to query online state for
		 * users that are formally on the contact list. Lastly, libkopete
		 * itself uses the Unknown state in @ref MetaContact for
		 * meta contacts that have no child contacts at all.
		 */
		Unknown=0,
		/**
		 * State where you really cannot be contacted. Although
		 * Kopete doesn't oppose any technical limitations it really
		 * doesn't make sense to have more than one status per protocol
		 * that maps to 'Offline', since you're supposed to be
		 * disconnected from the network in this state.
		 */
		Offline=10,
		/**
		 * State where the user is not available on the network yet
		 * but trying to get onto. Most useful to yourself contact, because
		 * this state means not visible but with network access
		 */
		Connecting=20,
		/**
		 * State where you are online but none of your contacts can
		 * see that you're online. Useful for all the protocols that support
		 * being invisible.
		 */
		Invisible=30,
		/**
		 * Refers to a state where you can be technically reached, but
		 * for one reason or another it is often not useful to do so.
		 * This can be because you really aren't behind the computer
		 * ('Away' or 'Idle') or because you have other things to do
		 * and don't want to get involved in messaging ('Busy' or 'Do
		 * not Disturb' for example).
		 */
		Away=40,
		/**
		 * Refers to a true online state, i.e. you can be contacted by
		 * others both technically and practically. This also applies
		 * to e.g. ICQ's 'Free for Chat' status.
		 */
		Online=50
	};
	// note than Unknown is first, because the metacontact algorithm to detect
	// the metacontact status from the contact status starts from Unknown, and
	// takes a contact only if its status is greater

	/**
	 * Reserved internal status values
	 *
	 * Any internal status value > 0x80000000 is reserved for internal
	 * libkopete use. This enumeration lists the currently known values.
	 */
	enum ReservedInternaltqStatus
	{
		/**
		 * The account this contact belongs to is offline. Used with
		 * the Unknown StatusType.
		 */
		AccountOffline = 0x80000001
	};


	/**
	 * Constructor.
	 *
	 * Creates an empty OnlineStatus object. Since you cannot change
	 * OnlineStatus objects that are already created other than by their
	 * assignment operator, this constructor is only a convenience method
	 * for use in e.g. class members and local variables.
	 */
	OnlineStatus();


	/**
	 * Constructor.
	 *
	 * Creates a new OnlineStatus object. All fields are mandatory; there
	 * are no default values. Also, you cannot change the object after creation.
	 *
	 * @param status is the global online status as used by libkopete
	 * @param weight is the 'weight' of this status. The contact list is
	 * sorted by status, and by weight within a status. It's not possible to
	 * 'promote' an Away item to a level above Online, since the status field
	 * always takes precedence. Weight is used when the same status is used
	 * more than once. Weight is also used for picking the most important
	 * 'Away' status for a protocol when going Away.
	 * @param protocol is a pointer to the protocol used. This is used when
	 * comparing two online status objects.
	 * @param internalStatus is the status as used internally by the protocol.
	 * This status is usually a lot more fine-grained than the status as used
	 * by libkopete and should be unique per protocol.
	 * @param overlayIcons is a list of TQStrings which are the name of status
	 * icons to be used by the KDE icon loader. (Statuses which don't have icons
	 * to overlay like Online and Offline should use TQString() as icon
	 * name ).  NOTE if the string is a movie ( *.mng ) it must be the first string in the list.
	 * TODO: KDE4 sort out movies and overlay icons.
	 * @param description is a description in e.g. tooltips.
	 */
	OnlineStatus( StatusType status, unsigned weight, Protocol *protocol,
		unsigned internalStatus, const TQStringList &overlayIcons, const TQString &description );

	/**
	 * Constructor.
	 *
	 * @p Creates a new OnlineStatus object and registers it with the @ref Kopete::OnlineStatusManager.
	 * Registration allows you to generate a KActionMenu filled with KActions for changing to this OnlineStatus,
	 * using Kopete::Account::accountMenu().
	 *
	 * @p Note that weight has an additional significance for registered protocols when used for menu generation.
	 *
	 * All fields are mandatory; there
	 * are no default values. Also, you cannot change the object after creation.
	 *
	 * @param status is the global online status as used by libkopete
	 * @param weight is the 'weight' of this status. The contact list is
	 * sorted by status, and by weight within a status. It's not possible to
	 * 'promote' an Away item to a level above Online, since the status field
	 * always takes precedence. Weight is used when the same status is used
	 * more than once. Weight is also used for picking the most important
	 * 'Away' status for a protocol when going Away. Additionally, Weight determinesis also
	 * @param protocol is a pointer to the protocol used. This is used when
	 * comparing two online status objects.
	 * @param internalStatus is the status as used internally by the protocol.
	 * This status is usually a lot more fine-grained than the status as used
	 * by libkopete and should be unique per protocol.
	 * @param overlayIcon is a string returning the name of the status icon to be
	 * used by the KDE icon loader. (tqStatus whiwh doesn't have icon to overlay like
	 * Online and Offline should use TQString() as icon string)
	 * @param description is a description in e.g. tooltips.
	 * @param caption is the text of the action in the menu
	 * @param categories the categories this online status is in
	 * @param options the options of this online status
	 * @see Kopete::OnlineStatusManager::registerOnlineStatus for more info about the categories and options parameters
	 */
	OnlineStatus( StatusType status, unsigned weight, Protocol *protocol, unsigned internalStatus, const TQStringList &overlayIcon,
		const TQString &description, const TQString& caption,  unsigned int categories=0x0 , unsigned int options=0x0 );


	/**
	 * Constructor.
	 *
	 * Creates a libkopete builtin status object. Weight, protocol and internal
	 * status are set to zero, the strings and icons are set to the meta contact
	 * strings.
	 */
	OnlineStatus( StatusType status );

	/**
	 * Copy constructor.
	 *
	 * Just adds a reference to the refcount. Used to copy around the status
	 * objects with very little overhead.
	 */
	OnlineStatus( const OnlineStatus &other );

	/**
	 * Destructor.
	 */
	~OnlineStatus();

	/**
	 * \brief Return the status
	 */
	StatusType status() const;

	/**
	 * \brief Return the internal status
	 */
	unsigned internalStatus() const;

	/**
	 * \brief Return the weight
	 */
	unsigned weight() const;

	/**
	 * \brief Return the list of overlay icons
	 */
	TQStringList overlayIcons() const;

	/**
	 * \brief Return the description
	 */
	TQString description() const;

	/**
	 * \brief Return the protocol this applies to
	 */
	Protocol* protocol() const;

	/**
	 * @return @c true if this a contact with this status is definitely online,
	 *         @c false if the contact is Offline, Connecting or Unknown.
	 */
	bool isDefinitelyOnline() const;


	/**
	 * \brief Return a status icon generated for the given Contact
	 *
	 * This will draw an overlay representing the online status
	 * of the contact the OnlineStatus applies to
	 * over the base icon.
	 * A cache is employed to reduce CPU and memory usage.
	 * @param contact is the contact the icon should apply to.
	 * @param size is the size we the icon should be scaled to - 16 is default and so costs nothing
	 */
	TQPixmap iconFor( const Contact *contact, int size = 16 ) const;

	/**
	 * \brief Return the mime source for a status icon generated for the given Contact
	 *
	 * This behaves essentially like the method above, except for that
	 * it returns a mime source string that can be used to render the
	 * image in richtext components and the like. The returned key
	 * is only valid until the cache is cleared for the next time,
	 * so no assumptions should be made about long-time availability
	 * of the referenced data.
	 * @param contact is the contact the icon should apply to.
	 * @param size is the size we the icon should be scaled to - 16 is default and so costs nothing
	 */
	TQString mimeSourceFor( const Contact *contact, int size = 16 ) const;

	/**
	 * \brief Return a status icon generated for the given Account
	 *
	 * This will draw an overlay representing the online status
	 * of the account the OnlineStatus applies to
	 * over the base icon.
	 * A cache is employed to reduce CPU and memory usage.
	 * @param account is the account the icon should apply to.
	 * The account's color causes tinting, if it's plain TQColor(), no tinting takes place.
	 * @param size is the size we the icon should be scaled to - 16 is default and so costs nothing
	 */
	TQPixmap iconFor( const Account *account, int size = 16 ) const;

	/**
	 * \brief Return the mime source for a status icon generated for the given Account
	 *
	 * This behaves essentially like the method above, except for that
	 * it returns a mime source string that can be used to render the
	 * image in richtext components and the like. The returned key
	 * is only valid until the cache is cleared for the next time,
	 * so no assumptions should be made about long-time availability
	 * of the referenced data.
	 * @param account is the account the icon should apply to.
	 * The account's color causes tinting, if it's plain TQColor(), no tinting takes place.
	 * @param size is the size we the icon should be scaled to - 16 is default and so costs nothing
	 */
	TQString mimeSourceFor( const Account *account, int size = 16 ) const;

	/**
	 * \brief Return a previously rendered status icon for a mime source key
	 *
	 * You can access icons with this method that have previously been rendered
	 * using mimeSourceFor(). Note that only a cache lookup will be done, so
	 * if the cache has been tqinvalidated due to a change of icon sets between
	 * requesting the key (thus rendering the icon) and trying to access the
	 * icon by key, an invalid pixmap will be returned.
	 */
	TQPixmap iconFor( const TQString &mimeSource ) const;

	/**
	 * \brief Returns the status icon for the protocol.
	 *
	 * A cache is employed to reduce CPU and memory usage.
	 */
	TQPixmap protocolIcon() const;

	/**
	 * Assignment operator
	 */
	OnlineStatus & operator=( const OnlineStatus &other );

	/**
	 * Comparison operator
	 *
	 * Returns true if both the protocol and the internal status are
	 * identical.
	 */
	bool operator==( const OnlineStatus &other ) const;

	/**
	 * Comparison operator
	 *
	 * This operator works exactly opposite of @ref operator==()
	 */
	bool operator!=( const OnlineStatus &other ) const;

	/**
	 * Comparison operator
	 *
	 * Returns true if the status() of this contact is of higher value than the other
	 * contact or if both statuses are equal and weight() is higher for this contact.
	 */
	bool operator>( const OnlineStatus &other ) const;

	/**
	 * Comparison operator
	 *
	 * This operator works exactly opposite of @ref operator>()
	 */
	bool operator<( const OnlineStatus &other ) const;

	/**
	 * \brief returns a TQString from a StatusType
	 *
	 * Static method to convert a Kopete::OnlineStatus::StatusType to a string to avoid
	 * many issues when saving StatusType to disk
	 */
	 static TQString statusTypeToString(OnlineStatus::StatusType status);

	 /**
	 * \brief returns a StatusType from a TQString
	 *
	 * Static method to convert a TQString representing a StatusType to a StatusType to avoid
	 * many issues when saving StatusType to disk
	 */
	 static OnlineStatus::StatusType statusStringToType(TQString& string);



private:

	class Private;
	KSharedPtr<Private> d;

	TQString mimeSource( const TQString& icon, int size, TQColor color, bool idle) const;


};

}  //END namespace Kopete

#endif