KDE 4.0 API Reference kopete/libkopete
Kopete::OnlineStatus Class Reference
#include <kopeteonlinestatus.h>
Detailed Description
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 66 of file kopeteonlinestatus.h.
Public Types | |
| enum | StatusType { Unknown = 0, Offline = 10, Connecting = 20, Invisible = 30, Away = 40, Online = 50 } |
| enum | ReservedInternalStatus { AccountOffline = 0x80000001 } |
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 () | |
| StatusType | status () const |
| unsigned | internalStatus () const |
| unsigned | weight () const |
| QStringList | overlayIcons () const |
| QString | description () const |
| Protocol * | protocol () const |
| bool | isDefinitelyOnline () const |
| QPixmap | iconFor (const Contact *contact, int size=16) const |
| QString | mimeSourceFor (const Contact *contact, int size=16) const |
| QPixmap | iconFor (const Account *account, int size=16) const |
| QString | mimeSourceFor (const Account *account, int size=16) const |
| QPixmap | iconFor (const QString &mimeSource) const |
| QPixmap | protocolIcon () const |
| OnlineStatus & | operator= (const OnlineStatus &other) |
| bool | operator== (const OnlineStatus &other) const |
| bool | operator!= (const OnlineStatus &other) const |
| bool | operator> (const OnlineStatus &other) const |
| bool | operator< (const OnlineStatus &other) const |
Static Public Member Functions | |
| static QString | statusTypeToString (OnlineStatus::StatusType status) |
| static OnlineStatus::StatusType | statusStringToType (QString &string) |
Member Enumeration Documentation
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 76 of file kopeteonlinestatus.h.
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 135 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 133 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 73 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::registerOnlineStatus for more info about the categories and options parameters
Definition at line 85 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 99 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 143 of file kopeteonlinestatus.cpp.
| OnlineStatus::~OnlineStatus | ( | ) |
Member Function Documentation
| OnlineStatus::StatusType OnlineStatus::status | ( | ) | const |
| unsigned OnlineStatus::internalStatus | ( | ) | const |
| unsigned OnlineStatus::weight | ( | ) | const |
| QStringList OnlineStatus::overlayIcons | ( | ) | const |
| QString OnlineStatus::description | ( | ) | const |
| Protocol * OnlineStatus::protocol | ( | ) | const |
| bool OnlineStatus::isDefinitelyOnline | ( | ) | const |
- Returns:
trueif this a contact with this status is definitely online,falseif the contact is Offline, Connecting or Unknown.
Definition at line 222 of file kopeteonlinestatus.cpp.
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. size is the size we the icon should be scaled to - 16 is default and so costs nothing
Definition at line 229 of file kopeteonlinestatus.cpp.
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 235 of file kopeteonlinestatus.cpp.
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 248 of file kopeteonlinestatus.cpp.
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 253 of file kopeteonlinestatus.cpp.
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 262 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 267 of file kopeteonlinestatus.cpp.
| OnlineStatus & OnlineStatus::operator= | ( | const OnlineStatus & | other | ) |
| bool OnlineStatus::operator== | ( | const OnlineStatus & | other | ) | const |
Comparison operator.
Returns true if both the protocol and the internal status are identical.
Definition at line 148 of file kopeteonlinestatus.cpp.
| bool OnlineStatus::operator!= | ( | const OnlineStatus & | other | ) | const |
Comparison operator.
This operator works exactly opposite of operator==()
Definition at line 160 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 166 of file kopeteonlinestatus.cpp.
| bool OnlineStatus::operator< | ( | const OnlineStatus & | other | ) | const |
Comparison operator.
This operator works exactly opposite of operator>()
Definition at line 174 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 280 of file kopeteonlinestatus.cpp.
| OnlineStatus::StatusType OnlineStatus::statusStringToType | ( | 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 291 of file kopeteonlinestatus.cpp.
The documentation for this class was generated from the following files:
