1/*
2 SPDX-FileCopyrightText: 2021 Nicolas Fella <nicolas.fella@gmx.de>
3 SPDX-FileCopyrightText: 2021 Alexander Lohnau <alexander.lohnau@gmx.de>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KPLUGINWIDGET_H
9#define KPLUGINWIDGET_H
10
11#include <QList>
12#include <QWidget>
13
14#include <KPluginMetaData>
15#include <KSharedConfig>
16#include <kcmutils_export.h>
17
18#include <memory>
19
20class QPushButton;
21class KPluginWidgetPrivate;
22
23/**
24 * @class KPluginWidget kpluginwidget.h KPluginWidget
25 * A widget that shows a list of available plugins and allows to disable/enable them and open their configuration UI.
26 *
27 * Plugins that get added to the KPluginWidget need to define the @c X-KDE-ConfigModule property.
28 * The value for this property is the namespace and file name of the KCM for the plugin.
29 * An example value is "kf6/krunner/kcms/kcm_krunner_charrunner", "kf6/krunner/kcms" is the namespace
30 * and "kcm_krunner_charrunner" the file name. The loaded KCMs don't need any embedded json metadata.
31 * @since 5.89
32 */
33class KCMUTILS_EXPORT KPluginWidget : public QWidget
34{
35 Q_OBJECT
36
37public:
38 explicit KPluginWidget(QWidget *parent = nullptr);
39
40 ~KPluginWidget();
41
42 /**
43 * Adds the plugins with the given label to the widget
44 */
45 void addPlugins(const QList<KPluginMetaData> &plugins, const QString &categoryLabel);
46
47 /**
48 * Set the config object that will be used to store the enabled state of the plugins.
49 * When porting away from KPluginSelector, the "Plugins" group from the config root should
50 * be used. For example:
51 * @code
52 * KSharedConfig::openConfig(QStringLiteral("krunnerrc"))->group("Plugins")
53 * @endcode
54 */
55 void setConfig(const KConfigGroup &config);
56
57 /**
58 * Clears all the added plugins and any unsaved changes.
59 */
60 void clear();
61
62 /**
63 * Saves the changes to the config set by @ref setConfig.
64 */
65 void save();
66
67 /**
68 * Loads the enabled state of the plugins from the config set by setConfig()
69 * and clears any changes by the user.
70 * @since 5.91
71 */
72 void load();
73
74 /**
75 * Resets the enabled state of the plugins to their defaults
76 * @see KPluginMetaData::isEnabledByDefault
77 */
78 void defaults();
79
80 /**
81 * Returns @c true if the enabled state of each plugin is the same as that plugin's default state.
82 */
83 bool isDefault() const;
84
85 /**
86 * Returns true if the plugin selector has any changes that are not yet saved to configuration.
87 * @see save()
88 */
89 bool isSaveNeeded() const;
90
91 /**
92 * Sets the @p arguments with which the configuration modules will be initialized
93 */
94 void setConfigurationArguments(const QVariantList &arguments);
95
96 /**
97 * Returns the configuration arguments that will be used
98 */
99 QVariantList configurationArguments() const;
100
101 /**
102 * Shows the configuration dialog for the plugin @p pluginId if it's available
103 */
104 void showConfiguration(const QString &pluginId);
105
106 /**
107 * Shows an indicator when a plugin status is different from default
108 */
109 void setDefaultsIndicatorsVisible(bool isVisible);
110
111 /**
112 * Add additional widgets to each row of the plugin selector
113 * @param handler returns the additional button that should be displayed in the row;
114 * the handler can return a null pointer if no button should be displayed
115 */
116 void setAdditionalButtonHandler(const std::function<QPushButton *(const KPluginMetaData &)> &handler);
117
118Q_SIGNALS:
119 /**
120 * Emitted when any of the plugins are changed.
121 * @param pluginId id of the changed plugin
122 * @param enabled if the given plugin is currently enabled or disabled
123 */
124 void pluginEnabledChanged(const QString &pluginId, bool enabled);
125
126 /**
127 * Emitted when any of the plugins are changed.
128 * @param changed if the KPluginWidget object contains changes
129 * @see needsSave
130 */
131 void changed(bool enabled);
132
133 /**
134 * Emitted after the config of an embedded KCM has been saved. The
135 * argument is the name of the parent component that needs to reload
136 * its config.
137 */
138 void pluginConfigSaved(const QString &pluginId);
139
140 /**
141 * Emitted after configuration is changed.
142 *
143 * @p isDefault @c true if the configuration state is the default, @c false otherwise
144 */
145 void defaulted(bool isDefault);
146
147private:
148 std::unique_ptr<KPluginWidgetPrivate> const d;
149};
150
151#endif
152

source code of kcmutils/src/kpluginwidget.h