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

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

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

Service Class Reference

Detailed Description

Signals

Methods

Static Methods

Method Documentation

Modules