1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
|
/*
kopetepluginmanager.h - Kopete Plugin Loader
Copyright (c) 2002-2003 by Duncan Mac-Vicar Prett <duncan@kde.org>
Copyright (c) 2002-2003 by Martijn Klingens <klingens@kde.org>
Kopete (c) 2002-2003 by the Kopete developers <kopete-devel@kde.org>
*************************************************************************
* *
* 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 <tqmap.h>
#include <tqobject.h>
#include <tqstring.h>
#include <tqstringlist.h>
#include <tqvaluelist.h>
#include "kopete_export.h"
class KPluginInfo;
namespace Kopete
{
class Plugin;
typedef TQValueList<Plugin*> PluginList;
/**
* @author Duncan Mac-Vicar Prett <duncan@kde.org>
* @author Martijn Klingens <klingens@kde.org>
*/
class KOPETE_EXPORT PluginManager : public QObject
{
Q_OBJECT
Q_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<KPluginInfo *> availablePlugins( const TQString &category = TQString::null ) 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::null ) const;
/**
* @brief Search by plugin name. This is the key used as X-KDE-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-KDE-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 KApplication. 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:
|
