Subversion Repositories Scribus

Rev

Rev 2972 | Rev 3189 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
2972 craig 1
#ifndef _SCPLUGIN_H
2
#define _SCPLUGIN_H
3
 
4
#include "qobject.h"
5
#include "qstring.h"
6
#include "qpixmap.h"
7
#include "qdatetime.h"
8
#include "scribusapi.h"
9
 
10
class QWidget;
11
class ScribusApp;
12
class DeferredTask;
13
 
14
/*
15
 * The idea here is that a ScPlugin is an information class stored by the
16
 * plug-in and returned to callers. It is a singleton that is always owned
17
 * by the plugin implementation.
18
 *
19
 * Note that the implementation below really creates two quite different
20
 * kinds of plugins. One for import/export of data which is generally
21
 * loaded, run, and unloaded. A second for persistent plugins that are loaded
22
 * (generally when the app starts) and remain resident.
23
 *
24
 * More plugin classes - such as plugins for text import and document import
25
 * - may be added in future.
2975 craig 26
 *
27
 * In addition to the API described here, a plugin is expected to implement
28
 * the following "extern C" functions, where 'pluginname' is the base name
29
 * of the plug-in:
30
 *
31
 * int pluginname_pluginAPIVersion();
32
 *    Return an integer indicating the plug-in API version implemented.
33
 *    If the version does not exactly match the running plugin API version,
34
 *    the plugin will not be initialised.
35
 *
36
 * ScPlugin* pluginname_getPlugin();
37
 *    Create and return an instance of the plug-ins ScPlugin subclass.
38
 *    Nothing should be done here that's overly slow or uses much memory,
39
 *    and the plugin should not initialize its self here beyond what is
40
 *    required to return a ScPlugin instance.
41
 *
42
 * void pluginname_freePlugin(ScPlugin* plugin);
43
 *    Free the scplugin instance returned earlier.
44
 *
2972 craig 45
 */
46
 
47
class SCRIBUS_API ScPlugin : public QObject
48
{
49
        Q_OBJECT
50
 
51
        /**
52
         * @brief ScPlugin provides an interface to ask plugins for information
53
         * about themselves.
54
         *
55
         * Plugins return a pointer to their ScPlugin instance when
56
         * asked for it by the plugin manager. This class provides general
57
         * information about the plugin. It should not generally be inherited
58
         * directly by plugins - use one of the provided base classes instead.
59
         */
60
        public:
61
 
62
                /** \brief Human readable enumertion of the plugin types */
2975 craig 63
                // FIXME: duplicated in pluginmanager, but different there.
2972 craig 64
                enum PluginType {
2975 craig 65
                        PluginType_Persistent = 4,
66
                        PluginType_Import = 7,
67
                        PluginType_Export = 8,
2972 craig 68
                };
69
 
70
                // A struct providing the information returned by getAboutData(), for
71
                // the "About Plug-ins" menu item.
72
                struct AboutData
73
                {
74
                        // Author name(s) and email address(es)
75
                        QString authors;
76
                        // One-liner description of the function of the plugin
77
                        QString shortDescription;
78
                        // Longer description of the plugin
79
                        QString description;
80
                        // Text plug-in version string
81
                        QString version;
82
                        // Date of the release of this version
83
                        QDateTime releaseDate;
84
                        // Copyright string
85
                        QString copyright;
86
                        // License text / name / URL / whatever. Please don't include
87
                        // the GPL here, just reference it. Remember that Scribus is
88
                        // licensed under the GPL, so plug-in authors must take that
89
                        // into account.
90
                        QString license;
91
                };
92
 
2975 craig 93
                /**
94
                 * @brief ctor, returns a new ScPlugin instance
95
                 *
96
                 * @param int id          Unique plugin ID, usually a static
97
                 *                        const int defined in the plugin.
98
                 * @param QString name    Name of the plugin as shown in the
99
                 *                        Start-up dialog and plugin mgr. This is
100
                 *                        the "friendly" human-readable name.
101
                 *                        PluginManager should already know the
102
                 *                        internal name.
103
                 *
104
                 * Only the actual plugin implmementation should call this, from
105
                 * its setup function.
106
                 */
107
                ScPlugin(int id, QString& name);
108
 
109
                /** @brief Pure virtual destructor - this is an abstract class */
110
                virtual ~ScPlugin() = 0;
111
 
2972 craig 112
                // Plug-in type, inited by ctor.
113
                const PluginType pluginType;
114
 
2975 craig 115
                // Plug-in ID, inited by ctor. This must be unique across all
116
                // plug-ins.
117
                const int id;
2972 craig 118
 
119
                // Plug-in's human-readable, translated name. Please don't use this for
120
                // anything except display to the user. Set up by ctor.
2975 craig 121
                const QString fullTrName;
2972 craig 122
 
123
                // Information for prefs dialog, to be set up by ctor.
124
                const bool hasPrefsUI;
125
                const QPixmap prefsPanelIcon;
126
                const QString prefsPanelName();
127
 
128
                // Methods to create and destroy the UI pane for the plugin
2975 craig 129
                // A plugin MUST implment destroyPrefsPanelWidget if it 
130
                // reimplements newPrefsPanelWidget .
131
                virtual QWidget* newPrefsPanelWidget();
2972 craig 132
                virtual void destroyPrefsPanelWidget(QWidget* prefsPanelWidget) = 0;
133
 
134
                // Returns a structure containing descriptive information about the
135
                // plug-in. This information is used in places like the Help->About
136
                // Plug-ins menu item. The stucture MUST be deleted using
137
                // deleteAboutData(AboutData* about) when finished with.
138
                //
2975 craig 139
                // Note: About data isn't stored as const members because (a) it can
140
                // be big, and (b) it isn't needed much.
141
                //
142
                // Every plug-in must re-implment these.
143
                virtual AboutData* getAboutData() = 0;
144
                virtual void deleteAboutData(AboutData* about) = 0;
2972 craig 145
 
2975 craig 146
                // Return human readable, translated text of last error to be
147
                // encountered. DO NOT ATTEMPT TO USE THIS VALUE TO MAKE
148
                // DECISIONS IN PROGRAM CODE.
149
                const QString & lastError() const;
150
 
2972 craig 151
        protected:
2975 craig 152
                // Human readable, translated version of last error to occur.
153
                QString m_lastError;
2972 craig 154
};
155
 
156
 
157
class SCRIBUS_API ScImportExportPlugin : public ScPlugin
158
{
159
        Q_OBJECT
160
 
161
        /*
162
         * @brief A plug-in that's loaded for data import/export duties
163
         *
164
         * ScImportExportPlugin describes a plug-in that is loaded on demand
165
         * to perform a data import/export task such as importing an SVG
166
         * image or exporting a page to EPS format. It'll generally by unloaded
167
         * after being queried, then loaded on demand when it needs to run.
168
         */
169
 
170
        public:
171
 
2975 craig 172
                /** @brief ctor
173
                 *
174
                 * @sa ScPlugin::ScPlugin()
175
                 */
176
                ScImportExportPlugin(int id, QString& name);
177
                // Pure virtual dtor - abstract class
178
                virtual ~ScImportExportPlugin() = 0;
179
 
2972 craig 180
                /**
181
                 * @brief Run the plug-in's main action.
182
                 *
183
                 * Run the plug-in's default action. That usually means prompting the
2975 craig 184
                 * user for a target (file to save as / file to import) then
185
                 * performing the import/export action the plug-in is written for.
2972 craig 186
                 *
2975 craig 187
                 * It should generally call run(..., QIODevice* target) or run(...,
188
                 * QString target) to do the work. This is done by default, with the
189
                 * assumption that the target is a file. An open QFile with
190
                 * IO_ReadOnly or IO_WriteOnly mode, depending on plugin type,
191
                 * is supplied. Override this if you need more flexibility.
2972 craig 192
                 *
193
                 * The optional target argument is a plugin-defined string indicating
194
                 * what the plugin should operate on. It will typically be a filename
195
                 * to import from / export to. Nothing stops a plugin doing funky
196
                 * things like accepting a WebDAV URI, etc, however.
197
                 *
198
                 * Plug-in authors might want to consider implementing this using the
199
                 * DeferredTask subclass used in runAsync, if the plug-in supports it.
200
                 *
201
                 * @param QWidget& parent Parent widget to this plugin. Usually the
202
                 * main window.  @param ScribusApp& mainWindow The main application
203
                 * window.  @param QString target Optional target to operate on (see
204
                 * above) @returns bool True for success.
205
                 *
206
                 */
2975 craig 207
                virtual bool run(QWidget* parent, ScribusApp* mainWindow, QString target = QString::null);
2972 craig 208
 
209
                /**
210
                 * @brief Run the plugin on a QIODevice
211
                 *
212
                 * This method is essentially the same as the above, except that it
213
                 * accepts a QIODevice* to work with. This will generally be used for
214
                 * file I/O without the plugin having to know or care where from.
215
                 *
216
                 * A plug-in MUST return false if it cannot support this method or upon
217
                 * failure. A plug-in MUST supply a working version of this method if
218
                 * it accepts runWith(..., QString) on a local file, and should
219
                 * generally implement the former using this method.
220
                 *
221
                 * Remember that not all QIODevice*s are seekable, and try to write
222
                 * your code to handle a non-seekable stream.
223
                 */
2975 craig 224
                virtual bool run(QWidget* parent, ScribusApp* mainWindow, QIODevice* target);
2972 craig 225
 
226
                /**
227
                 * @brief Run the plugin asynchronously
228
                 *
229
                 * This call is similar to the one above, but instead of doing all the
230
                 * work in one big batch, it creates an instance of a DeferredTask
231
                 * subclass to keep track of the job, does some setup, and returns
232
                 * immediately. The DeferredTask, a pointer to which is returned, has
233
                 * already been started when this method returns.
234
                 *
235
                 * The caller of this method is responsible for handling the aborted()
236
                 * and finished() signals from the DeferredTask, and (if necessary) for
237
                 * cleaning it up once it has finished. Remember that a DeferredTask is
238
                 * automatically deleted when its parent is, if it hasn't already been
239
                 * deleted.
240
                 *
241
                 * FIXME: The above is probably utterly broken on win32.
242
                 *
243
                 * See the DeferredTask documentation for details on how it works.
244
                 *
245
                 * If your plugin implementation does not support asynchronous
246
                 * operation, you must return null. This is the default implementation,
247
                 * so simply ignore this method unless you wish to support it. It is
248
                 * recommended that all new plugins support this interface where
249
                 * possible, even if they can only do part of their work progressively.
250
                 *
251
                 * If you implement this, you may want to implement run(...) using the
252
                 * same deferred operation and a modal dialog. That'll permit the event
253
                 * loop to continue running for redraws, permit you to update the
254
                 * progress bar, etc.
255
                 *
256
                 * NOTE: In current Scribus code (August 2005), callers of this method
257
                 * will generally create a modal dialog - possibly with progress meter
258
                 * - then attach signals from the DeferredTask, and exec() the dialog.
259
                 *   A caller is not required to do this, but with the current (August
260
                 *   2005) core code it's the only way to operate safely. This is
261
                 *   likely to change in future and you should avoid relying on it if
262
                 *   at all posssible.
263
                 *
264
                 * If this method is used, the plugin must not be unloaded until all
265
                 * DeferredTask instances have been deleted.
266
                 */
2975 craig 267
                virtual DeferredTask* runAsync(QWidget* parent, ScribusApp* mainWindow, QString target = QString::null);
2972 craig 268
 
269
                /**
270
                 * @brief Run the plugin asynchronously
271
                 *
272
                 * This method is much the same as the above, but takes a QIODevice* as
273
                 * the target. Please see the documentation for run(..., QIODevice*
274
                 * target) and runAsync(..., QString target) for details.
275
                 */
2975 craig 276
                virtual DeferredTask* runAsync(QWidget* parent, ScribusApp* mainWindow, QIODevice* target);
2972 craig 277
 
278
                // const members defining information about actions, to be
279
                // populated by the ctor.
280
                const QString m_actionName;
281
                const QString m_actionKeySequence;
282
                const QString m_actionMenu;
283
                const QString m_actionMenuAfterName;
284
                const bool m_actionEnabledOnStartup;
285
 
286
};
287
 
288
 
289
 
290
class SCRIBUS_API ScPersistentPlugin : public ScPlugin
291
{
292
        Q_OBJECT
293
 
294
        /**
295
         * @brief A plug-in that is resident for the lifetime of the app
296
         *
297
         * ScPersistentPlugin describes a plugin that is to be kept resident
298
         * for the lifetime of the app (or until unloaded by a request to
299
         * the plug-in manager).
300
         *
301
         * Such plug-ins have an init method and a cleanup method; they have
302
         * no "run" method as such.
303
         */
304
        public:
305
 
2975 craig 306
                /** @brief ctor
307
                 *
308
                 * @sa ScPlugin::ScPlugin()
309
                 */
310
                ScPersistentPlugin(int id, QString& name);
311
 
312
                // Pure virtual dtor for abstract class
313
                virtual ~ScPersistentPlugin() = 0;
314
 
2972 craig 315
                /**
316
                 * @brief Initialize the plugin
317
                 *
318
                 * This method must initialize the plugin. It is called at plug-in load
319
                 * time. This method will never be called twice without an intervening
320
                 * cleanupPlug call (but not necessarily unloading the plugin).
321
                 *
322
                 * It will usually instantiate a class and store a pointer to the
323
                 * instance in a static variable of the plugin or a member of its
324
                 * ScPersistentPlugin subclass, letting that class do the work of setup
325
                 * and integration into the app.
326
                 *
2975 craig 327
                 * Note that this is NOT the same as the init function of the plugin. That
328
                 * is always simple and lightweight, intended to just get an instance of this
329
                 * class back to the core app. This function is where any time-consuming or
330
                 * memory expensive init should be done.
331
                 *
332
                 * @param QWidget& parent Parent widget to this plugin.
333
                 *                        Usually the main window.
334
                 * @param ScribusApp& mainWindow The main application window.
335
                 * @returns bool True for success.
2972 craig 336
                 */
337
                virtual bool initPlug(QWidget& parent, ScribusApp& mainWindow) = 0;
338
 
339
                /**
340
                 * @brief Cleans up the plugin so it can be safely unloaded.
341
                 *
342
                 * This method will be called when the plug-in is about to be unloaded,
343
                 * or if the plug-in manager has been asked to disable the plug-in.
344
                 * This method will never be called unless initPlug has been called
345
                 * first, but there is no guarantee the plugin will be unloaded after
346
                 * this is called, or before initPlug is called again.
347
                 *
348
                 * @returns bool True for success.
349
                 */
350
                virtual bool cleanupPlug() = 0;
351
};
352
 
353
#endif