KCMUtils

kcmultidialog.h
1 /*
2  SPDX-FileCopyrightText: 2000 Matthias Elter <[email protected]>
3  SPDX-FileCopyrightText: 2003 Daniel Molkentin <[email protected]>
4  SPDX-FileCopyrightText: 2003, 2006 Matthias Kretz <[email protected]>
5  SPDX-FileCopyrightText: 2021 Alexander Lohnau <[email protected]>
6 
7  SPDX-License-Identifier: LGPL-2.0-or-later
8 */
9 
10 #ifndef KCMULTIDIALOG_H
11 #define KCMULTIDIALOG_H
12 
13 #include <QScrollArea>
14 #include <QScrollBar>
15 
16 #include <KPageDialog>
17 #include <KPluginMetaData>
18 #include <kcmoduleinfo.h>
19 
20 class KCMultiDialogPrivate;
21 
22 /**
23  * @short A class that offers a KPageDialog containing arbitrary
24  * KControl Modules.
25  *
26  * @author Matthias Elter <[email protected]>, Daniel Molkentin <[email protected]>
27  */
28 class KCMUTILS_EXPORT KCMultiDialog : public KPageDialog
29 {
30  Q_OBJECT
31  Q_DECLARE_PRIVATE(KCMultiDialog)
32 
33 public:
34  /**
35  * Constructs a new KCMultiDialog
36  *
37  * @param parent The parent widget
38  **/
39  explicit KCMultiDialog(QWidget *parent = nullptr);
40 
41  /**
42  * Destructor
43  **/
44  ~KCMultiDialog() override;
45 
46 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 85)
47  /**
48  * Add a module.
49  *
50  * The module is added according to its KCModuleInfo::weight(). The weight determines where in the list
51  * the module will appear. Lighter modules on top, heavier modules at the bottom.
52  *
53  * @param module Specify the name of the module that is to be added
54  * to the list of modules the dialog will show.
55  *
56  * @param args The arguments that should be given to the KCModule when it is created
57  *
58  * @returns The @see KPageWidgetItem associated with the new dialog page.
59  * @deprecated Since 5.85, use @p addModule(const KPluginMetaData &metaData) instead
60  **/
61  KCMUTILS_DEPRECATED_VERSION(5, 85, "use addModule(const KPluginMetaData &metaData) instead")
62  KPageWidgetItem *addModule(const QString &module, const QStringList &args = QStringList());
63 #endif
64 
65  /**
66  * @since 5.84
67  * @overload
68  */
69  KPageWidgetItem *addModule(const KPluginMetaData &metaData);
70 
71  /**
72  * Add a module to the dialog. Its position will be determined based on the @c X-KDE-Weight value.
73  * @param metaData KPluginMetaData that will be used to load the plugin
74  * @param args The arguments that should be given to the KCModule when it is created
75  * @since 5.85
76  */
77  KPageWidgetItem *addModule(const KPluginMetaData &metaData, const QStringList &args); // TODO KF6 merge with overload
78 
79 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 85)
80  /**
81  * Add a module.
82  *
83  * The module is added according to its KCModuleInfo::weight(). The weight determines where in the list
84  * the module will appear. Lighter modules on top, heavier modules at the bottom.
85  *
86  * @param moduleinfo Pass a KCModuleInfo object which will be
87  * used for creating the module. It will be added
88  * to the list of modules the dialog will show.
89  *
90  * @param parent The @see KPageWidgetItem that should appear as parents
91  * in the tree view or a 0 pointer if there is no parent.
92  *
93  * @param args The arguments that should be given to the KCModule when it is created
94  * @deprecated Since 5.85, use @p addModule(const KPluginMetaData &metaData) instead
95  **/
96  KCMUTILS_DEPRECATED_VERSION(5, 85, "use addModule(const KPluginMetaData &metaData) instead")
97  KPageWidgetItem *addModule(const KCModuleInfo &moduleinfo, KPageWidgetItem *parent = nullptr, const QStringList &args = QStringList());
98 #endif
99 
100  /**
101  * Removes all modules from the dialog.
102  */
103  void clear();
104 
105 Q_SIGNALS:
106  /**
107  * Emitted after all KCModules have been told to save their configuration.
108  *
109  * The applyClicked and okClicked signals are emitted before the
110  * configuration is saved.
111  */
112  void configCommitted();
113 
114 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 85)
115  /**
116  * Emitted after the KCModules have been told to save their configuration.
117  * It is emitted once for every instance the KCMs that were changed belong
118  * to.
119  *
120  * You can make use of this if you have more than one component in your
121  * application. componentName tells you the instance that has to reload its
122  * configuration.
123  *
124  * The applyClicked and okClicked signals are emitted before the
125  * configuration is saved.
126  *
127  * @param componentName The name of the instance that needs to reload its
128  * configuration.
129  * @deprecated Since 5.85, use @p KCMultiDialog::configCommitted() instead
130  */
131  KCMUTILS_DEPRECATED_VERSION(5, 85, "use KCMultiDialog::configCommitted() instead")
132  void configCommitted(const QByteArray &componentName);
133 #endif
134 
135 protected:
136  /**
137  * This constructor can be used by subclasses to provide a custom KPageWidget.
138  */
139  KCMultiDialog(KPageWidget *pageWidget, QWidget *parent, Qt::WindowFlags flags = Qt::WindowFlags());
140  KCMultiDialog(KCMultiDialogPrivate &dd, KPageWidget *pageWidget, QWidget *parent, Qt::WindowFlags flags = Qt::WindowFlags());
141 
142  KCMultiDialogPrivate *const d_ptr;
143 
144  void closeEvent(QCloseEvent *event) override;
145  void showEvent(QShowEvent *event) override;
146 
147 protected Q_SLOTS:
148  /**
149  * This slot is called when the user presses the "Default" Button.
150  * You can reimplement it if needed.
151  *
152  * @note Make sure you call the original implementation.
153  **/
154  void slotDefaultClicked();
155 
156  /**
157  * This slot is called when the user presses the "Reset" Button.
158  * You can reimplement it if needed.
159  *
160  * @note Make sure you call the original implementation.
161  */
162  void slotUser1Clicked();
163 
164  /**
165  * This slot is called when the user presses the "Apply" Button.
166  * You can reimplement it if needed.
167  *
168  * @note Make sure you call the original implementation.
169  **/
170  void slotApplyClicked();
171 
172  /**
173  * This slot is called when the user presses the "OK" Button.
174  * You can reimplement it if needed.
175  *
176  * @note Make sure you call the original implementation.
177  **/
178  void slotOkClicked();
179 
180  /**
181  * This slot is called when the user presses the "Help" Button.
182  * It reads the X-DocPath field of the currently selected KControl
183  * module's .desktop file to find the path to the documentation,
184  * which it then attempts to load.
185  *
186  * You can reimplement this slot if needed.
187  *
188  * @note Make sure you call the original implementation.
189  **/
190  void slotHelpClicked();
191 
192 private:
193  Q_PRIVATE_SLOT(d_func(), void _k_slotCurrentPageChanged(KPageWidgetItem *, KPageWidgetItem *))
194  Q_PRIVATE_SLOT(d_func(), void _k_clientChanged())
195  Q_PRIVATE_SLOT(d_func(), void _k_updateHeader(bool use, const QString &message))
196 };
197 
198 /**
199  * @brief Custom QScrollArea class that doesn't limit its size hint
200  *
201  * See original QScrollArea::sizeHint() function,
202  * where the size hint is bound by 36*24 font heights
203  *
204  * Workaround for https://bugreports.qt.io/browse/QTBUG-10459
205  */
206 
208 {
209  Q_OBJECT
210 public:
211  QSize sizeHint() const override
212  {
213  if (widget()) {
214  // Try to avoid horizontal scrollbar, which just scrolls a scrollbar width.
215  // We always need to reserve space for the vertical scroll bar,
216  // because we can’t know here whether vertical scrolling will be used.
217  QSize withScrollbar = widget()->sizeHint();
218  withScrollbar.rwidth() += verticalScrollBar()->sizeHint().width() + 4;
219  return withScrollbar;
220  } else {
221  return QScrollArea::sizeHint();
222  }
223  }
224 
226  : QScrollArea(w)
227  {
228  }
229  ~UnboundScrollArea() override = default;
230 };
231 
232 #endif
Q_OBJECTQ_OBJECT
QScrollBar * verticalScrollBar() const const
Q_SLOTSQ_SLOTS
virtual QSize sizeHint() const const override
QScrollArea(QWidget *parent)
int width() const const
virtual void closeEvent(QCloseEvent *e) override
virtual QSize sizeHint() const const override
typedef WindowFlags
QWidget * widget() const const
virtual void showEvent(QShowEvent *event) override
Custom QScrollArea class that doesn't limit its size hint.
int & rwidth()
Q_SIGNALSQ_SIGNALS
A class that provides information about a KCModule.
Definition: kcmoduleinfo.h:36
A class that offers a KPageDialog containing arbitrary KControl Modules.
Definition: kcmultidialog.h:28
QString message
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Mar 22 2023 04:09:55 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.