File indexing completed on 2024-05-05 12:10:57
0001 /* 0002 SPDX-FileCopyrightText: 2021 Nicolas Fella <nicolas.fella@gmx.de> 0003 SPDX-FileCopyrightText: 2021 Alexander Lohnau <alexander.lohnau@gmx.de> 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef KPLUGINWIDGET_H 0009 #define KPLUGINWIDGET_H 0010 0011 #include <QVector> 0012 #include <QWidget> 0013 0014 #include <KPluginMetaData> 0015 #include <KSharedConfig> 0016 #include <kcmutils_export.h> 0017 0018 #include <memory> 0019 0020 class QPushButton; 0021 class KPluginWidgetPrivate; 0022 0023 /** 0024 * A widget that shows a list of available plugins and allows to disable/enable them and open their configuration UI. 0025 * 0026 * For compatibility the KServiceTypeTrader querying of the associated KCMs for the plugins is still supported. 0027 * However it is recommended to define the "X-KDE-ConfigModule" property in the plugins that 0028 * get added to the KPluginWidget. The value for this property is the namespace and file name of the 0029 * KCM for the plugin. An example value is "kf5/krunner/kcms/kcm_krunner_charrunner", "kf5/krunner/kcms" is the namespace 0030 * and "kcm_krunner_charrunner" the file name. The loaded KCMs don't need any embedded json metadata and the old desktop files 0031 * that were used for querying can be removed. 0032 * @since 5.89 0033 */ 0034 class KCMUTILS_EXPORT KPluginWidget : public QWidget 0035 { 0036 Q_OBJECT 0037 0038 public: 0039 KPluginWidget(QWidget *parent = nullptr); 0040 0041 ~KPluginWidget(); 0042 0043 /** 0044 * Adds the plugins with the given label to the widget 0045 */ 0046 void addPlugins(const QVector<KPluginMetaData> &plugins, const QString &categoryLabel); 0047 0048 /** 0049 * Set the config object that will be used to store the enabled state of the plugins. 0050 * When porting away from KPluginSelector, the "Plugins" group from the config root should 0051 * be used. For example: 0052 * @code 0053 * KSharedConfig::openConfig(QStringLiteral("krunnerrc"))->group("Plugins") 0054 * @endcode 0055 */ 0056 void setConfig(const KConfigGroup &config); 0057 0058 /** 0059 * Clears all the added plugins and any unsaved changes. 0060 */ 0061 void clear(); 0062 0063 /** 0064 * Saves the changes to the config set by @ref setConfig. 0065 */ 0066 void save(); 0067 0068 /** 0069 * Loads the enabled state of the plugins from the config set by setConfig() 0070 * and clears any changes by the user. 0071 * @since 5.91 0072 */ 0073 void load(); 0074 0075 /** 0076 * Resets the enabled state of the plugins to their defaults 0077 * @see KPluginMetaData::isEnabledByDefault 0078 */ 0079 void defaults(); 0080 0081 /** 0082 * Returns @c true if the enabled state of each plugin is the same as that plugin's default state. 0083 */ 0084 bool isDefault() const; 0085 0086 /** 0087 * Returns true if the plugin selector has any changes that are not yet saved to configuration. 0088 * @see save() 0089 */ 0090 bool isSaveNeeded() const; 0091 0092 /** 0093 * Sets the @p arguments with which the configuration modules will be initialized 0094 */ 0095 void setConfigurationArguments(const QStringList &arguments); 0096 0097 /** 0098 * Returns the configuration arguments that will be used 0099 */ 0100 QStringList configurationArguments() const; 0101 0102 /** 0103 * Shows the configuration dialog for the plugin @p pluginId if it's available 0104 */ 0105 void showConfiguration(const QString &pluginId); 0106 0107 /** 0108 * Shows an indicator when a plugin status is different from default 0109 */ 0110 void setDefaultsIndicatorsVisible(bool isVisible); 0111 0112 /** 0113 * Add additional widgets to each row of the plugin selector 0114 * @param handler returns the additional button that should be displayed in the row; 0115 * the handler can return a null pointer if no button should be displayed 0116 */ 0117 void setAdditionalButtonHandler(const std::function<QPushButton *(const KPluginMetaData &)> &handler); 0118 0119 Q_SIGNALS: 0120 /** 0121 * Emitted when any of the plugins are changed. 0122 * @param pluginId id of the changed plugin 0123 * @param enabled if the given plugin is currently enabled or disabled 0124 */ 0125 void pluginEnabledChanged(const QString &pluginId, bool enabled); 0126 0127 /** 0128 * Emitted when any of the plugins are changed. 0129 * @param changed if the KPluginWidget object contains changes 0130 * @see needsSave 0131 */ 0132 void changed(bool enabled); 0133 0134 /** 0135 * Emitted after the config of an embedded KCM has been saved. The 0136 * argument is the name of the parent component that needs to reload 0137 * its config. 0138 */ 0139 void pluginConfigSaved(const QString &pluginId); 0140 0141 /** 0142 * Emitted after configuration is changed. 0143 * 0144 * @p isDefault @c true if the configuration state is the default, @c false otherwise 0145 */ 0146 void defaulted(bool isDefault); 0147 0148 private: 0149 std::unique_ptr<KPluginWidgetPrivate> const d; 0150 }; 0151 0152 #endif