kutils/kcmoduleproxy.h

   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 KUTILS_KCMODULEPROXY_H
  22 #define KUTILS_KCMODULEPROXY_H
  23
  24 #include <QtGui/QImage>
  25 #include <QtCore/QStringList>
  26
  27 #include <kcmodule.h>
  28 #include <kservice.h>
  29 #include <kutils_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 KUTILS_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         QSize minimumSizeHint() const;
 201
 202 public Q_SLOTS:
 203
 204         /**
 205          * Calling it will cause the contained module to
 206          * load its default values.
 207          */
 208         void defaults();
 209
 210         /**
 211          * Calling this, results in deleting the contained
 212          * module, and unregistering from DCOP. A similar result is achieved
 213          * by deleting the KCModuleProxy itself.
 214          */
 215         void deleteClient();
 216
 217 Q_SIGNALS:
 218
 219         /*
 220          * This signal is emitted when the contained module is changed.
 221          */
 222         void changed( bool state );
 223
 224         /**
 225          * This is emitted in the same situations as in the one above. Practical
 226          * when several KCModuleProxys are loaded.
 227          */
 228         void changed( KCModuleProxy* mod );
 229
 230         /**
 231          * When a module running with root privileges and exits, returns to normal mode, the
 232          * childClosed() signal is emitted.
 233          */
 234         void childClosed();
 235
 236         /*
 237          * This signal is relayed from the encapsulated module, and
 238          * is equivalent to the module's own quickHelpChanged() signal.
 239          */
 240         void quickHelpChanged();
 241
 242 protected:
 243
 244         /**
 245          * Reimplemented for internal purposes. Makes sure the encapsulated
 246          * module is loaded before the show event is taken care of.
 247          */
 248         void showEvent( QShowEvent * );
 249
 250 protected:
 251     KCModuleProxyPrivate *const d_ptr;
 252
 253 private:
 254     Q_PRIVATE_SLOT(d_func(), void _k_moduleChanged(bool))
 255     Q_PRIVATE_SLOT(d_func(), void _k_moduleDestroyed())
 256     Q_PRIVATE_SLOT(d_func(), void _k_ownerChanged(const QString &service, const QString &oldOwner, const QString &newOwner))
 257 };
 258
 259 #endif // KUTILS_KCMODULEPROXY_H
 260 // vim: ts=4