1/* This file is part of the KDE project
2 Copyright (C) 2003,2007 Matthias Kretz <kretz@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License version 2 as published by the Free Software Foundation.
7
8 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details.
12
13 You should have received a copy of the GNU Library General Public License
14 along with this library; see the file COPYING.LIB. If not, write to
15 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16 Boston, MA 02110-1301, USA.
17
18*/
19
20#ifndef KDECORE_KPLUGININFO_H
21#define KDECORE_KPLUGININFO_H
22
23#include <QtCore/QExplicitlySharedDataPointer>
24#include <QtCore/QString>
25#include <QtCore/QMap>
26#include <QtCore/QStringList>
27
28#include <kconfiggroup.h>
29#include <kservice.h>
30#include <kaboutdata.h>
31#include <QtCore/QList>
32
33class KPluginInfoPrivate;
34
35/**
36 * Information about a plugin.
37 *
38 * This holds all the information about a plugin there is. It's used for the
39 * user to decide whether he wants to use this plugin or not.
40 *
41 * @author Matthias Kretz <kretz@kde.org>
42 */
43class KDECORE_EXPORT KPluginInfo
44{
45 public:
46 typedef QList<KPluginInfo> List;
47
48 /**
49 * Read plugin info from @p filename.
50 *
51 * The file should be of the following form:
52 * \verbatim
53 [Desktop Entry]
54 Encoding=UTF-8
55 Icon=mypluginicon
56 Type=Service
57 ServiceTypes=KPluginInfo
58
59 Name=User Visible Name
60 Comment=Description of what the plugin does
61
62 X-KDE-PluginInfo-Author=Author's Name
63 X-KDE-PluginInfo-Email=author@foo.bar
64 X-KDE-PluginInfo-Name=internalname
65 X-KDE-PluginInfo-Version=1.1
66 X-KDE-PluginInfo-Website=http://www.plugin.org/
67 X-KDE-PluginInfo-Category=playlist
68 X-KDE-PluginInfo-Depends=plugin1,plugin3
69 X-KDE-PluginInfo-License=GPL
70 X-KDE-PluginInfo-EnabledByDefault=true
71 \endverbatim
72 * The Name and Comment fields must always be present.
73 *
74 * The "X-KDE-PluginInfo" keys you may add further entries which
75 * will be available using property(). The Website,Category,Require
76 * keys are optional.
77 * For EnabledByDefault look at isPluginEnabledByDefault.
78 *
79 * @param filename The filename of the .desktop file.
80 * @param resource If filename is relative, you need to specify a resource type
81 * (e.g. "service", "apps"... KStandardDirs). Otherwise,
82 * resource isn't used.
83 */
84 explicit KPluginInfo( const QString & filename, const char* resource = 0 );
85
86 /**
87 * Read plugin info from a KService object.
88 *
89 * The .desktop file should look like this:
90 * \verbatim
91 [Desktop Entry]
92 Encoding=UTF-8
93 Icon=mypluginicon
94 Type=Service
95 ServiceTypes=KPluginInfo
96
97 X-KDE-PluginInfo-Author=Author's Name
98 X-KDE-PluginInfo-Email=author@foo.bar
99 X-KDE-PluginInfo-Name=internalname
100 X-KDE-PluginInfo-Version=1.1
101 X-KDE-PluginInfo-Website=http://www.plugin.org/
102 X-KDE-PluginInfo-Category=playlist
103 X-KDE-PluginInfo-Depends=plugin1,plugin3
104 X-KDE-PluginInfo-License=GPL
105 X-KDE-PluginInfo-EnabledByDefault=true
106
107 Name=User Visible Name
108 Comment=Description of what the plugin does
109 \endverbatim
110 * In the first three entries the Icon entry is optional.
111 */
112 explicit KPluginInfo( const KService::Ptr service );
113
114 /**
115 * Creates an invalid plugin.
116 *
117 * \see isValid
118 */
119 KPluginInfo();
120
121 ~KPluginInfo();
122
123 /**
124 * @return A list of KPluginInfo objects constructed from a list of
125 * KService objects. If you get a trader offer of the plugins you want
126 * to use you can just pass them to this function.
127 *
128 * @param services The list of services to construct the list of KPluginInfo objects from
129 * @param config The config group where to save/load whether the plugin is enabled/disabled
130 */
131 static KPluginInfo::List fromServices(const KService::List &services, const KConfigGroup &config = KConfigGroup());
132
133 /**
134 * @return A list of KPluginInfo objects constructed from a list of
135 * filenames. If you make a lookup using, for example,
136 * KStandardDirs::findAllResources() you pass the list of files to this
137 * function.
138 *
139 * @param files The list of files to construct the list of KPluginInfo objects from
140 * @param config The config group where to save/load whether the plugin is enabled/disabled
141 */
142 static KPluginInfo::List fromFiles(const QStringList &files, const KConfigGroup &config = KConfigGroup());
143
144 /**
145 * @return A list of KPluginInfo objects for the KParts plugins of a
146 * component. You only need the name of the component not a pointer to the
147 * KComponentData object.
148 *
149 * @param componentName Use the component name to look up all KParts plugins for it.
150 * @param config The config group where to save/load whether the plugin is enabled/disabled
151 */
152 static KPluginInfo::List fromKPartsInstanceName(const QString &componentName, const KConfigGroup &config = KConfigGroup());
153
154 /**
155 * @return Whether the plugin should be hidden.
156 */
157 bool isHidden() const;
158
159 /**
160 * Set whether the plugin is currently loaded.
161 *
162 * @see isPluginEnabled()
163 * @see save()
164 */
165 void setPluginEnabled(bool enabled);
166
167 /**
168 * @return Whether the plugin is currently loaded.
169 *
170 * @see setPluginEnabled()
171 * @see load()
172 */
173 bool isPluginEnabled() const;
174
175 /**
176 * @return The default value whether the plugin is enabled or not.
177 * Defaults to the value set in the desktop file, or if that isn't set
178 * to false.
179 */
180 bool isPluginEnabledByDefault() const;
181
182 /**
183 * @return The value associated to the @p key. You can use it if you
184 * want to read custom values. To do this you need to define
185 * your own servicetype and add it to the ServiceTypes keys.
186 */
187 QVariant property( const QString & key ) const;
188
189 /**
190 * @return The user visible name of the plugin.
191 */
192 QString name() const;
193
194 /**
195 * @return A comment describing the plugin.
196 */
197 QString comment() const;
198
199 /**
200 * @return The iconname for this plugin
201 */
202 QString icon() const;
203
204 /**
205 * @return The file containing the information about the plugin.
206 */
207 QString entryPath() const;
208
209 /**
210 * @return The author of this plugin.
211 */
212 QString author() const;
213
214 /**
215 * @return The email address of the author.
216 */
217 QString email() const;
218
219 /**
220 * @return The category of this plugin (e.g. playlist/skin).
221 */
222 QString category() const;
223
224 /**
225 * @return The internal name of the plugin (for KParts Plugins this is
226 * the same name as set in the .rc file).
227 */
228 QString pluginName() const;
229
230 /**
231 * @return The version of the plugin.
232 */
233 QString version() const;
234
235 /**
236 * @return The website of the plugin/author.
237 */
238 QString website() const;
239
240
241 /**
242 * @return The license keyword of this plugin.
243 */
244 QString license() const;
245
246 /**
247 * @return The full license object, according to the license keyword.
248 * It can be used to present friendlier and more detailed
249 * license info to the user, when the license is one of the
250 * widespread within KDE. For other licenses, the license
251 * object will state not very useful, "custom license" info
252 * (this can be identified by KAboutLicense::key() returning
253 * KAboutData::License_Custom).
254 *
255 * @see KAboutLicense::byKeyword()
256 * @since 4.1
257 */
258 KAboutLicense fullLicense() const;
259
260 /**
261 * @return A list of plugins required for this plugin to be enabled. Use
262 * the pluginName in this list.
263 */
264 QStringList dependencies() const;
265
266 /**
267 * @return The KService object for this plugin. You might need it if you
268 * want to read custom values. To do this you need to define
269 * your own servicetype and add it to the ServiceTypes keys.
270 * Then you can use the KService::property() method to read your
271 * keys.
272 *
273 * @see property()
274 */
275 KService::Ptr service() const;
276
277 /**
278 * @return A list of Service pointers if the plugin installs one or more
279 * KCModule
280 */
281 QList<KService::Ptr> kcmServices() const;
282
283 /**
284 * Set the KConfigGroup to use for load()ing and save()ing the
285 * configuration. This will be overridden by the KConfigGroup passed to
286 * save() or load() (if one is passed).
287 */
288 void setConfig(const KConfigGroup &config);
289
290 /**
291 * @return If the KPluginInfo object has a KConfig object set return
292 * it, else returns an invalid KConfigGroup.
293 */
294 KConfigGroup config() const;
295
296 /**
297 * Save state of the plugin - enabled or not.
298 *
299 * @param config The KConfigGroup holding the information whether
300 * plugin is enabled.
301 */
302 void save(KConfigGroup config = KConfigGroup());
303
304 /**
305 * Load the state of the plugin - enabled or not.
306 *
307 * @param config The KConfigGroup holding the information whether
308 * plugin is enabled.
309 */
310 void load(const KConfigGroup &config = KConfigGroup());
311
312 /**
313 * Restore defaults (enabled or not).
314 */
315 void defaults();
316
317 /**
318 * Returns whether the object is valid. Treat invalid KPluginInfo objects like you would
319 * treat a null pointer.
320 */
321 bool isValid() const;
322
323 /**
324 * Creates a KPluginInfo object that shares the data with \p copy.
325 */
326 KPluginInfo(const KPluginInfo &copy);
327
328 /**
329 * Copies the KPluginInfo object to share the data with \p copy.
330 */
331 KPluginInfo &operator=(const KPluginInfo &rhs);
332
333 /**
334 * Compares two objects whether they share the same data.
335 */
336 bool operator==(const KPluginInfo &rhs) const;
337
338 /**
339 * Compares two objects whether they don't share the same data.
340 */
341 bool operator!=(const KPluginInfo &rhs) const;
342
343 /**
344 * Less than relation comparing the categories and if they are the same using the names.
345 */
346 bool operator<(const KPluginInfo &rhs) const;
347
348 /**
349 * Greater than relation comparing the categories and if they are the same using the names.
350 */
351 bool operator>(const KPluginInfo &rhs) const;
352
353 private:
354 friend KDECORE_EXPORT uint qHash(const KPluginInfo &);
355 QExplicitlySharedDataPointer<KPluginInfoPrivate> d;
356};
357
358KDECORE_EXPORT uint qHash(const KPluginInfo &);
359
360#endif // KDECORE_KPLUGININFO_H
361