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