1/* This file is part of the KDE libraries
2 Copyright (C) 2004 Frans Englich <frans.englich@telia.com>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KCMODULECONTAINER_H
21#define KCMODULECONTAINER_H
22
23#include <QtCore/QString>
24#include <QtCore/QStringList>
25
26#include <kcmodule.h>
27#include <kcmoduleloader.h>
28#include <QtCore/QList>
29
30class QWidget;
31
32class KCModuleProxy;
33
34/**
35 * @brief KCModuleContainer is a convenience class encapsulating several KCModules.
36 *
37 * The KCModuleContainer class is a convenience class for organizing a multiple set
38 * of KCModule. KCModuleContainer is a sub class of KCModule and builds an interface mainly
39 * consisting of a tab widget where each tab contains one of the modules specified via one of the
40 * constructors. KCModuleContainer can handle modules which requires root permissions. What you
41 * most likely want is the KCMODULECONTAINER macro. \n
42 * Sometimes it is of interest to detect in runtime whether a module should be loaded or not. This
43 * can be achieved by sub classing KCModuleContainer, doing the probing/testing checks and then manually
44 * call addModule for each module which should be displayed. When all calls to addModule is done, call
45 * finalize() which performs some necessary final steps.
46 *
47 * @author Frans Englich <frans.englich@telia.com>
48 */
49class KCMUTILS_EXPORT KCModuleContainer : public KCModule
50{
51 Q_OBJECT
52 public:
53 /**
54 * Creates a KCModuleContainer with tabs, each one containing one of the
55 * specified modules in @p mods.
56 *
57 * @param parent the parent QWidget.
58 * @param mods The list of KCModules to be loaded. The name of each
59 * KCModule is its service name, that is the name of the desktop file without
60 * the ".desktop" part
61 *
62 */
63 KCModuleContainer( QWidget* parent, const QStringList& mods );
64
65 /**
66 * This is a convenience function, instead of building a QStringList you
67 * can specify the modules in a comma separated QString. For example;
68 * \code
69 * KCModuleContainer* cont = KCModuleContainer( this, "kcm_misc", QString("kcm_energy, kcm_keyboard ,kcm_useraccount, kcm_mouse") );
70 * \endcode
71 * The other constructor takes its modules in a QStringlist which also can be constructed from a
72 * string and thus you will have to be explicit on the data type.
73 *
74 * What you probably want is the KCMODULECONTAINER macro which builds an KCModule
75 * for you, taking the modules you want as argument.
76 *
77 * @param parent The parent widget
78 * @param mods The modules to load
79 * @return The KCModule containing the requested modules.
80 */
81 explicit KCModuleContainer( QWidget *parent, const QString& mods = QString() );
82
83 /**
84 * Adds the specified module to the tab widget. Setting the tab icon, text,
85 * tool tip, connecting the signals is what it does.
86 *
87 * @param module the name of the module to add. The name is the desktop file's name
88 * without the ".desktop" part.
89 */
90 void addModule( const QString& module );
91
92 /**
93 * Default destructor.
94 */
95 virtual ~KCModuleContainer();
96
97 /**
98 * Reimplemented for internal purposes.
99 * @internal
100 */
101 void save();
102
103 /**
104 * Reimplemented for internal purposes.
105 * @internal
106 */
107 void load();
108
109 /**
110 * Reimplemented for internal purposes.
111 * @internal
112 */
113 void defaults();
114
115 protected:
116 typedef QList<KCModuleProxy*> ModuleList;
117
118 /**
119 * A list containing KCModuleProxy objects which
120 * have changed and must be saved.
121 */
122 ModuleList changedModules;
123
124 /**
125 * A list of all modules which are encapsulated.
126 */
127 ModuleList allModules; // KDE 4 put in the Private class and abstract with getter
128
129 private Q_SLOTS:
130
131 /**
132 * Enables/disables the Admin Mode button, as appropriate.
133 */
134 void tabSwitched(int);
135
136 void moduleChanged(KCModuleProxy *proxy);
137
138 private:
139
140 void init();
141
142 class KCModuleContainerPrivate;
143 KCModuleContainerPrivate* const d;
144
145};
146
147/**
148 * This macro creates an factory declaration which when run creates an KCModule with specified
149 * modules. For example:
150 * \code
151 * KCMODULECONTAINER("kcm_fonts,kcm_keyboard,kcm_foo", misc_modules)
152 * \endcode
153 * would create a KCModule with three tabs, each containing one of the specified KCMs. Each
154 * use of the macro must be accompanied by a desktop file where the factory name equals
155 * the second argument in the macro(in this example, misc_modules). \n
156 * The module container takes care of testing the contained modules when being shown, as well
157 * as when the module itself is asked whether it should be shown.
158 *
159 * @param modules the modules to put in the container
160 * @param factoryName what factory name the module should have
161 */
162#define KCMODULECONTAINER(modules, factoryName) \
163class KCModuleContainer##factoryName : public KCModuleContainer \
164{ \
165 public: \
166 KCModuleContainer##factoryName(QWidget *parent, const QVariantList &) \
167 : KCModuleContainer(parent, QLatin1String(modules)) \
168 { \
169 } \
170}; \
171K_PLUGIN_FACTORY(KCModuleContainer##factoryName##Factory, \
172 registerPlugin<KCModuleContainer#factoryName>(); \
173 ) \
174K_EXPORT_PLUGIN(KCModuleContainer##factoryName##Factory)
175
176#endif // KCMODULECONTAINER_H
177
178
179