• Skip to content
  • Skip to link menu
KDE 4.0 API Reference
  • KDE API Reference
  • API Reference
  • Sitemap
  • Contact Us
 

libplasma

Plasma::DataEngine

Plasma::DataEngine Class Reference

#include <dataengine.h>

Inheritance diagram for Plasma::DataEngine:

Inheritance graph
[legend]

List of all members.

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 51 of file dataengine.h.


Public Types

typedef QHash< QString,
DataEngine * > 		Dict
typedef QHash< QString, QVariant > Data
typedef QHashIterator< QString,
QVariant > 		DataIterator
typedef QHash< QString,
DataContainer * > 		SourceDict

Signals

void newSource (const QString &source)
void sourceRemoved (const QString &source)

Public Member Functions

 DataEngine (QObject *parent=0)
virtual ~DataEngine ()
virtual QStringList sources () const
Q_INVOKABLE void connectSource (const QString &source, QObject *visualization, uint updateInterval=0, Plasma::IntervalAlignment intervalAlignment=NoAlignment) const
Q_INVOKABLE void connectAllSources (QObject *viualization, uint updateInterval=0, Plasma::IntervalAlignment intervalAlignment=NoAlignment) const
Q_INVOKABLE void disconnectSource (const QString &source, QObject *visualization) const
Q_INVOKABLE DataContainer * containerForSource (const QString &source)
Q_INVOKABLE DataEngine::Data query (const QString &source) const
void ref ()
void deref ()
bool isUsed () const
bool isValid () const
bool isEmpty () const
void setIcon (const QString &icon)
QString icon () const

Protected Slots

void checkForUpdates ()
void removeSource (const QString &source)
void startInit ()
void internalUpdateSource (DataContainer *source)

Protected Member Functions

virtual void init ()
virtual bool sourceRequested (const QString &name)
virtual bool updateSource (const QString &source)
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 clearData (const QString &source)
void removeData (const QString &source, const QString &key)
void addSource (DataContainer *source)
void setSourceLimit (uint limit)
void setMinimumUpdateInterval (int minimumMs)
int minimumUpdateInterval () const
void setUpdateInterval (uint frequency)
void clearSources ()
void setValid (bool valid)
SourceDict sourceDict () const
void timerEvent (QTimerEvent *event)

Properties

QStringList sources
bool valid
QString icon

Member Typedef Documentation

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

Definition at line 59 of file dataengine.h.

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

Definition at line 60 of file dataengine.h.

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

Definition at line 61 of file dataengine.h.

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

Definition at line 62 of file dataengine.h.

Constructor & Destructor Documentation

Plasma::DataEngine::DataEngine ( QObject *  parent = 0  )  [explicit]

Default constructor.

Parameters:
parent The parent object.

Definition at line 173 of file dataengine.cpp.

Plasma::DataEngine::~DataEngine (  )  [virtual]

Definition at line 183 of file dataengine.cpp.

Member Function Documentation

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::connectSource ( const QString &  source,
QObject *  visualization,
uint  updateInterval = 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
updateInterval the frequency, in milliseconds, with which to signal 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.
intervalAlignedTo the number of ms to aling the interval to

Definition at line 194 of file dataengine.cpp.

void Plasma::DataEngine::connectAllSources ( QObject *  viualization,
uint  updateInterval = 0,
Plasma::IntervalAlignment  intervalAlignment = NoAlignment 
) const

Connects all 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 updateInterval.

Parameters:
visualization the object to connect the data source to
updateInterval the frequency, in milliseconds, with which to signal 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.

Definition at line 210 of file dataengine.cpp.

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

Disconnects a source to 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 218 of file dataengine.cpp.

DataContainer * Plasma::DataEngine::containerForSource ( const QString &  source  ) 

Retrevies 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.

  • source the name of the source.
    Returns:
    pointer to a DataContainer, or zero on failure

Definition at line 227 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 232 of file dataengine.cpp.

void Plasma::DataEngine::ref (  ) 

Reference counting method.

Calling this method increases the count by one.

Definition at line 410 of file dataengine.cpp.

void Plasma::DataEngine::deref (  ) 

Reference counting method.

Calling this method decreases the count by one.

Definition at line 415 of file dataengine.cpp.

bool Plasma::DataEngine::isUsed (  )  const

Reference counting method.

Used to determine if this DataEngine is used.

Returns:
true if the reference count is non-zero

Definition at line 420 of file dataengine.cpp.

bool Plasma::DataEngine::isValid (  )  const

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

Definition at line 425 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.

Definition at line 430 of file dataengine.cpp.

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

Sets the icon for this data engine.

Definition at line 472 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::newSource ( const QString &  source  )  [signal]

Emitted when a new data source is created.

Parameters:
source the name of the new data source

void Plasma::DataEngine::sourceRemoved ( const QString &  source  )  [signal]

Emitted when a data source is removed.

Parameters:
source the name of the data source that was removed

void Plasma::DataEngine::init (  )  [protected, 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 have the need to perform a startup routine.

Definition at line 268 of file dataengine.cpp.

bool Plasma::DataEngine::sourceRequested ( const QString &  name  )  [protected, virtual]

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) it must be the same as the name passed to sourceRequested 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());

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

Definition at line 275 of file dataengine.cpp.

bool Plasma::DataEngine::updateSource ( const QString &  source  )  [protected, virtual]

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 setUpdateInterval.

See also:
setUpdateInterval
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 281 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 288 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 293 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 300 of file dataengine.cpp.

void Plasma::DataEngine::clearData ( const QString &  source  )  [protected]

Clears all the data associated with a data source.

Parameters:
source the name of the data source

Definition at line 312 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 321 of file dataengine.cpp.

void Plasma::DataEngine::addSource ( DataContainer *  source  )  [protected]

Adds an already constructed data source.

The DataEngine takes ownership of the DataContainer object.

Parameters:
source the DataContainer to add to the DataEngine

Definition at line 330 of file dataengine.cpp.

void Plasma::DataEngine::setSourceLimit ( 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 342 of file dataengine.cpp.

void Plasma::DataEngine::setMinimumUpdateInterval ( 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.

  • 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 357 of file dataengine.cpp.

int Plasma::DataEngine::minimumUpdateInterval (  )  const [protected]

Returns:
the minimum time between updates.

See also:
setMinimumupdateInterval

Definition at line 362 of file dataengine.cpp.

void Plasma::DataEngine::setUpdateInterval ( uint  frequency  )  [protected]

Sets up an internal update tick for all data sources.

On every update, updateSource will be called for each applicable source.

See also:
updateSource
Parameters:
frequency the time, in milliseconds, between updates. A value of 0 will stop internally triggered updates.

Definition at line 367 of file dataengine.cpp.

void Plasma::DataEngine::clearSources (  )  [protected]

Returns the current update frequency.

See also:
setUpdateInterval NOTE: This is not implemented to prevent having to store the value internally. When there is a good use case for needing access to this value, we can add another member to the Private class and add this method. uint updateInterval(); Removes all data sources

Definition at line 399 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 435 of file dataengine.cpp.

DataEngine::SourceDict Plasma::DataEngine::sourceDict (  )  const [protected]

Returns:
the list of active DataContainers.

Definition at line 440 of file dataengine.cpp.

void Plasma::DataEngine::timerEvent ( QTimerEvent *  event  )  [protected]

Reimplemented from QObject.

Reimplemented from QObject.

Definition at line 445 of file dataengine.cpp.

void Plasma::DataEngine::checkForUpdates (  )  [protected, slot]

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 482 of file dataengine.cpp.

void Plasma::DataEngine::removeSource ( const QString &  source  )  [protected, slot]

Removes a data source.

Parameters:
source the name of the data source to remove

Definition at line 388 of file dataengine.cpp.

void Plasma::DataEngine::startInit (  )  [protected, slot]

Definition at line 245 of file dataengine.cpp.

void Plasma::DataEngine::internalUpdateSource ( DataContainer *  source  )  [protected, slot]

Definition at line 250 of file dataengine.cpp.

Property Documentation

QStringList Plasma::DataEngine::sources [read]

Definition at line 54 of file dataengine.h.

bool Plasma::DataEngine::valid [read]

Definition at line 55 of file dataengine.h.

QString Plasma::DataEngine::icon [read, write]

Definition at line 56 of file dataengine.h.

The documentation for this class was generated from the following files:
  • dataengine.h
  • dataengine.cpp

libplasma

Skip menu "libplasma"
  • Main Page
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

API Reference

Skip menu "API Reference"
  • KWin
  •   KWin Libraries
  • Libraries
  •   libkworkspace
  •   libplasma
  • Plasma
  •   Animators
  •   Applets
  •   Engines
  • Solid Modules
Generated for API Reference by doxygen 1.5.4
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal