File indexing completed on 2024-04-14 14:18:22
0001 /* 0002 This file is part of the KDE project 0003 SPDX-FileCopyrightText: 2003 Matthias Kretz <kretz@kde.org> 0004 SPDX-FileCopyrightText: 2004 Frans Englich <frans.englich@telia.com> 0005 SPDX-FileCopyrightText: 2021 Alexander Lohnau <alexander.lohnau@gmx.de> 0006 0007 SPDX-License-Identifier: LGPL-2.0-only 0008 */ 0009 0010 #ifndef KCMUTILS_KCMODULEPROXY_H 0011 #define KCMUTILS_KCMODULEPROXY_H 0012 0013 #include <QStringList> 0014 0015 #include <KCModule> 0016 #include <KService> 0017 #include <kcmutils_export.h> 0018 0019 class KAboutData; 0020 class KCModuleInfo; 0021 class KCModuleProxyPrivate; 0022 class KPluginMetaData; 0023 0024 /** 0025 * 0026 * @brief Encapsulates a KCModule for embedding. 0027 * 0028 * KCModuleProxy is a wrapper for KCModule intended for cases where 0029 * modules are to be displayed. It ensures layout is consistent 0030 * and in general takes care of the details 0031 * needed for making a module available in an interface. A KCModuleProxy 0032 * can be treated as a QWidget, without worrying about the details specific 0033 * for modules such as library loading. KCModuleProxy is not a sub class of KCModule 0034 * but its API closely resembles KCModule's.\n 0035 * Usually, an instance is created by passing one of the constructors a KService::Ptr, 0036 * KCModuleInfo or simply the name of the module and then added to the layout as any 0037 * other widget. \n 0038 * When the user has changed the module, changed(bool) as well as changed(KCModuleProxy *) 0039 * is emitted. KCModuleProxy does not take care of prompting for saving - if the object is deleted while 0040 * changes is not saved the changes will be lost. changed() returns true if changes are unsaved. \n 0041 * \n 0042 * KCModuleProxy does not take care of authorization of KCModules. \n 0043 * KCModuleProxy implements lazy loading, meaning the library will not be loaded or 0044 * any other initialization done before its show() function is called. This means 0045 * modules will only be loaded when they are actually needed as well as it is possible to 0046 * load many KCModuleProxy without any speed penalty. 0047 * 0048 * KCModuleProxy should be used in all cases where modules are embedded in order to 0049 * promote code efficiency and usability consistency. 0050 * 0051 * @author Frans Englich <frans.englich@telia.com> 0052 * @author Matthias Kretz <kretz@kde.org> 0053 * 0054 */ 0055 class KCMUTILS_EXPORT KCModuleProxy : public QWidget 0056 { 0057 Q_DECLARE_PRIVATE(KCModuleProxy) 0058 Q_OBJECT 0059 public: 0060 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 88) 0061 /** 0062 * Constructs a KCModuleProxy from a KCModuleInfo class. 0063 * 0064 * @param info The KCModuleInfo to construct the module from. 0065 * @param parent the parent QWidget. 0066 * @param args This is used in the implementation and is internal. 0067 * Use the default. 0068 * @deprecated Since 5.88, use KCModuleProxy(KPluginMetaData, QWidget *, QStringList) instead 0069 */ 0070 KCMUTILS_DEPRECATED_VERSION(5, 88, "Use KCModuleProxy(KPluginMetaData, QWidget *, QStringList) instead") 0071 explicit KCModuleProxy(const KCModuleInfo &info, QWidget *parent = nullptr, const QStringList &args = QStringList()); 0072 #endif 0073 0074 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 88) 0075 /** 0076 * Constructs a KCModuleProxy from a module's service name, which is 0077 * equivalent to the desktop file for the kcm without the ".desktop" part. 0078 * Otherwise equal to the one above. 0079 * 0080 * @param serviceName The module's service name to construct from. 0081 * @param parent the parent QWidget. 0082 * @param args This is used in the implementation and is internal. 0083 * Use the default. 0084 * @deprecated Since 5.88, use KCModuleProxy(KPluginMetaData, QWidget *, QStringList) instead 0085 */ 0086 KCMUTILS_DEPRECATED_VERSION(5, 88, "Use KCModuleProxy(KPluginMetaData, QWidget *, QStringList) instead") 0087 explicit KCModuleProxy(const QString &serviceName, QWidget *parent = nullptr, const QStringList &args = QStringList()); 0088 #endif 0089 0090 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 88) 0091 /** 0092 * Constructs a KCModuleProxy from KService. Otherwise equal to the one above. 0093 * 0094 * @param service The KService to construct from. 0095 * @param parent the parent QWidget. 0096 * @param args This is used in the implementation and is internal. 0097 * Use the default. 0098 * @deprecated Since 5.88, use KCModuleProxy(KPluginMetaData, QWidget *, QStringList) instead 0099 */ 0100 KCMUTILS_DEPRECATED_VERSION(5, 88, "Use KCModuleProxy(KPluginMetaData, QWidget *, QStringList) instead") 0101 explicit KCModuleProxy(const KService::Ptr &service, QWidget *parent = nullptr, const QStringList &args = QStringList()); 0102 #endif 0103 0104 /** 0105 * Constructs a KCModuleProxy from KPluginMetaData 0106 * @since 5.84 0107 */ 0108 explicit KCModuleProxy(const KPluginMetaData &metaData, QWidget *parent = nullptr, const QStringList &args = QStringList()); 0109 0110 /** 0111 * Default destructor 0112 */ 0113 ~KCModuleProxy() override; 0114 0115 /** 0116 * Calling it will cause the contained module to 0117 * run its load() routine. 0118 */ 0119 void load(); 0120 0121 /** 0122 * Calling it will cause the contained module to 0123 * run its save() routine. 0124 * 0125 * If the module was not modified, it will not be asked 0126 * to save. 0127 */ 0128 void save(); 0129 0130 /** 0131 * @return the module's quickHelp(); 0132 */ 0133 QString quickHelp() const; 0134 0135 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 85) 0136 /** 0137 * @return the module's aboutData() 0138 * @deprecated since 5.85, use metaData() instead. 0139 */ 0140 KCMUTILS_DEPRECATED_VERSION(5, 85, "Use metaData() instead") 0141 const KAboutData *aboutData() const; 0142 #endif 0143 0144 /** 0145 * @return what buttons the module 0146 * needs 0147 */ 0148 KCModule::Buttons buttons() const; 0149 0150 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 87) 0151 /** 0152 * @return true if the module is modified 0153 * and needs to be saved. 0154 * @deprecated Since 5.87, use isChanged instead 0155 */ 0156 KCMUTILS_DEPRECATED_VERSION(5, 87, "use isChanged instead") 0157 bool changed() const; 0158 #endif 0159 /** 0160 * @return true if the module is modified 0161 * and needs to be saved. 0162 * @since 5.87 0163 */ 0164 bool isChanged() const; 0165 0166 /** 0167 * @return true if the module is matching default settings 0168 * 0169 * @since 5.65 0170 */ 0171 bool defaulted() const; 0172 0173 /** 0174 * Access to the actual module. 0175 * It may return NULL if anything goes wrong. 0176 * 0177 * @return the encapsulated module. 0178 */ 0179 KCModule *realModule() const; 0180 0181 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 88) 0182 /** 0183 * @return a KCModuleInfo for the encapsulated 0184 * module 0185 * @deprecated Since 5.87 method is obsolete with deprecation of KCModuleInfo constructor, use metaData() instead 0186 */ 0187 KCMUTILS_DEPRECATED_VERSION(5, 88, "method is obsolete with deprecation of KCModuleInfo constructor, use metaData() instead") 0188 KCModuleInfo moduleInfo() const; 0189 #endif 0190 0191 /** 0192 * Returns the KPluginMetaData used to load the KCM. If the KCM is not loaded using KPluginMetaData the returned object is invalid. 0193 * @return a KPluginMetaData for the encapsulated module 0194 * @since 5.84 0195 */ 0196 KPluginMetaData metaData() const; 0197 0198 /** 0199 * Returns the D-Bus Service name 0200 */ 0201 QString dbusService() const; 0202 /** 0203 * Returns the D-Bus Path 0204 */ 0205 QString dbusPath() const; 0206 /** 0207 * Returns the recommended minimum size for the widget 0208 */ 0209 QSize minimumSizeHint() const override; 0210 0211 /** 0212 * Show or hide an indicator when settings have changed from their default value 0213 * 0214 * @since 5.73 0215 */ 0216 void setDefaultsIndicatorsVisible(bool show); 0217 0218 public Q_SLOTS: 0219 0220 /** 0221 * Calling it will cause the contained module to 0222 * load its default values. 0223 */ 0224 void defaults(); 0225 0226 /** 0227 * Calling this, results in deleting the contained 0228 * module, and unregistering from DCOP. A similar result is achieved 0229 * by deleting the KCModuleProxy itself. 0230 */ 0231 void deleteClient(); 0232 0233 Q_SIGNALS: 0234 0235 /* 0236 * This signal is emitted when the contained module is changed. 0237 */ 0238 void changed(bool state); 0239 0240 #if KCMUTILS_ENABLE_DEPRECATED_SINCE(5, 87) 0241 /** 0242 * This is emitted in the same situations as in the one above. Practical 0243 * when several KCModuleProxys are loaded. 0244 * @deprecated Since 5.87, use changed(bool) instead 0245 */ 0246 KCMUTILS_DEPRECATED_VERSION(5, 87, "use changed(bool) instead") 0247 void changed(KCModuleProxy *mod); 0248 #endif 0249 0250 /** 0251 * When a module running with root privileges and exits, returns to normal mode, the 0252 * childClosed() signal is emitted. 0253 */ 0254 void childClosed(); 0255 0256 /* 0257 * This signal is relayed from the encapsulated module, and 0258 * is equivalent to the module's own quickHelpChanged() signal. 0259 */ 0260 void quickHelpChanged(); 0261 0262 protected: 0263 /** 0264 * Reimplemented for internal purposes. Makes sure the encapsulated 0265 * module is loaded before the show event is taken care of. 0266 */ 0267 void showEvent(QShowEvent *) override; 0268 0269 protected: 0270 KCModuleProxyPrivate *const d_ptr; 0271 0272 private: 0273 Q_PRIVATE_SLOT(d_func(), void _k_moduleChanged(bool)) 0274 Q_PRIVATE_SLOT(d_func(), void _k_moduleDefaulted(bool)) 0275 Q_PRIVATE_SLOT(d_func(), void _k_moduleDestroyed()) 0276 Q_PRIVATE_SLOT(d_func(), void _k_ownerChanged(const QString &service, const QString &oldOwner, const QString &newOwner)) 0277 }; 0278 0279 #endif // KUTILS_KCMODULEPROXY_H