1 /* 2 This file is part of the KDE project 3 SPDX-FileCopyrightText: 2003 Matthias Kretz <kretz@kde.org> 4 SPDX-FileCopyrightText: 2004 Frans Englich <frans.englich@telia.com> 5 SPDX-FileCopyrightText: 2021 Alexander Lohnau <alexander.lohnau@gmx.de> 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 <frans.englich@telia.com> 52 * @author Matthias Kretz <kretz@kde.org> 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 280