kopete/libkopete

Kopete::OnlineStatus

Kopete::OnlineStatus Class Reference

#include <kopeteonlinestatus.h>

Detailed Description

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!

Definition at line 67 of file kopeteonlinestatus.h.


Public Types
enum	ReservedInternalStatus { AccountOffline = 0x80000001 }
enum	StatusType { Unknown = 0, Offline = 10, Connecting = 20, Invisible = 30, Away = 40, Online = 50 }
Public Member Functions
QString	caption () const
OnlineStatusManager::Categories	categories () const
QString	description () const
QPixmap	iconFor (const QString &mimeSource) const
KDE_DEPRECATED QPixmap	iconFor (const Account *account, int size) const
QIcon	iconFor (const Account *account) const
KDE_DEPRECATED QPixmap	iconFor (const Contact *contact, int size) const
QIcon	iconFor (const Contact *contact) const
unsigned	internalStatus () const
bool	isDefinitelyOnline () const
QString	mimeSourceFor (const Account *account, int size=16) const
QString	mimeSourceFor (const Contact *contact, int size=16) const
	OnlineStatus (const OnlineStatus &other)
	OnlineStatus (StatusType status)
	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, unsigned weight, Protocol *protocol, unsigned internalStatus, const QStringList &overlayIcons, const QString &description)
	OnlineStatus ()
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
StatusType	status () const
unsigned	weight () const
	~OnlineStatus ()
Static Public Member Functions
static OnlineStatus::StatusType	statusStringToType (const QString &string)
static QString	statusTypeToString (OnlineStatus::StatusType status)

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 136 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 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).
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 77 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 180 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 113 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 127 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 144 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 192 of file kopeteonlinestatus.cpp.

OnlineStatus::~OnlineStatus ( )

Destructor.

Definition at line 237 of file kopeteonlinestatus.cpp.

Member Function Documentation

QString OnlineStatus::caption ( ) const

Return the text for the action in the menu.

Definition at line 271 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 276 of file kopeteonlinestatus.cpp.

QString OnlineStatus::description ( ) const

Return the description.

Definition at line 261 of file kopeteonlinestatus.cpp.

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 336 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 364 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 318 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 325 of file kopeteonlinestatus.h.

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 293 of file kopeteonlinestatus.cpp.

unsigned OnlineStatus::internalStatus ( ) const

Return the internal status.

Definition at line 246 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 286 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 327 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.

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 305 of file kopeteonlinestatus.cpp.

bool OnlineStatus::operator!= ( const OnlineStatus & other ) const

Comparison operator.

This operator works exactly opposite of operator==()

Definition at line 209 of file kopeteonlinestatus.cpp.

bool OnlineStatus::operator< ( const OnlineStatus & other ) const

Comparison operator.

This operator works exactly opposite of operator>()

Definition at line 223 of file kopeteonlinestatus.cpp.

OnlineStatus & OnlineStatus::operator= ( const OnlineStatus & other )

Assignment operator.

Definition at line 231 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 197 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 215 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 281 of file kopeteonlinestatus.cpp.

QStringList OnlineStatus::overlayIcons ( ) const

Return the list of overlay icons.

Definition at line 256 of file kopeteonlinestatus.cpp.

Protocol * OnlineStatus::protocol ( ) const

Return the protocol this applies to.

Definition at line 266 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 341 of file kopeteonlinestatus.cpp.

OnlineStatus::StatusType OnlineStatus::status ( ) const

Return the status.

Definition at line 241 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 365 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 354 of file kopeteonlinestatus.cpp.

unsigned OnlineStatus::weight ( ) const

Return the weight.

Definition at line 251 of file kopeteonlinestatus.cpp.

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

kopete/libkopete

Kopete::OnlineStatus Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

kopete/libkopete

kdenetwork