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 | |
17 | class KConfig; |
18 | class KCoreConfigSkeleton; |
19 | class 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 | */ |
66 | class KCONFIGWIDGETS_EXPORT KConfigDialog : public KPageDialog |
67 | { |
68 | Q_OBJECT |
69 | |
70 | Q_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 | |
84 | public: |
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 & = 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 & = 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 | |
179 | protected 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 | |
249 | protected: |
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 | |
266 | private Q_SLOTS: |
267 | KCONFIGWIDGETS_NO_EXPORT void (KPageWidgetItem *item); |
268 | |
269 | private: |
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 | |