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_DATAENGINE_H
21 #define PLASMA_DATAENGINE_H
23 #include <QtCore/QHash>
24 #include <QtCore/QObject>
25 #include <QtCore/QStringList>
27 #include <kgenericfactory.h>
30 #include <plasma/version.h>
31 #include <plasma/plasma.h>
37 class DataEngineScript
;
40 class DataEnginePrivate
;
43 * @class DataEngine plasma/dataengine.h <Plasma/DataEngine>
45 * @short Data provider for plasmoids (Plasma plugins)
47 * This is the base class for DataEngines, which provide access to bodies of
48 * data via a common and consistent interface. The common use of a DataEngine
49 * is to provide data to a widget for display. This allows a user interface
50 * element to show all sorts of data: as long as there is a DataEngine, the
51 * data is retrievable.
53 * DataEngines are loaded as plugins on demand and provide zero, one or more
54 * data sources which are identified by name. For instance, a network
55 * DataEngine might provide a data source for each network interface.
57 class PLASMA_EXPORT DataEngine
: public QObject
60 Q_PROPERTY(QStringList sources READ sources
)
61 Q_PROPERTY(bool valid READ isValid
)
62 Q_PROPERTY(QString icon READ icon WRITE setIcon
)
65 typedef QHash
<QString
, DataEngine
*> Dict
;
66 typedef QHash
<QString
, QVariant
> Data
;
67 typedef QHashIterator
<QString
, QVariant
> DataIterator
;
68 typedef QHash
<QString
, DataContainer
*> SourceDict
;
73 * @param parent The parent object.
74 * @param service pointer to the service that describes the engine
76 explicit DataEngine(QObject
*parent
= 0, KService::Ptr service
= KService::Ptr(0));
77 DataEngine(QObject
*parent
, const QVariantList
&args
);
81 * This method is called when the DataEngine is started. When this
82 * method is called the DataEngine is fully constructed and ready to be
83 * used. This method should be reimplemented by DataEngine subclasses
84 * which have the need to perform a startup routine.
89 * @return a list of all the data sources available via this DataEngine
90 * Whether these sources are currently available (which is what
91 * the default implementation provides) or not is up to the
92 * DataEngine to decide.
94 Q_INVOKABLE
virtual QStringList
sources() const;
97 * @param source the source to target the Service at
98 * @return a Service that has the source as a destination. The service
99 * is parented to the DataEngine, but may be deleted by the
100 * caller when finished with it
102 Q_INVOKABLE
virtual Service
*serviceForSource(const QString
&source
);
105 * Returns the engine name for the DataEngine
107 Q_INVOKABLE QString
name() const;
110 * Connects a source to an object for data updates. The object must
111 * have a slot with the following signature:
113 * dataUpdated(const QString &sourceName, const Plasma::DataEngine::Data &data)
115 * The data is a QHash of QVariants keyed by QString names, allowing
116 * one data source to provide sets of related data.
118 * @param source the name of the data source
119 * @param visualization the object to connect the data source to
120 * @param pollingInterval the frequency, in milliseconds, with which to check for updates;
121 * a value of 0 (the default) means to update only
122 * when there is new data spontaneously generated
123 * (e.g. by the engine); any other value results in
124 * periodic updates from this source. This value is
125 * per-visualization and can be handy for items that require
126 * constant updates such as scrolling graphs or clocks.
127 * If the data has not changed, no update will be sent.
128 * @param intervalAlignment the number of ms to align the interval to
130 Q_INVOKABLE
void connectSource(
131 const QString
&source
, QObject
*visualization
,
132 uint pollingInterval
= 0,
133 Plasma::IntervalAlignment intervalAlignment
= NoAlignment
) const;
136 * Connects all currently existing sources to an object for data updates.
137 * The object must have a slot with the following signature:
139 * SLOT(dataUpdated(QString,Plasma::DataEngine::Data))
141 * The data is a QHash of QVariants keyed by QString names, allowing
142 * one data source to provide sets of related data.
144 * This method may be called multiple times for the same visualization
145 * without side-effects. This can be useful to change the pollingInterval.
147 * Note that this method does not automatically connect sources that
148 * may appear later on. Connecting and responding to the sourceAdded sigal
149 * is still required to achieve that.
151 * @param visualization the object to connect the data source to
152 * @param pollingInterval the frequency, in milliseconds, with which to check for updates;
153 * a value of 0 (the default) means to update only
154 * when there is new data spontaneously generated
155 * (e.g. by the engine); any other value results in
156 * periodic updates from this source. This value is
157 * per-visualization and can be handy for items that require
158 * constant updates such as scrolling graphs or clocks.
159 * If the data has not changed, no update will be sent.
160 * @param intervalAlignment the number of ms to align the interval to
162 Q_INVOKABLE
void connectAllSources(QObject
*visualization
, uint pollingInterval
= 0,
163 Plasma::IntervalAlignment intervalAlignment
= NoAlignment
) const;
166 * Disconnects a source to an object that was receiving data updates.
168 * @param source the name of the data source
169 * @param visualization the object to connect the data source to
171 Q_INVOKABLE
void disconnectSource(const QString
&source
, QObject
*visualization
) const;
174 * Retrevies a pointer to the DataContainer for a given source. This method
175 * should not be used if possible. An exception is for script engines that
176 * can not provide a QMetaObject as required by connectSource for the initial
177 * call to dataUpdated. Using this method, such engines can provide their own
180 * @param source the name of the source.
181 * @return pointer to a DataContainer, or zero on failure
183 Q_INVOKABLE DataContainer
*containerForSource(const QString
&source
);
186 * Gets the Data associated with a data source.
188 * The data is a QHash of QVariants keyed by QString names, allowing
189 * one data source to provide sets of related data.
191 * @param source the data source to retrieve the data for
192 * @return the Data associated with the source; if the source doesn't
193 * exist an empty data set is returned
195 Q_INVOKABLE
DataEngine::Data
query(const QString
&source
) const;
198 * Returns true if this engine is valid, otherwise returns false
200 bool isValid() const;
203 * Returns true if the data engine is empty, which is to say that it has no
204 * data sources currently.
206 bool isEmpty() const;
209 * Returns the maximum number of sources this DataEngine will have
212 * @return the maximum number of sources; zero means no limit.
214 uint
maxSourceCount() const;
217 * @return the name of the icon for this data engine; and empty string
218 * is returned if there is no associated icon.
220 QString
icon() const;
223 * Accessor for the associated Package object if any.
225 * @return the Package object, or 0 if none
227 const Package
*package() const;
230 * Returns the plugin name for the applet
232 QString
pluginName() const;
237 * Emitted when a new data source is created
239 * Note that you do not need to emit this yourself unless
240 * you are reimplementing sources() and want to advertise
241 * that a new source is available (but hasn't been created
244 * @param source the name of the new data source
246 void sourceAdded(const QString
&source
);
249 * Emitted when a data source is removed.
251 * Note that you do not need to emit this yourself unless
252 * you have reimplemented sources() and want to signal that
253 * a source that was available but was never created is no
256 * @param source the name of the data source that was removed
258 void sourceRemoved(const QString
&source
);
262 * When a source that does not currently exist is requested by the
263 * consumer, this method is called to give the DataEngine the
264 * opportunity to create one.
266 * The name of the data source (e.g. the source parameter passed into
267 * setData) must be the same as the name passed to sourceRequestEvent
268 * otherwise the requesting visualization may not receive notice of a
271 * If the source can not be populated with data immediately (e.g. due to
272 * an asynchronous data acquisition method such as an HTTP request)
273 * the source must still be created, even if it is empty. This can
274 * be accomplished in these cases with the follow line:
276 * setData(name, DataEngine::Data());
278 * @param source the name of the source that has been requested
279 * @return true if a DataContainer was set up, false otherwise
281 virtual bool sourceRequestEvent(const QString
&source
);
284 * Called by internal updating mechanisms to trigger the engine
285 * to refresh the data contained in a given source. Reimplement this
286 * method when using facilities such as setPollingInterval.
287 * @see setPollingInterval
289 * @param source the name of the source that should be updated
290 * @return true if the data was changed, or false if there was no
291 * change or if the change will occur later
293 virtual bool updateSourceEvent(const QString
&source
);
296 * Sets a value for a data source. If the source
297 * doesn't exist then it is created.
299 * @param source the name of the data source
300 * @param value the data to associated with the source
302 void setData(const QString
&source
, const QVariant
&value
);
305 * Sets a value for a data source. If the source
306 * doesn't exist then it is created.
308 * @param source the name of the data source
309 * @param key the key to use for the data
310 * @param value the data to associated with the source
312 void setData(const QString
&source
, const QString
&key
, const QVariant
&value
);
315 * Adds a set of data to a data source. If the source
316 * doesn't exist then it is created.
318 * @param source the name of the data source
319 * @param data the data to add to the source
321 void setData(const QString
&source
, const Data
&data
);
324 * Removes all the data associated with a data source.
326 * @param source the name of the data source
328 void removeAllData(const QString
&source
);
331 * Removes a data entry from a source
333 * @param source the name of the data source
334 * @param key the data entry to remove
336 void removeData(const QString
&source
, const QString
&key
);
339 * Adds an already constructed data source. The DataEngine takes
340 * ownership of the DataContainer object. The objectName of the source
341 * is used for the source name.
343 * @param source the DataContainer to add to the DataEngine
345 void addSource(DataContainer
*source
);
348 * Sets an upper limit on the number of data sources to keep in this engine.
349 * If the limit is exceeded, then the oldest data source, as defined by last
350 * update, is dropped.
352 * @param limit the maximum number of sources to keep active
354 void setMaxSourceCount(uint limit
);
357 * Sets the minimum amount of time, in milliseconds, that must pass between
358 * successive updates of data. This can help prevent too many updates happening
359 * due to multiple update requests coming in, which can be useful for
360 * expensive (time- or resource-wise) update mechanisms.
362 * @param minimumMs the minimum time lapse, in milliseconds, between updates.
363 * A value less than 0 means to never perform automatic updates,
364 * a value of 0 means update immediately on every update request,
365 * a value >0 will result in a minimum time lapse being enforced.
367 void setMinimumPollingInterval(int minimumMs
);
370 * @return the minimum time between updates. @see setMinimumPollingInterval
372 int minimumPollingInterval() const;
375 * Sets up an internal update tick for all data sources. On every update,
376 * updateSourceEvent will be called for each applicable source.
377 * @see updateSourceEvent
379 * @param frequency the time, in milliseconds, between updates. A value of 0
380 * will stop internally triggered updates.
382 void setPollingInterval(uint frequency
);
385 * Returns the current update frequency.
386 * @see setPollingInterval
387 NOTE: This is not implemented to prevent having to store the value internally.
388 When there is a good use case for needing access to this value, we can
389 add another member to the Private class and add this method.
390 uint pollingInterval();
394 * Removes all data sources
396 void removeAllSources();
399 * Sets whether or not this engine is valid, e.g. can be used.
400 * In practice, only the internal fall-back engine, the NullEngine
401 * should have need for this.
403 * @param valid whether or not the engine is valid
405 void setValid(bool valid
);
408 * @return the list of active DataContainers.
410 SourceDict
containerDict() const;
413 * Reimplemented from QObject
415 void timerEvent(QTimerEvent
*event
);
418 * Sets the engine name for the DataEngine
420 void setName(const QString
&name
);
423 * Sets the icon for this data engine
425 void setIcon(const QString
&icon
);
429 * Call this method when you call setData directly on a DataContainer instead
430 * of using the DataEngine::setData methods.
431 * If this method is not called, no dataUpdated(..) signals will be emitted!
433 void scheduleSourcesUpdated();
436 * Removes a data source.
437 * @param source the name of the data source to remove
439 void removeSource(const QString
&source
);
442 * Immediately updates all existing sources when called
444 void updateAllSources();
447 friend class DataEnginePrivate
;
448 friend class DataEngineScript
;
449 friend class DataEngineManager
;
450 friend class NullEngine
;
452 Q_PRIVATE_SLOT(d
, void internalUpdateSource(DataContainer
*source
))
454 DataEnginePrivate
*const d
;
457 } // Plasma namespace
460 * Register a data engine when it is contained in a loadable module
462 #define K_EXPORT_PLASMA_DATAENGINE(libname, classname) \
463 K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) \
464 K_EXPORT_PLUGIN(factory("plasma_engine_" #libname)) \
465 K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION)
467 #endif // multiple inclusion guard