1/*
2 Copyright (c) 2000 Matthias Elter <elter@kde.org>
3 Copyright (c) 2003 Daniel Molkentin <molkentin@kde.org>
4 Copyright (c) 2003,2006 Matthias Kretz <kretz@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*/
22
23#ifndef KCMULTIDIALOG_H
24#define KCMULTIDIALOG_H
25
26#include <kcmoduleinfo.h>
27#include <kpagedialog.h>
28
29class KCMultiDialogPrivate;
30
31/**
32 * @short A class that offers a KPageDialog containing arbitrary
33 * KControl Modules.
34 *
35 * @author Matthias Elter <elter@kde.org>, Daniel Molkentin <molkentin@kde.org>
36 */
37class KCMUTILS_EXPORT KCMultiDialog : public KPageDialog
38{
39 Q_OBJECT
40 Q_DECLARE_PRIVATE(KCMultiDialog)
41
42 public:
43 /**
44 * Constructs a new KCMultiDialog
45 *
46 * @param parent The parent widget
47 **/
48 KCMultiDialog( QWidget *parent = 0 );
49
50
51 /**
52 * Destructor
53 **/
54 virtual ~KCMultiDialog();
55
56 /**
57 * Add a module.
58 *
59 * The module is added according to its KCModuleInfo::weight(). The weight determines where in the list
60 * the module will appear. Lighter modules on top, heavier modules at the bottom.
61 *
62 * @param module Specify the name of the module that is to be added
63 * to the list of modules the dialog will show.
64 *
65 * @param args The arguments that should be given to the KCModule when it is created
66 *
67 * @returns The @see KPageWidgetItem associated with the new dialog page.
68 **/
69 KPageWidgetItem* addModule( const QString& module, const QStringList&
70 args = QStringList() );
71
72 /**
73 * Add a module.
74 *
75 * The module is added according to its KCModuleInfo::weight(). The weight determines where in the list
76 * the module will appear. Lighter modules on top, heavier modules at the bottom.
77 *
78 * @param moduleinfo Pass a KCModuleInfo object which will be
79 * used for creating the module. It will be added
80 * to the list of modules the dialog will show.
81 *
82 * @param parent The @see KPageWidgetItem that should appear as parents
83 * in the tree view or a 0 pointer if there is no parent.
84 *
85 * @param args The arguments that should be given to the KCModule when it is created
86 **/
87 KPageWidgetItem* addModule( const KCModuleInfo& moduleinfo, KPageWidgetItem *parent = 0,
88 const QStringList& args = QStringList() );
89
90 /**
91 * Removes all modules from the dialog.
92 */
93 void clear();
94
95 /**
96 * Reimplemented for internal reasons.
97 */
98 void setButtons(ButtonCodes buttonMask);
99
100 Q_SIGNALS:
101 /**
102 * Emitted after all KCModules have been told to save their configuration.
103 *
104 * The applyClicked and okClicked signals are emitted before the
105 * configuration is saved.
106 */
107 void configCommitted();
108
109 /**
110 * Emitted after the KCModules have been told to save their configuration.
111 * It is emitted once for every instance the KCMs that were changed belong
112 * to.
113 *
114 * You can make use of this if you have more than one component in your
115 * application. componentName tells you the instance that has to reload its
116 * configuration.
117 *
118 * The applyClicked and okClicked signals are emitted before the
119 * configuration is saved.
120 *
121 * @param componentName The name of the instance that needs to reload its
122 * configuration.
123 */
124 void configCommitted( const QByteArray & componentName );
125
126 protected:
127 /**
128 * This constructor can be used by subclasses to provide a custom KPageWidget.
129 */
130 KCMultiDialog(KPageWidget *pageWidget, QWidget *parent, Qt::WindowFlags flags = 0);
131 KCMultiDialog(KCMultiDialogPrivate &dd, KPageWidget *pageWidget, QWidget *parent, Qt::WindowFlags flags = 0);
132
133 protected Q_SLOTS:
134 /**
135 * This slot is called when the user presses the "Default" Button.
136 * You can reimplement it if needed.
137 *
138 * @note Make sure you call the original implementation.
139 **/
140 void slotDefaultClicked();
141
142 /**
143 * This slot is called when the user presses the "Reset" Button.
144 * You can reimplement it if needed.
145 *
146 * @note Make sure you call the original implementation.
147 */
148 void slotUser1Clicked();
149
150 /**
151 * This slot is called when the user presses the "Apply" Button.
152 * You can reimplement it if needed.
153 *
154 * @note Make sure you call the original implementation.
155 **/
156 void slotApplyClicked();
157
158 /**
159 * This slot is called when the user presses the "OK" Button.
160 * You can reimplement it if needed.
161 *
162 * @note Make sure you call the original implementation.
163 **/
164 void slotOkClicked();
165
166 /**
167 * This slot is called when the user presses the "Help" Button.
168 * It reads the X-DocPath field of the currently selected KControl
169 * module's .desktop file to find the path to the documentation,
170 * which it then attempts to load.
171 *
172 * You can reimplement this slot if needed.
173 *
174 * @note Make sure you call the original implementation.
175 **/
176 void slotHelpClicked();
177
178 private:
179 Q_PRIVATE_SLOT(d_func(), void _k_slotCurrentPageChanged(KPageWidgetItem *, KPageWidgetItem *))
180 Q_PRIVATE_SLOT(d_func(), void _k_clientChanged())
181 Q_PRIVATE_SLOT(d_func(), void _k_dialogClosed())
182 Q_PRIVATE_SLOT(d_func(), void _k_updateHeader(bool use, const QString &message))
183};
184
185#endif
186