KService

kplugininfo.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 2003, 2007 Matthias Kretz <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-only
6 */
7 
8 #ifndef KPLUGININFO_H
9 #define KPLUGININFO_H
10 
11 #include <QExplicitlySharedDataPointer>
12 #include <QString>
13 #include <QStringList>
14 
15 #include <KConfigGroup>
16 #include <QList>
17 #include <kservice.h>
18 
19 class KPluginMetaData;
20 class KPluginInfoPrivate;
21 
22 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 90)
23 /**
24  * @class KPluginInfo kplugininfo.h <KPluginInfo>
25  *
26  * Information about a plugin.
27  *
28  * This holds all the information about a plugin there is. It's used for the
29  * user to decide whether he wants to use this plugin or not.
30  *
31  * @author Matthias Kretz <[email protected]>
32  * @deprecated since 5.88, use QPluginLoader or the KPluginFactory::loadFactory/KPluginFactory::instantiatePlugins
33  * methods instead to create objects from the plugins.
34  * For accessing the metadata, use KPluginMetaData instead.
35  * To embed json metadata in your plugin, use K_PLUGIN_CLASS_WITH_JSON(MyClass, "mypluginmetadata.json")
36  *
37  * The reading of the enabled state can be done using the KPluginMetaData::isEnabled method.
38  * Writing the config should be done manually. Consider using KPluginWidget for the configuration
39  * of plugins in the UI.
40  *
41  */
42 class KSERVICE_EXPORT KPluginInfo
43 {
44 public:
45  /**
46  * A list of KPluginInfo objects.
47  */
49 
50  /**
51  * Read plugin info from @p filename.
52  *
53  * The file should be of the following form:
54  * \verbatim
55  [Desktop Entry]
56  Icon=mypluginicon
57  Type=Service
58  X-KDE-ServiceTypes=KPluginInfo
59 
60  Name=User Visible Name
61  Comment=Description of what the plugin does
62 
63  X-KDE-PluginInfo-Author=Author's Name
65  X-KDE-PluginInfo-Name=internalname
66  X-KDE-PluginInfo-Version=1.1
67  X-KDE-PluginInfo-Website=http://www.plugin.org/
68  X-KDE-PluginInfo-Category=playlist
69  X-KDE-PluginInfo-Depends=plugin1,plugin3
70  X-KDE-PluginInfo-License=GPL
71  X-KDE-PluginInfo-EnabledByDefault=true
72  \endverbatim
73  * The Name and Comment fields must always be present.
74  *
75  * The "X-KDE-PluginInfo" keys you may add further entries which
76  * will be available using property(). The Website,Category,Require
77  * keys are optional.
78  * For EnabledByDefault look at isPluginEnabledByDefault.
79  *
80  * @param filename The filename of the .desktop file.
81  * @param resource If filename is relative, you need to specify a resource type
82  * (e.g. "service", "apps"... KStandardDirs). Otherwise,
83  * resource isn't used.
84  * @deprecated Since 5.90, see class API docs
85  */
86  KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
87  explicit KPluginInfo(const QString &filename /*, QStandardPaths::StandardLocation resource = ...? GenericDataLocation + services ? Is this used? */);
88 
89  /**
90  * Read plugin info from a KService object.
91  *
92  * The .desktop file should look like this:
93  * \verbatim
94  [Desktop Entry]
95  Icon=mypluginicon
96  Type=Service
97  X-KDE-ServiceTypes=KPluginInfo
98 
99  X-KDE-PluginInfo-Author=Author's Name
101  X-KDE-PluginInfo-Name=internalname
102  X-KDE-PluginInfo-Version=1.1
103  X-KDE-PluginInfo-Website=http://www.plugin.org/
104  X-KDE-PluginInfo-Category=playlist
105  X-KDE-PluginInfo-Depends=plugin1,plugin3
106  X-KDE-PluginInfo-License=GPL
107  X-KDE-PluginInfo-EnabledByDefault=true
108 
109  Name=User Visible Name
110  Comment=Description of what the plugin does
111  \endverbatim
112  * In the first three entries the Icon entry is optional.
113  * @deprecated Since 5.90, see class API docs
114  */
115  KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
116  explicit KPluginInfo(const KService::Ptr service);
117 
118  /**
119  * Read plugin info from arguments passed to the plugin. These arguments should contain
120  * the plugin's metadata (as read from QPluginLoader::metaData(). This constructor uses
121  * the metadata read from the QVariantList. It reads the first QVariantMap it finds in a
122  * field called "MetaData".
123  *
124  * Use (Q|K)PluginLoader and build the metadata into the plugin using
125  * K_PLUGIN_CLASS_WITH_JSON( ..., "mypluginmetadata.json")
126  *
127  * You can use the "desktoptojson tool to generate a .json file from your .desktop file.
128  * The .json file should look like this:
129  *
130  * \verbatim
131  {
132  "Comment": "Date and time by timezone",
133  "Icon": "preferences-system-time",
134  "Name": "Date and Time",
135  "Type": "Service",
136  "X-KDE-Library": "plasma_engine_time",
137  "X-KDE-PluginInfo-Author": "Aaron Seigo",
138  "X-KDE-PluginInfo-Category": "Date and Time",
139  "X-KDE-PluginInfo-Depends": [
140  ],
141  "X-KDE-PluginInfo-Email": "[email protected]",
142  "X-KDE-PluginInfo-EnabledByDefault": true,
143  "X-KDE-PluginInfo-License": "LGPL",
144  "X-KDE-PluginInfo-Name": "time",
145  "X-KDE-PluginInfo-Version": "1.0",
146  "X-KDE-PluginInfo-Website": "http://plasma.kde.org/",
147  "X-KDE-ServiceTypes": [
148  "Plasma/DataEngine"
149  ],
150  "X-KDE-FormFactors": [
151  "tablet",
152  "handset"
153  ]
154  }
155  \endverbatim
156  * @param args QVariantList with arguments, should contain a QVariantMap, keyed "MetaData"
157  * as provided by QPluginLoader::metaData()
158  * @param libraryPath The path to the plugin file on disk
159  *
160  * \see K_PLUGIN_CLASS_WITH_JSON()
161  * \see KPluginFactory::factory()
162  * @since 5.0
163  * @deprecated Since 5.90, see class API docs
164  */
165  KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
166  explicit KPluginInfo(const QVariantList &args, const QString &libraryPath = QString());
167 
168  /**
169  * Read plugin info from a KPluginMetaData object.
170  *
171  * @param md The KPluginMetaData to read the information from
172  * @see K_PLUGIN_CLASS_WITH_JSON()
173  * @see KPluginLoader
174  * @since 5.5
175  * @deprecated Since 5.90, see class API docs
176  */
177  KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
178  explicit KPluginInfo(const KPluginMetaData &md);
179 
180  /**
181  * Creates an invalid plugin.
182  *
183  * \see isValid
184  */
185  KPluginInfo();
186 
187  ~KPluginInfo();
188 
189  /**
190  * @return A list of KPluginInfo objects constructed from a list of
191  * KService objects. If you get a trader offer of the plugins you want
192  * to use you can just pass them to this function.
193  *
194  * @param services The list of services to construct the list of KPluginInfo objects from
195  * @param config The config group where to save/load whether the plugin is enabled/disabled
196  * @deprecated Since 5.90, see class API docs
197  */
198  KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
199  static KPluginInfo::List fromServices(const KService::List &services, const KConfigGroup &config = KConfigGroup());
200 
201  /**
202  * @return A list of KPluginInfo objects constructed from a list of
203  * filenames. If you make a lookup using, for example,
204  * KStandardDirs::findAllResources() you pass the list of files to this
205  * function.
206  *
207  * @param files The list of files to construct the list of KPluginInfo objects from
208  * @param config The config group where to save/load whether the plugin is enabled/disabled
209  */
210  static KPluginInfo::List fromFiles(const QStringList &files, const KConfigGroup &config = KConfigGroup());
211 
212 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 81)
213  /**
214  * @return A list of KPluginInfo objects for the KParts plugins of a
215  * component.
216  *
217  * @param componentName Use the component name to look up all KParts plugins for it.
218  * @param config The config group where to save/load whether the plugin is enabled/disabled
219  * @deprecated since 5.81, removed for lack of usage, KParts loads the plugins all by itself
220  */
221  KSERVICE_DEPRECATED_VERSION(5, 81, "Removed for lack of usage, KParts plugins don't use this anymore (or never did)")
222  static KPluginInfo::List fromKPartsInstanceName(const QString &componentName, const KConfigGroup &config = KConfigGroup());
223 #endif
224 
225  /**
226  * @return Whether the plugin should be hidden.
227  */
228  bool isHidden() const;
229 
230  /**
231  * Set whether the plugin is currently loaded.
232  *
233  * @see isPluginEnabled()
234  * @see save()
235  */
236  void setPluginEnabled(bool enabled);
237 
238  /**
239  * @return Whether the plugin is currently loaded.
240  *
241  * @see setPluginEnabled()
242  * @see load()
243  */
244  bool isPluginEnabled() const;
245 
246  /**
247  * @return The default value whether the plugin is enabled or not.
248  * Defaults to the value set in the desktop file, or if that isn't set
249  * to false.
250  */
251  bool isPluginEnabledByDefault() const;
252 
253  /**
254  * @return The value associated to the @p key. You can use it if you
255  * want to read custom values. To do this you need to define
256  * your own servicetype and add it to the ServiceTypes keys.
257  */
258  QVariant property(const QString &key) const;
259 
260  /**
261  * @return All properties of this object. This can be used to read custom values.
262  * @since 5.3
263  * @see KPluginInfo::property()
264  */
265  QVariantMap properties() const;
266 
267  /**
268  * @return The user visible name of the plugin.
269  */
270  QString name() const;
271 
272  /**
273  * @return A comment describing the plugin.
274  */
275  QString comment() const;
276 
277  /**
278  * @return The iconname for this plugin
279  */
280  QString icon() const;
281 
282  /**
283  * @return The file containing the information about the plugin.
284  */
285  QString entryPath() const;
286 
287  /**
288  * @return The author of this plugin.
289  */
290  QString author() const;
291 
292  /**
293  * @return The email address of the author.
294  */
295  QString email() const;
296 
297  /**
298  * @return The category of this plugin (e.g. playlist/skin).
299  */
300  QString category() const;
301 
302  /**
303  * @return The internal name of the plugin (for KParts Plugins this is
304  * the same name as set in the .rc file).
305  */
306  QString pluginName() const;
307 
308  /**
309  * @return The version of the plugin.
310  */
311  QString version() const;
312 
313  /**
314  * @return The website of the plugin/author.
315  */
316  QString website() const;
317 
318  /**
319  * @return The license keyword of this plugin.
320  */
321  QString license() const;
322 
323 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 79)
324 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 79)
325  /**
326  * @return A list of plugins required for this plugin to be enabled. Use
327  * the pluginName in this list.
328  * @deprecated Since 5.79, plugin dependencies are deprecated and will be removed in KF6
329  */
330  KSERVICE_DEPRECATED_VERSION(5, 79, "Plugin dependencies are deprecated and will be removed in KF6")
331  QStringList dependencies() const;
332 #endif
333 #endif
334 
335  /**
336  * @return A list of ServiceTypes this plugin offers
337  * @since 5.0
338  */
339  QStringList serviceTypes() const;
340 
341  /**
342  * @return A list of FormFactors this plugin offers, corresponds to the
343  * "X-KDE-FormFactors" value in a .desktop service file, or to the "FormFactors"
344  * value in the "KPlugin" block of the json metadata. Formfactor values are
345  * freestyle, common values are "desktop", "handset", "tablet", "mediacenter".
346  * Values are comma-separated.
347  * @since 5.14
348  */
349  QStringList formFactors() const;
350 
351  /**
352  * @return The absolute path of the plugin on disk. This can be used to load the plugin from, using
353  * KPluginLoader or QPluginLoader
354  * @since 5.0
355  */
356  QString libraryPath() const;
357  // visibility check set to a later version because the BUILD variant was used before
358 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 88)
359  /**
360  * @return The KService object for this plugin. You might need it if you
361  * want to read custom values. To do this you need to define
362  * your own servicetype and add it to the ServiceTypes keys.
363  * Then you can use the KService::property() method to read your
364  * keys.
365  *
366  * @see property()
367  *
368  * @deprecated since 5.70, use KPluginMetaData and KPluginLoader(info.libraryPath())
369  */
370  KSERVICE_DEPRECATED_VERSION(5, 70, "Use KPluginMetaData and KPluginLoader(info.libraryPath())")
371  KService::Ptr service() const;
372 #endif
373 
374  /**
375  * @return A list of Service pointers if the plugin installs one or more
376  * KCModule
377  */
378  QList<KService::Ptr> kcmServices() const;
379 
380  /**
381  * Set the KConfigGroup to use for load()ing and save()ing the
382  * configuration. This will be overridden by the KConfigGroup passed to
383  * save() or load() (if one is passed).
384  */
385  void setConfig(const KConfigGroup &config);
386 
387  /**
388  * @return If the KPluginInfo object has a KConfig object set return
389  * it, else returns an invalid KConfigGroup.
390  */
391  KConfigGroup config() const;
392 
393  /**
394  * Save state of the plugin - enabled or not.
395  *
396  * @param config The KConfigGroup holding the information whether
397  * plugin is enabled.
398  */
399  void save(KConfigGroup config = KConfigGroup());
400 
401  /**
402  * Load the state of the plugin - enabled or not.
403  *
404  * @param config The KConfigGroup holding the information whether
405  * plugin is enabled.
406  */
407  void load(const KConfigGroup &config = KConfigGroup());
408 
409  /**
410  * Restore defaults (enabled or not).
411  */
412  void defaults();
413 
414  /**
415  * Returns whether the object is valid. Treat invalid KPluginInfo objects like you would
416  * treat a null pointer.
417  */
418  bool isValid() const;
419 
420  /**
421  * Creates a KPluginInfo object that shares the data with \p copy.
422  */
423  KPluginInfo(const KPluginInfo &copy);
424 
425  /**
426  * Copies the KPluginInfo object to share the data with \p copy.
427  */
428  KPluginInfo &operator=(const KPluginInfo &rhs);
429 
430  /**
431  * Compares two objects whether they share the same data.
432  */
433  bool operator==(const KPluginInfo &rhs) const;
434 
435  /**
436  * Compares two objects whether they don't share the same data.
437  */
438  bool operator!=(const KPluginInfo &rhs) const;
439 
440  /**
441  * Less than relation comparing the categories and if they are the same using the names.
442  */
443  bool operator<(const KPluginInfo &rhs) const;
444 
445  /**
446  * Greater than relation comparing the categories and if they are the same using the names.
447  */
448  bool operator>(const KPluginInfo &rhs) const;
449 
450  friend class KPluginTrader;
451 
452  /**
453  * @return a KPluginMetaData object with equivalent meta data.
454  * @since 5.3
455  */
456  KPluginMetaData toMetaData() const;
457 
458  /**
459  * @param info the KPluginInfo object to convert
460  * @return a KPluginMetaData object with equivalent meta data.
461  * @since 5.3
462  * @deprecated Since 5.90, see class API docs
463  */
464  KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
465  static KPluginMetaData toMetaData(const KPluginInfo &info);
466 
467  /**
468  * @param meta the KPluginMetaData to convert
469  * @return a KPluginInfo object with equivalent meta data.
470  * @since 5.3
471  * @deprecated Since 5.90, see class API docs
472  */
473  KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
474  static KPluginInfo fromMetaData(const KPluginMetaData &meta);
475 
476  /**
477  * @param list the list of KPluginInfo objects to convert
478  * @return a list of KPluginMetaData objects with equivalent meta data.
479  * @since 5.3
480  * @deprecated Since 5.90, see class API docs
481  */
482  KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
483  static QVector<KPluginMetaData> toMetaData(const KPluginInfo::List &list);
484 
485  /**
486  * @param list the list of KPluginMetaData objects to convert
487  * @return a list of KPluginInfo objects with equivalent meta data.
488  * @since 5.3
489  * @deprecated Since 5.90, see class API docs
490  */
491  KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
492  static KPluginInfo::List fromMetaData(const QVector<KPluginMetaData> &list);
493 
494 private:
495  friend KSERVICE_EXPORT uint qHash(const KPluginInfo &);
496  QExplicitlySharedDataPointer<KPluginInfoPrivate> d;
497 };
498 
499 KSERVICE_EXPORT uint qHash(const KPluginInfo &);
500 
501 #endif
502 #endif // KPLUGININFO_H
unsigned int version()
QList< KPluginInfo > List
A list of KPluginInfo objects.
Definition: kplugininfo.h:48
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Feb 6 2023 04:00:17 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.