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
25 * \inmodule KCMUtils
26 *
27 * \brief A widget that shows a list of available plugins
28 * and allows to disable/enable them and open their configuration UI.
29 *
30 * Plugins that get added to the KPluginWidget need to define the \c X-KDE-ConfigModule property.
31 * The value for this property is the namespace and file name of the KCM for the plugin.
32 *
33 * An example value is "kf6/krunner/kcms/kcm_krunner_charrunner",
34 * "kf6/krunner/kcms" is the namespace and "kcm_krunner_charrunner"
35 * the file name. The loaded KCMs don't need any embedded JSON metadata.
36 *
37 * \since 5.89
38 */
39class KCMUTILS_EXPORT KPluginWidget : public QWidget
40{
41 Q_OBJECT
42
43public:
44 /*!
45 *
46 */
47 explicit KPluginWidget(QWidget *parent = nullptr);
48
49 ~KPluginWidget();
50
51 /*!
52 * \brief Adds the \a plugins with the given \a categoryLabel to the widget.
53 */
54 void addPlugins(const QList<KPluginMetaData> &plugins, const QString &categoryLabel);
55
56 /*!
57 * \brief Sets the \a config object that will be used to store the enabled state of the plugins.
58 *
59 * When porting away from KPluginSelector, the "Plugins" group
60 * from the config root should be used. For example:
61 * \code
62 * KSharedConfig::openConfig(QStringLiteral("krunnerrc"))->group("Plugins")
63 * \endcode
64 */
65 void setConfig(const KConfigGroup &config);
66
67 /*!
68 * \brief Clears all the added plugins and any unsaved changes.
69 */
70 void clear();
71
72 /*!
73 * \brief Saves the changes to the config set by \l setConfig.
74 */
75 void save();
76
77 /*!
78 * \brief Loads the enabled state of the plugins from the config set
79 * by setConfig() and clears any changes by the user.
80 * \since 5.91
81 */
82 void load();
83
84 /*!
85 * \brief Resets the enabled state of the plugins to their defaults.
86 * \sa KPluginMetaData::isEnabledByDefault
87 */
88 void defaults();
89
90 /*!
91 * \brief Returns \c true if the enabled state of each plugin is the same as that plugin's default state.
92 */
93 bool isDefault() const;
94
95 /*!
96 * \brief Returns true if the plugin selector has any changes that are not yet saved to configuration.
97 * \sa save()
98 */
99 bool isSaveNeeded() const;
100
101 /*!
102 * \brief Sets the \a arguments with which the configuration modules will be initialized.
103 */
104 void setConfigurationArguments(const QVariantList &arguments);
105
106 /*!
107 * \brief Returns the configuration arguments that will be used.
108 */
109 QVariantList configurationArguments() const;
110
111 /*!
112 * \brief Shows the configuration dialog for the plugin \a pluginId if it's available.
113 */
114 void showConfiguration(const QString &pluginId);
115
116 /*!
117 * \brief Shows an indicator when a plugin status is different from default.
118 *
119 * \a isVisible Whether the indicator is visible.
120 */
121 void setDefaultsIndicatorsVisible(bool isVisible);
122
123 /*!
124 * \brief Add additional widgets to each row of the plugin selector.
125 *
126 * \a handler Returns the additional button that should be displayed in the row;
127 * the handler can return a null pointer if no button should be displayed.
128 */
129 void setAdditionalButtonHandler(const std::function<QPushButton *(const KPluginMetaData &)> &handler);
130
131Q_SIGNALS:
132 /*!
133 * \brief Emitted when any of the plugins are changed.
134 *
135 * \a pluginId The ID of the changed plugin.
136 *
137 * \a enabled Whether the given plugin is currently enabled.
138 */
139 void pluginEnabledChanged(const QString &pluginId, bool enabled);
140
141 /*!
142 * \brief Emitted when any of the plugins are changed.
143 *
144 * \a enabled Whether the given plugin is enabled.
145 *
146 * \sa isSaveNeeded()
147 */
148 void changed(bool enabled);
149
150 /*!
151 * \brief Emitted after the config of an embedded KCM has been saved.
152 *
153 * The \a pluginId is the name of the parent component
154 * that needs to reload its config.
155 */
156 void pluginConfigSaved(const QString &pluginId);
157
158 /*!
159 * \brief Emitted after configuration is changed.
160 *
161 * \a isDefault Returns whether the configuration state is the default.
162 */
163 void defaulted(bool isDefault);
164
165private:
166 std::unique_ptr<KPluginWidgetPrivate> const d;
167};
168
169#endif
170

source code of kcmutils/src/kpluginwidget.h