• Skip to content
  • Skip to link menu
KDE API Reference
  • KDE API Reference
  • kdenetwork API Reference
  • KDE Home
  • Contact Us
 

kopete/libkopete

  • Kopete
  • OnlineStatus
Public Types | Public Member Functions | Static Public Member Functions | List of all members
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
statusis the global online status as used by libkopete
weightis 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.
protocolis a pointer to the protocol used. This is used when comparing two online status objects.
internalStatusis 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.
overlayIconsis 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.
descriptionis 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
statusis the global online status as used by libkopete
weightis 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
protocolis a pointer to the protocol used. This is used when comparing two online status objects.
internalStatusis 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.
overlayIconis 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)
descriptionis a description in e.g. tooltips.
captionis the text of the action in the menu
categoriesthe categories this online status is in
optionsthe 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
contactis 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
contactis the contact the icon should apply to.
sizeis 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
accountis the account the icon should apply to. The account's color causes tinting, if it's plain QColor(), no tinting takes place.
sizeis 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
accountis the account the icon should apply to. The account's color causes tinting, if it's plain QColor(), no tinting takes place.
sizeis 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
contactis the contact the icon should apply to.
sizeis 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
accountis the account the icon should apply to. The account's color causes tinting, if it's plain QColor(), no tinting takes place.
sizeis 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
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Mon Jun 22 2020 13:29:20 by doxygen 1.8.7 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

kopete/libkopete

Skip menu "kopete/libkopete"
  • Main Page
  • Namespace List
  • Namespace Members
  • Alphabetical List
  • Class List
  • Class Hierarchy
  • Class Members
  • File List
  • File Members
  • Related Pages

kdenetwork API Reference

Skip menu "kdenetwork API Reference"
  • kget
  • kopete
  •   kopete
  •   libkopete
  • krdc
  • krfb

Search



Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal