KCMUtils

dialog.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 2003 Matthias Kretz <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-only
6 */
7 
8 #ifndef KSETTINGS_DIALOG_H
9 #define KSETTINGS_DIALOG_H
10 
11 #include <kcmultidialog.h>
12 #include <kcmutils_export.h>
13 
14 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 85)
15 #include <KPluginInfo>
16 #include <KService>
17 
18 template<class T>
19 class QList;
20 class KCModuleInfo;
21 
22 namespace KSettings
23 {
24 class DialogPrivate;
25 
26 /**
27  * @short Generic configuration dialog that works over component boundaries
28  *
29  * For more information see \ref KSettings.
30  *
31  * This class aims to standardize the use of configuration dialogs in applications.
32  * Especially when using KParts and/or Plugins you face problems creating consistent
33  * config dialogs.
34  *
35  * To show a configuration dialog you only have to call the show method and be
36  * done with it. A code example:
37  *
38  * You initialize @c m_cfgdlg with
39  * @code
40  * m_cfgdlg = new Dialog(this);
41  * @endcode
42  *
43  * If you use a KPart that was not especially designed for your app you can use
44  * the second constructor:
45  * @code
46  * QStringList kpartslist;
47  * for (all my kparts) {
48  * kpartslist += m_mypart->componentData().componentName();
49  * }
50  *
51  * m_cfgdlg = new Dialog(kpartslist, this);
52  * @endcode
53  *
54  * and ideally you can connect the "Configure MyApp" action to the config
55  * dialog show() slot:
56  * @code
57  * KStandardAction::preferences(m_cfgdlg, &QDialog::show, actionCollection());
58  * @endcode
59  *
60  * If you need to be informed when the config is changed by the dialog, you can
61  * connect to the @c KCMultiDialog::configCommitted() signal (which emits the
62  * component name as its argument):
63  * @code
64  * connect(m_cfgdlg, QOverload<const QByteArray &>::of(&KCMultiDialog::configCommitted), this, &Foo::slotConfigUpdated);
65  * @endcode
66  *
67  * @see KSettings.
68  *
69  * @author Matthias Kretz <[email protected]>
70  */
71 class KCMUTILS_EXPORT Dialog : public KCMultiDialog
72 {
73  friend class PageNode;
74  Q_DECLARE_PRIVATE(Dialog)
75  Q_OBJECT
76 public:
77  /**
78  * Construct a new Preferences Dialog for the application. It uses all
79  * KCMs with X-KDE-ParentApp set to QCoreApplication::instance()->applicationName().
80  *
81  * @param content Select whether you want a static or configurable
82  * config dialog.
83  * @param parent The parent is only used as the parent for the
84  * dialog - centering the dialog over the parent
85  * widget.
86  * @deprecated Since 5.85, use @ref KCMultiDialog instead
87  */
88  KCMUTILS_DEPRECATED_VERSION(5, 85, "use KCMultiDialog instead")
89  explicit Dialog(QWidget *parent = nullptr);
90 
91  /**
92  * Construct a new Preferences Dialog with the pages for the selected
93  * instance names. For example if you want to have the configuration
94  * pages for the kviewviewer KPart you would pass a
95  * QStringList consisting of only the name of the part "kviewviewer".
96  *
97  * @param components A list of the names of the components that your
98  * config dialog should merge the config pages in.
99  * @param parent The parent is only used as the parent for the
100  * dialog - centering the dialog over the parent
101  * widget.
102  * @deprecated Since 5.85, use @ref KCMultiDialog instead
103  */
104  KCMUTILS_DEPRECATED_VERSION(5, 85, "use KCMultiDialog instead")
105  explicit Dialog(const QStringList &components, QWidget *parent = nullptr);
106 
107  ~Dialog() override;
108 
109  /**
110  * If you use a Configurable dialog you need to pass KPluginInfo
111  * objects that the dialog should configure.
112  */
113  void addPluginInfos(const QList<KPluginInfo> &plugininfos);
114 
115  /**
116  * Sets the argument list that is given to all the KControlModule's when
117  * they are created.
118  * Use this if you have KControlModule's that need special arguments to
119  * work
120  *
121  * Note that this function only works before showing the
122  * KSettings::Dialog for the first time.
123  * @param arguments The list of arguments passed to each KCM
124  */
125  void setKCMArguments(const QStringList &arguments);
126 
127  /**
128  * Set the blacklisted component list. Any KCM that lists one
129  * of the components in the given blacklist is not loaded even if it
130  * would fit otherwise. This is a way to explicitly prevent loading of
131  * certain KControlModules.
132  *
133  * Note that this function only works before showing the
134  * KSettings::Dialog for the first time.
135  * @param blacklist the list of components that prevent a KCM from being
136  * loaded
137  */
138  void setComponentBlacklist(const QStringList &blacklist);
139 
140  /**
141  * Tells the dialog whether the entries in the listview are all static
142  * or whether it should add checkboxes to select which parts
143  * of the optional functionality should be active or not.
144  *
145  * Note that this function only works before showing the dialog for the first time.
146  *
147  * Defaults to \p false.
148  *
149  * @param allowSelection \p true The user can select what functionality he wants.
150  * @param allowSelection \p false While running no entries are added or deleted
151  */
152  void setAllowComponentSelection(bool allowSelection);
153 
154  bool allowComponentSelection() const;
155 
156  /**
157  * Returns a list of all KPluginInfo objects the dialog uses.
158  */
159  QList<KPluginInfo> pluginInfos() const;
160 
161 protected:
162  /**
163  * Reimplemented to lazy create the dialog on first show.
164  */
165  void showEvent(QShowEvent *) override;
166 
167 Q_SIGNALS:
168  /**
169  * If you use the dialog in Configurable mode and want to be notified
170  * when the user changes the plugin selections use this signal. It's
171  * emitted if the selection has changed and the user pressed Apply or
172  * Ok. In the slot you would then load and unload the plugins as
173  * requested.
174  */
175  void pluginSelectionChanged();
176 
177 private:
178  // Q_PRIVATE_SLOT(d_func(), void _k_configureTree())
179  Q_PRIVATE_SLOT(d_func(), void _k_updateEnabledState(bool))
180 };
181 
182 }
183 
184 #endif // KSETTINGS_DIALOG_H
185 #endif
Definition: dialog.h:19
A collection of classes to create configuration dialogs that work over component boundaries.
Definition: dialog.cpp:35
A class that provides information about a KCModule.
Definition: kcmoduleinfo.h:36
Generic configuration dialog that works over component boundaries.
Definition: dialog.h:71
A class that offers a KPageDialog containing arbitrary KControl Modules.
Definition: kcmultidialog.h:28
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jun 25 2022 06:17:34 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.