diff options
Diffstat (limited to 'kutils/tdecmoduleproxy.h')
| -rw-r--r-- | kutils/tdecmoduleproxy.h | 358 |
1 files changed, 358 insertions, 0 deletions
diff --git a/kutils/tdecmoduleproxy.h b/kutils/tdecmoduleproxy.h new file mode 100644 index 000000000..9fc559d97 --- /dev/null +++ b/kutils/tdecmoduleproxy.h @@ -0,0 +1,358 @@ +/* This file is part of the KDE project + Copyright (C) 2003 Matthias Kretz <kretz@kde.org> + Copyright (C) 2004 Frans Englich <frans.englich@telia.com> + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License version 2 as published by the Free Software Foundation. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. + +*/ + +#ifndef KCMODULEPROXY_H +#define KCMODULEPROXY_H + +#include <tqwidget.h> +#include <tqstringlist.h> + +#include <kservice.h> +#include <tdelibs_export.h> + +class TDEAboutData; +class TDECModule; +class TDECModuleInfo; +class TDEInstance; +class TDEProcess; + +/** + * @ingroup tdecmodule + * + * @brief Encapsulates a TDECModule for embedding. + * + * TDECModuleProxy is a wrapper for TDECModule intended for cases where + * modules are to be displayed. It ensures layout is consistent, handles + * root/administrator modules and in general takes care of the details + * needed for making a module available in an interface. A TDECModuleProxy + * can be treated as a TQWidget, without worrying about the details specific + * for modules such as library loading. TDECModuleProxy is not a sub class of TDECModule + * but its API closely resembles TDECModule's.\n + * Usually, an instance is created by passing one of the constructors a KService::Ptr, + * TDECModuleInfo or simply the name of the module and then added to the layout as any + * other widget. \n + * When the user have changed the module, changed( bool ) as well as changed ( TDECModuleProxy * ) + * is emitted. TDECModuleProxy does not take care of prompting for saving - if the object is deleted while + * changes is not saved the changes will be lost. changed() returns true if changes are unsaved. \n + * \n + * TDECModuleProxy does not take care of authorization of TDECModules. \n + * TDECModuleProxy do lazy loading, meaning the library will not be loaded or + * any other initialization done before its show() function is called. This means + * modules will only be loaded when they are actually needed as well as it is possible to + * load many TDECModuleProxy without any speed penalty. + * + * TDECModuleProxy should be used in all cases where modules are embedded in order to + * promote code efficiency and usability consistency. + * + * @author Frans Englich <frans.englich@telia.com> + * @author Matthias Kretz <kretz@kde.org> + * + */ +class KUTILS_EXPORT TDECModuleProxy : public TQWidget +{ +Q_OBJECT + + + friend class TDECModuleProxyRootCommunicatorImpl; + +public: + + /** + * Constructs a TDECModuleProxy from a TDECModuleInfo class. + * + * @param info The TDECModuleInfo to construct the module from. + * @param withFallback If set to true and loading of the module fails, + * a alternative will be tried, resulting in the module appearing in its + * own window, if at all. + * The embedded module will be load()ed. + * @param parent the parent TQWidget. + * @param name the module's name. + * @param args This is used in the implementation and is internal. + * Use the default. + */ + TDECModuleProxy( const TDECModuleInfo & info, bool withFallback = true, + TQWidget * parent = 0, const char * name = 0, + const TQStringList & args = TQStringList() ); + + /** + * Constructs a TDECModuleProxy from a module's service name, which is + * equivalent to the desktop file for the kcm without the ".desktop" part. + * Otherwise equal to the one above. + * + * @param serviceName The module's service name to construct from. + * @param withFallback If set to true and loading of the module fails, + * a alternative will be tried, resulting in the module appearing in its + * own window, if at all. + * The embedded module will be load()ed. + * @param parent the parent TQWidget. + * @param name the module's name. + * @param args This is used in the implementation and is internal. + * Use the default. + */ + TDECModuleProxy( const TQString& serviceName, bool withFallback = true, + TQWidget * parent = 0, const char * name = 0, + const TQStringList & args = TQStringList() ); + + /** + * Constructs a TDECModuleProxy from KService. Otherwise equal to the one above. + * + * @param service The KService to construct from. + * @param withFallback If set to true and loading of the module fails, + * a alternative will be tried, resulting in the module appearing in its + * own window, if at all. + * The embedded module will be load()ed. + * @param parent the parent TQWidget. + * @param name the module's name. + * @param args This is used in the implementation and is internal. + * Use the default. + */ + TDECModuleProxy( const KService::Ptr& service, bool withFallback = true, + TQWidget * parent = 0, const char * name = 0, + const TQStringList & args = TQStringList() ); + + /** + * Default destructor + */ + ~TDECModuleProxy(); + + /** + * Calling it will cause the contained module to + * run its load() routine. + */ + void load(); + + /** + * Calling it will cause the contained module to + * run its save() routine. + * + * If the module was not modified, it will not be asked + * to save. + */ + void save(); + + /** + * @return the module's quickHelp(); + */ + TQString quickHelp() const; + + /** + * @return the module's aboutData() + */ + const TDEAboutData * aboutData() const; + + /** + * @return what buttons the module + * needs + */ + int buttons() const; + + /** + * @return The module's custom root + * message, if it has one + * @deprecated + */ + TQString rootOnlyMsg() const; + //KDE4 remove. There's a limit for convenience functions, + // this one's available via moduleInfo()-> and realModule()-> + + /** + * @return If the module is a root module. + * @deprecated + */ + bool useRootOnlyMsg() const; + //KDE4 remove. There's a limit for convenience functions, + // this one's available via moduleInfo()-> and realModule()-> + + /** + * Returns the embedded TDECModule's TDEInstance. + * @return The module's TDEInstance. + * @deprecated + */ + TDEInstance * instance() const; + //KDE4 remove. There's a limit for convenience functions, + // this one's available via realModule() + + /** + * @return true if the module is modified + * and needs to be saved. + */ + bool changed() const; + + /** + * Returns whether the module is running in root mode. A module is in root mode + * when runAsRoot() has been called. A session under root user will never reach + * root mode. + * + * @note realModule() will return null when the module is running in root mode. + * + * @return true if the module is running with root privileges + * @since 3.4 + */ + bool rootMode() const; + + /** + * Access to the actual module. However, if the module is + * running in root mode, see rootMode(), this function returns + * a NULL pointer, since the module is in another process. It may also + * return NULL if anything goes wrong. + * + * @return the encapsulated module. + */ + TDECModule* realModule() const; + + /** + * @return a TDECModuleInfo for the encapsulated + * module + */ + const TDECModuleInfo& moduleInfo() const; + + /** + * Returns the DCOP the module's DCOPClient + * and DCOPObject has(they are identical). + * + * @since 3.4 + */ + TQCString dcopName() const; + +public slots: + + /** + * Calling this will cause the module to be run in + * "administrator mode". + * + * @since 3.4 + */ + void runAsRoot(); + + /** + * Calling it will cause the contained module to + * load its default values. + */ + void defaults(); + + /** + * Calling this, results in deleting the contained + * module, and unregistering from DCOP. A similar result is achieved + * by deleting the TDECModuleProxy itself. + * + * @since 3.4 + */ + void deleteClient(); + +signals: + + /* + * This signal is emitted when the contained module is changed. + */ + void changed( bool state ); + + /** + * This is emitted in the same situations as in the one above. Practical + * when several TDECModuleProxys are loaded. + * + * @since 3.4 + */ + void changed( TDECModuleProxy* mod ); + + /** + * When a module running with root privileges and exits, returns to normal mode, the + * childClosed() signal is emitted. + * + * @since 3.4 + */ + void childClosed(); + + /* + * This signal is relayed from the encapsulated module, and + * is equivalent to the module's own quickHelpChanged() signal. + * + * @since 3.4 + */ + void quickHelpChanged(); + +protected: + + /** + * Reimplemented for internal purposes. Makes sure the encapsulated + * module is loaded before the show event is taken care of. + */ + void showEvent( TQShowEvent * ); + + /** + * Internal intialization function, called by the constructors. + * + * @internal + * @since 3.4 + */ + void init( const TDECModuleInfo& info ); + + + /** + * Emits the quickHelpChanged signal. + * @since 3.4 + */ + void emitQuickHelpChanged(); + +private slots: + + /** + * Calls the function @p function of the root module's TDECModuleProxy + * DCOP interface. + * + * @param function the function signature of the function to call. + * @since 3.4 + */ + void callRootModule( const TQCString& function ); + + /** + * This is called when the module exits from root mode. It zeroes + * pointers, deletes the embed window, and so forth. + * + * @since 3.4 + */ + void rootExited(); + + /** + * Makes sure the proper variables is set and signals are emitted. + */ + void moduleChanged( bool ); + + /** + * Zeroes d->kcm + */ + void moduleDestroyed(); + + /** + * Gets called by DCOP when an application closes. + * Is used to (try to) reload a KCM which previously + * was loaded. + * + * @since 3.4 + */ + void applicationRemoved( const TQCString& app ); + +private: + + class TDECModuleProxyPrivate; + TDECModuleProxyPrivate * d; +}; + +#endif // KCMODULEPROXY_H +// vim: sw=4 ts=4 noet |