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., 51 Franklin Street, Fifth Floor, |
19 | Boston, MA 02110-1301, USA. |
20 | |
21 | */ |
22 | |
23 | #ifndef KCMODULE_H |
24 | #define KCMODULE_H |
25 | |
26 | #include <kdeui_export.h> |
27 | |
28 | #include <QtCore/QVariant> |
29 | #include <QtGui/QWidget> |
30 | |
31 | #ifdef Q_WS_X11 |
32 | #include <fixx11h.h> |
33 | #endif |
34 | |
35 | class QStringList; |
36 | class KAboutData; |
37 | class KConfigDialogManager; |
38 | class KCoreConfigSkeleton; |
39 | class KConfigSkeleton; |
40 | class KCModulePrivate; |
41 | class KComponentData; |
42 | |
43 | namespace KAuth { |
44 | class Action; |
45 | } |
46 | |
47 | /** |
48 | * The base class for configuration modules. |
49 | * |
50 | * Configuration modules are realized as plugins that are loaded only when |
51 | * needed. |
52 | * |
53 | * The module in principle is a simple widget displaying the |
54 | * item to be changed. The module has a very small interface. |
55 | * |
56 | * All the necessary glue logic and the GUI bells and whistles |
57 | * are provided by the control center and must not concern |
58 | * the module author. |
59 | * |
60 | * To write a config module, you have to create a library |
61 | * that contains a factory function like the following: |
62 | * |
63 | * \code |
64 | * #include <KPluginFactory> |
65 | * |
66 | * K_PLUGIN_FACTORY(MyKCModuleFactory, registerPlugin<MyKCModule>() ) |
67 | * K_EXPORT_PLUGIN(MyKCModuleFactory("yourLibName","name_of_the_po_file") ) |
68 | * \endcode |
69 | * |
70 | * The optional parameter "name_of_the_po_file" has to correspond with the messages target |
71 | * that containst the strings to be translated. Instead of using the library name for |
72 | * \p yourLibName you can also use another name which you specify in the desktop |
73 | * file with \p X-KDE-FactoryName. This is useful to have more than one factory |
74 | * in one lib. |
75 | * |
76 | * The constructor of the KCModule then looks like this: |
77 | * \code |
78 | * YourKCModule::YourKCModule( QWidget* parent ) |
79 | * : KCModule( YourKCModuleFactory::componentData(), parent ) |
80 | * { |
81 | * KAboutData *about = new KAboutData( |
82 | * <kcm name>, 0, ki18n( "..." ), |
83 | * KDE_VERSION_STRING, KLocalizedString(), KAboutData::License_GPL, |
84 | * ki18n( "Copyright 2006 ..." ) ); |
85 | * about->addAuthor( ki18n(...) ); |
86 | * setAboutData( about ); |
87 | * . |
88 | * . |
89 | * . |
90 | * } |
91 | * \endcode |
92 | * |
93 | * If you want to make the KCModule available only conditionally (i.e. show in |
94 | * the list of available modules only if some test succeeds) then you can use |
95 | * Hidden in the .desktop file. An example: |
96 | * \code |
97 | * Hidden[$e]=$(if test -e /dev/js*; then echo "false"; else echo "true"; fi) |
98 | * \endcode |
99 | * The example executes the given code in a shell and uses the stdout output for |
100 | * the Hidden value (so it's either Hidden=true or Hidden=false). |
101 | * |
102 | * See http://techbase.kde.org/Development/Tutorials/KCM_HowTo |
103 | * for more detailed documentation. |
104 | * |
105 | * @author Matthias Hoelzer-Kluepfel <hoelzer@kde.org> |
106 | */ |
107 | class KDEUI_EXPORT KCModule : public QWidget |
108 | { |
109 | Q_OBJECT |
110 | |
111 | public: |
112 | |
113 | /** |
114 | * An enumeration type for the buttons used by this module. |
115 | * You should only use Help, Default and Apply. The rest is obsolete. |
116 | * NoAdditionalButton can be used when we do not want have other button that Ok Cancel |
117 | * |
118 | * @see KCModule::buttons @see KCModule::setButtons |
119 | */ |
120 | enum Button { NoAdditionalButton=0, Help=1, Default=2, Apply=4, Export=8 }; |
121 | Q_DECLARE_FLAGS( Buttons, Button ) |
122 | |
123 | #ifdef KDE3_SUPPORT |
124 | KDE_CONSTRUCTOR_DEPRECATED KCModule( QWidget *parent, const char *name, const QStringList& args = QStringList() ); |
125 | |
126 | KDE_CONSTRUCTOR_DEPRECATED KCModule(const KComponentData &componentData, QWidget *parent, const QStringList& args); |
127 | #endif |
128 | |
129 | /** |
130 | * Base class for all KControlModules. |
131 | * |
132 | * @note do not emit changed signals here, since they are not yet connected |
133 | * to any slot. |
134 | */ |
135 | explicit KCModule(const KComponentData &componentData, QWidget *parent = 0, const QVariantList& args = QVariantList()); |
136 | |
137 | /** |
138 | * Destroys the module. |
139 | */ |
140 | ~KCModule(); |
141 | |
142 | /** |
143 | * Return a quick-help text. |
144 | * |
145 | * This method is called when the module is docked. |
146 | * The quick-help text should contain a short description of the module and |
147 | * links to the module's help files. You can use QML formatting tags in the text. |
148 | * |
149 | * @note make sure the quick help text gets translated (use i18n()). |
150 | */ |
151 | virtual QString quickHelp() const; |
152 | |
153 | /** |
154 | * This is generally only called for the KBugReport. |
155 | * If you override you should have it return a pointer to a constant. |
156 | * |
157 | * |
158 | * @returns the KAboutData for this module |
159 | */ |
160 | virtual const KAboutData *aboutData() const; |
161 | |
162 | /** |
163 | * This sets the KAboutData returned by aboutData() |
164 | */ |
165 | void setAboutData( const KAboutData* about ); |
166 | |
167 | /** |
168 | * Indicate which buttons will be used. |
169 | * |
170 | * The return value is a value or'ed together from |
171 | * the Button enumeration type. |
172 | * |
173 | * @see KCModule::setButtons |
174 | */ |
175 | Buttons buttons() const; |
176 | |
177 | /** |
178 | * Get the RootOnly message for this module. |
179 | * |
180 | * When the module must be run as root, or acts differently |
181 | * for root and a normal user, it is sometimes useful to |
182 | * customize the message that appears at the top of the module |
183 | * when used as a normal user. This function returns this |
184 | * customized message. If none has been set, a default message |
185 | * will be used. |
186 | * |
187 | * @see KCModule::setRootOnlyMessage |
188 | */ |
189 | QString rootOnlyMessage() const; |
190 | |
191 | /** |
192 | * Tell if KControl should show a RootOnly message when run as |
193 | * a normal user. |
194 | * |
195 | * In some cases, the module don't want a RootOnly message to |
196 | * appear (for example if it has already one). This function |
197 | * tells KControl if a RootOnly message should be shown |
198 | * |
199 | * @see KCModule::setUseRootOnlyMessage |
200 | */ |
201 | bool useRootOnlyMessage() const; |
202 | |
203 | KComponentData componentData() const; |
204 | |
205 | /** |
206 | * @return a list of @ref KConfigDialogManager's in use, if any. |
207 | */ |
208 | QList<KConfigDialogManager*> configs() const; |
209 | |
210 | /** |
211 | * @brief Set if the module's save() method requires authorization to be executed. |
212 | * |
213 | * The module can set this property to @c true if it requires authorization. |
214 | * It will still have to execute the action itself using the KAuth library, so |
215 | * this method is not technically needed to perform the action, but |
216 | * using this and/or the setAuthAction() method will ensure that hosting |
217 | * applications like System Settings or kcmshell behave correctly. |
218 | * |
219 | * Called with @c true, this method will set the action to "org.kde.kcontrol.name.save" where |
220 | * "name" is aboutData()->appName() return value. This default action won't be set if |
221 | * the aboutData() object is not valid. |
222 | * |
223 | * Note that called with @c false, this method will reset the action name set with setAuthAction(). |
224 | * |
225 | * @param needsAuth Tells if the module's save() method requires authorization to be executed. |
226 | */ |
227 | void setNeedsAuthorization(bool needsAuth); |
228 | |
229 | /** |
230 | * Returns the value previously set with setNeedsAuthorization(). By default it's @c false. |
231 | * |
232 | * @return @c true if the module's save() method requires authorization, @c false otherwise |
233 | */ |
234 | bool needsAuthorization() const; |
235 | |
236 | /** |
237 | * Returns the action previously set with setAuthAction(). By default its an invalid action. |
238 | * |
239 | * @return The action that has to be authorized to execute the save() method. |
240 | */ |
241 | KAuth::Action *authAction() const; |
242 | |
243 | /** |
244 | * Returns the value set by setExportText(); |
245 | */ |
246 | QString exportText() const; |
247 | |
248 | /** |
249 | * Sets the export QString value, used for exporting data. |
250 | */ |
251 | void setExportText(const QString &); |
252 | |
253 | public Q_SLOTS: |
254 | /** |
255 | * Load the configuration data into the module. |
256 | * |
257 | * The load method sets the user interface elements of the |
258 | * module to reflect the current settings stored in the |
259 | * configuration files. |
260 | * |
261 | * This method is invoked whenever the module should read its configuration |
262 | * (most of the times from a config file) and update the user interface. |
263 | * This happens when the user clicks the "Reset" button in the control |
264 | * center, to undo all of his changes and restore the currently valid |
265 | * settings. It is also called right after construction. |
266 | */ |
267 | virtual void load(); |
268 | |
269 | /** |
270 | * Save the configuration data. |
271 | * |
272 | * The save method stores the config information as shown |
273 | * in the user interface in the config files. |
274 | * |
275 | * If necessary, this method also updates the running system, |
276 | * e.g. by restarting applications. This normally does not apply for |
277 | * KSettings::Dialog modules where the updating is taken care of by |
278 | * KSettings::Dispatcher. |
279 | * |
280 | * save is called when the user clicks "Apply" or "Ok". |
281 | * |
282 | * If you use KConfigXT, saving is taken care off automatically and |
283 | * you do not need to load manually. However, if you for some reason reimplement it and |
284 | * also are using KConfigXT, you must call this function, otherwise the saving of KConfigXT |
285 | * options will not work. Call it at the very end of your reimplementation, to avoid |
286 | * changed() signals getting emitted when you modify widgets. |
287 | */ |
288 | virtual void save(); |
289 | |
290 | /** |
291 | * Sets the configuration to sensible default values. |
292 | * |
293 | * This method is called when the user clicks the "Default" |
294 | * button. It should set the display to useful values. |
295 | * |
296 | * If you use KConfigXT, you do not have to reimplement this function since |
297 | * the fetching and settings of default values is done automatically. However, if you |
298 | * reimplement and also are using KConfigXT, remember to call the base function at the |
299 | * very end of your reimplementation. |
300 | */ |
301 | virtual void defaults(); |
302 | |
303 | protected: |
304 | /** |
305 | * Adds a KCoreConfigskeleton @p config to watch the widget @p widget |
306 | * |
307 | * This function is useful if you need to handle multiple configuration files. |
308 | * |
309 | * @return a pointer to the KCoreConfigDialogManager in use |
310 | * @param config the KCoreConfigSkeleton to use |
311 | * @param widget the widget to watch |
312 | */ |
313 | KConfigDialogManager* addConfig( KCoreConfigSkeleton *config, QWidget* widget ); |
314 | |
315 | /** |
316 | * Adds a KConfigskeleton @p config to watch the widget @p widget |
317 | * |
318 | * This function is useful if you need to handle multiple configuration files. |
319 | * |
320 | * @return a pointer to the KConfigDialogManager in use |
321 | * @param config the KConfigSkeleton to use |
322 | * @param widget the widget to watch |
323 | */ |
324 | KConfigDialogManager* addConfig( KConfigSkeleton *config, QWidget* widget ); |
325 | |
326 | /** |
327 | * Sets the quick help. |
328 | */ |
329 | void setQuickHelp( const QString& help ); |
330 | |
331 | virtual void showEvent(QShowEvent *ev); |
332 | |
333 | friend class KCModuleProxy; |
334 | |
335 | Q_SIGNALS: |
336 | |
337 | /** |
338 | * Indicate that the state of the modules contents has changed. |
339 | * |
340 | * This signal is emitted whenever the state of the configuration |
341 | * shown in the module changes. It allows the module container to |
342 | * keep track of unsaved changes. |
343 | */ |
344 | void changed(bool state); |
345 | |
346 | /** |
347 | * Indicate that the module's quickhelp has changed. |
348 | * |
349 | * Emit this signal whenever the module's quickhelp changes. |
350 | * Modules implemented as tabbed dialogs might want to implement |
351 | * per-tab quickhelp for example. |
352 | * |
353 | */ |
354 | void quickHelpChanged(); |
355 | |
356 | /** |
357 | * Indicate that the module's root message has changed. |
358 | * |
359 | * Emits this signal whenever the module's root message changes. |
360 | * |
361 | * @since 4.4 |
362 | * |
363 | */ |
364 | void rootOnlyMessageChanged(bool use, QString message); |
365 | |
366 | protected Q_SLOTS: |
367 | |
368 | /** |
369 | * Calling this slot is equivalent to emitting changed(true). |
370 | */ |
371 | void changed(); |
372 | |
373 | /** |
374 | * A managed widget was changed, the widget settings and the current |
375 | * settings are compared and a corresponding changed() signal is emitted |
376 | */ |
377 | void widgetChanged(); |
378 | |
379 | /** |
380 | * The status of the auth action, if one, has changed |
381 | */ |
382 | void authStatusChanged(int); |
383 | |
384 | protected: |
385 | |
386 | /** |
387 | * Sets the buttons to display. |
388 | * |
389 | * Help: shows a "Help" button. |
390 | * |
391 | * Default: shows a "Use Defaults" button. |
392 | * |
393 | * Apply: in kcontrol this will show an "Apply" and "Reset" button, |
394 | * in kcmshell this will show an "Ok", "Apply" and "Cancel" button. |
395 | * |
396 | * If Apply is not specified, kcmshell will show a "Close" button. |
397 | * |
398 | * @see KCModule::buttons |
399 | */ |
400 | void setButtons(Buttons btn); |
401 | |
402 | /** |
403 | * Sets the RootOnly message. |
404 | * |
405 | * This message will be shown at the top of the module if useRootOnlyMessage is |
406 | * set. If no message is set, a default one will be used. |
407 | * |
408 | * @see KCModule::rootOnlyMessage |
409 | */ |
410 | void setRootOnlyMessage(const QString& message); |
411 | |
412 | /** |
413 | * Change whether or not the RootOnly message should be shown. |
414 | * |
415 | * Following the value of @p on, the RootOnly message will be |
416 | * shown or not. |
417 | * |
418 | * @see KCModule::useRootOnlyMessage |
419 | */ |
420 | void setUseRootOnlyMessage(bool on); |
421 | |
422 | /** |
423 | * Returns the changed state of automatically managed widgets in this dialog |
424 | */ |
425 | bool managedWidgetChangeState() const; |
426 | |
427 | /** |
428 | * Call this method when your manually managed widgets change state between |
429 | * changed and not changed |
430 | */ |
431 | void unmanagedWidgetChangeState(bool); |
432 | |
433 | private: |
434 | KCModulePrivate *const d; |
435 | }; |
436 | |
437 | Q_DECLARE_OPERATORS_FOR_FLAGS( KCModule::Buttons ) |
438 | |
439 | #endif //KCMODULE_H |
440 | |
441 | |