1/*
2 * Copyright 2010 by Ryan Rix <ry@n.rix.si>
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 PLUGIN_LOADER_H
21#define PLUGIN_LOADER_H
22
23#include <plasma/plasma.h>
24#include <kplugininfo.h>
25
26namespace Plasma {
27
28class Applet;
29class DataEngine;
30class Service;
31class AbstractRunner;
32
33class PluginLoaderPrivate;
34
35//TODO:
36// * add support for ContainmentActions plugins
37// * add KPluginInfo listing support for Containments (already loaded via the applet loading code)
38
39/**
40 * This is an abstract base class which defines an interface to which Plasma's
41 * Applet Loading logic can communicate with a parent application. The plugin loader
42 * must be set before any plugins are loaded, otherwise (for safety reasons), the
43 * default PluginLoader implementation will be used. The reimplemented version should
44 * not do more than simply returning a loaded plugin. It should not init() it, and it should not
45 * hang on to it. The associated methods will be called only when a component of Plasma
46 * needs to load a _new_ plugin. (e.g. DataEngine does its own caching).
47 *
48 * @author Ryan Rix <ry@n.rix.si>
49 * @since 4.6
50 **/
51class PLASMA_EXPORT PluginLoader
52{
53public:
54 PluginLoader();
55
56 virtual ~PluginLoader();
57
58 /**
59 * Load an Applet plugin.
60 *
61 * @param name the plugin name, as returned by KPluginInfo::pluginName()
62 * @param appletId unique ID to assign the applet, or zero to have one
63 * assigned automatically.
64 * @param args to send the applet extra arguments
65 * @return a pointer to the loaded applet, or 0 on load failure
66 **/
67 Applet *loadApplet(const QString &name, uint appletId = 0,
68 const QVariantList &args = QVariantList());
69
70 /**
71 * Load a DataEngine plugin.
72 *
73 * @param name the name of the engine
74 * @return the DataEngine that was loaded, or the NullEngine on failure.
75 **/
76 DataEngine *loadDataEngine(const QString &name);
77
78 /**
79 * Load a Runner plugin
80 *
81 * @return the Runner that was loaded, or 0 on failure.
82 */
83 AbstractRunner *loadRunner(const QString &name);
84
85 /**
86 * Load a Service plugin.
87 *
88 * @param name the plugin name of the service to load
89 * @param args a list of arguments to supply to the service plugin when loading it
90 * @param parent the parent object, if any, for the service
91 *
92 * @return a Service object, unlike Plasma::Service::loadService, this can return null.
93 **/
94 Service *loadService(const QString &name, const QVariantList &args, QObject *parent = 0);
95
96 /**
97 * Returns a list of all known applets.
98 * This may skip applets based on security settings and ExcludeCategories in the application's config.
99 *
100 * @param category Only applets matchin this category will be returned.
101 * Useful in conjunction with knownCategories.
102 * If "Misc" is passed in, then applets without a
103 * Categories= entry are also returned.
104 * If an empty string is passed in, all applets are
105 * returned.
106 * @param parentApp the application to filter applets on. Uses the
107 * X-KDE-ParentApp entry (if any) in the plugin info.
108 * The default value of QString() will result in a
109 * list containing only applets not specifically
110 * registered to an application.
111 * @return list of applets
112 **/
113 KPluginInfo::List listAppletInfo(const QString &category, const QString &parentApp = QString());
114
115 /**
116 * Returns a list of all known DataEngines.
117 *
118 * @param parentApp the application to filter applets on. Uses the
119 * X-KDE-ParentApp entry (if any) in the plugin info.
120 * The default value of QString() will result in a
121 * list containing only applets not specifically
122 * registered to an application.
123 * @return list of DataEngines
124 **/
125 KPluginInfo::List listDataEngineInfo(const QString &parentApp = QString());
126
127 /**
128 * Returns a list of all known Runner implementations
129 *
130 * @param parentApp the application to filter applets on. Uses the
131 * X-KDE-ParentApp entry (if any) in the plugin info.
132 * The default value of QString() will result in a
133 * list containing only applets not specifically
134 * registered to an application.
135 * @return list of AbstractRunners
136 **/
137 KPluginInfo::List listRunnerInfo(const QString &parentApp = QString());
138
139 /**
140 * Set the plugin loader which will be queried for all loads.
141 *
142 * @param loader A subclass of PluginLoader which will be supplied
143 * by the application
144 **/
145 static void setPluginLoader(PluginLoader* loader);
146
147 /**
148 * Return the active plugin loader
149 **/
150 static PluginLoader* pluginLoader();
151
152protected:
153 /**
154 * A re-implementable method that allows subclasses to override
155 * the default behaviour of loadApplet. If the applet requested is not recognized,
156 * then the implementation should return a NULL pointer. This method is called
157 * by loadApplet prior to attempting to load an applet using the standard Plasma
158 * plugin mechanisms.
159 *
160 * @param name the plugin name, as returned by KPluginInfo::pluginName()
161 * @param appletId unique ID to assign the applet, or zero to have one
162 * assigned automatically.
163 * @param args to send the applet extra arguments
164 * @return a pointer to the loaded applet, or 0 on load failure
165 **/
166 virtual Applet *internalLoadApplet(const QString &name, uint appletId = 0,
167 const QVariantList &args = QVariantList());
168
169 /**
170 * A re-implementable method that allows subclasses to override
171 * the default behaviour of loadRunner. If the runner requested is not recognized,
172 * then the implementation should return a NULL pointer. This method is called
173 * by loadRunner prior to attempting to load a DataEgine using the standard Plasma
174 * plugin mechanisms.
175 *
176 * @param name the name of the engine
177 * @return the data engine that was loaded, or the NullEngine on failure.
178 **/
179 virtual AbstractRunner *internalLoadRunner(const QString &name);
180
181 /**
182 * A re-implementable method that allows subclasses to override
183 * the default behaviour of loadDataEngine. If the engine requested is not recognized,
184 * then the implementation should return a NULL pointer. This method is called
185 * by loadDataEngine prior to attempting to load a DataEgine using the standard Plasma
186 * plugin mechanisms.
187 *
188 * @param name the name of the engine
189 * @return the data engine that was loaded, or the NullEngine on failure.
190 **/
191 virtual DataEngine *internalLoadDataEngine(const QString &name);
192
193 /**
194 * A re-implementable method that allows subclasses to override
195 * the default behaviour of loadService. If the service requested is not recognized,
196 * then the implementation should return a NULL pointer. This method is called
197 * by loadService prior to attempting to load a Service using the standard Plasma
198 * plugin mechanisms.
199 *
200 * @param name the plugin name of the service to load
201 * @param args a list of arguments to supply to the service plugin when loading it
202 * @param parent the parent object, if any, for the service
203 *
204 * @return a Service object, unlike Plasma::Service::loadService, this can return null.
205 **/
206 virtual Service *internalLoadService(const QString &name, const QVariantList &args, QObject *parent = 0);
207
208 /**
209 * A re-implementable method that allows subclasses to provide additional applets
210 * for listAppletInfo. If the application has no applets to give to the application,
211 * then the implementation should return an empty list.
212 *
213 * This method is called by listAppletInfo prior to generating the list of applets installed
214 * on the system using the standard Plasma plugin mechanisms, and will try to find .desktop
215 * files for your applets.
216 *
217 * @param category Only applets matching this category will be returned.
218 * Useful in conjunction with knownCategories.
219 * If "Misc" is passed in, then applets without a
220 * Categories= entry are also returned.
221 * If an empty string is passed in, all applets are
222 * returned.
223 * @return list of applets
224 **/
225 virtual KPluginInfo::List internalAppletInfo(const QString &category) const;
226
227 /**
228 * A re-implementable method that allows subclasses to provide additional DataEngines
229 * for DataEngineManager::listDataEngines.
230 *
231 * @return list of DataEngines, or an empty list if none
232 **/
233 virtual KPluginInfo::List internalDataEngineInfo() const;
234
235 /**
236 * Returns a list of all known Runner implementations
237 *
238 * @return list of AbstractRunners, or an empty list if none
239 */
240 virtual KPluginInfo::List internalRunnerInfo() const;
241
242 /**
243 * Returns a list of all known Runner implementations
244 *
245 * @return list of AbstractRunners, or an empty list if none
246 */
247 virtual KPluginInfo::List internalServiceInfo() const;
248
249 /**
250 * Standardized mechanism for providing internal Applets by install .desktop files
251 * in $APPPDATA/plasma/internal/applets/
252 *
253 * For applications that do this, internalAppletInfo can be implemented as a one-liner
254 * call to this method.
255 *
256 * @param category Only applets matching this category will be returned.
257 * Useful in conjunction with knownCategories.
258 * If "Misc" is passed in, then applets without a
259 * Categories= entry are also returned.
260 * If an empty string is passed in, all applets are
261 * returned.
262 * @return list of Applets, or an empty list if none
263 */
264 KPluginInfo::List standardInternalAppletInfo(const QString &category) const;
265
266 /**
267 * Standardized mechanism for providing internal Applets by install .desktop files
268 * in $APPPDATA/plasma/internal/dataengines/
269 *
270 * For applications that do this, internalDataEngineInfo can be implemented as a one-liner
271 * call to this method.
272 *
273 * @return list of applets
274 */
275 KPluginInfo::List standardInternalDataEngineInfo() const;
276
277 /**
278 * Standardized mechanism for providing internal Applets by install .desktop files
279 * in $APPPDATA/plasma/internal/runners/
280 *
281 * For applications that do this, internalRunnerInfo can be implemented as a one-liner
282 * call to this method.
283 *
284 * @return list of applets
285 */
286 KPluginInfo::List standardInternalRunnerInfo() const;
287
288 /**
289 * Standardized mechanism for providing internal Applets by install .desktop files
290 * in $APPPDATA/plasma/internal/services/
291 *
292 * For applications that do this, internalRunnerInfo can be implemented as a one-liner
293 * call to this method.
294 *
295 * @return list of applets
296 */
297 KPluginInfo::List standardInternalServiceInfo() const;
298
299private:
300 PluginLoaderPrivate * const d;
301};
302
303}
304
305Q_DECLARE_METATYPE(Plasma::PluginLoader*)
306
307#endif
308