Plasma::DataEngine

Search for usage in LXR

#include <Plasma/DataEngine>

Inheritance diagram for Plasma::DataEngine:

Public Types

typedef QMap< QString, QVariantData
 
typedef QMapIterator< QString, QVariantDataIterator
 
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 (const KPluginInfo &plugin, QObject *parent=nullptr)
 
 DataEngine (const KPluginMetaData &plugin, QObject *parent=nullptr)
 
 DataEngine (QObject *parent=nullptr, const QVariantList &args=QVariantList())
 
Q_INVOKABLE void connectAllSources (QObject *visualization, uint pollingInterval=0, Plasma::Types::IntervalAlignment intervalAlignment=Types::NoAlignment) const
 
Q_INVOKABLE void connectSource (const QString &source, QObject *visualization, uint pollingInterval=0, Plasma::Types::IntervalAlignment intervalAlignment=Types::NoAlignment) const
 
Q_INVOKABLE DataContainercontainerForSource (const QString &source)
 
Q_INVOKABLE void disconnectSource (const QString &source, QObject *visualization) const
 
bool isEmpty () const
 
bool isValid () const
 
KPluginMetaData metadata () const
 
QAbstractItemModelmodelForSource (const QString &source)
 
Package package () const
 
KPluginInfo pluginInfo () const
 
virtual Q_INVOKABLE ServiceserviceForSource (const QString &source)
 
virtual QStringList sources () const
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
bool blockSignals (bool block)
 
const QObjectListchildren () const const
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method) const const
 
bool disconnect (const QObject *receiver, const char *method) const const
 
void dumpObjectInfo ()
 
void dumpObjectInfo () const const
 
void dumpObjectTree ()
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_DISABLE_COPY (Class)
 
 Q_DISABLE_COPY_MOVE (Class)
 
 Q_DISABLE_MOVE (Class)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_NAMESPACE Q_NAMESPACE
 
 Q_NAMESPACE_EXPORT (EXPORT_MACRO)
 
 Q_OBJECT Q_OBJECT
 
 Q_PROPERTY (...)
 
 Q_REVISION Q_REVISION
 
 Q_SET_OBJECT_NAME (Object)
 
 Q_SIGNAL Q_SIGNAL
 
 Q_SIGNALS Q_SIGNALS
 
 Q_SLOT Q_SLOT
 
 Q_SLOTS Q_SLOTS
 
qFindChild (const QObject *obj, const QString &name)
 
QList< T > qFindChildren (const QObject *obj, const QRegExp &regExp)
 
QList< T > qFindChildren (const QObject *obj, const QString &name)
 
qobject_cast (const QObject *object)
 
qobject_cast (QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
 
QThreadthread () const const
 

Protected Slots

void forceImmediateUpdateOfAllVisualizations ()
 
void removeSource (const QString &source)
 
void updateAllSources ()
 

Protected Member Functions

void addSource (DataContainer *source)
 
QHash< QString, DataContainer * > 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 QString &key, const QVariant &value)
 
void setData (const QString &source, const QVariant &value)
 
void setData (const QString &source, const QVariantMap &data)
 
void setMinimumPollingInterval (int minimumMs)
 
void setModel (const QString &source, QAbstractItemModel *model)
 
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) override
 
virtual bool updateSourceEvent (const QString &source)
 
- Protected Member Functions inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
bool isSignalConnected (const QMetaMethod &signal) const const
 
int receivers (const char *signal) const const
 
QObjectsender () const const
 
int senderSignalIndex () const const
 

Additional Inherited Members

- Properties inherited from QObject
 objectName
 
- Static Public Member Functions inherited from QObject
QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
bool disconnect (const QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 
- Public Attributes inherited from QObject
typedef QObjectList
 

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

Constructor & Destructor Documentation

◆ DataEngine() [1/2]

Plasma::DataEngine::DataEngine ( const KPluginInfo plugin,
QObject parent = nullptr 
)
explicit

Constructor.

Parameters
parentThe parent object.
pluginplugin info that describes the engine
Deprecated:
since 5.67

Definition at line 37 of file dataengine.cpp.

◆ DataEngine() [2/2]

Plasma::DataEngine::DataEngine ( const KPluginMetaData plugin,
QObject parent = nullptr 
)
explicit

Constructor.

Parameters
parentThe parent object.
pluginmetadata that describes the engine
Since
5.67

Definition at line 43 of file dataengine.cpp.

Member Function Documentation

◆ addSource()

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
sourcethe DataContainer to add to the DataEngine

Definition at line 257 of file dataengine.cpp.

◆ connectAllSources()

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

Connects all currently existing sources to an object for data updates.

The object must have a slot with the following signature:

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

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
visualizationthe object to connect the data source to
pollingIntervalthe 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.
intervalAlignmentthe number of ms to align the interval to

Definition at line 128 of file dataengine.cpp.

◆ connectSource()

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

Connects a source to an object for data updates.

The object must have a slot with the following signature:

void 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
sourcethe name of the data source
visualizationthe object to connect the data source to
pollingIntervalthe 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.
intervalAlignmentthe number of ms to align the interval to

Definition at line 109 of file dataengine.cpp.

◆ containerDict()

QHash< QString, DataContainer * > Plasma::DataEngine::containerDict ( ) const
protected
Returns
the list of active DataContainers.

Definition at line 343 of file dataengine.cpp.

◆ containerForSource()

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
sourcethe name of the source.
Returns
pointer to a DataContainer, or zero on failure

Definition at line 144 of file dataengine.cpp.

◆ disconnectSource()

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

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

Parameters
sourcethe name of the data source
visualizationthe object to connect the data source to

Definition at line 135 of file dataengine.cpp.

◆ forceImmediateUpdateOfAllVisualizations

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

◆ isEmpty()

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

◆ isValid()

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

◆ metadata()

KPluginMetaData Plasma::DataEngine::metadata ( ) const
Returns
description of the plugin that implements this DataEngine
Since
5.67

Definition at line 104 of file dataengine.cpp.

◆ minimumPollingInterval()

int Plasma::DataEngine::minimumPollingInterval ( ) const
protected
Returns
the minimum time between updates.
See also
setMinimumPollingInterval

Definition at line 278 of file dataengine.cpp.

◆ modelForSource()

QAbstractItemModel * Plasma::DataEngine::modelForSource ( const QString source)
Returns
The model associated to a source if any. The ownership of the model stays with the DataContainer. Returns 0 if there isn't any model associated or if the source doesn't exists.

Definition at line 246 of file dataengine.cpp.

◆ package()

Package Plasma::DataEngine::package ( ) const

Accessor for the associated Package object if any.

Returns
the Package object, or 0 if none

Definition at line 403 of file dataengine.cpp.

◆ pluginInfo()

KPluginInfo Plasma::DataEngine::pluginInfo ( ) const
Returns
description of the plugin that implements this DataEngine
Deprecated:
since 5.67, use metadata

Definition at line 98 of file dataengine.cpp.

◆ removeAllData()

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

Removes all the data associated with a data source.

Parameters
sourcethe name of the data source

Definition at line 213 of file dataengine.cpp.

◆ removeAllSources()

void Plasma::DataEngine::removeAllSources ( )
protected

Removes all data sources.

Definition at line 309 of file dataengine.cpp.

◆ removeData()

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

Removes a data entry from a source.

Parameters
sourcethe name of the data source
keythe data entry to remove

Definition at line 222 of file dataengine.cpp.

◆ removeSource

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

Removes a data source.

Parameters
sourcethe name of the data source to remove

Definition at line 293 of file dataengine.cpp.

◆ serviceForSource()

Service * Plasma::DataEngine::serviceForSource ( const QString source)
virtual
Parameters
sourcethe 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 85 of file dataengine.cpp.

◆ setData() [1/3]

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
sourcethe name of the data source
keythe key to use for the data
valuethe data to associated with the source

Definition at line 173 of file dataengine.cpp.

◆ setData() [2/3]

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
sourcethe name of the data source
valuethe data to associated with the source

Definition at line 168 of file dataengine.cpp.

◆ setData() [3/3]

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

Adds a set of data to a data source.

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

Parameters
sourcethe name of the data source
datathe data to add to the source

Definition at line 191 of file dataengine.cpp.

◆ setMinimumPollingInterval()

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

◆ setModel()

void Plasma::DataEngine::setModel ( const QString source,
QAbstractItemModel model 
)
protected

Associates a model to a data source.

If the source doesn't exist then it is created. The source will have the key "HasModel" to easily indicate there is a model present.

The ownership of the model is transferred to the DataContainer, so the model will be deleted when a new one is set or when the DataContainer itself is deleted. As the DataContainer, it will be deleted when there won't be any visualization associated to this source.

Parameters
sourcethe name of the data source
modelthe model instance

Definition at line 231 of file dataengine.cpp.

◆ setPollingInterval()

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
frequencythe time, in milliseconds, between updates. A value of 0 will stop internally triggered updates.

Definition at line 283 of file dataengine.cpp.

◆ setStorageEnabled()

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
sourcethe name of the source
storeif source should be stored
Since
4.6

Definition at line 409 of file dataengine.cpp.

◆ setValid()

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
validwhether or not the engine is valid

Definition at line 338 of file dataengine.cpp.

◆ sourceAdded

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
sourcethe name of the new data source

◆ sourceRemoved

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
sourcethe name of the data source that was removed

◆ sourceRequestEvent()

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
sourcethe name of the source that has been requested
Returns
true if a DataContainer was set up, false otherwise

Definition at line 149 of file dataengine.cpp.

◆ sources()

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.

Definition at line 76 of file dataengine.cpp.

◆ timerEvent()

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

Reimplemented from QObject.

Reimplemented from QObject.

Definition at line 348 of file dataengine.cpp.

◆ updateAllSources

void Plasma::DataEngine::updateAllSources ( )
protectedslot

Immediately updates all existing sources when called.

Definition at line 380 of file dataengine.cpp.

◆ updateSourceEvent()

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


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Sep 26 2023 04:05:57 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.