KDE 4.5 PyKDE API Reference
Service Class Reference
from PyKDE4.plasma import *
Inherits: QObject
Namespace: Plasma
Detailed Description
Service plasma/service.h <Plasma/Service>
This class provides a generic API for write access to settings or services.
Plasma.Service allows interaction with a "destination", the definition of which depends on the Service itself. For a network settings Service this might be a profile name ("Home", "Office", "Road Warrior") while a web based Service this might be a username ("aseigo", "stranger65").
A Service provides one or more operations, each of which provides some sort of interaction with the destination. Operations are described using config XML which is used to create a KConfig object with one group per operation. The group names are used as the operation names, and the defined items in the group are the parameters available to be set when using that operation.
A service is started with a KConfigGroup (representing a ready to be serviced operation) and automatically deletes itself after completion and signaling success or failure. See KJob for more information on this part of the process.
Services may either be loaded "stand alone" from plugins, or from a DataEngine by passing in a source name to be used as the destination.
Sample use might look like:
Plasma.DataEngine *twitter = dataEngine("twitter");
Plasma.Service *service = twitter.serviceForSource("aseigo");
KConfigGroup op = service->operationDescription("update");
op.writeEntry("tweet", "Hacking on plasma!");
Plasma.ServiceJob *job = service->startOperationCall(op);
connect(job, SIGNAL(finished(KJob*)), this, SLOT(jobCompeted()));
Please remember, the service needs to be deleted when it will no longer be used. This can be done manually or by these (perhaps easier) alternatives:
If it is needed throughout the lifetime of the object:
service->setParent(this);
If the service will not be used after just one operation call, use:
connect(job, SIGNAL(finished(KJob*)), service, SLOT(deleteLater()));
Signal Documentation
| finished | ( | Plasma.ServiceJob | job | |
| ) |
Emitted when a job associated with this Service completes its task
- Signal syntax:
QObject.connect(source, SIGNAL("finished(Plasma::ServiceJob*)"), target_slot)
| operationsChanged | ( | ) |
Emitted when the Service's operations change. For example, a media player service may change what operations are available in response to the state of the player.
- Signal syntax:
QObject.connect(source, SIGNAL("operationsChanged()"), target_slot)
| serviceReady | ( | Plasma.Service | service | |
| ) |
Emitted when this service is ready for use
- Signal syntax:
QObject.connect(source, SIGNAL("serviceReady(Plasma::Service*)"), target_slot)
Method Documentation
| __init__ | ( | self, | ||
| QObject | parent=0 | |||
| ) |
Default constructor
@arg parent the parent object for this service
Assoicates a widget with an operation, which allows the service to automatically manage, for example, the enabled state of a widget.
This will remove any previous associations the widget had with operations on this engine.
- Parameters:
-
widget the QGraphicsItem to associate with the service operation the operation to associate the widget with
| associateWidget | ( | self, | ||
| QGraphicsWidget | widget, | |||
| QString | operation | |||
| ) |
Assoicates a widget with an operation, which allows the service to automatically manage, for example, the enabled state of a widget.
This will remove any previous associations the widget had with operations on this engine.
- Parameters:
-
widget the QGraphicsItem to associate with the service operation the operation to associate the widget with
| Plasma.ServiceJob createJob | ( | self, | ||
| QString | operation, | |||
| {QString:QVariant} | parameters | |||
| ) |
- Abstract method:
- This method is abstract and can be overridden but not called directly.
Called when a job should be created by the Service.
- Parameters:
-
operation which operation to work on parameters the parameters set by the user for the operation
- Returns:
- a ServiceJob that can be started and monitored by the consumer
| QString destination | ( | self ) |
- Returns:
- the target destination, if any, that this service is associated with
| disassociateWidget | ( | self, | ||
| QWidget | widget | |||
| ) |
Disassociates a widget if it has been associated with an operation on this service.
This will not change the enabled state of the widget.
- Parameters:
-
widget the QGraphicsWidget to disassociate.
| disassociateWidget | ( | self, | ||
| QGraphicsWidget | widget | |||
| ) |
Disassociates a widget if it has been associated with an operation on this service.
This will not change the enabled state of the widget.
- Parameters:
-
widget the QGraphicsWidget to disassociate.
| bool isOperationEnabled | ( | self, | ||
| QString | operation | |||
| ) |
Query to find if an operation is enabled or not.
- Parameters:
-
operation the name of the operation to check
- Returns:
- true if the operation is enabled, false otherwise
| QString name | ( | self ) |
The name of this service
| KConfigGroup operationDescription | ( | self, | ||
| QString | operationName | |||
| ) |
Retrieves the parameters for a given operation
- Parameters:
-
operationName the operation to retrieve parameters for
- Returns:
- KConfigGroup containing the parameters
| QStringList operationNames | ( | self ) |
- Returns:
- the possible operations for this profile
| {QString:QVariant} parametersFromDescription | ( | self, | ||
| KConfigGroup | description | |||
| ) |
- Returns:
- a parameter map for the given description
- Since:
- 4.4
| registerOperationsScheme | ( | self ) |
By default this is based on the file in plasma/services/name.operations, but can be reimplented to use a different mechanism.
It should result in a call to setOperationsScheme(QIODevice *);
| setDestination | ( | self, | ||
| QString | destination | |||
| ) |
Sets the destination for this Service to operate on
@arg destination specific to each Service, this sets which target or address for ServiceJobs to operate on
| setName | ( | self, | ||
| QString | name | |||
| ) |
Sets the name of the Service; useful for Services not loaded from plugins, which use the plugin name for this.
@arg name the name to use for this service
| setOperationEnabled | ( | self, | ||
| QString | operation, | |||
| bool | enable | |||
| ) |
Enables a given service by name
- Parameters:
-
operation the name of the operation to enable or disable enable true if the operation should be enabld, false if disabled
| setOperationsScheme | ( | self, | ||
| QIODevice | xml | |||
| ) |
Sets the XML used to define the operation schema for this Service.
| Plasma.ServiceJob startOperationCall | ( | self, | ||
| KConfigGroup | description, | |||
| QObject | parent=0 | |||
| ) |
Called to create a ServiceJob which is associated with a given operation and parameter set.
- Returns:
- a started ServiceJob; the consumer may connect to relevant signals before returning to the event loop
Static Method Documentation
| Plasma.Service access | ( | KUrl | url, | |
| QObject | parent=0 | |||
| ) |
Used to access a service from an url. Always check for the signal serviceReady() that fires when this service is actually ready for use.
| Plasma.Service load | ( | QString | name, | |
| QObject | parent=0 | |||
| ) |
Used to load a given service from a plugin.
- Parameters:
-
name the plugin name of the service to load parent the parent object, if any, for the service
- Returns:
- a Service object, guaranteed to be not null.
| Plasma.Service load | ( | QString | name, | |
| [QVariant] | args, | |||
| QObject | parent=0 | |||
| ) |
Used to load a given service from a plugin.
- Parameters:
-
name the plugin name of the service to load parent the parent object, if any, for the service
- Returns:
- a Service object, guaranteed to be not null.
