From 479a9778304e4a2771ba167d4d15faae9c6013b6 Mon Sep 17 00:00:00 2001 From: "Aaron J. Seigo" Date: Wed, 23 May 2007 06:38:44 +0000 Subject: [PATCH] * api documentation * void addSource(DataSource* source): allows adding of DataSources directly; useful for more complex engines where setData would be inneficient and clumsy or just not powerful enough svn path=/trunk/KDE/kdebase/workspace/plasma/lib/; revision=667584 --- dataengine.cpp | 14 +++++- dataengine.h | 118 +++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 128 insertions(+), 4 deletions(-) diff --git a/dataengine.cpp b/dataengine.cpp index c1b0fe915..80aa19a6b 100644 --- a/dataengine.cpp +++ b/dataengine.cpp @@ -49,9 +49,9 @@ class DataEngine::Private << ": could not find DataSource " << sourceName << ", creating" << endl; DataSource* s = new DataSource(engine); - emit engine->newDataSource(sourceName); s->setName(sourceName); sources.insert(sourceName, s); + emit engine->newDataSource(sourceName); return s; } @@ -125,6 +125,18 @@ void DataEngine::setData(const QString& source, const QString& key, const QVaria d->queueUpdate(); } +void DataEngine::addSource(DataSource* source) +{ + DataSource::Dict::const_iterator it = d->sources.find(source->name()); + if (it != d->sources.constEnd()) { + kDebug() << "source named \"" << source->name() << "\" already exists." << endl; + return; + } + + d->sources.insert(source->name(), source); + emit newDataSource(source->name()); +} + /* Plasma::DataSource* DataEngine::createDataSource(const QString& source, const QString& domain) { diff --git a/dataengine.h b/dataengine.h index 8fb62e2c0..73b53b0ab 100644 --- a/dataengine.h +++ b/dataengine.h @@ -29,6 +29,22 @@ namespace Plasma { +class DataSource; + +/** + * @class DataEngine + * @brief 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 one more data + * sources which are identified by name. For instance, a network DataEngine + * might provide a data source for each network interface. + **/ class PLASMA_EXPORT DataEngine : public QObject { Q_OBJECT @@ -38,32 +54,128 @@ class PLASMA_EXPORT DataEngine : public QObject typedef QHash Data; typedef QHashIterator DataIterator; - DataEngine(QObject* parent); + /** + * Default constructor. + * + * @param parent The parent object. + **/ + explicit DataEngine(QObject* parent); virtual ~DataEngine(); + /** + * @return a list of all the data sources currently available via this + * DataEngine + **/ virtual QStringList dataSources(); + + /** + * Connects a source to an object for data updates. The object must + * have a slot with the following signature: + * + * SLOT(updated(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. + * + * @param source the name of the data source + * @param visualization the object to connect the data source to + **/ void connectSource(const QString& source, QObject* visualization); + + /** + * 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. + * + * @param source the data source to retrieve the data for + * @return the Data associated with the source; if the source doesn't + * exist an empty data set is returned + **/ Data query(const QString& source); + /** + * Reference counting method. Calling this method increases the count + * by one. + **/ void ref(); + + /** + * Reference counting method. Calling this method decreases the count + * by one. + **/ void deref(); + + /** + * Reference counting method. Used to determine if this DataEngine is + * used. + * @return true if the reference count is zero + **/ bool isUsed(); - Q_SIGNALS: + /** + * Emitted when a new data source is created + * @param source the name of the new data source + **/ void newDataSource(const QString& source); + + /** + * Emitted when a data source is removed. + * @param source the name of the data source that was removed + **/ void dataSourceRemoved(const QString& source); protected: + /** + * 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. + **/ virtual void init(); + + /** + * Sets a value for a data source. If the source + * doesn't exist then it is created. + * + * @param source the name of the data source + * @param value the data to associated with the source + **/ void setData(const QString& source, const QVariant& value); + + /** + * Sets a value for a data source. If the source + * doesn't exist then it is created. + * + * @param source the name of the data source + * @param key the key to use for the data + * @param value the data to associated with the source + **/ void setData(const QString& source, const QString& key, const QVariant& value); + + /** + * Adds an already constructed data source. The DataEngine takes + * ownership of the DataSource object. + * @param source the DataSource to add to the DataEngine + **/ + void addSource(DataSource* source); + /* void createDataSource(const QString& source, const QString& domain = QString());*/ + + /** + * Removes a data source. + * @param source the name of the data source to remove + **/ void removeDataSource(const QString& source); + + /** + * Removes all data sources + **/ void clearAllDataSources(); - protected Q_SLOTS: + private Q_SLOTS: void checkForUpdates(); private: