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 class DataContainerPrivate;
  33
  34 /**
  35  * @class DataContainer plasma/datacontainer.h <Plasma/DataContainer>
  36  *
  37  * @brief A set of data exported via a DataEngine
  38  *
  39  * Plasma::DataContainer wraps the data exported by a DataEngine
  40  * implementation, providing a generic wrapper for the data.
  41  *
  42  * A DataContainer may have zero or more associated pieces of data which
  43  * are keyed by strings. The data itself is stored as QVariants. This allows
  44  * easy and flexible retrieval of the information associated with this object
  45  * without writing DataContainer or DataEngine specific code in visualizations.
  46  *
  47  * If you are creating your own DataContainer objects (and are passing them to
  48  * DataEngine::addSource()), you normally just need to listen to the
  49  * updateRequested() signal (as well as any other methods you might have of
  50  * being notified of new data) and call setData() to actually update the data.
  51  * Then you need to either trigger the scheduleSourcesUpdated signal of the
  52  * parent DataEngine or call checkForUpdate() on the DataContainer.
  53  *
  54  * You also need to set a suitable name for the source with setObjectName().
  55  * See DataEngine::addSource() for more information.
  56  *
  57  * Note that there is normally no need to subclass DataContainer, except as
  58  * a way of encapsulating the data retreival for a source, since all notifications
  59  * are done via signals rather than virtual methods.
  60  **/
  61 class PLASMA_EXPORT DataContainer : public QObject
  62 {
  63     friend class DataEngine;
  64     friend class DataEnginePrivate;
  65     Q_OBJECT
  66
  67     public:
  68         /**
  69          * Constructs a default DataContainer that has no name or data
  70          * associated with it
  71          **/
  72         explicit DataContainer(QObject *parent = 0);
  73         virtual ~DataContainer();
  74
  75         /**
  76          * Returns the data for this DataContainer
  77          **/
  78         const DataEngine::Data data() const;
  79
  80         /**
  81          * Set a value for a key.
  82          *
  83          * This also marks this source as needing to signal an update.
  84          *
  85          * If you call setData() directly on a DataContainer, you need to
  86          * either trigger the scheduleSourcesUpdated() slot for the
  87          * data engine it belongs to or call checkForUpdate() on the
  88          * DataContainer.
  89          *
  90          * @param key a string used as the key for the data
  91          * @param value a QVariant holding the actual data. If a null or invalid
  92          *              QVariant is passed in and the key currently exists in the
  93          *              data, then the data entry is removed
  94          **/
  95         void setData(const QString &key, const QVariant &value);
  96
  97         /**
  98          * Removes all data currently associated with this source
  99          *
 100          * If you call removeAllData() on a DataContainer, you need to
 101          * either trigger the scheduleSourcesUpdated() slot for the
 102          * data engine it belongs to or call checkForUpdate() on the
 103          * DataContainer.
 104          **/
 105         void removeAllData();
 106
 107         /**
 108          * @return true if the visualization is currently connected
 109          */
 110         bool visualizationIsConnected(QObject *visualization) const;
 111
 112         /**
 113          * Connects an object to this DataContainer.
 114          *
 115          * May be called repeatedly for the same visualization without
 116          * side effects
 117          *
 118          * @param visualization the object to connect to this DataContainer
 119          * @param pollingInterval the time in milliseconds between updates
 120          * @param alignment the clock position to align updates to
 121          **/
 122         void connectVisualization(QObject *visualization, uint pollingInterval,
 123                                   Plasma::IntervalAlignment alignment);
 124
 125     public Q_SLOTS:
 126         /**
 127          * Disconnects an object from this DataContainer.
 128          *
 129          * Note that if this source was created by DataEngine::sourceRequestEvent(),
 130          * it will be deleted by DataEngine once control returns to the event loop.
 131          **/
 132         void disconnectVisualization(QObject *visualization);
 133
 134     Q_SIGNALS:
 135         /**
 136          * Emitted when the data has been updated, allowing visualizations to
 137          * reflect the new data.
 138          *
 139          * Note that you should not normally emit this directly.  Instead, use
 140          * checkForUpdates() or the DataEngine::scheduleSourcesUpdated() slot.
 141          *
 142          * @param source the objectName() of the DataContainer (and hence the name
 143          *               of the source) that updated its data
 144          * @param data   the updated data
 145          **/
 146         void dataUpdated(const QString &source, const Plasma::DataEngine::Data &data);
 147
 148         /**
 149          * Emitted when the last visualization is disconnected.
 150          *
 151          * Note that if this source was created by DataEngine::sourceRequestEvent(),
 152          * it will be deleted by DataEngine once control returns to the event loop
 153          * after this signal is emitted.
 154          *
 155          * @param source  the name of the source that became unused
 156          **/
 157         void becameUnused(const QString &source);
 158
 159         /**
 160          * Emitted when an update is requested.
 161          *
 162          * If a polling interval was passed connectVisualization(), this signal
 163          * will be emitted every time the interval expires.
 164          *
 165          * Note that if you create your own DataContainer (and pass it to
 166          * DataEngine::addSource()), you will need to listen to this signal
 167          * and refresh the data when it is triggered.
 168          *
 169          * @param source  the datacontainer the update was requested for.  Useful
 170          *                for classes that update the data for several containers.
 171          **/
 172         void updateRequested(DataContainer *source);
 173
 174     protected:
 175         /**
 176          * Checks whether any data has changed and, if so, emits dataUpdated().
 177          **/
 178         void checkForUpdate();
 179
 180         /**
 181          * Returns how long ago, in msecs, that the data in this container was last updated.
 182          *
 183          * This is used by DataEngine to compress updates that happen more quickly than the
 184          * minimum polling interval by calling setNeedsUpdate() instead of calling
 185          * updateSourceEvent() immediately.
 186          **/
 187         uint timeSinceLastUpdate() const;
 188
 189         /**
 190          * Indicates that the data should be treated as dirty the next time hasUpdates() is called.
 191          *
 192          * This is needed for the case where updateRequested() is triggered but we don't want to
 193          * update the data immediately because it has just been updated.  The second request won't
 194          * be fulfilled in this case, because we never updated the data and so never called
 195          * checkForUpdate().  So we claim it needs an update anyway.
 196          **/
 197         void setNeedsUpdate(bool update = true);
 198
 199     protected Q_SLOTS:
 200         /**
 201          * Check if the DataContainer is still in use.
 202          *
 203          * If not the signal "becameUnused" will be emitted.
 204          *
 205          * Warning: The DataContainer may be invalid after calling this function, because a listener
 206          * to becameUnused() may have deleted it.
 207          **/
 208         void checkUsage();
 209
 210     private:
 211         friend class SignalRelay;
 212         DataContainerPrivate *const d;
 213 };
 214
 215 } // Plasma namespace
 216
 217 #endif // multiple inclusion guard