/* kopetepluginmanager.h - Kopete Plugin Loader Copyright (c) 2002-2003 by Duncan Mac-Vicar Prett Copyright (c) 2002-2003 by Martijn Klingens Kopete (c) 2002-2003 by the Kopete developers ************************************************************************* * * * This library is free software; you can redistribute it and/or * * modify it under the terms of the GNU Lesser General Public * * License as published by the Free Software Foundation; either * * version 2 of the License, or (at your option) any later version. * * * ************************************************************************* */ #ifndef KOPETEPLUGINMANAGER_H #define KOPETEPLUGINMANAGER_H #include #include #include #include #include #include "kopete_export.h" class KPluginInfo; namespace Kopete { class Plugin; typedef TQValueList PluginList; /** * @author Duncan Mac-Vicar Prett * @author Martijn Klingens */ class KOPETE_EXPORT PluginManager : public TQObject { Q_OBJECT TQ_ENUMS( PluginLoadMode ) public: /** * Retrieve the plugin loader instance. */ static PluginManager* self(); ~PluginManager(); /** * Returns a list of all available plugins for the given category. * Currently there are two categories, "Plugins" and "Protocols", but * you can add your own categories if you want. * * If you pass an empty string you get the complete list of ALL plugins. * * You can query all information on the plugins through the KPluginInfo * interface. */ TQValueList availablePlugins( const TQString &category = TQString() ) const; /** * Returns a list of all plugins that are actually loaded. * If you omit the category you get all, otherwise it's a filtered list. * See also @ref availablePlugins(). */ PluginList loadedPlugins( const TQString &category = TQString() ) const; /** * @brief Search by plugin name. This is the key used as X-TDE-PluginInfo-Name in * the .desktop file, e.g. "kopete_jabber" * * @return The @ref Kopete::Plugin object found by the search, or a null * pointer if the plugin is not loaded. * * If you want to also load the plugin you can better use @ref loadPlugin, which returns * the pointer to the plugin if it's already loaded. */ Plugin *plugin( const TQString &pluginName ) const; /** * @return the KPluginInfo for the specified plugin */ KPluginInfo *pluginInfo( const Kopete::Plugin *plugin ) const; /** * Shuts down the plugin manager on Kopete shutdown, but first * unloads all plugins asynchronously. * * After 3 seconds all plugins should be removed; what's still left * by then is unloaded through a hard delete instead. * * Note that this call also derefs the plugin manager from the event * loop, so do NOT call this method when not terminating Kopete! */ void shutdown(); /** * Enable a plugin. * * This marks a plugin as enabled in the config file, so loadAll() * can pick it up later. * * This method does not actually load a plugin, it only edits the * config file. * * @param name is the name of the plugin as it is listed in the .desktop * file in the X-TDE-Library field. * @param enabled sets whether or not the plugin is enabled * * Returns false when no appropriate plugin can be found. */ bool setPluginEnabled( const TQString &name, bool enabled = true ); /** * This method check if all the plugins are loaded. * @return true if all the plugins are loaded. */ bool isAllPluginsLoaded() const; /** * Plugin loading mode. Used by @ref loadPlugin(). Code that doesn't want to block * the GUI and/or lot a lot of plugins at once should use asynchronous loading (@c LoadAsync). * The default is synchronous loading (@c LoadSync). */ enum PluginLoadMode { LoadSync, LoadAsync }; public slots: /** * @brief Load a single plugin by plugin name. Returns an existing plugin * if one is already loaded in memory. * * If mode is set to Async, the plugin will be queued and loaded in * the background. This method will return a null pointer. To get * the loaded plugin you can track the @ref pluginLoaded() signal. * * See also @ref plugin(). */ Plugin *loadPlugin( const TQString &pluginId, PluginLoadMode mode = LoadSync ); /** * @brief Unload the plugin specified by @p pluginName */ bool unloadPlugin( const TQString &pluginName ); /** * @brief Loads all the enabled plugins. Also used to reread the * config file when the configuration has changed. */ void loadAllPlugins(); signals: /** * @brief Signals a new plugin has just been loaded. */ void pluginLoaded( Kopete::Plugin *plugin ); /** * @brief All plugins have been loaded by the plugin manager. * * This signal is emitted exactly ONCE, when the plugin manager has emptied * its plugin queue for the first time. This means that if you call an async * loadPlugin() before loadAllPlugins() this signal is probably emitted after * the initial call completes, unless you are quick enough to fill the queue * before it completes, which is a dangerous race you shouldn't count upon :) * * The signal is delayed one event loop iteration through a singleShot timer, * but that is not guaranteed to be enough for account instantiation. You may * need an additional timer for it in the code if you want to programmatically * act on it. * * If you use the signal for enabling/disabling GUI objects there is little * chance a user is able to activate them in the short while that's remaining, * the slow part of the code is over now and the remaining processing time * is neglectable for the user. */ void allPluginsLoaded(); private slots: /** * @brief Cleans up some references if the plugin is destroyed */ void slotPluginDestroyed( TQObject *plugin ); /** * shutdown() starts a timer, when it fires we force all plugins * to be unloaded here by deref()-ing the event loop to trigger the plugin * manager's destruction */ void slotShutdownTimeout(); /** * Common entry point to deref() the TDEApplication. Used both by the clean * shutdown and the timeout condition of slotShutdownTimeout() */ void slotShutdownDone(); /** * Emitted by a Kopete::Plugin when it's ready for unload */ void slotPluginReadyForUnload(); /** * Load a plugin from our queue. Does nothing if the queue is empty. * Schedules itself again if more plugins are pending. */ void slotLoadNextPlugin(); private: /** * @internal * * The internal method for loading plugins. * Called by @ref loadPlugin directly or through the queue for async plugin * loading. */ Plugin * loadPluginInternal( const TQString &pluginId ); /** * @internal * * Find the KPluginInfo structure by key. Reduces some code duplication. * * Returns a null pointer when no plugin info is found. */ KPluginInfo * infoForPluginId( const TQString &pluginId ) const; PluginManager(); class Private; Private *d; static PluginManager *s_self; }; } #endif // KOPETEPLUGINMANAGER_H // vim: set noet ts=4 sts=4 sw=4: