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