Kopete::OnlineStatus Class Reference

#include <kopeteonlinestatus.h>

Public Types
enum	ReservedInternalStatus { AccountOffline = 0x80000001 }
enum	StatusType {   Unknown =0, Offline =10, Connecting =20, Invisible =30,   Away =40, Busy =45, Online =50 }

Public Member Functions
	OnlineStatus ()
	OnlineStatus (StatusType status, unsigned weight, Protocol *protocol, unsigned internalStatus, const QStringList &overlayIcons, const QString &description)
	OnlineStatus (StatusType status, unsigned weight, Protocol *protocol, unsigned internalStatus, const QStringList &overlayIcon, const QString &description, const QString &caption, OnlineStatusManager::Categories categories=0x0, OnlineStatusManager::Options options=0x0)
	OnlineStatus (StatusType status)
	OnlineStatus (const OnlineStatus &other)
	~OnlineStatus ()
QString	caption () const
OnlineStatusManager::Categories	categories () const
QString	description () const
QIcon	iconFor (const Contact *contact) const
KDE_DEPRECATED QPixmap	iconFor (const Contact *contact, int size) const
QIcon	iconFor (const Account *account) const
KDE_DEPRECATED QPixmap	iconFor (const Account *account, int size) const
QPixmap	iconFor (const QString &mimeSource) const
unsigned	internalStatus () const
bool	isDefinitelyOnline () const
QString	mimeSourceFor (const Contact *contact, int size=16) const
QString	mimeSourceFor (const Account *account, int size=16) const
bool	operator!= (const OnlineStatus &other) const
bool	operator< (const OnlineStatus &other) const
OnlineStatus &	operator= (const OnlineStatus &other)
bool	operator== (const OnlineStatus &other) const
bool	operator> (const OnlineStatus &other) const
OnlineStatusManager::Options	options () const
QStringList	overlayIcons () const
Protocol *	protocol () const
QPixmap	protocolIcon (const KIconLoader::StdSizes size) const
KDE_DEPRECATED QPixmap	protocolIcon () const
StatusType	status () const
unsigned	weight () const

Static Public Member Functions
static OnlineStatus::StatusType	statusStringToType (const QString &string)
static QString	statusTypeToString (OnlineStatus::StatusType status)

Detailed Description

Author

Martijn Klingens kling.nosp@m.ens@.nosp@m.kde.o.nosp@m.rg

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!

Definition at line 68 of file kopeteonlinestatus.h.

Member Enumeration Documentation

enum Kopete::OnlineStatus::ReservedInternalStatus

Reserved internal status values.

Any internal status value > 0x80000000 is reserved for internal libkopete use. This enumeration lists the currently known values.

Enumerator
AccountOffline	The account this contact belongs to is offline. Used with the Unknown StatusType.

Definition at line 141 of file kopeteonlinestatus.h.

enum Kopete::OnlineStatus::StatusType

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

Enumerator
Unknown	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 MetaContact for meta contacts that have no child contacts at all.
Offline	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.
Connecting	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
Invisible	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.
Away	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 will be because you are not in front of the computer or because the client detected you don't interact.
Busy	Means that you have other things to do and don't want to get involved in messaging ('Busy' or 'Do not Disturb' for example).
Online	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.

Definition at line 78 of file kopeteonlinestatus.h.

Constructor & Destructor Documentation

OnlineStatus::OnlineStatus

(

)

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.

Definition at line 181 of file kopeteonlinestatus.cpp.

OnlineStatus::OnlineStatus	(	StatusType	status,
		unsigned	weight,
		Protocol *	protocol,
		unsigned	internalStatus,
		const QStringList &	overlayIcons,
		const QString &	description
	)

Constructor.

Creates a new OnlineStatus object. All fields are mandatory; there are no default values. Also, you cannot change the object after creation.

Parameters

status	is the global online status as used by libkopete
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.
protocol	is a pointer to the protocol used. This is used when comparing two online status objects.
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.
overlayIcons	is a list of QStrings 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 QString() 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.
description	is a description in e.g. tooltips.

Definition at line 114 of file kopeteonlinestatus.cpp.

OnlineStatus::OnlineStatus	(	StatusType	status,
		unsigned	weight,
		Protocol *	protocol,
		unsigned	internalStatus,
		const QStringList &	overlayIcon,
		const QString &	description,
		const QString &	caption,
		OnlineStatusManager::Categories	categories = 0x0,
		OnlineStatusManager::Options	options = 0x0
	)

Constructor.

Creates a new OnlineStatus object and registers it with the Kopete::OnlineStatusManager. Registration allows you to generate a KActionMenu filled with KActions for changing to this OnlineStatus, using Kopete::Account::accountMenu().

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.

Parameters

status	is the global online status as used by libkopete
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
protocol	is a pointer to the protocol used. This is used when comparing two online status objects.
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.
overlayIcon	is a string returning the name of the status icon to be used by the KDE icon loader. (Status whiwh doesn't have icon to overlay like Online and Offline should use QString() as icon string)
description	is a description in e.g. tooltips.
caption	is the text of the action in the menu
categories	the categories this online status is in
options	the options of this online status

See also

Kopete::OnlineStatusManager for more info about the categories and options parameters

You can set the status to be in the predefined categories. Ideally, each category should own one status. A status may be in several categories, or in none. There shouldn't be more than one status per protocol per categories.

Definition at line 128 of file kopeteonlinestatus.cpp.

OnlineStatus::OnlineStatus

(

StatusType

status

)

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.

Definition at line 145 of file kopeteonlinestatus.cpp.

OnlineStatus::OnlineStatus

(

const OnlineStatus &

other

)

Copy constructor.

Just adds a reference to the refcount. Used to copy around the status objects with very little overhead.

Definition at line 193 of file kopeteonlinestatus.cpp.

OnlineStatus::~OnlineStatus

(

)

Destructor.

Definition at line 238 of file kopeteonlinestatus.cpp.

Member Function Documentation

QString OnlineStatus::caption

(

)

const

Return the text for the action in the menu.

Definition at line 272 of file kopeteonlinestatus.cpp.

OnlineStatusManager::Categories OnlineStatus::categories

(

)

const

Return the categories this online status is in.

See also

Kopete::OnlineStatusManager for more info about the categories

Definition at line 277 of file kopeteonlinestatus.cpp.

QString OnlineStatus::description

(

)

const

Return the description.

Definition at line 262 of file kopeteonlinestatus.cpp.

QIcon OnlineStatus::iconFor

(

const Contact *

contact

)

const

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.

Parameters

contact

is the contact the icon should apply to.

Definition at line 294 of file kopeteonlinestatus.cpp.

KDE_DEPRECATED QPixmap Kopete::OnlineStatus::iconFor ( const Contact *  contact, int  size  ) const

inline

Return a status icon generated for the given Contact This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Deprecated:

Use the one that return a QIcon

Parameters

contact	is the contact the icon should apply to.
size	is the size we the icon should be scaled to

Definition at line 330 of file kopeteonlinestatus.h.

QIcon OnlineStatus::iconFor

(

const Account *

account

)

const

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.

Parameters

account	is the account the icon should apply to. The account's color causes tinting, if it's plain QColor(), no tinting takes place.
size	is the size we the icon should be scaled to - 16 is default and so costs nothing

Definition at line 319 of file kopeteonlinestatus.cpp.

KDE_DEPRECATED QPixmap Kopete::OnlineStatus::iconFor ( const Account *  account, int  size  ) const

inline

Return a status icon generated for the given Account This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Deprecated:

Use the varient which return a QIcon

Parameters

account	is the account the icon should apply to. The account's color causes tinting, if it's plain QColor(), no tinting takes place.
size	is the size we the icon should be scaled to - 16 is default and so costs nothing

Definition at line 369 of file kopeteonlinestatus.h.

QPixmap OnlineStatus::iconFor

(

const QString &

mimeSource

)

const

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 invalidated 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.

Definition at line 337 of file kopeteonlinestatus.cpp.

unsigned OnlineStatus::internalStatus

(

)

const

Return the internal status.

Definition at line 247 of file kopeteonlinestatus.cpp.

bool OnlineStatus::isDefinitelyOnline

(

)

const

Returns

true if this a contact with this status is definitely online, false if the contact is Offline, Connecting or Unknown.

Definition at line 287 of file kopeteonlinestatus.cpp.

QString OnlineStatus::mimeSourceFor	(	const Contact *	contact,
		int	size = 16
	)		const

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.

Parameters

contact	is the contact the icon should apply to.
size	is the size we the icon should be scaled to - 16 is default and so costs nothing

Definition at line 306 of file kopeteonlinestatus.cpp.

QString OnlineStatus::mimeSourceFor	(	const Account *	account,
		int	size = 16
	)		const

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.

Parameters

account	is the account the icon should apply to. The account's color causes tinting, if it's plain QColor(), no tinting takes place.
size	is the size we the icon should be scaled to - 16 is default and so costs nothing

Definition at line 328 of file kopeteonlinestatus.cpp.

bool OnlineStatus::operator!=

(

const OnlineStatus &

other

)

const

Comparison operator.

This operator works exactly opposite of operator==()

Definition at line 210 of file kopeteonlinestatus.cpp.

bool OnlineStatus::operator<

(

const OnlineStatus &

other

)

const

Comparison operator.

This operator works exactly opposite of operator>()

Definition at line 224 of file kopeteonlinestatus.cpp.

OnlineStatus & OnlineStatus::operator=

(

const OnlineStatus &

other

)

Assignment operator.

Definition at line 232 of file kopeteonlinestatus.cpp.

bool OnlineStatus::operator==

(

const OnlineStatus &

other

)

const

Comparison operator.

Returns true if both the protocol and the internal status are identical.

Definition at line 198 of file kopeteonlinestatus.cpp.

bool OnlineStatus::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.

Definition at line 216 of file kopeteonlinestatus.cpp.

OnlineStatusManager::Options OnlineStatus::options

(

)

const

Return the options of this online status.

See also

Kopete::OnlineStatusManager for more info about the options parameters

Definition at line 282 of file kopeteonlinestatus.cpp.

QStringList OnlineStatus::overlayIcons

(

)

const

Return the list of overlay icons.

Definition at line 257 of file kopeteonlinestatus.cpp.

Protocol * OnlineStatus::protocol

(

)

const

Return the protocol this applies to.

Definition at line 267 of file kopeteonlinestatus.cpp.

QPixmap OnlineStatus::protocolIcon

(

const KIconLoader::StdSizes

size

)

const

Returns the status icon for the protocol.

A cache is employed to reduce CPU and memory usage.

Definition at line 342 of file kopeteonlinestatus.cpp.

QPixmap OnlineStatus::protocolIcon

(

)

const

Returns the status icon for the protocol.

A cache is employed to reduce CPU and memory usage.

Definition at line 347 of file kopeteonlinestatus.cpp.

OnlineStatus::StatusType OnlineStatus::status

(

)

const

Return the status.

Definition at line 242 of file kopeteonlinestatus.cpp.

OnlineStatus::StatusType OnlineStatus::statusStringToType ( const QString &  string )

static

returns a StatusType from a QString

Static method to convert a QString representing a StatusType to a StatusType to avoid many issues when saving StatusType to disk

Definition at line 371 of file kopeteonlinestatus.cpp.

QString OnlineStatus::statusTypeToString ( OnlineStatus::StatusType  status )

static

returns a QString from a StatusType

Static method to convert a Kopete::OnlineStatus::StatusType to a string to avoid many issues when saving StatusType to disk

Definition at line 360 of file kopeteonlinestatus.cpp.

unsigned OnlineStatus::weight

(

)

const

Return the weight.

Definition at line 252 of file kopeteonlinestatus.cpp.

---

The documentation for this class was generated from the following files:

• kopeteonlinestatus.h
• kopeteonlinestatus.cpp