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 | |
30 | class QWidget; |
31 | |
32 | class 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 | */ |
49 | class 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) \ |
163 | class KCModuleContainer##factoryName : public KCModuleContainer \ |
164 | { \ |
165 | public: \ |
166 | KCModuleContainer##factoryName(QWidget *parent, const QVariantList &) \ |
167 | : KCModuleContainer(parent, QLatin1String(modules)) \ |
168 | { \ |
169 | } \ |
170 | }; \ |
171 | K_PLUGIN_FACTORY(KCModuleContainer##factoryName##Factory, \ |
172 | registerPlugin<KCModuleContainer#factoryName>(); \ |
173 | ) \ |
174 | K_EXPORT_PLUGIN(KCModuleContainer##factoryName##Factory) |
175 | |
176 | #endif // KCMODULECONTAINER_H |
177 | |
178 | |
179 | |