Plasma
Plasma::DataEngine Class Reference
Data provider for plasmoids (Plasma plugins). More...
#include <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 | |
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) |
DataEngine (QObject *parent, const QVariantList &args) | |
DataEngine (QObject *parent=0, KService::Ptr service=KService::Ptr(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 |
Q_INVOKABLE 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 Q_INVOKABLE QStringList | sources () const |
~DataEngine () | |
Protected Slots | |
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 Data &data) |
void | setData (const QString &source, const QString &key, const QVariant &value) |
void | setData (const QString &source, const QVariant &value) |
void | setIcon (const QString &icon) |
void | setMaxSourceCount (uint limit) |
void | setMinimumPollingInterval (int minimumMs) |
void | setName (const QString &name) |
void | setPollingInterval (uint frequency) |
void | setValid (bool valid) |
virtual bool | sourceRequestEvent (const QString &source) |
void | timerEvent (QTimerEvent *event) |
virtual bool | updateSourceEvent (const QString &source) |
Properties | |
QString | icon |
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 57 of file dataengine.h.
Member Typedef Documentation
typedef QHash<QString, QVariant> Plasma::DataEngine::Data |
Definition at line 66 of file dataengine.h.
Definition at line 67 of file dataengine.h.
typedef QHash<QString, DataEngine*> Plasma::DataEngine::Dict |
Definition at line 65 of file dataengine.h.
typedef QHash<QString, DataContainer*> Plasma::DataEngine::SourceDict |
Definition at line 68 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 44 of file dataengine.cpp.
Plasma::DataEngine::DataEngine | ( | QObject * | parent, | |
const QVariantList & | args | |||
) |
Definition at line 51 of file dataengine.cpp.
Plasma::DataEngine::~DataEngine | ( | ) |
Definition at line 58 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 235 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 sigal 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 101 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 82 of file dataengine.cpp.
DataEngine::SourceDict Plasma::DataEngine::containerDict | ( | ) | const [protected] |
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.
- Parameters:
-
source the name of the source.
- Returns:
- pointer to a DataContainer, or zero on failure
Definition at line 118 of file dataengine.cpp.
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 109 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 have the need to perform a startup routine.
Definition at line 142 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 345 of file dataengine.cpp.
bool Plasma::DataEngine::isValid | ( | ) | const |
Returns true if this engine is valid, otherwise returns false.
Definition at line 340 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 264 of file dataengine.cpp.
int Plasma::DataEngine::minimumPollingInterval | ( | ) | const [protected] |
- Returns:
- the minimum time between updates.
- See also:
- setMinimumPollingInterval
Definition at line 278 of file dataengine.cpp.
QString Plasma::DataEngine::name | ( | ) | const |
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 416 of file dataengine.cpp.
QString Plasma::DataEngine::pluginName | ( | ) | const |
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 123 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 217 of file dataengine.cpp.
void Plasma::DataEngine::removeAllSources | ( | ) | [protected] |
Returns the current update frequency.
- See also:
- setPollingInterval 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 pollingInterval(); Removes all data sources
Definition at line 329 of file dataengine.cpp.
Removes a data entry from a source.
- Parameters:
-
source the name of the data source key the data entry to remove
Definition at line 226 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 304 of file dataengine.cpp.
void Plasma::DataEngine::scheduleSourcesUpdated | ( | ) | [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 421 of file dataengine.cpp.
- 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 may be deleted by the caller when finished with it
Definition at line 73 of file dataengine.cpp.
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 195 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 177 of file dataengine.cpp.
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 172 of file dataengine.cpp.
void Plasma::DataEngine::setIcon | ( | const QString & | icon | ) | [protected] |
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 249 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.
- 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 269 of file dataengine.cpp.
void Plasma::DataEngine::setName | ( | const QString & | name | ) | [protected] |
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 283 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 350 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 | ) | [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) 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 153 of file dataengine.cpp.
virtual Q_INVOKABLE 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.
Reimplemented from QObject.
Definition at line 360 of file dataengine.cpp.
void Plasma::DataEngine::updateAllSources | ( | ) | [protected, slot] |
Immediately updates all existing sources when called.
Definition at line 385 of file dataengine.cpp.
bool Plasma::DataEngine::updateSourceEvent | ( | 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 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 162 of file dataengine.cpp.
Property Documentation
QString Plasma::DataEngine::icon [read, write] |
Definition at line 62 of file dataengine.h.
QStringList Plasma::DataEngine::sources [read] |
Definition at line 60 of file dataengine.h.
bool Plasma::DataEngine::valid [read] |
Definition at line 61 of file dataengine.h.
The documentation for this class was generated from the following files: