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 | |
26 | namespace Plasma { |
27 | |
28 | class Applet; |
29 | class DataEngine; |
30 | class Service; |
31 | class AbstractRunner; |
32 | |
33 | class 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 | **/ |
51 | class PLASMA_EXPORT PluginLoader |
52 | { |
53 | public: |
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 | |
152 | protected: |
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 | |
299 | private: |
300 | PluginLoaderPrivate * const d; |
301 | }; |
302 | |
303 | } |
304 | |
305 | Q_DECLARE_METATYPE(Plasma::PluginLoader*) |
306 | |
307 | #endif |
308 | |