DataEngine Class Reference

from PyKDE4.plasma import *

Inherits: QObject
Namespace: Plasma

Detailed Description

DataEngine plasma/dataengine.h <Plasma/DataEngine>

Data provider for plasmoids (Plasma plugins)

This is the base class for DataEngines, which provide access to bodies of data via a common and consistent interface. The common use of a DataEngine is to provide data to a widget for display. This allows a user interface element to show all sorts of data: as long as there is a DataEngine, the data is retrievable.

DataEngines are loaded as plugins on demand and provide zero, one or more data sources which are identified by name. For instance, a network DataEngine might provide a data source for each network interface.

Signals
	sourceAdded (QString source)
	sourceRemoved (QString source)
Methods
	__init__ (self, QObject parent=0, KSharedPtr service=KService.Ptr(0))
	__init__ (self, QObject parent, [QVariant] args)
	addSource (self, Plasma.DataContainer source)
	connectAllSources (self, QObject visualization, long pollingInterval=0, Plasma.IntervalAlignment intervalAlignment=Plasma.NoAlignment)
	connectSource (self, QString source, QObject visualization, long pollingInterval=0, Plasma.IntervalAlignment intervalAlignment=Plasma.NoAlignment)
{QString:Plasma.DataContainer}	containerDict (self)
Plasma.DataContainer	containerForSource (self, QString source)
Plasma.Service	createDefaultService (self, QObject parent=0)
	disconnectSource (self, QString source, QObject visualization)
	forceImmediateUpdateOfAllVisualizations (self)
QString	icon (self)
	init (self)
bool	isEmpty (self)
bool	isValid (self)
long	maxSourceCount (self)
int	minimumPollingInterval (self)
QString	name (self)
Plasma.Package	package (self)
QString	pluginName (self)
{QString:QVariant}	query (self, QString source)
	removeAllData (self, QString source)
	removeAllSources (self)
	removeData (self, QString source, QString key)
	removeSource (self, QString source)
	scheduleSourcesUpdated (self)
Plasma.Service	serviceForSource (self, QString source)
	setData (self, QString source, QVariant value)
	setData (self, QString source, QString key, QVariant value)
	setData (self, QString source, {QString:QVariant} data)
	setDefaultService (self, QString serviceName)
	setIcon (self, QString icon)
	setMaxSourceCount (self, long limit)
	setMinimumPollingInterval (self, int minimumMs)
	setName (self, QString name)
	setPollingInterval (self, long frequency)
	setStorageEnabled (self, QString source, bool store)
	setValid (self, bool valid)
bool	sourceRequestEvent (self, QString source)
QStringList	sources (self)
	timerEvent (self, QTimerEvent event)
	updateAllSources (self)
bool	updateSourceEvent (self, QString source)

Signal Documentation

sourceAdded	(	QString	source
	)

Emitted when a new data source is created

Note that you do not need to emit this yourself unless you are reimplementing sources() and want to advertise that a new source is available (but hasn't been created yet).

Parameters:

source

the name of the new data source

Signal syntax:: QObject.connect(source, SIGNAL("sourceAdded(const QString&)"), target_slot)

sourceRemoved	(	QString	source
	)

Emitted when a data source is removed.

Note that you do not need to emit this yourself unless you have reimplemented sources() and want to signal that a source that was available but was never created is no longer available.

Parameters:

source

the name of the data source that was removed

Signal syntax:: QObject.connect(source, SIGNAL("sourceRemoved(const QString&)"), target_slot)

Method Documentation

__init__	(	self,
		QObject	parent=0,
		KSharedPtr	service=KService.Ptr(0)
	)

Constructor.

Parameters:

	parent	The parent object.
	service	pointer to the service that describes the engine

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

addSource	(	self,
		Plasma.DataContainer	source
	)

Adds an already constructed data source. The DataEngine takes ownership of the DataContainer object. The objectName of the source is used for the source name.

Parameters:

source

the DataContainer to add to the DataEngine

connectAllSources	(	self,
		QObject	visualization,
		long	pollingInterval=0,
		Plasma.IntervalAlignment	intervalAlignment=Plasma.NoAlignment
	)

Connects all currently existing sources to an object for data updates. The object must have a slot with the following signature:

SLOT(dataUpdated(QString,Plasma.DataEngine.Data))

The data is a QHash of QVariants keyed by QString names, allowing one data source to provide sets of related data.

This method may be called multiple times for the same visualization without side-effects. This can be useful to change the pollingInterval.

Note that this method does not automatically connect sources that may appear later on. Connecting and responding to the sourceAdded signal is still required to achieve that.

Parameters:

	visualization	the object to connect the data source to
	pollingInterval	the frequency, in milliseconds, with which to check for updates; a value of 0 (the default) means to update only when there is new data spontaneously generated (e.g. by the engine); any other value results in periodic updates from this source. This value is per-visualization and can be handy for items that require constant updates such as scrolling graphs or clocks. If the data has not changed, no update will be sent.
	intervalAlignment	the number of ms to align the interval to

connectSource	(	self,
		QString	source,
		QObject	visualization,
		long	pollingInterval=0,
		Plasma.IntervalAlignment	intervalAlignment=Plasma.NoAlignment
	)

Connects a source to an object for data updates. The object must have a slot with the following signature:

dataUpdated(const QString &sourceName, const Plasma.DataEngine.Data &data)

The data is a QHash of QVariants keyed by QString names, allowing one data source to provide sets of related data.

Parameters:

	source	the name of the data source
	visualization	the object to connect the data source to
	pollingInterval	the frequency, in milliseconds, with which to check for updates; a value of 0 (the default) means to update only when there is new data spontaneously generated (e.g. by the engine); any other value results in periodic updates from this source. This value is per-visualization and can be handy for items that require constant updates such as scrolling graphs or clocks. If the data has not changed, no update will be sent.
	intervalAlignment	the number of ms to align the interval to

{QString:Plasma.DataContainer} containerDict ( self )

Returns:: the list of active DataContainers.

Plasma.DataContainer containerForSource	(	self,
		QString	source
	)

Retrieves a pointer to the DataContainer for a given source. This method should not be used if possible. An exception is for script engines that can not provide a QMetaObject as required by connectSource for the initial call to dataUpdated. Using this method, such engines can provide their own connectSource API.

Parameters:

source

the name of the source.

Returns:: pointer to a DataContainer, or zero on failure

Plasma.Service createDefaultService	(	self,
		QObject	parent=0
	)

Initializes and returns a new service from the name that was set with setDefaultService. (service name is set internally). Remember to dispose of the Service* when you are finished with it (even if a parent is passed) A DataEngine* is sent to the created service via the QVariantList arguments.

See also:: setDefaultService

Parameters:

the

parent of the object, if any, for the returned service

Returns:: the newly created service

Since:: 4.5

disconnectSource	(	self,
		QString	source,
		QObject	visualization
	)

Disconnects a source from an object that was receiving data updates.

Parameters:

	source	the name of the data source
	visualization	the object to connect the data source to

forceImmediateUpdateOfAllVisualizations ( self )

Forces an immediate update to all connected sources, even those with timeouts that haven't yet expired. This should _only_ be used when there was no data available, e.g. due to network non-availability, and then it becomes available. Normal changes in data values due to calls to updateSource or in the natural progression of the monitored object (e.g. CPU heat) should not result in a call to this method!

Since:: 4.4

QString icon ( self )

Returns:: the name of the icon for this data engine; and empty string is returned if there is no associated icon.

init ( self )

This method is called when the DataEngine is started. When this method is called the DataEngine is fully constructed and ready to be used. This method should be reimplemented by DataEngine subclasses which need to perform a startup routine.

The default implementation does nothing. Reimplementations in subclasses don't need to call this one.

bool isEmpty ( self )

Returns true if the data engine is empty, which is to say that it has no data sources currently.

Returns:: true if the engine has no sources currently

bool isValid ( self )

Returns true if this engine is valid, otherwise returns false

Returns:: true if the engine is valid

long maxSourceCount ( self )

Returns the maximum number of sources this DataEngine will have at any given time.

Returns:: the maximum number of sources; zero means no limit.

int minimumPollingInterval ( self )

Returns:

the minimum time between updates.

See also:: setMinimumPollingInterval

QString name ( self )

Returns the engine name for the DataEngine

Plasma.Package package ( self )

Accessor for the associated Package object if any.

Returns:: the Package object, or 0 if none

QString pluginName ( self )

Returns:: the plugin name for the applet

{QString:QVariant} query	(	self,
		QString	source
	)

Gets the Data associated with a data source.

The data is a QHash of QVariants keyed by QString names, allowing one data source to provide sets of related data.

Parameters:

source

the data source to retrieve the data for

Returns:: the Data associated with the source; if the source doesn't exist an empty data set is returned

removeAllData	(	self,
		QString	source
	)

Removes all the data associated with a data source.

Parameters:

source

the name of the data source

removeAllSources ( self )

Removes all data sources

removeData	(	self,
		QString	source,
		QString	key
	)

Removes a data entry from a source

Parameters:

	source	the name of the data source
	key	the data entry to remove

removeSource	(	self,
		QString	source
	)

Removes a data source.

Parameters:

source

the name of the data source to remove

scheduleSourcesUpdated ( self )

Call this method when you call setData directly on a DataContainer instead of using the DataEngine.setData methods. If this method is not called, no dataUpdated(..) signals will be emitted!

Plasma.Service serviceForSource	(	self,
		QString	source
	)

Parameters:

source

the source to target the Service at

Returns:: a Service that has the source as a destination. The service is parented to the DataEngine, but should be deleted by the caller when finished with it

setData	(	self,
		QString	source,
		QVariant	value
	)

Adds a set of data to a data source. If the source doesn't exist then it is created.

Parameters:

	source	the name of the data source
	data	the data to add to the source

setData	(	self,
		QString	source,
		QString	key,
		QVariant	value
	)

Adds a set of data to a data source. If the source doesn't exist then it is created.

Parameters:

	source	the name of the data source
	data	the data to add to the source

setData	(	self,
		QString	source,
		{QString:QVariant}	data
	)

Adds a set of data to a data source. If the source doesn't exist then it is created.

Parameters:

	source	the name of the data source
	data	the data to add to the source

setDefaultService	(	self,
		QString	serviceName
	)

Should be set if there will be 1 main service. This saves any users of this DataEngine from having to know the service name to load. It is not created until createDefaultService is called.

  DataEngine *engine = dataEngine("foo");
  Service *service = engine->createDefaultService(this);

See also:: createDefaultService

Parameters:

serviceName

the name of the service to load (plugin name)

Since:: 4.5

setIcon	(	self,
		QString	icon
	)

Sets the icon for this data engine

setMaxSourceCount	(	self,
		long	limit
	)

Sets an upper limit on the number of data sources to keep in this engine. If the limit is exceeded, then the oldest data source, as defined by last update, is dropped.

Parameters:

limit

the maximum number of sources to keep active

setMinimumPollingInterval	(	self,
		int	minimumMs
	)

Sets the minimum amount of time, in milliseconds, that must pass between successive updates of data. This can help prevent too many updates happening due to multiple update requests coming in, which can be useful for expensive (time- or resource-wise) update mechanisms.

The default minimumPollingInterval is -1, or "never perform automatic updates"

Parameters:

minimumMs

the minimum time lapse, in milliseconds, between updates. A value less than 0 means to never perform automatic updates, a value of 0 means update immediately on every update request, a value >0 will result in a minimum time lapse being enforced.

setName	(	self,
		QString	name
	)

Sets the engine name for the DataEngine

setPollingInterval	(	self,
		long	frequency
	)

Sets up an internal update tick for all data sources. On every update, updateSourceEvent will be called for each applicable source.

See also:: updateSourceEvent

Parameters:

frequency

the time, in milliseconds, between updates. A value of 0 will stop internally triggered updates.

setStorageEnabled	(	self,
		QString	source,
		bool	store
	)

Sets a source to be stored for easy retrieval when the real source of the data (usually a network connection) is unavailable.

Parameters:

	source	the name of the source
	store	if source should be stored

Since:: 4.6

setValid	(	self,
		bool	valid
	)

Sets whether or not this engine is valid, e.g. can be used. In practice, only the internal fall-back engine, the NullEngine should have need for this.

Parameters:

valid

whether or not the engine is valid

bool sourceRequestEvent	(	self,
		QString	source
	)

When a source that does not currently exist is requested by the consumer, this method is called to give the DataEngine the opportunity to create one.

The name of the data source (e.g. the source parameter passed into setData) must be the same as the name passed to sourceRequestEvent otherwise the requesting visualization may not receive notice of a data update.

If the source can not be populated with data immediately (e.g. due to an asynchronous data acquisition method such as an HTTP request) the source must still be created, even if it is empty. This can be accomplished in these cases with the follow line:

setData(name, DataEngine.Data());

Parameters:

source

the name of the source that has been requested

Returns:: true if a DataContainer was set up, false otherwise

QStringList sources ( self )

Returns:: a list of all the data sources available via this DataEngine Whether these sources are currently available (which is what the default implementation provides) or not is up to the DataEngine to decide.

timerEvent	(	self,
		QTimerEvent	event
	)

Reimplemented from QObject

updateAllSources ( self )

Immediately updates all existing sources when called

bool updateSourceEvent	(	self,
		QString	source
	)

Called by internal updating mechanisms to trigger the engine to refresh the data contained in a given source. Reimplement this method when using facilities such as setPollingInterval.

See also:: setPollingInterval

Parameters:

source

the name of the source that should be updated

Returns:: true if the data was changed, or false if there was no change or if the change will occur later

DataEngine Class Reference

Detailed Description

Signals

Methods

Signal Documentation

Method Documentation

Modules