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
26class KConfig;
27class KCoreConfigSkeleton;
28class KConfigSkeleton;
29class 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 */
73class KDEUI_EXPORT KConfigDialog : public KPageDialog {
74Q_OBJECT
75
76Q_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
89public:
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 &header=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 &header=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
190protected 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
232protected:
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
252private Q_SLOTS:
253 /**
254 * Slot which cleans up the KConfigDialogManager of the page.
255 * */
256 void onPageRemoved(KPageWidgetItem* item);
257
258private:
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