File: PluginManager.h

package info (click to toggle)
kwave 0.7.2-5
  • links: PTS
  • area: main
  • in suites: sarge
  • size: 9,048 kB
  • ctags: 4,906
  • sloc: cpp: 31,275; ansic: 13,111; sh: 9,511; perl: 2,724; makefile: 786; asm: 145
file content (383 lines) | stat: -rw-r--r-- 12,796 bytes parent folder | download
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
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
/***************************************************************************
	    PluginManager.h  -  manager class for kwave's plugins
			     -------------------
    begin                : Sun Aug 27 2000
    copyright            : (C) 2000 by Thomas Eschenbacher
    email                : Thomas.Eschenbacher@gmx.de
 ***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/

#ifndef _PLUGIN_MANAGER_H_
#define _PLUGIN_MANAGER_H_

#include "config.h"
#include <qobject.h>
#include <qmemarray.h>
#include <qptrlist.h>
#include <qptrvector.h>
#include <qmap.h>

#include <arts/artsflow.h>

#include "mt/SignalProxy.h"
#include "libkwave/InsertMode.h"

class ArtsMultiSink;
class FileInfo;
class KwavePlugin;
class PlaybackController;
class PlaybackDeviceFactory;
class QBitmap;
class QString;
class QStringList;
class SampleWriter;
class TopWidget;
class UndoAction;
class MultiTrackReader;
class MultiTrackWriter;

/**
 * Manages the loading, initializing, starting, running and closing
 * of the plugins of kwave. Each instance of a TopWidget creates a
 * new instance of the PluginManager to be independent from other
 * toplevel widgets.
 * @author Thomas Eschenbacher
 */
class PluginManager : public QObject
{
    Q_OBJECT

public:

    /**
     * Constructor.
     * @param parent reference to the toplevel widget (our parent)
     */
    PluginManager(TopWidget &parent);

    /**
     * Returns true if this instance was successfully initialized, or
     * false if something went wrong during initialization.
     */
    virtual bool isOK();

    /**
     * Default destructor
     */
    virtual ~PluginManager();

    /**
     * Tries to load all plugins. If a pesistent plugin is found,
     * it will stay loaded in memory, all other (non-persistent)
     * plugins will be unloaded afterwards. This also filters out
     * all plugins that do not correctly load.
     * @internal used once by each toplevel window at startup
     */
    void loadAllPlugins();

    /**
     * Executes a plugin in the context of a given parent widget.
     * @return zero on success or negative error code
     */
    int executePlugin(const QString &name, QStringList *params);

    /**
     * Waits until all currently running acions have completed.
     */
    void sync();

    /**
     * Loads a plugin, calls it's setup function and then closes
     * it again. The parameters will be loaded before the setup
     * and saved if the setup has not been aborted.
     */
    int setupPlugin(const QString &name);

    /**
     * Returns a reference to the FileInfo object associated with the
     * currently opened file.
     */
    FileInfo &fileInfo();

    /**
     * Returns the length of the current signal in samples.
     * If no signal is present the return value will be 0.
     */
    unsigned int signalLength();

    /**
     * Returns the current sample rate in samples per second.
     * If no signal is present the return value will be 0.
     */
    double signalRate();

    /**
     * Returns an array of indices of currently selected channels.
     */
    const QMemArray<unsigned int> selectedTracks();

    /**
     * Returns the start of the selection. If nothing is currently
     * selected this will be the first sample (0).
     */
    unsigned int selectionStart();

    /**
     * Returns the end of the selection. If nothing is currently
     * selected this will be the last sample (length-1).
     */
    unsigned int selectionEnd();

    /**
     * Sets the current start and length of the selection to new values.
     * @param offset index of the first sample
     * @param length number of samples
     */
    void selectRange(unsigned int offset, unsigned int length);

    /** Returns a reference to our toplevel widget */
    inline TopWidget &topWidget() { return m_top_widget; };

    /**
     * Returns a set of opened SampleReader objects for reading from
     * multiple tracks. The list of tracks may contain indices of tracks
     * in any order and even duplicate entries are allowed. One useful
     * application is passing the output of selectedTracks() in order
     * to read from only from selected tracks.
     * @param readers reference to the MultiTrackReader to be filled.
     * @note the returned vector has set "autoDelete" to true, so you
     *       don't have to care about cleaning up
     * @param track_list array of indices of tracks for reading
     * @param first index of the first sample
     * @param last index of the last sample
     * @see SampleReader
     * @see selectedTracks()
     */
    void openMultiTrackReader(MultiTrackReader &readers,
	const QMemArray<unsigned int> &track_list,
	unsigned int first, unsigned int last);

    /**
     * Opens an input stream for a track, starting at a specified sample
     * position. Also handles undo information.
     * @param track index of the track. If the track does not exist, this
     *        function will fail and return 0
     * @param mode specifies where and how to insert
     * @param left start of the input (only useful in insert and
     *             overwrite mode)
     * @param right end of the input (only useful with overwrite mode)
     * @see InsertMode
     */
    SampleWriter *openSampleWriter(unsigned int track, InsertMode mode,
	unsigned int left = 0, unsigned int right = 0);

    /**
     * Opens a set of SampleWriters and internally handles the creation of
     * needed undo information. This is useful for multi-channel operations.
     * @param writers reference to a vector that receives all writers.
     * @param track_list list of indices of tracks to be modified.
     * @param mode specifies where and how to insert
     * @param left start of the input (only useful in insert and
     *             overwrite mode)
     * @param right end of the input (only useful with overwrite mode)
     * @see InsertMode
     */
    void openMultiTrackWriter(MultiTrackWriter &writers,
	const QMemArray<unsigned int> &track_list, InsertMode mode,
	unsigned int left, unsigned int right);

    /**
     * Opens a set of SampleWriters using the currently selected list of
     * tracks and the current selection. If nothing is selected, the whole
     * signal will be selected.
     * @param writers reference to a vector that receives all writers.
     * @param mode specifies where and how to insert
     */
    void openMultiTrackWriter(MultiTrackWriter &writers,
                              InsertMode mode);

    /**
     * Opens a set of SampleWriters for playback purposes.
     * @param tracks number of tracks
     * @param name of the device, optional. If not given, the default
     *        playback device is used
     * @return a multitrack aRts sink that receives the playback stream
     */
    ArtsMultiSink *openMultiTrackPlayback(unsigned int tracks,
                                          const QString *name = 0);

    /**
     * Returns a reference to the current playback controller. This is
     * only needed for plugins doing playback.
     */
    PlaybackController &playbackController();

    /**
     * Enqueues a command that will be processed threadsafe in the X11
     * thread. Calls m_spx_command.enqueue().
     */
    void enqueueCommand(const QString &command);

    /**
     * Searches the standard KDE data directories for plugins (through
     * the KDE's standard search algorithm) and creates a map of
     * plugin names and file names. First it collects a list of
     * filenames and then filters it to sort out invalid entries.
     */
    static void findPlugins();

    /** Returns a reference to the global aRts dispatcher */
    inline Arts::Dispatcher *artsDispatcher() {
	return Arts::Dispatcher::the();
    };

    /**
     * Registers a PlaybackDeviceFactory
     */
    void registerPlaybackDeviceFactory(PlaybackDeviceFactory *factory);

    /**
     * Unregisters a PlaybackDeviceFactory
     */
    void unregisterPlaybackDeviceFactory(PlaybackDeviceFactory *factory);
    
signals:
    /**
     * Forwards commands to the parent TopWidget execute a command
     */
    void sigCommand(const QString &command);

    /**
     * Informs all plugins and client windows that we close down
     */
    void sigClosed();

    /**
     * Informs the plugins that the name of the signal has changed.
     * This might be used to update the caption of a window.
     */
    void sigSignalNameChanged(const QString &name);

public slots:

    /**
     * Will be connected to the plugin's "closed" signal.
     * @param p pointer to the plugin to be closed
     */
    void pluginClosed(KwavePlugin *p);

    /**
     * Called if the name of the current signal has changed. This will be
     * forwarded to all plugins by emitting the signal sigSignalChanged.
     * @see #sigSignalChanged()
     */
    void setSignalName(const QString &name);

private slots:

    /** emits sigSignalNameChanged to the plugins (threadsafe) */
    void emitNameChanged();

    /**
     * de-queues a command from m_spx_command and executes it
     * through the toplevel widget.
     */
    void forwardCommand();

    /** called when a plugin has started (running) it's worker thread */
    void pluginStarted(KwavePlugin *p);

    /** called when a plugin has finished it's worker thread */
    void pluginDone(KwavePlugin *p);

private:

    /**
     * Helper class for deferred deleting and unloading a plugin
     * @internal
     */
    class PluginDeleter: public QObject
    {
    public:
        /** Constructor, stores data for later removal */
	PluginDeleter(KwavePlugin *plugin, void *handle);
	
	/** Destructor, deletes and unloads the plugin */
	virtual ~PluginDeleter();
	
    private:
	KwavePlugin *m_plugin; /**< Plugin to be deleted */
	void *m_handle;        /**< Handle of the shared object */
    };

    /**
     * Uses the dynamic linker to load a plugin into memory.
     * @param name the name of the plugin (filename)
     * @return pointer to the loaded plugin or zero if the
     *         plugin was not found or invalid
     */
    KwavePlugin *loadPlugin(const QString &name);

    /**
     * loads a plugin's default parameters from the user's
     * configuration file. If nothing is found in the config file,
     * the return value will be 0. If the current version number of
     * the plugin does not match the version number in the config file,
     * the return value will also be 0.
     * @param name the name of the plugin
     * @param version the version number of the plugin
     * @return list of strings
     */
    QStringList loadPluginDefaults(const QString &name,
                                   const QString &version);

    /**
     * Saves a plugin's default parameters to the user's configuration
     * file. The whole section in the configuration file will be deleted
     * before saving the new settings in order to wipe out invalid
     * entries and settings that belong to an older version.
     * @param name the name of the plugin
     * @param version the version number of the plugin
     * @param params a list of configuration strings
     */
    void savePluginDefaults(const QString &name, const QString &version,
                            QStringList &params);

    /** connects all signals of and for a plugin */
    void connectPlugin(KwavePlugin *plugin);

    /** connects all signals from and to a plugin */
    void disconnectPlugin(KwavePlugin *plugin);

    /** threadsafe signal proxy for setSignalName / sigSignalNameChanged */
    SignalProxy1<const QString> m_spx_name_changed;

    /** threadsafe proxy for sigCommand() */
    SignalProxy1<const QString> m_spx_command;

    /** map for finding plugin files through their name */
    static QMap<QString, QString> m_plugin_files;

    /** list of own loaded plugins */
    QPtrList<KwavePlugin> m_loaded_plugins;

    /** global list of loaded unique plugins */
    static QPtrList<KwavePlugin> m_unique_plugins;

    /** list of currently running plugins */
    QPtrList<KwavePlugin> m_running_plugins;

    /** reference to our parent toplevel widget */
    TopWidget &m_top_widget;

};

#endif /* _PLUGIN_MANAGER_H_ */