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_DATAENGINEMANAGER_H
21#define PLASMA_DATAENGINEMANAGER_H
22
23#include <QtCore/QHash>
24
25#include <kplugininfo.h>
26
27#include <plasma/dataengine.h>
28
29namespace Plasma
30{
31
32class DataEngineManagerPrivate;
33
34/**
35 * @class DataEngineManager plasma/dataenginemanager.h <Plasma/DataEngineManager>
36 *
37 * @short DataEngine loader and life time manager
38 *
39 * Plasma::DataEngineManager provides facilities for listing, loading and
40 * according to reference count unloading of DataEngines.
41 **/
42class PLASMA_EXPORT DataEngineManager: public QObject
43{
44 Q_OBJECT
45 public:
46 /**
47 * Singleton pattern accessor.
48 */
49 static DataEngineManager *self();
50
51 /**
52 * Returns a data engine object if one is loaded and available.
53 * On failure, the fallback NullEngine (which does nothing and
54 * !isValid()) is returned.
55 *
56 * @param name the name of the engine
57 */
58 Plasma::DataEngine *engine(const QString &name) const;
59
60 /**
61 * Loads a data engine and increases the reference count on it.
62 * This should be called once per object (or set of objects) using the
63 * DataEngine. Afterwards, dataEngine should be used or the return
64 * value cached. Call unloadDataEngine when finished with the engine.
65 *
66 * @param name the name of the engine
67 * @return the data engine that was loaded, or the NullEngine on failure.
68 */
69 Plasma::DataEngine *loadEngine(const QString &name);
70
71 /**
72 * Decreases the reference count on the engine. If the count reaches
73 * zero, then the engine is deleted to save resources.
74 */
75 void unloadEngine(const QString &name);
76
77 /**
78 * @return a listing of all known DataEngines by name
79 *
80 * @param parentApp the application to filter applets on. Uses the
81 * X-KDE-ParentApp entry (if any) in the plugin info.
82 * The default value of QString() will result in a
83 * list containing only applets not specifically
84 * registered to an application.
85 */
86 static QStringList listAllEngines(const QString &parentApp = QString());
87
88 /**
89 * Returns a list of all known DataEngines.
90 *
91 * @param parentApp the application to filter applets on. Uses the
92 * X-KDE-ParentApp entry (if any) in the plugin info.
93 * The default value of QString() will result in a
94 * list containing only applets not specifically
95 * registered to an application.
96 * @return list of DataEngines
97 **/
98 static KPluginInfo::List listEngineInfo(const QString &parentApp = QString());
99
100 /**
101 * Returns a list of all known DataEngines filtering by category.
102 *
103 * @param category the category to filter applets on. Uses the
104 * X-KDE-PluginInfo-Category entry (if any) in the
105 * plugin info. The value of QString() will
106 * result in a list of engines with an empty category.
107 *
108 * @param parentApp the application to filter applets on. Uses the
109 * X-KDE-ParentApp entry (if any) in the plugin info.
110 * The default value of QString() will result in a
111 * list containing only applets not specifically
112 * registered to an application.
113 * @return list of DataEngines
114 * @since 4.3
115 **/
116 static KPluginInfo::List listEngineInfoByCategory(const QString &category, const QString &parentApp = QString());
117
118 protected:
119 /**
120 * Reimplemented from QObject
121 **/
122 void timerEvent(QTimerEvent *event);
123
124 private:
125 /**
126 * Default constructor. The singleton method self() is the
127 * preferred access mechanism.
128 */
129 DataEngineManager();
130 ~DataEngineManager();
131
132 DataEngineManagerPrivate *const d;
133
134 friend class DataEngineManagerSingleton;
135};
136
137} // namespace Plasma
138
139#endif // multiple inclusion guard
140