1 | /* This file is part of the KDE project |
2 | Copyright (C) 2003 Matthias Kretz <kretz@kde.org> |
3 | Copyright (C) 2004 Frans Englich <frans.englich@telia.com> |
4 | |
5 | This library is free software; you can redistribute it and/or |
6 | modify it under the terms of the GNU Library General Public |
7 | License version 2 as published by the Free Software Foundation. |
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 | |
21 | #ifndef KCMUTILS_KCMODULEPROXY_H |
22 | #define KCMUTILS_KCMODULEPROXY_H |
23 | |
24 | #include <QtGui/QImage> |
25 | #include <QtCore/QStringList> |
26 | |
27 | #include <kcmodule.h> |
28 | #include <kservice.h> |
29 | #include <kcmutils_export.h> |
30 | |
31 | class KAboutData; |
32 | class KCModuleInfo; |
33 | class KComponentData; |
34 | class KCModuleProxyPrivate; |
35 | |
36 | /** |
37 | * |
38 | * @brief Encapsulates a KCModule for embedding. |
39 | * |
40 | * KCModuleProxy is a wrapper for KCModule intended for cases where |
41 | * modules are to be displayed. It ensures layout is consistent |
42 | * and in general takes care of the details |
43 | * needed for making a module available in an interface. A KCModuleProxy |
44 | * can be treated as a QWidget, without worrying about the details specific |
45 | * for modules such as library loading. KCModuleProxy is not a sub class of KCModule |
46 | * but its API closely resembles KCModule's.\n |
47 | * Usually, an instance is created by passing one of the constructors a KService::Ptr, |
48 | * KCModuleInfo or simply the name of the module and then added to the layout as any |
49 | * other widget. \n |
50 | * When the user has changed the module, changed(bool) as well as changed(KCModuleProxy *) |
51 | * is emitted. KCModuleProxy does not take care of prompting for saving - if the object is deleted while |
52 | * changes is not saved the changes will be lost. changed() returns true if changes are unsaved. \n |
53 | * \n |
54 | * KCModuleProxy does not take care of authorization of KCModules. \n |
55 | * KCModuleProxy implements lazy loading, meaning the library will not be loaded or |
56 | * any other initialization done before its show() function is called. This means |
57 | * modules will only be loaded when they are actually needed as well as it is possible to |
58 | * load many KCModuleProxy without any speed penalty. |
59 | * |
60 | * KCModuleProxy should be used in all cases where modules are embedded in order to |
61 | * promote code efficiency and usability consistency. |
62 | * |
63 | * @author Frans Englich <frans.englich@telia.com> |
64 | * @author Matthias Kretz <kretz@kde.org> |
65 | * |
66 | */ |
67 | class KCMUTILS_EXPORT KCModuleProxy : public QWidget |
68 | { |
69 | Q_DECLARE_PRIVATE(KCModuleProxy) |
70 | Q_OBJECT |
71 | public: |
72 | /** |
73 | * Constructs a KCModuleProxy from a KCModuleInfo class. |
74 | * |
75 | * @param info The KCModuleInfo to construct the module from. |
76 | * @param parent the parent QWidget. |
77 | * @param args This is used in the implementation and is internal. |
78 | * Use the default. |
79 | */ |
80 | explicit KCModuleProxy( const KCModuleInfo& info, QWidget* parent = 0, |
81 | const QStringList& args = QStringList() ); |
82 | |
83 | /** |
84 | * Constructs a KCModuleProxy from a module's service name, which is |
85 | * equivalent to the desktop file for the kcm without the ".desktop" part. |
86 | * Otherwise equal to the one above. |
87 | * |
88 | * @param serviceName The module's service name to construct from. |
89 | * @param parent the parent QWidget. |
90 | * @param args This is used in the implementation and is internal. |
91 | * Use the default. |
92 | */ |
93 | explicit KCModuleProxy( const QString& serviceName, QWidget* parent = 0, |
94 | const QStringList& args = QStringList() ); |
95 | |
96 | /** |
97 | * Constructs a KCModuleProxy from KService. Otherwise equal to the one above. |
98 | * |
99 | * @param service The KService to construct from. |
100 | * @param parent the parent QWidget. |
101 | * @param args This is used in the implementation and is internal. |
102 | * Use the default. |
103 | */ |
104 | explicit KCModuleProxy( const KService::Ptr& service, QWidget* parent = 0, |
105 | const QStringList& args = QStringList() ); |
106 | |
107 | /** |
108 | * Default destructor |
109 | */ |
110 | ~KCModuleProxy(); |
111 | |
112 | /** |
113 | * Calling it will cause the contained module to |
114 | * run its load() routine. |
115 | */ |
116 | void load(); |
117 | |
118 | /** |
119 | * Calling it will cause the contained module to |
120 | * run its save() routine. |
121 | * |
122 | * If the module was not modified, it will not be asked |
123 | * to save. |
124 | */ |
125 | void save(); |
126 | |
127 | /** |
128 | * @return the module's quickHelp(); |
129 | */ |
130 | QString quickHelp() const; |
131 | |
132 | /** |
133 | * @return the module's aboutData() |
134 | */ |
135 | const KAboutData * aboutData() const; |
136 | |
137 | /** |
138 | * @return what buttons the module |
139 | * needs |
140 | */ |
141 | KCModule::Buttons buttons() const; |
142 | |
143 | /** |
144 | * @return The module's custom root |
145 | * message, if it has one |
146 | * @deprecated |
147 | */ |
148 | QString rootOnlyMessage() const; |
149 | //KDE4 remove. There's a limit for convenience functions, |
150 | // this one's available via realModule()-> |
151 | |
152 | /** |
153 | * @return If the module is a root module. |
154 | * @deprecated |
155 | */ |
156 | bool useRootOnlyMessage() const; |
157 | //KDE4 remove. There's a limit for convenience functions, |
158 | // this one's available via realModule()-> |
159 | |
160 | /** |
161 | * Returns the embedded KCModule's KComponentData. |
162 | * @return The module's KComponentData. |
163 | * @deprecated |
164 | */ |
165 | KComponentData componentData() const; |
166 | //KDE4 remove. There's a limit for convenience functions, |
167 | // this one's available via realModule() |
168 | |
169 | /** |
170 | * @return true if the module is modified |
171 | * and needs to be saved. |
172 | */ |
173 | bool changed() const; |
174 | |
175 | /** |
176 | * Access to the actual module. However, if the module is |
177 | * running in root mode, see rootMode(), this function returns |
178 | * a NULL pointer, since the module is in another process. It may also |
179 | * return NULL if anything goes wrong. |
180 | * |
181 | * @return the encapsulated module. |
182 | */ |
183 | KCModule* realModule() const; |
184 | |
185 | /** |
186 | * @return a KCModuleInfo for the encapsulated |
187 | * module |
188 | */ |
189 | KCModuleInfo moduleInfo() const; |
190 | |
191 | /** |
192 | * Returns the DBUS Service name |
193 | */ |
194 | QString dbusService() const; |
195 | /** |
196 | * Returns the DBUS Path |
197 | */ |
198 | QString dbusPath() const; |
199 | /** |
200 | * Returns the recommended minimum size for the widget |
201 | */ |
202 | QSize minimumSizeHint() const; |
203 | |
204 | public Q_SLOTS: |
205 | |
206 | /** |
207 | * Calling it will cause the contained module to |
208 | * load its default values. |
209 | */ |
210 | void defaults(); |
211 | |
212 | /** |
213 | * Calling this, results in deleting the contained |
214 | * module, and unregistering from DCOP. A similar result is achieved |
215 | * by deleting the KCModuleProxy itself. |
216 | */ |
217 | void deleteClient(); |
218 | |
219 | Q_SIGNALS: |
220 | |
221 | /* |
222 | * This signal is emitted when the contained module is changed. |
223 | */ |
224 | void changed( bool state ); |
225 | |
226 | /** |
227 | * This is emitted in the same situations as in the one above. Practical |
228 | * when several KCModuleProxys are loaded. |
229 | */ |
230 | void changed( KCModuleProxy* mod ); |
231 | |
232 | /** |
233 | * When a module running with root privileges and exits, returns to normal mode, the |
234 | * childClosed() signal is emitted. |
235 | */ |
236 | void childClosed(); |
237 | |
238 | /* |
239 | * This signal is relayed from the encapsulated module, and |
240 | * is equivalent to the module's own quickHelpChanged() signal. |
241 | */ |
242 | void quickHelpChanged(); |
243 | |
244 | protected: |
245 | |
246 | /** |
247 | * Reimplemented for internal purposes. Makes sure the encapsulated |
248 | * module is loaded before the show event is taken care of. |
249 | */ |
250 | void showEvent( QShowEvent * ); |
251 | |
252 | protected: |
253 | KCModuleProxyPrivate *const d_ptr; |
254 | |
255 | private: |
256 | Q_PRIVATE_SLOT(d_func(), void _k_moduleChanged(bool)) |
257 | Q_PRIVATE_SLOT(d_func(), void _k_moduleDestroyed()) |
258 | Q_PRIVATE_SLOT(d_func(), void _k_ownerChanged(const QString &service, const QString &oldOwner, const QString &newOwner)) |
259 | }; |
260 | |
261 | #endif // KUTILS_KCMODULEPROXY_H |
262 | // vim: ts=4 |
263 | |