workspace/libs/plasma/dataengine.h

   1 /*
   2  *   Copyright 2006-2007 Aaron Seigo <aseigo@kde.org>
   3  *
   4  *   This program is free software; you can redistribute it and/or modify
   5  *   it under the terms of the GNU Library General Public License as
   6  *   published by the Free Software Foundation; either version 2, or
   7  *   (at your option) any later version.
   8  *
   9  *   This program is distributed in the hope that it will be useful,
  10  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  *   GNU General Public License for more details
  13  *
  14  *   You should have received a copy of the GNU Library General Public
  15  *   License along with this program; if not, write to the
  16  *   Free Software Foundation, Inc.,
  17  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  18  */
  19
  20 #ifndef PLASMA_DATAENGINE_H
  21 #define PLASMA_DATAENGINE_H
  22
  23 #include <QtCore/QHash>
  24 #include <QtCore/QObject>
  25 #include <QtCore/QStringList>
  26
  27 #include <KGenericFactory>
  28 #include <KService>
  29
  30 #include <plasma/plasma_export.h>
  31 #include <plasma/plasma.h>
  32
  33 namespace Plasma
  34 {
  35
  36 class DataContainer;
  37 class DataEngineScript;
  38
  39 /**
  40  * @class DataEngine
  41  * @brief Data provider for plasmoids (Plasma plugins)
  42  *
  43  * This is the base class for DataEngines, which provide access to bodies of
  44  * data via a common and consistent interface. The common use of a DataEngine
  45  * is to provide data to a widget for display. This allows a user interface
  46  * element to show all sorts of data: as long as there is a DataEngine, the
  47  * data is retrievable.
  48  *
  49  * DataEngines are loaded as plugins on demand and provide zero, one or more
  50  * data sources which are identified by name. For instance, a network
  51  * DataEngine might provide a data source for each network interface.
  52  **/
  53 class PLASMA_EXPORT DataEngine : public QObject
  54 {
  55     friend class DataEngineScript;
  56     Q_OBJECT
  57     Q_PROPERTY( QStringList sources READ sources )
  58     Q_PROPERTY( bool valid READ isValid )
  59     Q_PROPERTY( QString icon READ icon WRITE setIcon )
  60
  61     public:
  62         typedef QHash<QString, DataEngine*> Dict;
  63         typedef QHash<QString, QVariant> Data;
  64         typedef QHashIterator<QString, QVariant> DataIterator;
  65         typedef QHash<QString, DataContainer*> SourceDict;
  66
  67         /**
  68          * Constructor.
  69          *
  70          * @param parent The parent object.
  71          * @param service pointer to the service that describes the engine
  72          **/
  73         explicit DataEngine(QObject* parent = 0, KService::Ptr service = KService::Ptr(0));
  74         DataEngine(QObject* parent, const QVariantList& args);
  75         virtual ~DataEngine();
  76
  77         /**
  78          * @return a list of all the data sources available via this DataEngine
  79          *         Whether these sources are currently available (which is what
  80          *         the default implementation provides) or not is up to the
  81          *         DataEngine to decide.
  82          **/
  83         virtual QStringList sources() const;
  84
  85         /**
  86          * Returns the engine name for the DataEngine
  87          */
  88         QString engineName() const;
  89
  90         /**
  91          * Connects a source to an object for data updates. The object must
  92          * have a slot with the following signature:
  93          *
  94          * dataUpdated(const QString &sourceName, const Plasma::DataEngine::Data &data)
  95          *
  96          * The data is a QHash of QVariants keyed by QString names, allowing
  97          * one data source to provide sets of related data.
  98          *
  99          * @param source the name of the data source
 100          * @param visualization the object to connect the data source to
 101          * @param updateInterval the frequency, in milliseconds, with which to signal updates;
 102          *                        a value of 0 (the default) means to update only
 103          *                        when there is new data spontaneously generated
 104          *                        (e.g. by the engine); any other value results in
 105          *                        periodic updates from this source. This value is
 106          *                        per-visualization and can be handy for items that require
 107          *                        constant updates such as scrolling graphs or clocks.
 108          * @param intervalAlignedTo the number of ms to aling the interval to
 109          **/
 110         Q_INVOKABLE void connectSource(const QString& source, QObject* visualization,
 111                                        uint updateInterval = 0,
 112                                        Plasma::IntervalAlignment intervalAlignment = NoAlignment) const;
 113
 114         /**
 115          * Connects all sources to an object for data updates. The object must
 116          * have a slot with the following signature:
 117          *
 118          * SLOT(dataUpdated(QString, Plasma::DataEngine::Data))
 119          *
 120          * The data is a QHash of QVariants keyed by QString names, allowing
 121          * one data source to provide sets of related data.
 122          *
 123          * This method may be called multiple times for the same visualization
 124          * without side-effects. This can be useful to change the updateInterval.
 125          *
 126          * @param visualization the object to connect the data source to
 127          * @param updateInterval the frequency, in milliseconds, with which to signal updates;
 128          *                        a value of 0 (the default) means to update only
 129          *                        when there is new data spontaneously generated
 130          *                        (e.g. by the engine); any other value results in
 131          *                        periodic updates from this source. This value is
 132          *                        per-visualization and can be handy for items that require
 133          *                        constant updates such as scrolling graphs or clocks.
 134          **/
 135         Q_INVOKABLE void connectAllSources(QObject* viualization, uint updateInterval = 0,
 136                                            Plasma::IntervalAlignment intervalAlignment = NoAlignment) const;
 137
 138         /**
 139          * Disconnects a source to an object that was receiving data updates.
 140          *
 141          * @param source the name of the data source
 142          * @param visualization the object to connect the data source to
 143          **/
 144         Q_INVOKABLE void disconnectSource(const QString& source, QObject* visualization) const;
 145
 146         /**
 147          * Retrevies a pointer to the DataContainer for a given source. This method
 148          * should not be used if possible. An exception is for script engines that
 149          * can not provide a QMetaObject as required by connectSource for the initial
 150          * call to dataUpdated. Using this method, such engines can provide their own
 151          * connectSource API.
 152          *
 153          * @arg source the name of the source.
 154          * @return pointer to a DataContainer, or zero on failure
 155          **/
 156         Q_INVOKABLE DataContainer* containerForSource(const QString &source);
 157
 158         /**
 159          * Gets the Data associated with a data source.
 160          *
 161          * The data is a QHash of QVariants keyed by QString names, allowing
 162          * one data source to provide sets of related data.
 163          *
 164          * @param source the data source to retrieve the data for
 165          * @return the Data associated with the source; if the source doesn't
 166          *         exist an empty data set is returned
 167          **/
 168         Q_INVOKABLE DataEngine::Data query(const QString& source) const;
 169
 170         /**
 171          * Reference counting method. Calling this method increases the count
 172          * by one.
 173          **/
 174         void ref();
 175
 176         /**
 177          * Reference counting method. Calling this method decreases the count
 178          * by one.
 179          **/
 180         void deref();
 181
 182         /**
 183          * Reference counting method. Used to determine if this DataEngine is
 184          * used.
 185          * @return true if the reference count is non-zero
 186          **/
 187         bool isUsed() const;
 188
 189         /**
 190          * Returns true if this engine is valid, otherwise returns false
 191          **/
 192         bool isValid() const;
 193
 194         /**
 195          * Returns true if the data engine is empty, which is to say that it has no
 196          * data sources currently.
 197          */
 198         bool isEmpty() const;
 199
 200         /**
 201          * Sets the icon for this data engine
 202          **/
 203         void setIcon(const QString& icon);
 204
 205         /**
 206          * @return the name of the icon for this data engine; and empty string
 207          *         is returned if there is no associated icon.
 208          **/
 209         QString icon() const;
 210
 211     Q_SIGNALS:
 212         /**
 213          * Emitted when a new data source is created
 214          * @param source the name of the new data source
 215          **/
 216         void newSource(const QString& source);
 217
 218         /**
 219          * Emitted when a data source is removed.
 220          * @param source the name of the data source that was removed
 221          **/
 222         void sourceRemoved(const QString& source);
 223
 224     protected:
 225         /**
 226          * This method is called when the DataEngine is started. When this
 227          * method is called the DataEngine is fully constructed and ready to be
 228          * used. This method should be reimplemented by DataEngine subclasses
 229          * which have the need to perform a startup routine.
 230          **/
 231         virtual void init();
 232
 233         /**
 234          * When a source that does not currently exist is requested by the
 235          * consumer, this method is called to give the DataEngine the
 236          * opportunity to create one.
 237          *
 238          * The name of the data source (e.g. the source parameter passed into
 239          * setData) it must be the same as the name passed to sourceRequested
 240          * otherwise the requesting visualization may not receive notice of a
 241          * data update.
 242          *
 243          * If the source can not be populated with data immediately (e.g. due to
 244          * an asynchronous data acquisition method such as an HTTP request)
 245          * the source must still be created, even if it is empty. This can
 246          * be accomplished in these cases with the follow line:
 247          *
 248          *      setData(name, DataEngine::Data());
 249          *
 250          * @return true if a DataContainer was set up, false otherwise
 251          */
 252         virtual bool sourceRequested(const QString &name);
 253
 254         /**
 255          * Called by internal updating mechanisms to trigger the engine
 256          * to refresh the data contained in a given source. Reimplement this
 257          * method when using facilities such as setUpdateInterval.
 258          * @see setUpdateInterval
 259          *
 260          * @param source the name of the source that should be updated
 261          * @return true if the data was changed, or false if there was no
 262          *         change or if the change will occur later
 263          **/
 264         virtual bool updateSource(const QString& source);
 265
 266         /**
 267          * Sets a value for a data source. If the source
 268          * doesn't exist then it is created.
 269          *
 270          * @param source the name of the data source
 271          * @param value the data to associated with the source
 272          **/
 273         void setData(const QString &source, const QVariant &value);
 274
 275         /**
 276          * Sets a value for a data source. If the source
 277          * doesn't exist then it is created.
 278          *
 279          * @param source the name of the data source
 280          * @param key the key to use for the data
 281          * @param value the data to associated with the source
 282          **/
 283         void setData(const QString& source, const QString& key, const QVariant& value);
 284
 285         /**
 286          * Adds a set of data to a data source. If the source
 287          * doesn't exist then it is created.
 288          *
 289          * @param source the name of the data source
 290          * @param data the data to add to the source
 291          **/
 292         void setData(const QString &source, const Data &data);
 293
 294         /**
 295          * Clears all the data associated with a data source.
 296          *
 297          * @param source the name of the data source
 298          **/
 299         void clearData(const QString& source);
 300
 301         /**
 302          * Removes a data entry from a source
 303          *
 304          * @param source the name of the data source
 305          * @param key the data entry to remove
 306          **/
 307         void removeData(const QString& source, const QString& key);
 308
 309         /**
 310          * Adds an already constructed data source. The DataEngine takes
 311          * ownership of the DataContainer object.
 312          * @param source the DataContainer to add to the DataEngine
 313          **/
 314         void addSource(DataContainer* source);
 315
 316         /**
 317          * Sets an upper limit on the number of data sources to keep in this engine.
 318          * If the limit is exceeded, then the oldest data source, as defined by last
 319          * update, is dropped.
 320          *
 321          * @param limit the maximum number of sources to keep active
 322          **/
 323         void setSourceLimit(uint limit);
 324
 325         /**
 326          * Sets the minimum amount of time, in milliseconds, that must pass between
 327          * successive updates of data. This can help prevent too many updates happening
 328          * due to multiple update requests coming in, which can be useful for
 329          * expensive (time- or resource-wise) update mechanisms.
 330          *
 331          * @arg minimumMs the minimum time lapse, in milliseconds, between updates.
 332          *                A value less than 0 means to never perform automatic updates,
 333          *                a value of 0 means update immediately on every update request,
 334          *                a value >0 will result in a minimum time lapse being enforced.
 335          **/
 336         void setMinimumUpdateInterval(int minimumMs);
 337
 338         /**
 339          * @return the minimum time between updates. @see setMinimumupdateInterval
 340          **/
 341         int minimumUpdateInterval() const;
 342
 343         /**
 344          * Sets up an internal update tick for all data sources. On every update,
 345          * updateSource will be called for each applicable source.
 346          * @see updateSource
 347          *
 348          * @param frequency the time, in milliseconds, between updates. A value of 0
 349          *                  will stop internally triggered updates.
 350          **/
 351         void setUpdateInterval(uint frequency);
 352
 353         /**
 354          * Returns the current update frequency.
 355          * @see setUpdateInterval
 356          NOTE: This is not implemented to prevent having to store the value internally.
 357                When there is a good use case for needing access to this value, we can
 358                add another member to the Private class and add this method.
 359         uint updateInterval();
 360          **/
 361
 362         /**
 363          * Removes all data sources
 364          **/
 365         void clearSources();
 366
 367         /**
 368          * Sets whether or not this engine is valid, e.g. can be used.
 369          * In practice, only the internal fall-back engine, the NullEngine
 370          * should have need for this.
 371          *
 372          * @param valid whether or not the engine is valid
 373          **/
 374         void setValid(bool valid);
 375
 376         /**
 377          * @return the list of active DataContainers.
 378          */
 379         SourceDict sourceDict() const;
 380
 381         /**
 382          * Reimplemented from QObject
 383          **/
 384         void timerEvent(QTimerEvent *event);
 385
 386     protected Q_SLOTS:
 387         /**
 388          * Call this method when you call setData directly on a DataContainer instead
 389          * of using the DataEngine::setData methods.
 390          * If this method is not called, no dataUpdated(..) signals will be emitted!
 391          */
 392         void checkForUpdates();
 393
 394         /**
 395          * Removes a data source.
 396          * @param source the name of the data source to remove
 397          **/
 398         void removeSource(const QString& source);
 399
 400         /**
 401          * @internal
 402          **/
 403         void internalUpdateSource(DataContainer* source);
 404
 405     private:
 406         class Private;
 407         Private* const d;
 408 };
 409
 410 } // Plasma namespace
 411
 412 #define K_EXPORT_PLASMA_DATAENGINE(libname, classname) \
 413 K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) \
 414 K_EXPORT_PLUGIN(factory("plasma_engine_" #libname))
 415 #endif // multiple inclusion guard
 416