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 | |
33 | class 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 | */ |
43 | class 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 () 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 ©); |
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 | |
358 | KDECORE_EXPORT uint qHash(const KPluginInfo &); |
359 | |
360 | #endif // KDECORE_KPLUGININFO_H |
361 | |