File indexing completed on 2023-12-03 07:47:45

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 2003, 2007 Matthias Kretz <kretz@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-only
0006 */
0007 
0008 #ifndef KPLUGININFO_H
0009 #define KPLUGININFO_H
0010 
0011 #include <QExplicitlySharedDataPointer>
0012 #include <QString>
0013 #include <QStringList>
0014 
0015 #include <KConfigGroup>
0016 #include <QList>
0017 #include <kservice.h>
0018 
0019 class KPluginMetaData;
0020 class KPluginInfoPrivate;
0021 
0022 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 90)
0023 /**
0024  * @class KPluginInfo kplugininfo.h <KPluginInfo>
0025  *
0026  * Information about a plugin.
0027  *
0028  * This holds all the information about a plugin there is. It's used for the
0029  * user to decide whether he wants to use this plugin or not.
0030  *
0031  * @author Matthias Kretz <kretz@kde.org>
0032  * @deprecated since 5.88, use QPluginLoader or the KPluginFactory::loadFactory/KPluginFactory::instantiatePlugins
0033  * methods instead to create objects from the plugins.
0034  * For accessing the metadata, use KPluginMetaData instead.
0035  * To embed json metadata in your plugin, use K_PLUGIN_CLASS_WITH_JSON(MyClass, "mypluginmetadata.json")
0036  *
0037  * The reading of the enabled state can be done using the KPluginMetaData::isEnabled method.
0038  * Writing the config should be done manually. Consider using KPluginWidget for the configuration
0039  * of plugins in the UI.
0040  *
0041  */
0042 class KSERVICE_EXPORT KPluginInfo
0043 {
0044 public:
0045     /**
0046      * A list of KPluginInfo objects.
0047      */
0048     typedef QList<KPluginInfo> List;
0049 
0050     /**
0051      * Read plugin info from @p filename.
0052      *
0053      * The file should be of the following form:
0054      * \verbatim
0055        [Desktop Entry]
0056        Icon=mypluginicon
0057        Type=Service
0058        X-KDE-ServiceTypes=KPluginInfo
0059 
0060        Name=User Visible Name
0061        Comment=Description of what the plugin does
0062 
0063        X-KDE-PluginInfo-Author=Author's Name
0064        X-KDE-PluginInfo-Email=author@foo.bar
0065        X-KDE-PluginInfo-Name=internalname
0066        X-KDE-PluginInfo-Version=1.1
0067        X-KDE-PluginInfo-Website=http://www.plugin.org/
0068        X-KDE-PluginInfo-Category=playlist
0069        X-KDE-PluginInfo-Depends=plugin1,plugin3
0070        X-KDE-PluginInfo-License=GPL
0071        X-KDE-PluginInfo-EnabledByDefault=true
0072        \endverbatim
0073      * The Name and Comment fields must always be present.
0074      *
0075      * The "X-KDE-PluginInfo" keys you may add further entries which
0076      * will be available using property(). The Website,Category,Require
0077      * keys are optional.
0078      * For EnabledByDefault look at isPluginEnabledByDefault.
0079      *
0080      * @param filename  The filename of the .desktop file.
0081      * @param resource  If filename is relative, you need to specify a resource type
0082      * (e.g. "service", "apps"... KStandardDirs). Otherwise,
0083      * resource isn't used.
0084      * @deprecated Since 5.90, see class API docs
0085      */
0086     KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
0087     explicit KPluginInfo(const QString &filename /*, QStandardPaths::StandardLocation resource = ...? GenericDataLocation + services ? Is this used? */);
0088 
0089     /**
0090      * Read plugin info from a KService object.
0091      *
0092      * The .desktop file should look like this:
0093      * \verbatim
0094        [Desktop Entry]
0095        Icon=mypluginicon
0096        Type=Service
0097        X-KDE-ServiceTypes=KPluginInfo
0098 
0099        X-KDE-PluginInfo-Author=Author's Name
0100        X-KDE-PluginInfo-Email=author@foo.bar
0101        X-KDE-PluginInfo-Name=internalname
0102        X-KDE-PluginInfo-Version=1.1
0103        X-KDE-PluginInfo-Website=http://www.plugin.org/
0104        X-KDE-PluginInfo-Category=playlist
0105        X-KDE-PluginInfo-Depends=plugin1,plugin3
0106        X-KDE-PluginInfo-License=GPL
0107        X-KDE-PluginInfo-EnabledByDefault=true
0108 
0109        Name=User Visible Name
0110        Comment=Description of what the plugin does
0111        \endverbatim
0112      * In the first three entries the Icon entry is optional.
0113      * @deprecated Since 5.90, see class API docs
0114      */
0115     KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
0116     explicit KPluginInfo(const KService::Ptr service);
0117 
0118     /**
0119      * Read plugin info from arguments passed to the plugin. These arguments should contain
0120      * the plugin's metadata (as read from QPluginLoader::metaData(). This constructor uses
0121      * the metadata read from the QVariantList. It reads the first QVariantMap it finds in a
0122      * field called "MetaData".
0123      *
0124      * Use (Q|K)PluginLoader and build the metadata into the plugin using
0125      * K_PLUGIN_CLASS_WITH_JSON( ..., "mypluginmetadata.json")
0126      *
0127      * You can use the "desktoptojson tool to generate a .json file from your .desktop file.
0128      * The .json file should look like this:
0129      *
0130      * \verbatim
0131         {
0132             "Comment": "Date and time by timezone",
0133             "Icon": "preferences-system-time",
0134             "Name": "Date and Time",
0135             "Type": "Service",
0136             "X-KDE-Library": "plasma_engine_time",
0137             "X-KDE-PluginInfo-Author": "Aaron Seigo",
0138             "X-KDE-PluginInfo-Category": "Date and Time",
0139             "X-KDE-PluginInfo-Depends": [
0140             ],
0141             "X-KDE-PluginInfo-Email": "aseigo@kde.org",
0142             "X-KDE-PluginInfo-EnabledByDefault": true,
0143             "X-KDE-PluginInfo-License": "LGPL",
0144             "X-KDE-PluginInfo-Name": "time",
0145             "X-KDE-PluginInfo-Version": "1.0",
0146             "X-KDE-PluginInfo-Website": "http://plasma.kde.org/",
0147             "X-KDE-ServiceTypes": [
0148                 "Plasma/DataEngine"
0149             ],
0150             "X-KDE-FormFactors": [
0151                 "tablet",
0152                 "handset"
0153             ]
0154         }
0155        \endverbatim
0156      * @param args QVariantList with arguments, should contain a QVariantMap, keyed "MetaData"
0157      * as provided by QPluginLoader::metaData()
0158      * @param libraryPath The path to the plugin file on disk
0159      *
0160      * \see K_PLUGIN_CLASS_WITH_JSON()
0161      * \see KPluginFactory::factory()
0162      * @since 5.0
0163      * @deprecated Since 5.90, see class API docs
0164      */
0165     KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
0166     explicit KPluginInfo(const QVariantList &args, const QString &libraryPath = QString());
0167 
0168     /**
0169      * Read plugin info from a KPluginMetaData object.
0170      *
0171      * @param md The KPluginMetaData to read the information from
0172      * @see K_PLUGIN_CLASS_WITH_JSON()
0173      * @see KPluginLoader
0174      * @since 5.5
0175      * @deprecated Since 5.90, see class API docs
0176      */
0177     KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
0178     explicit KPluginInfo(const KPluginMetaData &md);
0179 
0180     /**
0181      * Creates an invalid plugin.
0182      *
0183      * \see isValid
0184      */
0185     KPluginInfo();
0186 
0187     ~KPluginInfo();
0188 
0189     /**
0190      * @return A list of KPluginInfo objects constructed from a list of
0191      * KService objects. If you get a trader offer of the plugins you want
0192      * to use you can just pass them to this function.
0193      *
0194      * @param services The list of services to construct the list of KPluginInfo objects from
0195      * @param config The config group where to save/load whether the plugin is enabled/disabled
0196      * @deprecated Since 5.90, see class API docs
0197      */
0198     KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
0199     static KPluginInfo::List fromServices(const KService::List &services, const KConfigGroup &config = KConfigGroup());
0200 
0201     /**
0202      * @return A list of KPluginInfo objects constructed from a list of
0203      * filenames. If you make a lookup using, for example,
0204      * KStandardDirs::findAllResources() you pass the list of files to this
0205      * function.
0206      *
0207      * @param files The list of files to construct the list of KPluginInfo objects from
0208      * @param config The config group where to save/load whether the plugin is enabled/disabled
0209      */
0210     static KPluginInfo::List fromFiles(const QStringList &files, const KConfigGroup &config = KConfigGroup());
0211 
0212 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 81)
0213     /**
0214      * @return A list of KPluginInfo objects for the KParts plugins of a
0215      * component.
0216      *
0217      * @param componentName Use the component name to look up all KParts plugins for it.
0218      * @param config The config group where to save/load whether the plugin is enabled/disabled
0219      * @deprecated since 5.81, removed for lack of usage, KParts loads the plugins all by itself
0220      */
0221     KSERVICE_DEPRECATED_VERSION(5, 81, "Removed for lack of usage, KParts plugins don't use this anymore (or never did)")
0222     static KPluginInfo::List fromKPartsInstanceName(const QString &componentName, const KConfigGroup &config = KConfigGroup());
0223 #endif
0224 
0225     /**
0226      * @return Whether the plugin should be hidden.
0227      */
0228     bool isHidden() const;
0229 
0230     /**
0231      * Set whether the plugin is currently loaded.
0232      *
0233      * @see isPluginEnabled()
0234      * @see save()
0235      */
0236     void setPluginEnabled(bool enabled);
0237 
0238     /**
0239      * @return Whether the plugin is currently loaded.
0240      *
0241      * @see setPluginEnabled()
0242      * @see load()
0243      */
0244     bool isPluginEnabled() const;
0245 
0246     /**
0247      * @return The default value whether the plugin is enabled or not.
0248      * Defaults to the value set in the desktop file, or if that isn't set
0249      * to false.
0250      */
0251     bool isPluginEnabledByDefault() const;
0252 
0253     /**
0254      * @return The value associated to the @p key. You can use it if you
0255      *         want to read custom values. To do this you need to define
0256      *         your own servicetype and add it to the ServiceTypes keys.
0257      */
0258     QVariant property(const QString &key) const;
0259 
0260     /**
0261      * @return All properties of this object. This can be used to read custom values.
0262      * @since 5.3
0263      * @see KPluginInfo::property()
0264      */
0265     QVariantMap properties() const;
0266 
0267     /**
0268      * @return The user visible name of the plugin.
0269      */
0270     QString name() const;
0271 
0272     /**
0273      * @return A comment describing the plugin.
0274      */
0275     QString comment() const;
0276 
0277     /**
0278      * @return The iconname for this plugin
0279      */
0280     QString icon() const;
0281 
0282     /**
0283      * @return The file containing the information about the plugin.
0284      */
0285     QString entryPath() const;
0286 
0287     /**
0288      * @return The author of this plugin.
0289      */
0290     QString author() const;
0291 
0292     /**
0293      * @return The email address of the author.
0294      */
0295     QString email() const;
0296 
0297     /**
0298      * @return The category of this plugin (e.g. playlist/skin).
0299      */
0300     QString category() const;
0301 
0302     /**
0303      * @return The internal name of the plugin (for KParts Plugins this is
0304      * the same name as set in the .rc file).
0305      */
0306     QString pluginName() const;
0307 
0308     /**
0309      * @return The version of the plugin.
0310      */
0311     QString version() const;
0312 
0313     /**
0314      * @return The website of the plugin/author.
0315      */
0316     QString website() const;
0317 
0318     /**
0319      * @return The license keyword of this plugin.
0320      */
0321     QString license() const;
0322 
0323 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 79)
0324 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 79)
0325     /**
0326      * @return A list of plugins required for this plugin to be enabled. Use
0327      *         the pluginName in this list.
0328      * @deprecated Since 5.79, plugin dependencies are deprecated and will be removed in KF6
0329      */
0330     KSERVICE_DEPRECATED_VERSION(5, 79, "Plugin dependencies are deprecated and will be removed in KF6")
0331     QStringList dependencies() const;
0332 #endif
0333 #endif
0334 
0335     /**
0336      * @return A list of ServiceTypes this plugin offers
0337      * @since 5.0
0338      */
0339     QStringList serviceTypes() const;
0340 
0341     /**
0342      * @return A list of FormFactors this plugin offers, corresponds to the
0343      * "X-KDE-FormFactors" value in a .desktop service file, or to the "FormFactors"
0344      * value in the "KPlugin" block of the json metadata. Formfactor values are
0345      * freestyle, common values are "desktop", "handset", "tablet", "mediacenter".
0346      * Values are comma-separated.
0347      * @since 5.14
0348      */
0349     QStringList formFactors() const;
0350 
0351     /**
0352      * @return The absolute path of the plugin on disk. This can be used to load the plugin from, using
0353      * KPluginLoader or QPluginLoader
0354      * @since 5.0
0355      */
0356     QString libraryPath() const;
0357     // visibility check set to a later version because the BUILD variant was used before
0358 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 88)
0359     /**
0360      * @return The KService object for this plugin. You might need it if you
0361      *         want to read custom values. To do this you need to define
0362      *         your own servicetype and add it to the ServiceTypes keys.
0363      *         Then you can use the KService::property() method to read your
0364      *         keys.
0365      *
0366      * @see property()
0367      *
0368      * @deprecated since 5.70, use KPluginMetaData and KPluginLoader(info.libraryPath())
0369      */
0370     KSERVICE_DEPRECATED_VERSION(5, 70, "Use KPluginMetaData and KPluginLoader(info.libraryPath())")
0371     KService::Ptr service() const;
0372 #endif
0373 
0374     /**
0375      * @return A list of Service pointers if the plugin installs one or more
0376      *         KCModule
0377      */
0378     QList<KService::Ptr> kcmServices() const;
0379 
0380     /**
0381      * Set the KConfigGroup to use for load()ing and save()ing the
0382      * configuration. This will be overridden by the KConfigGroup passed to
0383      * save() or load() (if one is passed).
0384      */
0385     void setConfig(const KConfigGroup &config);
0386 
0387     /**
0388      * @return If the KPluginInfo object has a KConfig object set return
0389      * it, else returns an invalid KConfigGroup.
0390      */
0391     KConfigGroup config() const;
0392 
0393     /**
0394      * Save state of the plugin - enabled or not.
0395      *
0396      * @param config    The KConfigGroup holding the information whether
0397      *                  plugin is enabled.
0398      */
0399     void save(KConfigGroup config = KConfigGroup());
0400 
0401     /**
0402      * Load the state of the plugin - enabled or not.
0403      *
0404      * @param config    The KConfigGroup holding the information whether
0405      *                  plugin is enabled.
0406      */
0407     void load(const KConfigGroup &config = KConfigGroup());
0408 
0409     /**
0410      * Restore defaults (enabled or not).
0411      */
0412     void defaults();
0413 
0414     /**
0415      * Returns whether the object is valid. Treat invalid KPluginInfo objects like you would
0416      * treat a null pointer.
0417      */
0418     bool isValid() const;
0419 
0420     /**
0421      * Creates a KPluginInfo object that shares the data with \p copy.
0422      */
0423     KPluginInfo(const KPluginInfo &copy);
0424 
0425     /**
0426      * Copies the KPluginInfo object to share the data with \p copy.
0427      */
0428     KPluginInfo &operator=(const KPluginInfo &rhs);
0429 
0430     /**
0431      * Compares two objects whether they share the same data.
0432      */
0433     bool operator==(const KPluginInfo &rhs) const;
0434 
0435     /**
0436      * Compares two objects whether they don't share the same data.
0437      */
0438     bool operator!=(const KPluginInfo &rhs) const;
0439 
0440     /**
0441      * Less than relation comparing the categories and if they are the same using the names.
0442      */
0443     bool operator<(const KPluginInfo &rhs) const;
0444 
0445     /**
0446      * Greater than relation comparing the categories and if they are the same using the names.
0447      */
0448     bool operator>(const KPluginInfo &rhs) const;
0449 
0450     friend class KPluginTrader;
0451 
0452     /**
0453      * @return a KPluginMetaData object with equivalent meta data.
0454      * @since 5.3
0455      */
0456     KPluginMetaData toMetaData() const;
0457 
0458     /**
0459      * @param info the KPluginInfo object to convert
0460      * @return a KPluginMetaData object with equivalent meta data.
0461      * @since 5.3
0462      * @deprecated Since 5.90, see class API docs
0463      */
0464     KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
0465     static KPluginMetaData toMetaData(const KPluginInfo &info);
0466 
0467     /**
0468      * @param meta the KPluginMetaData to convert
0469      * @return a KPluginInfo object with equivalent meta data.
0470      * @since 5.3
0471      * @deprecated Since 5.90, see class API docs
0472      */
0473     KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
0474     static KPluginInfo fromMetaData(const KPluginMetaData &meta);
0475 
0476     /**
0477      * @param list the list of KPluginInfo objects to convert
0478      * @return a list of KPluginMetaData objects with equivalent meta data.
0479      * @since 5.3
0480      * @deprecated Since 5.90, see class API docs
0481      */
0482     KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
0483     static QVector<KPluginMetaData> toMetaData(const KPluginInfo::List &list);
0484 
0485     /**
0486      * @param list the list of KPluginMetaData objects to convert
0487      * @return a list of KPluginInfo objects with equivalent meta data.
0488      * @since 5.3
0489      * @deprecated Since 5.90, see class API docs
0490      */
0491     KSERVICE_DEPRECATED_VERSION(5, 90, "see class API docs")
0492     static KPluginInfo::List fromMetaData(const QVector<KPluginMetaData> &list);
0493 
0494 private:
0495     friend KSERVICE_EXPORT uint qHash(const KPluginInfo &);
0496     QExplicitlySharedDataPointer<KPluginInfoPrivate> d;
0497 };
0498 
0499 KSERVICE_EXPORT uint qHash(const KPluginInfo &);
0500 
0501 #endif
0502 #endif // KPLUGININFO_H