workspace/libs/plasma/datacontainer.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_DATACONTAINER_H
  21 #define PLASMA_DATACONTAINER_H
  22
  23 #include <QtCore/QHash>
  24 #include <QtCore/QObject>
  25
  26 #include <plasma/plasma_export.h>
  27 #include <plasma/dataengine.h>
  28
  29 namespace Plasma
  30 {
  31 /**
  32  * @brief A set of data exported via a DataEngine
  33  *
  34  * Plasma::DataContainer wraps the data exported by a DataEngine
  35  * implementation, providing a generic wrapper for the data.
  36  *
  37  * A DataContainer may have zero or more associated pieces of data which
  38  * are keyed by strings. The data itself is stored as QVariants. This allows
  39  * easy and flexible retrieval of the information associated with this object
  40  * without writing DataContainer or DataEngine specific code in visualizations.
  41  **/
  42 class PLASMA_EXPORT DataContainer : public QObject
  43 {
  44     Q_OBJECT
  45
  46     public:
  47         //typedef QHash<QString, DataEngine::SourceDict> Grouping;
  48
  49         /**
  50          * Constructs a default DataContainer, which has no name or data
  51          * associated with it
  52          **/
  53         explicit DataContainer(QObject* parent = 0);
  54         virtual ~DataContainer();
  55
  56         /**
  57          * Returns the data for this DataContainer
  58          **/
  59         const DataEngine::Data data() const;
  60
  61         /**
  62          * Set a value for a key. This also marks this source as needing
  63          * to signal an update. After calling this, a call to checkForUpdate()
  64          * is done by the engine. This allows for batching updates.
  65          *
  66          * @param key a string used as the key for the data
  67          * @param value a QVariant holding the actual data. If a null or invalid
  68          *              QVariant is passed in and the key currently exists in the
  69          *              data, then the data entry is removed
  70          **/
  71         void setData(const QString& key, const QVariant& value);
  72
  73         /**
  74          * Clears all data currently associated with this source
  75          **/
  76         void clearData();
  77
  78         /**
  79          * Checks for whether the data has changed and therefore an update
  80          * signal needs to be emitted.
  81          **/
  82         void checkForUpdate();
  83
  84         /**
  85          * Returns how long ago, in msecs, that the data in this container was last updated
  86          **/
  87         int timeSinceLastUpdate() const;
  88
  89         /**
  90          * @internal
  91          **/
  92         bool hasUpdates() const;
  93
  94         /**
  95          * Indicates that the data should be treated as dirty the next time hasUpdates() is called.
  96          *
  97          * why? because if one SignalRelay times out just after another, the minimum update
  98          * interval stops a real update from being done - but that relay still needs to be given
  99          * data, because it won't have been in the queue and won't have gotten that last update.
 100          * when it checks hasUpdates() we'll lie, and then everything will return to normal.
 101          **/
 102         void setNeedsUpdate(bool update = true);
 103
 104     public Q_SLOTS:
 105         /**
 106          * Check if the DataContainer is still in use.
 107          * If not the signal "unused" will be emitted.
 108          * Warning: The DataContainer may be invalid after calling this function.
 109          */
 110         void checkUsage();
 111
 112         /**
 113          * Connects an object to this DataContainer. May be called repeatedly
 114          * for the same visualization without side effects
 115          *
 116          * @param visualization the object to connect to this DataContainer
 117          * @param updateInterval the time in milliseconds between updates
 118          **/
 119         void connectVisualization(QObject* visualization, uint updateInterval, Plasma::IntervalAlignment alignment);
 120
 121         /**
 122          * Disconnects an object from this DataContainer.
 123          **/
 124         void disconnectVisualization(QObject* visualization);
 125
 126     Q_SIGNALS:
 127         /**
 128          * Emitted when the data has been updated, allowing visualization to
 129          * reflect the new data.
 130          **/
 131         void dataUpdated(const QString& source, const Plasma::DataEngine::Data& data);
 132
 133         /**
 134          * Emitted when this source becomes unused
 135          **/
 136         void unused(const QString& source);
 137
 138         /**
 139          * Emitted when the source, usually due to an internal timer firing,
 140          * requests to be updated.
 141          **/
 142         void requestUpdate(DataContainer *source);
 143
 144     private:
 145         friend class SignalRelay;
 146         class Private;
 147         Private* const d;
 148 };
 149
 150 } // Plasma namespace
 151
 152 #endif // multiple inclusion guard