2 * Copyright 2006-2007 Aaron Seigo <aseigo@kde.org>
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.
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
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.
20 #ifndef PLASMA_DATACONTAINER_H
21 #define PLASMA_DATACONTAINER_H
23 #include <QtCore/QHash>
24 #include <QtCore/QObject>
26 #include <plasma/plasma_export.h>
27 #include <plasma/dataengine.h>
32 * @brief A set of data exported via a DataEngine
34 * Plasma::DataContainer wraps the data exported by a DataEngine
35 * implementation, providing a generic wrapper for the data.
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.
42 class PLASMA_EXPORT DataContainer
: public QObject
47 //typedef QHash<QString, DataEngine::SourceDict> Grouping;
50 * Constructs a default DataContainer, which has no name or data
53 explicit DataContainer(QObject
* parent
= 0);
54 virtual ~DataContainer();
57 * Returns the data for this DataContainer
59 const DataEngine::Data
data() const;
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.
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
71 void setData(const QString
& key
, const QVariant
& value
);
74 * Clears all data currently associated with this source
79 * Checks for whether the data has changed and therefore an update
80 * signal needs to be emitted.
82 void checkForUpdate();
85 * Returns how long ago, in msecs, that the data in this container was last updated
87 int timeSinceLastUpdate() const;
92 bool hasUpdates() const;
95 * Indicates that the data should be treated as dirty the next time hasUpdates() is called.
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.
102 void setNeedsUpdate(bool update
= true);
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.
113 * Connects an object to this DataContainer. May be called repeatedly
114 * for the same visualization without side effects
116 * @param visualization the object to connect to this DataContainer
117 * @param updateInterval the time in milliseconds between updates
119 void connectVisualization(QObject
* visualization
, uint updateInterval
, Plasma::IntervalAlignment alignment
);
122 * Disconnects an object from this DataContainer.
124 void disconnectVisualization(QObject
* visualization
);
128 * Emitted when the data has been updated, allowing visualization to
129 * reflect the new data.
131 void dataUpdated(const QString
& source
, const Plasma::DataEngine::Data
& data
);
134 * Emitted when this source becomes unused
136 void unused(const QString
& source
);
139 * Emitted when the source, usually due to an internal timer firing,
140 * requests to be updated.
142 void requestUpdate(DataContainer
*source
);
145 friend class SignalRelay
;
150 } // Plasma namespace
152 #endif // multiple inclusion guard