KDE 4.2 PyKDE API Reference

- KDE's Python API

# Service Class Reference

`from PyKDE4.plasma import *`

Inherits: QObject
Namespace: Plasma

## Detailed Description

Abstract class:
  This class can be used as a base class for new classes, but can not be instantiated directly.

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

## Signals

| finished (Plasma.ServiceJob job)
| operationsChanged ()

## Methods

| __init__ (self, QObject parent=0)
| __init__ (self, QObject parent, QVariantList args)
| associateWidget (self, QWidget widget, QString operation)
| associateWidget (self, QGraphicsWidget widget, QString operation)
ServiceJob | createJob (self, QString operation, QMap<QString,QVariant> parameters)
QString | destination (self)
| disassociateWidget (self, QWidget widget)
| disassociateWidget (self, QGraphicsWidget widget)
| finished (self, Plasma.ServiceJob job)
bool | isOperationEnabled (self, QString operation)
QString | name (self)
KConfigGroup | operationDescription (self, QString operationName)
QStringList | operationNames (self)
| operationsChanged (self)
| registerOperationsScheme (self)
| setDestination (self, QString destination)
| setName (self, QString name)
| setOperationEnabled (self, QString operation, bool enable)
| setOperationsScheme (self, QIODevice xml)
ServiceJob | startOperationCall (self, KConfigGroup description, QObject parent=0)

## Static Methods

Plasma.Service | load (QString name, QObject parent=0)

## Method Documentation

__init__ | ( | self, |
|  | QObject | parent=0
| ) |  |  |

Default constructor

@arg parent the parent object for this service

__init__ | ( | self, |
|  | QObject | parent,
|  | QVariantList | 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 QWidget 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

ServiceJob createJob | ( | self, |
|  | QString | operation,
|  | QMap<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 QWidget 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.

finished | ( | self, |
|  | Plasma.ServiceJob | job
| ) |  |  |

Emitted when a job associated with this Service completes its task

Signal syntax:
  `QObject.connect(source, SIGNAL("finished(ServiceJob*)"), target_slot)`

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

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.

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

operationsChanged | ( |  | self ) |

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)`

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.

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