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
31class KAboutData;
32class KCModuleInfo;
33class KComponentData;
34class 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 */
67class KCMUTILS_EXPORT KCModuleProxy : public QWidget
68{
69Q_DECLARE_PRIVATE(KCModuleProxy)
70Q_OBJECT
71public:
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
204public 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
219Q_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
244protected:
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
252protected:
253 KCModuleProxyPrivate *const d_ptr;
254
255private:
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