KCMUtils

kpluginselector.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 2007, 2006 Rafael Fernández López <[email protected]>
4  SPDX-FileCopyrightText: 2002-2003 Matthias Kretz <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-only
7 */
8 
9 #ifndef KPLUGINSELECTOR_H
10 #define KPLUGINSELECTOR_H
11 
12 #include <kcmutils_export.h>
13 
14 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 90)
15 
16 #include <QWidget>
17 
18 #include <QList>
19 
20 #include <KSharedConfig>
21 
22 class KPluginInfo;
23 class QPushButton;
24 
25 /**
26  * @short A widget to select what plugins to load and configure the plugins.
27  *
28  * It shows the list of available plugins
29  *
30  * Since the user needs a way to know what a specific plugin does every plugin
31  * should install a desktop file containing a name, comment and category field.
32  * The category is useful for applications that can use different kinds of
33  * plugins like a playlist, skin or visualization
34  *
35  * The location of these desktop files is the
36  * share/apps/&lt;instancename&gt;/&lt;plugindir&gt; directory. But if you need
37  * you may use a different directory
38  *
39  * You can add plugins from different KConfig[group], by just calling all times
40  * you want addPlugins method with the correct parameters
41  *
42  * Additionally, calls to constructor with same @p categoryName, will add new
43  * items to the same category, even if plugins are from different categories
44  *
45  * @author Matthias Kretz <[email protected]>
46  * @author Rafael Fernández López <[email protected]>
47  * @deprecated Since 5.90, use KPluginWidget instead
48  */
49 class KCMUTILS_EXPORT KPluginSelector : public QWidget
50 {
51  Q_OBJECT
52  Q_PROPERTY(QStringList configurationArguments READ configurationArguments WRITE setConfigurationArguments)
53 
54 public:
55  enum PluginLoadMethod {
56  ReadConfigFile = 0,
57  IgnoreConfigFile,
58  };
59 
60  /**
61  * Create a new KPluginSelector
62  */
63  KCMUTILS_DEPRECATED_VERSION(5, 90, "Use KPluginWidget instead")
64  KPluginSelector(QWidget *parent = nullptr);
65 
66  /**
67  * Destructor
68  */
69  ~KPluginSelector() override;
70 
71  /**
72  * Add a list of KParts plugins
73  *
74  * The information about the plugins will be loaded from the
75  * share/apps/&lt;instancename&gt;/kpartplugins directory
76  *
77  * @param componentName The name of the component of the plugin's parent.
78  * @param categoryName The translated name of the category. This is the
79  * name that is shown in the title. If the category
80  * did exist before because of another call to
81  * addPlugins, then they will be shown in that
82  * category. If @p categoryName is a new one, then
83  * a new category will be shown on the plugin window,
84  * and the list of plugins added to it
85  * @param categoryKey When you have different categories of KParts
86  * plugins you distinguish between the plugins using
87  * the Category key in the .desktop file. Use this
88  * parameter to select only those KParts plugins
89  * with the Category key == @p categoryKey. If
90  * @p categoryKey is not set the Category key is
91  * ignored and all plugins are shown. Not match case
92  * @param config The KConfig object that holds the state of the
93  * plugins being enabled or not. By default it will be
94  * set to KSharedConfig::openConfig(componentName + "rc").
95  */
96  void addPlugins(const QString &componentName,
97  const QString &categoryName = QString(),
98  const QString &categoryKey = QString(),
99  KSharedConfig::Ptr config = KSharedConfig::Ptr());
100 
101  /**
102  * Add a list of non-KParts plugins
103  *
104  * @param pluginInfoList A list of KPluginInfo objects containing the
105  * necessary information for the plugins you want to
106  * add to the list
107  * @param pluginLoadMethod If KPluginSelector will try to load the
108  * state of the plugin when loading the
109  * dialog from the configuration file or not.
110  * This is useful if for some reason you
111  * called the setPluginEnabled() for each plugin
112  * individually before loading the dialog, and
113  * don't want KPluginSelector to override them
114  * when loading
115  * @param categoryName The translated name of the category. This is the
116  * name that is shown in the title. If the category
117  * did exist before because of another call to
118  * addPlugins, then they will be shown in that
119  * category. If @p categoryName is a new one, then
120  * a new category will be shown on the plugin window,
121  * and the list of plugins added to it
122  * @param categoryKey When you have different categories of KParts
123  * plugins you distinguish between the plugins using
124  * the Category key in the .desktop file. Use this
125  * parameter to select only those KParts plugins
126  * with the Category key == @p categoryKey. If
127  * @p categoryKey is not set the Category key is
128  * ignored and all plugins are shown. Not match case
129  * @param config The KConfig object that holds the state of the
130  * plugins being enabled or not. By default it will
131  * use KSharedConfig::openConfig(). It is recommended to
132  * always pass a KConfig object if you use
133  * KSettings::PluginPage since you never know from
134  * where the page will be called (think global
135  * config app). For example KViewCanvas passes
136  * KConfig("kviewcanvas")
137  *
138  * @note All plugins that were set a config group using setConfig() method
139  * will load and save their information from there. For those that
140  * weren't any config object, @p config will be used
141  */
142  void addPlugins(const QList<KPluginInfo> &pluginInfoList,
143  PluginLoadMethod pluginLoadMethod = ReadConfigFile,
144  const QString &categoryName = QString(),
145  const QString &categoryKey = QString(),
146  const KSharedConfig::Ptr &config = KSharedConfig::Ptr());
147 
148  /**
149  * Remove all plugins from the entry list.
150  * @since 5.73
151  */
152  void clearPlugins();
153 
154  /**
155  * Load the state of the plugins (selected or not) from the KPluginInfo
156  * objects
157  */
158  void load();
159 
160  /**
161  * Save the configuration
162  */
163  void save();
164 
165  /**
166  * Returns true if the plugin selector has any changes that are not yet saved to configuration.
167  * @see save()
168  * @since 5.78
169  */
170  bool isSaveNeeded() const;
171 
172  /**
173  * Change to applications defaults
174  * @see isDefault()
175  */
176  void defaults();
177 
178  /**
179  * Returns true if the plugin selector does not have any changes to application defaults
180  * @see defaults()
181  * @since 4.3
182  */
183  bool isDefault() const;
184 
185  /**
186  * Updates plugins state (enabled or not)
187  *
188  * This method won't save anything on any configuration file. It will just
189  * be useful if you added plugins with the method:
190  *
191  * \code
192  * void addPlugins(const QList<KPluginInfo> &pluginInfoList,
193  * const QString &categoryName = QString(),
194  * const QString &categoryKey = QString(),
195  * const KSharedConfig::Ptr &config = KSharedConfig::Ptr());
196  * \endcode
197  *
198  * To sum up, this method will update your plugins state depending if plugins
199  * are ticked or not on the KPluginSelector dialog, without saving anything
200  * anywhere
201  */
202  void updatePluginsState();
203 
204  /**
205  * Sets the @p arguments with which the configuration modules will be initialized
206  *
207  * @since 5.9
208  */
209  void setConfigurationArguments(const QStringList &arguments);
210 
211  /**
212  * Returns the configuration arguments that will be used
213  *
214  * @since 5.9
215  */
216  QStringList configurationArguments() const;
217 
218  /**
219  * Shows the configuration dialog for the plugin @p pluginId if it's available
220  *
221  * @since 5.45
222  */
223  void showConfiguration(const QString &pluginId);
224 
225  /**
226  * Add additional widgets to each row of the plugin selector
227  * @param handler returns the additional button that should be displayed in the row
228  * the handler can return a null pointer if no button should be displayed
229  * @since 5.74
230  */
231  void setAdditionalButtonHandler(std::function<QPushButton *(const KPluginInfo &)> handler);
232 
233  /**
234  * Show an indicator when a plugin status is different from default
235  *
236  * @since 5.78
237  */
238  void setDefaultsIndicatorsVisible(bool isVisible);
239 
240 Q_SIGNALS:
241  /**
242  * Tells you whether the configuration is changed or not.
243  */
244  void changed(bool hasChanged);
245 
246  /**
247  * Emitted after the config of an embedded KCM has been saved. The
248  * argument is the name of the parent component that needs to reload
249  * its config
250  */
251  void configCommitted(const QByteArray &componentName);
252 
253  /**
254  * Emitted after configuration is changed, tell if configuration represent default or not
255  * @since 5.67
256  */
257  void defaulted(bool isDefault);
258 
259  /**
260  * Emitted when show defaults indicators changed
261  * @see setDefaultsIndicatorsVisible
262  *
263  * @since 5.78
264  */
265  void defaultsIndicatorsVisible();
266 
267 private:
268  class Private;
269  Private *const d;
270 };
271 
272 #endif
273 #endif
Q_PROPERTY(...)
A widget to select what plugins to load and configure the plugins.
Definition: dialog.h:19
Q_SIGNALSQ_SIGNALS
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Fri May 27 2022 03:51:38 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.