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
35class QStringList;
36class KAboutData;
37class KConfigDialogManager;
38class KCoreConfigSkeleton;
39class KConfigSkeleton;
40class KCModulePrivate;
41class KComponentData;
42
43namespace 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 */
107class KDEUI_EXPORT KCModule : public QWidget
108{
109 Q_OBJECT
110
111public:
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
253public 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
303protected:
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
335Q_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
366protected 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
384protected:
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
433private:
434 KCModulePrivate *const d;
435};
436
437Q_DECLARE_OPERATORS_FOR_FLAGS( KCModule::Buttons )
438
439#endif //KCMODULE_H
440
441