1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2003 Benjamin C Meyer <ben+kdelibs at meyerhome dot net>
4 SPDX-FileCopyrightText: 2003 Waldo Bastian <bastian@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef KCONFIGDIALOG_H
10#define KCONFIGDIALOG_H
11
12#include <KPageDialog>
13#include <memory>
14
15#include "kconfigwidgets_export.h"
16
17class KConfig;
18class KCoreConfigSkeleton;
19class KConfigDialogManager;
20
21/*!
22 * \class KConfigDialog
23 * \inmodule KConfigWidgets
24 *
25 * \brief Standard KDE configuration dialog class.
26 *
27 * The KConfigDialog class provides an easy and uniform means of displaying
28 * a settings dialog using KPageDialog, KConfigDialogManager and a
29 * KConfigSkeleton derived settings class.
30 *
31 * KConfigDialog handles the enabling and disabling of buttons, creation
32 * of the dialog, and deletion of the widgets. Because of
33 * KConfigDialogManager, this class also manages: restoring
34 * the settings, resetting them to the default values, and saving them. This
35 * requires that the names of the widgets corresponding to configuration entries
36 * have to have the same name plus an additional "kcfg_" prefix. For example the
37 * widget named "kcfg_MyOption" would be associated with the configuration entry
38 * "MyOption".
39 *
40 * Here is an example usage of KConfigDialog:
41 *
42 * \code
43 * void KCoolApp::showSettings(){
44 * if (KConfigDialog::showDialog(QStringLiteral("settings"))) {
45 * return;
46 * }
47 * KConfigDialog *dialog = new KConfigDialog(this, QStringLiteral("settings"), MySettings::self());
48 * dialog->setFaceType(KPageDialog::List);
49 * dialog->addPage(new General(0, "General"), i18n("General"));
50 * dialog->addPage(new Appearance(0, "Style"), i18n("Appearance"));
51 * connect(dialog, &KConfigDialog::settingsChanged, mainWidget, &Bar::loadSettings);
52 * connect(dialog, &KConfigDialog::settingsChanged, this, &Foo::loadSettings);
53 * dialog->show();
54 * }
55 * \endcode
56 *
57 * Other than the above code, each class that has settings in the dialog should
58 * have a loadSettings() type slot to read settings and perform any
59 * necessary changes.
60 *
61 * For dialog appearance options (like buttons, default button, ...) please see
62 * KPageDialog.
63 *
64 * \sa KConfigSkeleton
65 */
66class KCONFIGWIDGETS_EXPORT KConfigDialog : public KPageDialog
67{
68 Q_OBJECT
69
70Q_SIGNALS:
71 /*!
72 * A widget in the dialog was modified.
73 */
74 void widgetModified();
75
76 /*!
77 * One or more of the settings have been permanently changed such as if
78 * the user clicked on the Apply or Ok button.
79 *
80 * \a dialogName the name of the dialog.
81 */
82 void settingsChanged(const QString &dialogName);
83
84public:
85 /*!
86 * \a parent The parent of this object. Even though the class
87 * deletes itself the parent should be set so the dialog can be centered
88 * with the application on the screen.
89 *
90 * \a name The name of this object. The name is used in determining if
91 * there can be more than one dialog at a time. Use names such as:
92 * "Font Settings" or "Color Settings" and not just "Settings" in
93 * applications where there is more than one dialog.
94 *
95 * \a config Config object containing settings.
96 */
97 KConfigDialog(QWidget *parent, const QString &name, KCoreConfigSkeleton *config);
98
99 /*!
100 * Deconstructor, removes name from the list of open dialogs.
101 * \sa exists()
102 */
103 ~KConfigDialog() override;
104
105 /*!
106 * Adds page to the dialog and to KConfigDialogManager. When an
107 * application is done adding pages show() should be called to
108 * display the dialog.
109 *
110 * \a page Pointer to the page that is to be added to the dialog.
111 * This object is reparented.
112 *
113 * \a itemName Name of the page.
114 *
115 * \a pixmapName Name of the icon that should be used, if needed, when
116 * displaying the page. The string may either be the name of a themed
117 * icon (e.g. "document-save"), which the internal icon loader will be
118 * used to retrieve, or an absolute path to the pixmap on disk.
119 *
120 * \a header Header text use in the list modes. Ignored in Tabbed
121 * mode. If empty, the itemName text is used when needed.
122 *
123 * \a manage Whether KConfigDialogManager should manage the page or not.
124 *
125 * Returns the KPageWidgetItem associated with the page.
126 */
127 KPageWidgetItem *
128 addPage(QWidget *page, const QString &itemName, const QString &pixmapName = QString(), const QString &header = QString(), bool manage = true);
129
130 /*!
131 * Adds page to the dialog that is managed by a custom KConfigDialogManager.
132 * This is useful for dialogs that contain settings spread over more than
133 * one configuration file and thus have/need more than one KConfigSkeleton.
134 * When an application is done adding pages show() should be called to
135 * display the dialog.
136 *
137 * \a page Pointer to the page that is to be added to the dialog.
138 * This object is reparented.
139 *
140 * \a config Config object containing corresponding settings.
141 *
142 * \a itemName Name of the page.
143 *
144 * \a pixmapName Name of the icon that should be used, if needed, when
145 * displaying the page. The string may either be the name of a themed
146 * icon (e.g. "document-save"), which the internal icon loader will be
147 * used to retrieve, or an absolute path to the pixmap on disk.
148 *
149 * \a header Header text use in the list modes. Ignored in Tabbed
150 * mode. If empty, the itemName text is used when needed.
151 *
152 * Returns the KPageWidgetItem associated with the page.
153 */
154 KPageWidgetItem *
155 addPage(QWidget *page, KCoreConfigSkeleton *config, const QString &itemName, const QString &pixmapName = QString(), const QString &header = QString());
156
157 /*!
158 * See if a dialog with the name 'name' already exists.
159 *
160 * \sa showDialog()
161 *
162 * \a name Dialog name to look for.
163 *
164 * Returns pointer to widget or \c nullptr if it does not exist.
165 */
166 static KConfigDialog *exists(const QString &name);
167
168 /*!
169 * Attempts to show the dialog with the name 'name'.
170 *
171 * \sa exists()
172 *
173 * \a name The name of the dialog to show.
174 *
175 * Returns \c true if the dialog 'name' exists and was shown.
176 */
177 static bool showDialog(const QString &name);
178
179protected Q_SLOTS:
180 /*!
181 * Update the settings from the dialog.
182 *
183 * Virtual function for custom additions.
184 *
185 * Example use: User clicks Ok or Apply button in a configure dialog.
186 */
187 virtual void updateSettings();
188
189 /*!
190 * Update the dialog based on the settings.
191 *
192 * Virtual function for custom additions.
193 *
194 * Example use: Initialisation of dialog.
195 *
196 * Example use: User clicks Reset button in a configure dialog.
197 */
198 virtual void updateWidgets();
199
200 /*!
201 * Update the dialog based on the default settings.
202 *
203 * Virtual function for custom additions.
204 *
205 * Example use: User clicks Defaults button in a configure dialog.
206 */
207 virtual void updateWidgetsDefault();
208
209 /*!
210 * Updates the Apply and Default buttons.
211 *
212 * Connect to this slot if you implement your own hasChanged()
213 * or isDefault() methods for widgets not managed by KConfig.
214 *
215 * \since 4.3
216 */
217 void updateButtons();
218
219 /*!
220 * Some setting was changed. Emit the signal with the dialogs name.
221 *
222 * Connect to this slot if there are widgets not managed by KConfig.
223 *
224 * \since 4.3
225 */
226 void settingsChangedSlot();
227
228 /*!
229 * Sets the help path and topic.
230 *
231 * The HTML file will be found using the X-DocPath entry in the application's desktop file.
232 * It can be either a relative path, or a website URL.
233 *
234 * \a anchor This has to be a defined anchor in your
235 * docbook sources or website. If empty the main index
236 * is loaded.
237 *
238 * \a appname This allows you to specify the .desktop file to get the help path from.
239 * If empty the QCoreApplication::applicationName() is used.
240 */
241 void setHelp(const QString &anchor, const QString &appname = QString());
242
243 /*!
244 * Displays help for this config dialog.
245 * \since 5.0
246 */
247 virtual void showHelp();
248
249protected:
250 /*!
251 * Returns whether the current state of the dialog is
252 * different from the current configuration.
253 *
254 * Virtual function for custom additions.
255 */
256 virtual bool hasChanged();
257
258 /*!
259 * Returns whether the current state of the dialog is
260 * the same as the default configuration.
261 */
262 virtual bool isDefault();
263
264 void showEvent(QShowEvent *e) override;
265
266private Q_SLOTS:
267 KCONFIGWIDGETS_NO_EXPORT void onPageRemoved(KPageWidgetItem *item);
268
269private:
270 friend class KConfigDialogPrivate;
271 std::unique_ptr<class KConfigDialogPrivate> const d;
272
273 Q_DISABLE_COPY(KConfigDialog)
274};
275
276#endif // KCONFIGDIALOG_H
277

source code of kconfigwidgets/src/kconfigdialog.h