#include <Plasma/DataEngine>

Inheritance diagram for Plasma::DataEngine:

Public Types
typedef QHash< QString, QVariant >	Data

typedef QHashIterator< QString, QVariant >	DataIterator

typedef QHash< QString, DataEngine * >	Dict

typedef QHash< QString, DataContainer * >	SourceDict

Signals
void	sourceAdded (const QString &source)

void	sourceRemoved (const QString &source)

Public Member Functions
	DataEngine (QObject *parent=0, KService::Ptr service=KService::Ptr(0))

	DataEngine (QObject *parent, const QVariantList &args)

	~DataEngine ()

Q_INVOKABLE void	connectAllSources (QObject *visualization, uint pollingInterval=0, Plasma::IntervalAlignment intervalAlignment=NoAlignment) const

Q_INVOKABLE void	connectSource (const QString &source, QObject *visualization, uint pollingInterval=0, Plasma::IntervalAlignment intervalAlignment=NoAlignment) const

Q_INVOKABLE DataContainer *	containerForSource (const QString &source)

Q_INVOKABLE Service *	createDefaultService (QObject *parent=0)

Q_INVOKABLE void	disconnectSource (const QString &source, QObject *visualization) const

QString	icon () const

virtual void	init ()

bool	isEmpty () const

bool	isValid () const

uint	maxSourceCount () const

QString	name () const

const Package *	package () const

QString	pluginName () const

Q_INVOKABLE DataEngine::Data	query (const QString &source) const

virtual Q_INVOKABLE Service *	serviceForSource (const QString &source)

virtual QStringList	sources () const

Protected Slots
void	forceImmediateUpdateOfAllVisualizations ()

void	removeSource (const QString &source)

void	scheduleSourcesUpdated ()

void	updateAllSources ()

Protected Member Functions
void	addSource (DataContainer *source)

SourceDict	containerDict () const

int	minimumPollingInterval () const

void	removeAllData (const QString &source)

void	removeAllSources ()

void	removeData (const QString &source, const QString &key)

void	setData (const QString &source, const QVariant &value)

void	setData (const QString &source, const QString &key, const QVariant &value)

void	setData (const QString &source, const Data &data)

void	setDefaultService (const QString &serviceName)

void	setIcon (const QString &icon)

void	setMaxSourceCount (uint limit)

void	setMinimumPollingInterval (int minimumMs)

void	setName (const QString &name)

void	setPollingInterval (uint frequency)

void	setStorageEnabled (const QString &source, bool store)

void	setValid (bool valid)

virtual bool	sourceRequestEvent (const QString &source)

void	timerEvent (QTimerEvent *event)

virtual bool	updateSourceEvent (const QString &source)

Properties
QString	icon

QString	name

QStringList	sources

bool	valid

Detailed Description

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.

Definition at line 58 of file dataengine.h.

Member Typedef Documentation

typedef QHash<QString, QVariant> Plasma::DataEngine::Data

Definition at line 68 of file dataengine.h.

typedef QHashIterator<QString, QVariant> Plasma::DataEngine::DataIterator

Definition at line 69 of file dataengine.h.

typedef QHash<QString, DataEngine*> Plasma::DataEngine::Dict

Definition at line 67 of file dataengine.h.

typedef QHash<QString, DataContainer*> Plasma::DataEngine::SourceDict

Definition at line 70 of file dataengine.h.

Constructor & Destructor Documentation

Plasma::DataEngine::DataEngine	(	QObject *	parent = `0`,
		KService::Ptr	service = `KService::Ptr(0)`
	)

explicit

Constructor.

Parameters

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

Definition at line 50 of file dataengine.cpp.

Plasma::DataEngine::DataEngine	(	QObject *	parent,
		const QVariantList &	args
	)

Definition at line 56 of file dataengine.cpp.

Plasma::DataEngine::~DataEngine ( )

Definition at line 62 of file dataengine.cpp.

Member Function Documentation

void Plasma::DataEngine::addSource ( DataContainer * source )

protected

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

Definition at line 247 of file dataengine.cpp.

void Plasma::DataEngine::connectAllSources	(	QObject *	visualization,
		uint	pollingInterval = `0`,
		Plasma::IntervalAlignment	intervalAlignment = `NoAlignment`
	)		const

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

Definition at line 111 of file dataengine.cpp.

void Plasma::DataEngine::connectSource	(	const QString &	source,
		QObject *	visualization,
		uint	pollingInterval = `0`,
		Plasma::IntervalAlignment	intervalAlignment = `NoAlignment`
	)		const

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

Definition at line 89 of file dataengine.cpp.

DataEngine::SourceDict Plasma::DataEngine::containerDict ( ) const

protected

Returns: the list of active DataContainers.

Definition at line 357 of file dataengine.cpp.

DataContainer * Plasma::DataEngine::containerForSource ( const 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

Definition at line 128 of file dataengine.cpp.

Service * Plasma::DataEngine::createDefaultService ( 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

Definition at line 437 of file dataengine.cpp.

void Plasma::DataEngine::disconnectSource	(	const QString &	source,
		QObject *	visualization
	)		const

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

Definition at line 119 of file dataengine.cpp.

void Plasma::DataEngine::forceImmediateUpdateOfAllVisualizations ( )

protectedslot

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

Definition at line 406 of file dataengine.cpp.

QString Plasma::DataEngine::icon ( ) const

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

void Plasma::DataEngine::init ( )

virtual

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.

Definition at line 153 of file dataengine.cpp.

bool Plasma::DataEngine::isEmpty ( ) const

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

Definition at line 347 of file dataengine.cpp.

bool Plasma::DataEngine::isValid ( ) const

Returns true if this engine is valid, otherwise returns false.

Returns: true if the engine is valid

Definition at line 342 of file dataengine.cpp.

uint Plasma::DataEngine::maxSourceCount ( ) const

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

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

Definition at line 277 of file dataengine.cpp.

int Plasma::DataEngine::minimumPollingInterval ( ) const

protected

Returns: the minimum time between updates.

See also: setMinimumPollingInterval

Definition at line 287 of file dataengine.cpp.

QString Plasma::DataEngine::name ( ) const

Returns the engine name for the DataEngine.

const Package * Plasma::DataEngine::package ( ) const

Accessor for the associated Package object if any.

Returns: the Package object, or 0 if none

Definition at line 476 of file dataengine.cpp.

QString Plasma::DataEngine::pluginName ( ) const

Returns: the plugin name for the applet

Definition at line 423 of file dataengine.cpp.

DataEngine::Data Plasma::DataEngine::query ( const QString & source ) const

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

Definition at line 133 of file dataengine.cpp.

void Plasma::DataEngine::removeAllData ( const QString & source )

protected

Removes all the data associated with a data source.

Parameters

source the name of the data source

Definition at line 229 of file dataengine.cpp.

void Plasma::DataEngine::removeAllSources ( )

protected

Removes all data sources.

Definition at line 328 of file dataengine.cpp.

void Plasma::DataEngine::removeData	(	const QString &	source,
		const QString &	key
	)

protected

Removes a data entry from a source.

Parameters

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

Definition at line 238 of file dataengine.cpp.

void Plasma::DataEngine::removeSource ( const QString & source )

protectedslot

Removes a data source.

Parameters

source the name of the data source to remove

Definition at line 302 of file dataengine.cpp.

void Plasma::DataEngine::scheduleSourcesUpdated ( )

protectedslot

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!

Definition at line 481 of file dataengine.cpp.

Service * Plasma::DataEngine::serviceForSource ( const QString & source )

virtual

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

Definition at line 77 of file dataengine.cpp.

void Plasma::DataEngine::setData	(	const QString &	source,
		const QVariant &	value
	)

protected

Sets a value for a data source.

If the source doesn't exist then it is created.

Parameters

source	the name of the data source
value	the data to associated with the source

Definition at line 184 of file dataengine.cpp.

void Plasma::DataEngine::setData	(	const QString &	source,
		const QString &	key,
		const QVariant &	value
	)

protected

Sets a value for a data source.

If the source doesn't exist then it is created.

Parameters

source	the name of the data source
key	the key to use for the data
value	the data to associated with the source

Definition at line 189 of file dataengine.cpp.

void Plasma::DataEngine::setData	(	const QString &	source,
		const Data &	data
	)

protected

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

Definition at line 207 of file dataengine.cpp.

void Plasma::DataEngine::setDefaultService ( const QString & serviceName )

protected

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

Definition at line 432 of file dataengine.cpp.

void Plasma::DataEngine::setIcon ( const QString & icon )

protected

Sets the icon for this data engine.

Definition at line 413 of file dataengine.cpp.

void Plasma::DataEngine::setMaxSourceCount ( uint limit )

protected

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

Definition at line 262 of file dataengine.cpp.

void Plasma::DataEngine::setMinimumPollingInterval ( int minimumMs )

protected

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.

Definition at line 282 of file dataengine.cpp.

void Plasma::DataEngine::setName ( const QString & name )

protected

Sets the engine name for the DataEngine.

Definition at line 495 of file dataengine.cpp.

void Plasma::DataEngine::setPollingInterval ( uint frequency )

protected

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.

Definition at line 292 of file dataengine.cpp.

void Plasma::DataEngine::setStorageEnabled	(	const QString &	source,
		bool	store
	)

protected

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

Definition at line 501 of file dataengine.cpp.

void Plasma::DataEngine::setValid ( bool valid )

protected

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

Definition at line 352 of file dataengine.cpp.

void Plasma::DataEngine::sourceAdded ( const QString & source )

signal

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

void Plasma::DataEngine::sourceRemoved ( const QString & source )

signal

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

bool Plasma::DataEngine::sourceRequestEvent ( const QString & source )

protectedvirtual

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

Definition at line 165 of file dataengine.cpp.

virtual QStringList Plasma::DataEngine::sources ( ) const

virtual

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.

void Plasma::DataEngine::timerEvent ( QTimerEvent * event )

protected

Reimplemented from QObject.

Definition at line 362 of file dataengine.cpp.

void Plasma::DataEngine::updateAllSources ( )

protectedslot

Immediately updates all existing sources when called.

Definition at line 394 of file dataengine.cpp.

bool Plasma::DataEngine::updateSourceEvent ( const QString & source )

protectedvirtual

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

Definition at line 174 of file dataengine.cpp.

Property Documentation

QString Plasma::DataEngine::icon

readwrite

Definition at line 63 of file dataengine.h.

QString Plasma::DataEngine::name

read

Definition at line 64 of file dataengine.h.

QStringList Plasma::DataEngine::sources

read

Definition at line 61 of file dataengine.h.

bool Plasma::DataEngine::valid

read

Definition at line 62 of file dataengine.h.

The documentation for this class was generated from the following files:

Plasma

Public Types

Signals

Public Member Functions

Protected Slots

Protected Member Functions

Properties

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Property Documentation

Plasma

kdelibs API Reference

Search