KDE API Referencekopete/libkopete
#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
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
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.
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.
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.
|
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.
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.
|
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.
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
trueif this a contact with this status is definitely online,falseif the contact is Offline, Connecting or Unknown.
Definition at line 287 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 306 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 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.
|
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.
|
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:
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.
