DataContainer Class Reference

from PyKDE4.plasma import *

Inherits: QObject
Namespace: Plasma

Detailed Description

DataContainer plasma/datacontainer.h <Plasma/DataContainer>

A set of data exported via a DataEngine

Plasma.DataContainer wraps the data exported by a DataEngine implementation, providing a generic wrapper for the data.

A DataContainer may have zero or more associated pieces of data which are keyed by strings. The data itself is stored as QVariants. This allows easy and flexible retrieval of the information associated with this object without writing DataContainer or DataEngine specific code in visualizations.

If you are creating your own DataContainer objects (and are passing them to DataEngine.addSource()), you normally just need to listen to the updateRequested() signal (as well as any other methods you might have of being notified of new data) and call setData() to actually update the data. Then you need to either trigger the scheduleSourcesUpdated signal of the parent DataEngine or call checkForUpdate() on the DataContainer.

You also need to set a suitable name for the source with setObjectName(). See DataEngine.addSource() for more information.

Note that there is normally no need to subclass DataContainer, except as a way of encapsulating the data retreival for a source, since all notifications are done via signals rather than virtual methods.

Signals
	becameUnused (QString source)
	dataUpdated (QString source, {QString:QVariant} data)
	updateRequested (Plasma.DataContainer source)
Methods
	__init__ (self, QObject parent=0)
	checkForUpdate (self)
	checkUsage (self)
	connectVisualization (self, QObject visualization, long pollingInterval, Plasma.IntervalAlignment alignment)
{QString:QVariant}	data (self)
	disconnectVisualization (self, QObject visualization)
	forceImmediateUpdate (self)
Plasma.DataEngine	getDataEngine (self)
bool	isStorageEnabled (self)
bool	needsToBeStored (self)
	removeAllData (self)
	setData (self, QString key, QVariant value)
	setNeedsToBeStored (self, bool store)
	setNeedsUpdate (self, bool update=1)
	setStorageEnabled (self, bool store)
long	timeSinceLastUpdate (self)
bool	visualizationIsConnected (self, QObject visualization)

Signal Documentation

becameUnused	(	QString	source
	)

Emitted when the last visualization is disconnected.

Note that if this source was created by DataEngine.sourceRequestEvent(), it will be deleted by DataEngine once control returns to the event loop after this signal is emitted.

Parameters:

source

the name of the source that became unused

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

dataUpdated	(	QString	source,
		{QString:QVariant}	data
	)

Emitted when the data has been updated, allowing visualizations to reflect the new data.

Note that you should not normally emit this directly. Instead, use checkForUpdate() or the DataEngine.scheduleSourcesUpdated() slot.

Parameters:

	source	the objectName() of the DataContainer (and hence the name of the source) that updated its data
	data	the updated data

Signal syntax:: QObject.connect(source, SIGNAL("dataUpdated(const QString&, const Plasma::DataEngine::Data&)"), target_slot)

updateRequested	(	Plasma.DataContainer	source
	)

Emitted when an update is requested.

If a polling interval was passed connectVisualization(), this signal will be emitted every time the interval expires.

Note that if you create your own DataContainer (and pass it to DataEngine.addSource()), you will need to listen to this signal and refresh the data when it is triggered.

Parameters:

source

the datacontainer the update was requested for. Useful for classes that update the data for several containers.

Signal syntax:: QObject.connect(source, SIGNAL("updateRequested(Plasma::DataContainer*)"), target_slot)

Method Documentation

__init__	(	self,
		QObject	parent=0
	)

Constructs a default DataContainer that has no name or data associated with it

checkForUpdate ( self )

Checks whether any data has changed and, if so, emits dataUpdated().

checkUsage ( self )

Check if the DataContainer is still in use.

If not the signal "becameUnused" will be emitted.

Warning: The DataContainer may be invalid after calling this function, because a listener to becameUnused() may have deleted it.

connectVisualization	(	self,
		QObject	visualization,
		long	pollingInterval,
		Plasma.IntervalAlignment	alignment
	)

Connects an object to this DataContainer.

May be called repeatedly for the same visualization without side effects

Parameters:

	visualization	the object to connect to this DataContainer
	pollingInterval	the time in milliseconds between updates
	alignment	the clock position to align updates to

{QString:QVariant} data ( self )

Returns the data for this DataContainer

disconnectVisualization	(	self,
		QObject	visualization
	)

Disconnects an object from this DataContainer.

Note that if this source was created by DataEngine.sourceRequestEvent(), it will be deleted by DataEngine once control returns to the event loop.

forceImmediateUpdate ( self )

Forces immediate update signals to all visualizations

Since:: 4.4

Plasma.DataEngine getDataEngine ( self )

Returns:: the DataEngine that the DataContainer is a child of.

bool isStorageEnabled ( self )

Returns:: true if the data container has been marked for storage

Since:: 4.6

bool needsToBeStored ( self )

Returns:: true if the data container has been updated, but not stored

removeAllData ( self )

Removes all data currently associated with this source

If you call removeAllData() on a DataContainer, you need to either trigger the scheduleSourcesUpdated() slot for the data engine it belongs to or call checkForUpdate() on the DataContainer.

setData	(	self,
		QString	key,
		QVariant	value
	)

Set a value for a key.

This also marks this source as needing to signal an update.

If you call setData() directly on a DataContainer, you need to either trigger the scheduleSourcesUpdated() slot for the data engine it belongs to or call checkForUpdate() on the DataContainer.

Parameters:

	key	a string used as the key for the data
	value	a QVariant holding the actual data. If a invalid QVariant is passed in and the key currently exists in the data, then the data entry is removed

setNeedsToBeStored	(	self,
		bool	store
	)

sets that the data container needs to be stored or not.

Parameters:

whether

the data container needs to be stored

setNeedsUpdate	(	self,
		bool	update=1
	)

Indicates that the data should be treated as dirty the next time hasUpdates() is called.

This is needed for the case where updateRequested() is triggered but we don't want to update the data immediately because it has just been updated. The second request won't be fulfilled in this case, because we never updated the data and so never called checkForUpdate(). So we claim it needs an update anyway.

setStorageEnabled	(	self,
		bool	store
	)

sets this data container to be automatically stored.

Parameters:

whether

this data container should be stored

Since:: 4.6

long timeSinceLastUpdate ( self )

Returns how long ago, in msecs, that the data in this container was last updated.

This is used by DataEngine to compress updates that happen more quickly than the minimum polling interval by calling setNeedsUpdate() instead of calling updateSourceEvent() immediately.

bool visualizationIsConnected	(	self,
		QObject	visualization
	)

Returns:: true if the visualization is currently connected

DataContainer Class Reference

Detailed Description

Signals

Methods

Signal Documentation

Method Documentation

Modules