-rw-r--r-- | microkde/kdeui/kcmodule.h | 266 |
1 files changed, 266 insertions, 0 deletions
diff --git a/microkde/kdeui/kcmodule.h b/microkde/kdeui/kcmodule.h new file mode 100644 index 0000000..90a87c9 --- a/dev/null +++ b/microkde/kdeui/kcmodule.h | |||
@@ -0,0 +1,266 @@ | |||
1 | /* | ||
2 | This file is part of the KDE libraries | ||
3 | |||
4 | Copyright (c) 1999 Matthias Hoelzer-Kluepfel <hoelzer@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., 59 Temple Place - Suite 330, | ||
19 | Boston, MA 02111-1307, USA. | ||
20 | |||
21 | */ | ||
22 | #ifndef __KCMODULE_H__ | ||
23 | #define __KCMODULE_H__ | ||
24 | |||
25 | #include <qwidget.h> | ||
26 | #include <qstringlist.h> | ||
27 | //USclass KAboutData; | ||
28 | class KCModulePrivate; | ||
29 | //US class KInstance; | ||
30 | |||
31 | /** | ||
32 | * The base class for control center modules. | ||
33 | * | ||
34 | * Starting from KDE 2.0, control center modules are realized as shared | ||
35 | * libraries that are loaded into the control center at runtime. | ||
36 | * | ||
37 | * The module in principle is a simple widget displaying the | ||
38 | * item to be changed. The module has a very small interface. | ||
39 | * | ||
40 | * All the necessary glue logic and the GUI bells and whistles | ||
41 | * are provided by the control center and must not concern | ||
42 | * the module author. | ||
43 | * | ||
44 | * To write a config module, you have to create a library | ||
45 | * that contains at one factory function like this: | ||
46 | * | ||
47 | * <pre> | ||
48 | * #include <kgenericfactory.h> | ||
49 | * | ||
50 | * typedef KGenericFactory<YourKCModule, QWidget> YourKCModuleFactory; | ||
51 | * K_EXPORT_COMPONENT_FACTORY( yourLibName, YourKCModuleFactory("name_of_the_po_file") ); | ||
52 | * </pre> | ||
53 | * | ||
54 | * The parameter "name_of_the_po_file" has to correspond with the messages target | ||
55 | * that you created in your Makefile.am. | ||
56 | * | ||
57 | * See kdebase/kcontrol/HOWTO for more detailed documentation. | ||
58 | * | ||
59 | * @author Matthias Hoelzer-Kluepfel <hoelzer@kde.org> | ||
60 | */ | ||
61 | |||
62 | class KCModule : public QWidget | ||
63 | { | ||
64 | Q_OBJECT | ||
65 | |||
66 | public: | ||
67 | |||
68 | /** | ||
69 | * An enumeration type for the buttons used by this module. | ||
70 | * You should only use Help, Default and Apply. The rest is obsolete. | ||
71 | * | ||
72 | * @see KCModule::buttons @see KCModule::setButtons | ||
73 | */ | ||
74 | enum Button {Help=1, Default=2, Apply=16, | ||
75 | Reset=4, /* obsolete, do not use! */ | ||
76 | Cancel=8, /* obsolete, do not use! */ | ||
77 | Ok=32, /* obsolete, do not use! */ | ||
78 | SysDefault=64 /* obsolete, do not use! */ }; | ||
79 | |||
80 | /* | ||
81 | * Base class for all KControlModules. | ||
82 | * Make sure you have a QStringList argument in your | ||
83 | * implementation. | ||
84 | */ | ||
85 | KCModule(QWidget *parent=0, const char *name=0, const QStringList &args=QStringList() ); | ||
86 | |||
87 | //US KCModule(KInstance *instance, QWidget *parent=0, const QStringList &args=QStringList() ); | ||
88 | |||
89 | /* | ||
90 | * Destroys the module. | ||
91 | */ | ||
92 | ~KCModule(); | ||
93 | |||
94 | /** | ||
95 | * Load the configuration data into the module. | ||
96 | * | ||
97 | * The load method sets the user interface elements of the | ||
98 | * module to reflect the current settings stored in the | ||
99 | * configuration files. | ||
100 | * | ||
101 | * 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 | * 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 | * 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 | */ | ||
108 | virtual void load() {}; | ||
109 | |||
110 | /** | ||
111 | * Save the configuration data. | ||
112 | * | ||
113 | * The save method stores the config information as shown | ||
114 | * in the user interface in the config files. | ||
115 | * | ||
116 | * If necessary, this method also updates the running system, | ||
117 | * e.g. by restarting applications. | ||
118 | * | ||
119 | * save is called when the user clicks "Apply" or "Ok". | ||
120 | */ | ||
121 | virtual void save() {}; | ||
122 | |||
123 | /** | ||
124 | * Sets the configuration to sensible default values. | ||
125 | * | ||
126 | * This method is called when the user clicks the "Default" | ||
127 | * button. It should set the display to useful values. | ||
128 | */ | ||
129 | virtual void defaults() {}; | ||
130 | |||
131 | /** | ||
132 | * Set the configuration to system default values. | ||
133 | * | ||
134 | * This method is called when the user clicks the "System-Default" | ||
135 | * button. It should set the display to the system default values. | ||
136 | * | ||
137 | * NOTE: The default behaviour is to call defaults(). | ||
138 | */ | ||
139 | virtual void sysdefaults() { defaults(); }; | ||
140 | |||
141 | /** | ||
142 | * Return a quick-help text. | ||
143 | * | ||
144 | * This method is called when the module is docked. | ||
145 | * 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 | * | ||
148 | * NOTE: Please make sure the quick help text gets translated (use i18n()). | ||
149 | */ | ||
150 | virtual QString quickHelp() const { return QString::null; }; | ||
151 | |||
152 | /** | ||
153 | * Returns a the KAboutData for this module | ||
154 | * This is generally only called for the KBugReport. | ||
155 | * Override and have it return a pointer to a constant | ||
156 | */ | ||
157 | //US virtual const KAboutData *aboutData() const { return 0; } | ||
158 | |||
159 | /** | ||
160 | * Indicate which buttons will be used. | ||
161 | * | ||
162 | * The return value is a value or'ed together from | ||
163 | * the Button enumeration type. | ||
164 | * | ||
165 | * @see KCModule::setButtons | ||
166 | */ | ||
167 | int buttons() const { return _btn; }; | ||
168 | |||
169 | /** | ||
170 | * Get the RootOnly message for this module. | ||
171 | * | ||
172 | * When the module must be run as root, or acts differently | ||
173 | * for root and a normal user, it is sometimes useful to | ||
174 | * customize the message that appears at the top of the module | ||
175 | * when used as a normal user. This function returns this | ||
176 | * customized message. If none has been set, a default message | ||
177 | * will be used. | ||
178 | * | ||
179 | * @see KCModule::setRootOnlyMsg | ||
180 | */ | ||
181 | QString rootOnlyMsg() const; | ||
182 | |||
183 | /** | ||
184 | * Tell if KControl should show a RootOnly message when run as | ||
185 | * a normal user. | ||
186 | * | ||
187 | * In some cases, the module don't want a RootOnly message to | ||
188 | * appear (for example if it has already one). This function | ||
189 | * tells KControl if a RootOnly message should be shown | ||
190 | * | ||
191 | * @see KCModule::setUseRootOnlyMsg | ||
192 | */ | ||
193 | bool useRootOnlyMsg() const; | ||
194 | |||
195 | |||
196 | //US KInstance *instance() const; | ||
197 | |||
198 | signals: | ||
199 | |||
200 | /** | ||
201 | * Indicate that the state of the modules contents has changed. | ||
202 | * | ||
203 | * This signal is emitted whenever the state of the configuration | ||
204 | * shown in the module changes. It allows the control center to | ||
205 | * keep track of unsaved changes. | ||
206 | * | ||
207 | */ | ||
208 | void changed(bool state); | ||
209 | |||
210 | /** | ||
211 | * Indicate that the module's quickhelp has changed. | ||
212 | * | ||
213 | * Emit this signal whenever the module's quickhelp changes. | ||
214 | * Modules implemented as tabbed dialogs might want to implement | ||
215 | * per-tab quickhelp for example. | ||
216 | * | ||
217 | */ | ||
218 | void quickHelpChanged(); | ||
219 | |||
220 | protected: | ||
221 | |||
222 | /** | ||
223 | * Sets the buttons to display. | ||
224 | * | ||
225 | * Help: shows a "Help" button. | ||
226 | * Default: shows a "Use Defaults" button | ||
227 | * Apply: in kcontrol this will show an "Apply" and "Reset" button | ||
228 | * in kcmshell this will show an "Ok", "Apply" and "Cancel" button | ||
229 | * | ||
230 | * If Apply is not specified, kcmshell will show a "Close" button. | ||
231 | * | ||
232 | * @see KCModule::buttons | ||
233 | */ | ||
234 | void setButtons(int btn) { _btn = btn; }; | ||
235 | |||
236 | /** | ||
237 | * Sets the RootOnly message. | ||
238 | * | ||
239 | * This message will be shown at the top of the module of the | ||
240 | * corresponding desktop file contains the line X-KDE-RootOnly=true. | ||
241 | * If no message is set, a default one will be used. | ||
242 | * | ||
243 | * @see KCModule::rootOnlyMessage | ||
244 | */ | ||
245 | void setRootOnlyMsg(const QString& msg); | ||
246 | |||
247 | /** | ||
248 | * Change wether or not the RootOnly message should be shown. | ||
249 | * | ||
250 | * Following the value of @p on, the RootOnly message will be | ||
251 | * shown or not. | ||
252 | * | ||
253 | * @see KCModule::useRootOnlyMsg | ||
254 | */ | ||
255 | void setUseRootOnlyMsg(bool on); | ||
256 | |||
257 | private: | ||
258 | |||
259 | int _btn; | ||
260 | protected: | ||
261 | virtual void virtual_hook( int id, void* data ); | ||
262 | private: | ||
263 | KCModulePrivate *d; | ||
264 | }; | ||
265 | |||
266 | #endif | ||