KDE 4.5 PyKDE API Reference

- KDE's Python API

# 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()));

## Signals
| finished (Plasma.ServiceJob job)
| operationsChanged ()
| serviceReady (Plasma.Service service)
## Methods
| __init__ (self, QObject parent=0)
| __init__ (self, QObject parent, [QVariant] args)
| associateWidget (self, QWidget widget, QString operation)
| associateWidget (self, QGraphicsWidget widget, QString operation)
Plasma.ServiceJob | createJob (self, QString operation, {QString:QVariant} parameters)
QString | destination (self)
| disassociateWidget (self, QWidget widget)
| disassociateWidget (self, QGraphicsWidget widget)
bool | isOperationEnabled (self, QString operation)
QString | name (self)
KConfigGroup | operationDescription (self, QString operationName)
QStringList | operationNames (self)
{QString:QVariant} | parametersFromDescription (self, KConfigGroup description)
| registerOperationsScheme (self)
| setDestination (self, QString destination)
| setName (self, QString name)
| setOperationEnabled (self, QString operation, bool enable)
| setOperationsScheme (self, QIODevice xml)
Plasma.ServiceJob | startOperationCall (self, KConfigGroup description, QObject parent=0)
## Static Methods
Plasma.Service | access (KUrl url, QObject parent=0)
Plasma.Service | load (QString name, QObject parent=0)
Plasma.Service | load (QString name, [QVariant] args, QObject parent=0)

## 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

__init__ | ( | self, |
|  | QObject | parent,
|  | [QVariant] | args
| ) |  |  |

Constructor for plugin loading

associateWidget | ( | self, |
|  | QWidget | 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

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

@arg description the configuration values to turn into the parameter map

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.