KCMUtils

kcmoduleproxy.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 2003 Matthias Kretz <[email protected]>
4  SPDX-FileCopyrightText: 2004 Frans Englich <[email protected]>
5  SPDX-FileCopyrightText: 2021 Alexander Lohnau <[email protected]>
6 
7  SPDX-License-Identifier: LGPL-2.0-only
8 */
9 
10 #ifndef KCMUTILS_KCMODULEPROXY_H
11 #define KCMUTILS_KCMODULEPROXY_H
12 
13 #include <QStringList>
14 
15 #include <KCModule>
16 #include <KService>
17 #include <kcmutils_export.h>
18 
19 class KAboutData;
20 class KCModuleInfo;
21 class KCModuleProxyPrivate;
22 class KPluginMetaData;
23 
24 /**
25  *
26  * @brief Encapsulates a KCModule for embedding.
27  *
28  * KCModuleProxy is a wrapper for KCModule intended for cases where
29  * modules are to be displayed. It ensures layout is consistent
30  * and in general takes care of the details
31  * needed for making a module available in an interface. A KCModuleProxy
32  * can be treated as a QWidget, without worrying about the details specific
33  * for modules such as library loading. KCModuleProxy is not a sub class of KCModule
34  * but its API closely resembles KCModule's.\n
35  * Usually, an instance is created by passing one of the constructors a KService::Ptr,
36  * KCModuleInfo or simply the name of the module and then added to the layout as any
37  * other widget. \n
38  * When the user has changed the module, changed(bool) as well as changed(KCModuleProxy *)
39  * is emitted. KCModuleProxy does not take care of prompting for saving - if the object is deleted while
40  * changes is not saved the changes will be lost. changed() returns true if changes are unsaved. \n
41  * \n
42  * KCModuleProxy does not take care of authorization of KCModules. \n
43  * KCModuleProxy implements lazy loading, meaning the library will not be loaded or
44  * any other initialization done before its show() function is called. This means
45  * modules will only be loaded when they are actually needed as well as it is possible to
46  * load many KCModuleProxy without any speed penalty.
47  *
48  * KCModuleProxy should be used in all cases where modules are embedded in order to
49  * promote code efficiency and usability consistency.
50  *
51  * @author Frans Englich <[email protected]>
52  * @author Matthias Kretz <[email protected]>
53  *
54  */
55 class KCMUTILS_EXPORT KCModuleProxy : public QWidget
56 {
57  Q_DECLARE_PRIVATE(KCModuleProxy)
58  Q_OBJECT
59 public:
60 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 88)
61  /**
62  * Constructs a KCModuleProxy from a KCModuleInfo class.
63  *
64  * @param info The KCModuleInfo to construct the module from.
65  * @param parent the parent QWidget.
66  * @param args This is used in the implementation and is internal.
67  * Use the default.
68  * @deprecated Since 5.88, use KCModuleProxy(KPluginMetaData, QWidget *, QStringList) instead
69  */
70  KCMUTILS_DEPRECATED_VERSION(5, 88, "Use KCModuleProxy(KPluginMetaData, QWidget *, QStringList) instead")
71  explicit KCModuleProxy(const KCModuleInfo &info, QWidget *parent = nullptr, const QStringList &args = QStringList());
72 #endif
73 
74 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 88)
75  /**
76  * Constructs a KCModuleProxy from a module's service name, which is
77  * equivalent to the desktop file for the kcm without the ".desktop" part.
78  * Otherwise equal to the one above.
79  *
80  * @param serviceName The module's service name to construct from.
81  * @param parent the parent QWidget.
82  * @param args This is used in the implementation and is internal.
83  * Use the default.
84  * @deprecated Since 5.88, use KCModuleProxy(KPluginMetaData, QWidget *, QStringList) instead
85  */
86  KCMUTILS_DEPRECATED_VERSION(5, 88, "Use KCModuleProxy(KPluginMetaData, QWidget *, QStringList) instead")
87  explicit KCModuleProxy(const QString &serviceName, QWidget *parent = nullptr, const QStringList &args = QStringList());
88 #endif
89 
90 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 88)
91  /**
92  * Constructs a KCModuleProxy from KService. Otherwise equal to the one above.
93  *
94  * @param service The KService to construct from.
95  * @param parent the parent QWidget.
96  * @param args This is used in the implementation and is internal.
97  * Use the default.
98  * @deprecated Since 5.88, use KCModuleProxy(KPluginMetaData, QWidget *, QStringList) instead
99  */
100  KCMUTILS_DEPRECATED_VERSION(5, 88, "Use KCModuleProxy(KPluginMetaData, QWidget *, QStringList) instead")
101  explicit KCModuleProxy(const KService::Ptr &service, QWidget *parent = nullptr, const QStringList &args = QStringList());
102 #endif
103 
104  /**
105  * Constructs a KCModuleProxy from KPluginMetaData
106  * @since 5.84
107  */
108  explicit KCModuleProxy(const KPluginMetaData &metaData, QWidget *parent = nullptr, const QStringList &args = QStringList());
109 
110  /**
111  * Default destructor
112  */
113  ~KCModuleProxy() override;
114 
115  /**
116  * Calling it will cause the contained module to
117  * run its load() routine.
118  */
119  void load();
120 
121  /**
122  * Calling it will cause the contained module to
123  * run its save() routine.
124  *
125  * If the module was not modified, it will not be asked
126  * to save.
127  */
128  void save();
129 
130  /**
131  * @return the module's quickHelp();
132  */
133  QString quickHelp() const;
134 
135 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 85)
136  /**
137  * @return the module's aboutData()
138  * @deprecated since 5.85, use metaData() instead.
139  */
140  KCMUTILS_DEPRECATED_VERSION(5, 85, "Use metaData() instead")
141  const KAboutData *aboutData() const;
142 #endif
143 
144  /**
145  * @return what buttons the module
146  * needs
147  */
148  KCModule::Buttons buttons() const;
149 
150 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 87)
151  /**
152  * @return true if the module is modified
153  * and needs to be saved.
154  * @deprecated Since 5.87, use isChanged instead
155  */
156  KCMUTILS_DEPRECATED_VERSION(5, 87, "use isChanged instead")
157  bool changed() const;
158 #endif
159  /**
160  * @return true if the module is modified
161  * and needs to be saved.
162  * @since 5.87
163  */
164  bool isChanged() const;
165 
166  /**
167  * @return true if the module is matching default settings
168  *
169  * @since 5.65
170  */
171  bool defaulted() const;
172 
173  /**
174  * Access to the actual module.
175  * It may return NULL if anything goes wrong.
176  *
177  * @return the encapsulated module.
178  */
179  KCModule *realModule() const;
180 
181 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 88)
182  /**
183  * @return a KCModuleInfo for the encapsulated
184  * module
185  * @deprecated Since 5.87 method is obsolete with deprecation of KCModuleInfo constructor, use metaData() instead
186  */
187  KCMUTILS_DEPRECATED_VERSION(5, 88, "method is obsolete with deprecation of KCModuleInfo constructor, use metaData() instead")
188  KCModuleInfo moduleInfo() const;
189 #endif
190 
191  /**
192  * Returns the KPluginMetaData used to load the KCM. If the KCM is not loaded using KPluginMetaData the returned object is invalid.
193  * @return a KPluginMetaData for the encapsulated module
194  * @since 5.84
195  */
196  KPluginMetaData metaData() const;
197 
198  /**
199  * Returns the D-Bus Service name
200  */
201  QString dbusService() const;
202  /**
203  * Returns the D-Bus Path
204  */
205  QString dbusPath() const;
206  /**
207  * Returns the recommended minimum size for the widget
208  */
209  QSize minimumSizeHint() const override;
210 
211  /**
212  * Show or hide an indicator when settings have changed from their default value
213  *
214  * @since 5.73
215  */
216  void setDefaultsIndicatorsVisible(bool show);
217 
218 public Q_SLOTS:
219 
220  /**
221  * Calling it will cause the contained module to
222  * load its default values.
223  */
224  void defaults();
225 
226  /**
227  * Calling this, results in deleting the contained
228  * module, and unregistering from DCOP. A similar result is achieved
229  * by deleting the KCModuleProxy itself.
230  */
231  void deleteClient();
232 
233 Q_SIGNALS:
234 
235  /*
236  * This signal is emitted when the contained module is changed.
237  */
238  void changed(bool state);
239 
240 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 87)
241  /**
242  * This is emitted in the same situations as in the one above. Practical
243  * when several KCModuleProxys are loaded.
244  * @deprecated Since 5.87, use changed(bool) instead
245  */
246  KCMUTILS_DEPRECATED_VERSION(5, 87, "use changed(bool) instead")
247  void changed(KCModuleProxy *mod);
248 #endif
249 
250  /**
251  * When a module running with root privileges and exits, returns to normal mode, the
252  * childClosed() signal is emitted.
253  */
254  void childClosed();
255 
256  /*
257  * This signal is relayed from the encapsulated module, and
258  * is equivalent to the module's own quickHelpChanged() signal.
259  */
260  void quickHelpChanged();
261 
262 protected:
263  /**
264  * Reimplemented for internal purposes. Makes sure the encapsulated
265  * module is loaded before the show event is taken care of.
266  */
267  void showEvent(QShowEvent *) override;
268 
269 protected:
270  KCModuleProxyPrivate *const d_ptr;
271 
272 private:
273  Q_PRIVATE_SLOT(d_func(), void _k_moduleChanged(bool))
274  Q_PRIVATE_SLOT(d_func(), void _k_moduleDefaulted(bool))
275  Q_PRIVATE_SLOT(d_func(), void _k_moduleDestroyed())
276  Q_PRIVATE_SLOT(d_func(), void _k_ownerChanged(const QString &service, const QString &oldOwner, const QString &newOwner))
277 };
278 
279 #endif // KUTILS_KCMODULEPROXY_H
Encapsulates a KCModule for embedding.
Definition: kcmoduleproxy.h:55
Q_SLOTSQ_SLOTS
virtual void showEvent(QShowEvent *event)
Q_SIGNALSQ_SIGNALS
A class that provides information about a KCModule.
Definition: kcmoduleinfo.h:36
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sun Jun 26 2022 03:51:23 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.