KCMUtils

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

KDE's Doxygen guidelines are available online.