summaryrefslogtreecommitdiffabout
path: root/microkde/kdeui
Unidiff
Diffstat (limited to 'microkde/kdeui') (more/less context) (ignore whitespace changes)
-rw-r--r--microkde/kdeui/kcmodule.h9
1 files changed, 5 insertions, 4 deletions
diff --git a/microkde/kdeui/kcmodule.h b/microkde/kdeui/kcmodule.h
index 90a87c9..bc020bc 100644
--- a/microkde/kdeui/kcmodule.h
+++ b/microkde/kdeui/kcmodule.h
@@ -1,235 +1,236 @@
1/* 1/*
2 This file is part of the KDE libraries 2 This file is part of the KDE libraries
3 3
4 Copyright (c) 1999 Matthias Hoelzer-Kluepfel <hoelzer@kde.org> 4 Copyright (c) 1999 Matthias Hoelzer-Kluepfel <hoelzer@kde.org>
5 5
6 This library is free software; you can redistribute it and/or 6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public 7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either 8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version. 9 version 2 of the License, or (at your option) any later version.
10 10
11 This library is distributed in the hope that it will be useful, 11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details. 14 Library General Public License for more details.
15 15
16 You should have received a copy of the GNU Library General Public License 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 17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 59 Temple Place - Suite 330, 18 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 Boston, MA 02111-1307, USA. 19 Boston, MA 02111-1307, USA.
20 20
21*/ 21*/
22#ifndef __KCMODULE_H__ 22#ifndef __KCMODULE_H__
23#define __KCMODULE_H__ 23#define __KCMODULE_H__
24 24
25#include <qwidget.h> 25#include <qwidget.h>
26#include <qstringlist.h> 26#include <qstringlist.h>
27//USclass KAboutData; 27//USclass KAboutData;
28class KCModulePrivate; 28class KCModulePrivate;
29class KPrefs;
29//US class KInstance; 30//US class KInstance;
30 31
31/** 32/**
32 * The base class for control center modules. 33 * The base class for control center modules.
33 * 34 *
34 * Starting from KDE 2.0, control center modules are realized as shared 35 * Starting from KDE 2.0, control center modules are realized as shared
35 * libraries that are loaded into the control center at runtime. 36 * libraries that are loaded into the control center at runtime.
36 * 37 *
37 * The module in principle is a simple widget displaying the 38 * The module in principle is a simple widget displaying the
38 * item to be changed. The module has a very small interface. 39 * item to be changed. The module has a very small interface.
39 * 40 *
40 * All the necessary glue logic and the GUI bells and whistles 41 * All the necessary glue logic and the GUI bells and whistles
41 * are provided by the control center and must not concern 42 * are provided by the control center and must not concern
42 * the module author. 43 * the module author.
43 * 44 *
44 * To write a config module, you have to create a library 45 * To write a config module, you have to create a library
45 * that contains at one factory function like this: 46 * that contains at one factory function like this:
46 * 47 *
47 * <pre> 48 * <pre>
48 * #include <kgenericfactory.h> 49 * #include <kgenericfactory.h>
49 * 50 *
50 * typedef KGenericFactory<YourKCModule, QWidget> YourKCModuleFactory; 51 * typedef KGenericFactory<YourKCModule, QWidget> YourKCModuleFactory;
51 * K_EXPORT_COMPONENT_FACTORY( yourLibName, YourKCModuleFactory("name_of_the_po_file") ); 52 * K_EXPORT_COMPONENT_FACTORY( yourLibName, YourKCModuleFactory("name_of_the_po_file") );
52 * </pre> 53 * </pre>
53 * 54 *
54 * The parameter "name_of_the_po_file" has to correspond with the messages target 55 * The parameter "name_of_the_po_file" has to correspond with the messages target
55 * that you created in your Makefile.am. 56 * that you created in your Makefile.am.
56 * 57 *
57 * See kdebase/kcontrol/HOWTO for more detailed documentation. 58 * See kdebase/kcontrol/HOWTO for more detailed documentation.
58 * 59 *
59 * @author Matthias Hoelzer-Kluepfel <hoelzer@kde.org> 60 * @author Matthias Hoelzer-Kluepfel <hoelzer@kde.org>
60 */ 61 */
61 62
62class KCModule : public QWidget 63class KCModule : public QWidget
63{ 64{
64 Q_OBJECT 65 Q_OBJECT
65 66
66public: 67public:
67 68
68 /** 69 /**
69 * An enumeration type for the buttons used by this module. 70 * An enumeration type for the buttons used by this module.
70 * You should only use Help, Default and Apply. The rest is obsolete. 71 * You should only use Help, Default and Apply. The rest is obsolete.
71 * 72 *
72 * @see KCModule::buttons @see KCModule::setButtons 73 * @see KCModule::buttons @see KCModule::setButtons
73 */ 74 */
74 enum Button {Help=1, Default=2, Apply=16, 75 enum Button {Help=1, Default=2, Apply=16,
75 Reset=4, /* obsolete, do not use! */ 76 Reset=4, /* obsolete, do not use! */
76 Cancel=8, /* obsolete, do not use! */ 77 Cancel=8, /* obsolete, do not use! */
77 Ok=32, /* obsolete, do not use! */ 78 Ok=32, /* obsolete, do not use! */
78 SysDefault=64 /* obsolete, do not use! */ }; 79 SysDefault=64 /* obsolete, do not use! */ };
79 80
80 /* 81 /*
81 * Base class for all KControlModules. 82 * Base class for all KControlModules.
82 * Make sure you have a QStringList argument in your 83 * Make sure you have a QStringList argument in your
83 * implementation. 84 * implementation.
84 */ 85 */
85 KCModule(QWidget *parent=0, const char *name=0, const QStringList &args=QStringList() ); 86 KCModule(QWidget *parent=0, const char *name=0, const QStringList &args=QStringList() );
86 87
87//US KCModule(KInstance *instance, QWidget *parent=0, const QStringList &args=QStringList() ); 88//US KCModule(KInstance *instance, QWidget *parent=0, const QStringList &args=QStringList() );
88 89
89 /* 90 /*
90 * Destroys the module. 91 * Destroys the module.
91 */ 92 */
92 ~KCModule(); 93 ~KCModule();
93 94
94 /** 95 /**
95 * Load the configuration data into the module. 96 * Load the configuration data into the module.
96 * 97 *
97 * The load method sets the user interface elements of the 98 * The load method sets the user interface elements of the
98 * module to reflect the current settings stored in the 99 * module to reflect the current settings stored in the
99 * configuration files. 100 * configuration files.
100 * 101 *
101 * This method is invoked whenever the module should read its configuration 102 * This method is invoked whenever the module should read its configuration
102 * (most of the times from a config file) and update the user interface. 103 * (most of the times from a config file) and update the user interface.
103 * This happens when the user clicks the "Reset" button in the control 104 * This happens when the user clicks the "Reset" button in the control
104 * center, to undo all of his changes and restore the currently valid 105 * center, to undo all of his changes and restore the currently valid
105 * settings. NOTE that this is not called after the modules is loaded, 106 * settings. NOTE that this is not called after the modules is loaded,
106 * so you probably want to call this method in the constructor. 107 * so you probably want to call this method in the constructor.
107 */ 108 */
108 virtual void load() {}; 109 virtual void load(KPrefs* prefs) {};
109 110
110 /** 111 /**
111 * Save the configuration data. 112 * Save the configuration data.
112 * 113 *
113 * The save method stores the config information as shown 114 * The save method stores the config information as shown
114 * in the user interface in the config files. 115 * in the user interface in the config files.
115 * 116 *
116 * If necessary, this method also updates the running system, 117 * If necessary, this method also updates the running system,
117 * e.g. by restarting applications. 118 * e.g. by restarting applications.
118 * 119 *
119 * save is called when the user clicks "Apply" or "Ok". 120 * save is called when the user clicks "Apply" or "Ok".
120 */ 121 */
121 virtual void save() {}; 122 virtual void save(KPrefs* prefs) {};
122 123
123 /** 124 /**
124 * Sets the configuration to sensible default values. 125 * Sets the configuration to sensible default values.
125 * 126 *
126 * This method is called when the user clicks the "Default" 127 * This method is called when the user clicks the "Default"
127 * button. It should set the display to useful values. 128 * button. It should set the display to useful values.
128 */ 129 */
129 virtual void defaults() {}; 130 virtual void defaults(KPrefs* prefs) {};
130 131
131 /** 132 /**
132 * Set the configuration to system default values. 133 * Set the configuration to system default values.
133 * 134 *
134 * This method is called when the user clicks the "System-Default" 135 * This method is called when the user clicks the "System-Default"
135 * button. It should set the display to the system default values. 136 * button. It should set the display to the system default values.
136 * 137 *
137 * NOTE: The default behaviour is to call defaults(). 138 * NOTE: The default behaviour is to call defaults().
138 */ 139 */
139 virtual void sysdefaults() { defaults(); }; 140 virtual void sysdefaults(KPrefs* prefs) { defaults(prefs); };
140 141
141 /** 142 /**
142 * Return a quick-help text. 143 * Return a quick-help text.
143 * 144 *
144 * This method is called when the module is docked. 145 * This method is called when the module is docked.
145 * The quick-help text should contain a short description of the module and 146 * The quick-help text should contain a short description of the module and
146 * links to the module's help files. You can use QML formating tags in the text. 147 * links to the module's help files. You can use QML formating tags in the text.
147 * 148 *
148 * NOTE: Please make sure the quick help text gets translated (use i18n()). 149 * NOTE: Please make sure the quick help text gets translated (use i18n()).
149 */ 150 */
150 virtual QString quickHelp() const { return QString::null; }; 151 virtual QString quickHelp() const { return QString::null; };
151 152
152 /** 153 /**
153 * Returns a the KAboutData for this module 154 * Returns a the KAboutData for this module
154 * This is generally only called for the KBugReport. 155 * This is generally only called for the KBugReport.
155 * Override and have it return a pointer to a constant 156 * Override and have it return a pointer to a constant
156 */ 157 */
157//US virtual const KAboutData *aboutData() const { return 0; } 158//US virtual const KAboutData *aboutData() const { return 0; }
158 159
159 /** 160 /**
160 * Indicate which buttons will be used. 161 * Indicate which buttons will be used.
161 * 162 *
162 * The return value is a value or'ed together from 163 * The return value is a value or'ed together from
163 * the Button enumeration type. 164 * the Button enumeration type.
164 * 165 *
165 * @see KCModule::setButtons 166 * @see KCModule::setButtons
166 */ 167 */
167 int buttons() const { return _btn; }; 168 int buttons() const { return _btn; };
168 169
169 /** 170 /**
170 * Get the RootOnly message for this module. 171 * Get the RootOnly message for this module.
171 * 172 *
172 * When the module must be run as root, or acts differently 173 * When the module must be run as root, or acts differently
173 * for root and a normal user, it is sometimes useful to 174 * for root and a normal user, it is sometimes useful to
174 * customize the message that appears at the top of the module 175 * customize the message that appears at the top of the module
175 * when used as a normal user. This function returns this 176 * when used as a normal user. This function returns this
176 * customized message. If none has been set, a default message 177 * customized message. If none has been set, a default message
177 * will be used. 178 * will be used.
178 * 179 *
179 * @see KCModule::setRootOnlyMsg 180 * @see KCModule::setRootOnlyMsg
180 */ 181 */
181 QString rootOnlyMsg() const; 182 QString rootOnlyMsg() const;
182 183
183 /** 184 /**
184 * Tell if KControl should show a RootOnly message when run as 185 * Tell if KControl should show a RootOnly message when run as
185 * a normal user. 186 * a normal user.
186 * 187 *
187 * In some cases, the module don't want a RootOnly message to 188 * In some cases, the module don't want a RootOnly message to
188 * appear (for example if it has already one). This function 189 * appear (for example if it has already one). This function
189 * tells KControl if a RootOnly message should be shown 190 * tells KControl if a RootOnly message should be shown
190 * 191 *
191 * @see KCModule::setUseRootOnlyMsg 192 * @see KCModule::setUseRootOnlyMsg
192 */ 193 */
193 bool useRootOnlyMsg() const; 194 bool useRootOnlyMsg() const;
194 195
195 196
196//US KInstance *instance() const; 197//US KInstance *instance() const;
197 198
198signals: 199signals:
199 200
200 /** 201 /**
201 * Indicate that the state of the modules contents has changed. 202 * Indicate that the state of the modules contents has changed.
202 * 203 *
203 * This signal is emitted whenever the state of the configuration 204 * This signal is emitted whenever the state of the configuration
204 * shown in the module changes. It allows the control center to 205 * shown in the module changes. It allows the control center to
205 * keep track of unsaved changes. 206 * keep track of unsaved changes.
206 * 207 *
207 */ 208 */
208 void changed(bool state); 209 void changed(bool state);
209 210
210 /** 211 /**
211 * Indicate that the module's quickhelp has changed. 212 * Indicate that the module's quickhelp has changed.
212 * 213 *
213 * Emit this signal whenever the module's quickhelp changes. 214 * Emit this signal whenever the module's quickhelp changes.
214 * Modules implemented as tabbed dialogs might want to implement 215 * Modules implemented as tabbed dialogs might want to implement
215 * per-tab quickhelp for example. 216 * per-tab quickhelp for example.
216 * 217 *
217 */ 218 */
218 void quickHelpChanged(); 219 void quickHelpChanged();
219 220
220protected: 221protected:
221 222
222 /** 223 /**
223 * Sets the buttons to display. 224 * Sets the buttons to display.
224 * 225 *
225 * Help: shows a "Help" button. 226 * Help: shows a "Help" button.
226 * Default: shows a "Use Defaults" button 227 * Default: shows a "Use Defaults" button
227 * Apply: in kcontrol this will show an "Apply" and "Reset" button 228 * Apply: in kcontrol this will show an "Apply" and "Reset" button
228 * in kcmshell this will show an "Ok", "Apply" and "Cancel" button 229 * in kcmshell this will show an "Ok", "Apply" and "Cancel" button
229 * 230 *
230 * If Apply is not specified, kcmshell will show a "Close" button. 231 * If Apply is not specified, kcmshell will show a "Close" button.
231 * 232 *
232 * @see KCModule::buttons 233 * @see KCModule::buttons
233 */ 234 */
234 void setButtons(int btn) { _btn = btn; }; 235 void setButtons(int btn) { _btn = btn; };
235 236