Subversion Repositories Scribus

Rev

Rev 2975 | Rev 3193 | 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
                 */
3189 craig 107
                ScPlugin(int id, QString& name, PluginType pluginType);
2975 craig 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
                // Methods to create and destroy the UI pane for the plugin
3189 craig 124
                // A plugin MUST reimplment destroyPrefsPanelWidget if it
2975 craig 125
                // reimplements newPrefsPanelWidget .
3189 craig 126
                // By default, returns 0 to indicate no prefs UI.
2975 craig 127
                virtual QWidget* newPrefsPanelWidget();
3189 craig 128
                virtual void destroyPrefsPanelWidget(QWidget* prefsPanelWidget);
2972 craig 129
 
3189 craig 130
                // Return icon and caption to use for preferences panel in the prefs
131
                // dialog. Unless overridden, returns QString::null and an empty pixmap.
132
                virtual const QPixmap prefsPanelIcon() const;
133
                virtual const QString prefsPanelName() const;
134
 
2972 craig 135
                // Returns a structure containing descriptive information about the
136
                // plug-in. This information is used in places like the Help->About
137
                // Plug-ins menu item. The stucture MUST be deleted using
138
                // deleteAboutData(AboutData* about) when finished with.
139
                //
2975 craig 140
                // Every plug-in must re-implment these.
3189 craig 141
                virtual const AboutData* getAboutData() const = 0;
142
                virtual void deleteAboutData(const AboutData* about) const = 0;
2972 craig 143
 
2975 craig 144
                // Return human readable, translated text of last error to be
145
                // encountered. DO NOT ATTEMPT TO USE THIS VALUE TO MAKE
146
                // DECISIONS IN PROGRAM CODE.
147
                const QString & lastError() const;
148
 
2972 craig 149
        protected:
2975 craig 150
                // Human readable, translated version of last error to occur.
151
                QString m_lastError;
2972 craig 152
};
153
 
154
 
155
class SCRIBUS_API ScImportExportPlugin : public ScPlugin
156
{
157
        Q_OBJECT
158
 
159
        /*
160
         * @brief A plug-in that's loaded for data import/export duties
161
         *
162
         * ScImportExportPlugin describes a plug-in that is loaded on demand
163
         * to perform a data import/export task such as importing an SVG
164
         * image or exporting a page to EPS format. It'll generally by unloaded
165
         * after being queried, then loaded on demand when it needs to run.
166
         */
167
 
168
        public:
169
 
2975 craig 170
                /** @brief ctor
171
                 *
172
                 * @sa ScPlugin::ScPlugin()
173
                 */
3189 craig 174
                ScImportExportPlugin(int id, QString& name, PluginType pluginType);
2975 craig 175
                // Pure virtual dtor - abstract class
176
                virtual ~ScImportExportPlugin() = 0;
177
 
2972 craig 178
                /**
179
                 * @brief Run the plug-in's main action.
180
                 *
181
                 * Run the plug-in's default action. That usually means prompting the
2975 craig 182
                 * user for a target (file to save as / file to import) then
183
                 * performing the import/export action the plug-in is written for.
2972 craig 184
                 *
2975 craig 185
                 * It should generally call run(..., QIODevice* target) or run(...,
186
                 * QString target) to do the work. This is done by default, with the
187
                 * assumption that the target is a file. An open QFile with
188
                 * IO_ReadOnly or IO_WriteOnly mode, depending on plugin type,
189
                 * is supplied. Override this if you need more flexibility.
2972 craig 190
                 *
191
                 * The optional target argument is a plugin-defined string indicating
192
                 * what the plugin should operate on. It will typically be a filename
193
                 * to import from / export to. Nothing stops a plugin doing funky
194
                 * things like accepting a WebDAV URI, etc, however.
195
                 *
196
                 * Plug-in authors might want to consider implementing this using the
197
                 * DeferredTask subclass used in runAsync, if the plug-in supports it.
198
                 *
199
                 * @param QWidget& parent Parent widget to this plugin. Usually the
200
                 * main window.  @param ScribusApp& mainWindow The main application
201
                 * window.  @param QString target Optional target to operate on (see
202
                 * above) @returns bool True for success.
203
                 *
204
                 */
2975 craig 205
                virtual bool run(QWidget* parent, ScribusApp* mainWindow, QString target = QString::null);
2972 craig 206
 
207
                /**
208
                 * @brief Run the plugin on a QIODevice
209
                 *
210
                 * This method is essentially the same as the above, except that it
211
                 * accepts a QIODevice* to work with. This will generally be used for
212
                 * file I/O without the plugin having to know or care where from.
213
                 *
214
                 * A plug-in MUST return false if it cannot support this method or upon
215
                 * failure. A plug-in MUST supply a working version of this method if
216
                 * it accepts runWith(..., QString) on a local file, and should
217
                 * generally implement the former using this method.
218
                 *
219
                 * Remember that not all QIODevice*s are seekable, and try to write
220
                 * your code to handle a non-seekable stream.
221
                 */
2975 craig 222
                virtual bool run(QWidget* parent, ScribusApp* mainWindow, QIODevice* target);
2972 craig 223
 
224
                /**
225
                 * @brief Run the plugin asynchronously
226
                 *
227
                 * This call is similar to the one above, but instead of doing all the
228
                 * work in one big batch, it creates an instance of a DeferredTask
229
                 * subclass to keep track of the job, does some setup, and returns
230
                 * immediately. The DeferredTask, a pointer to which is returned, has
231
                 * already been started when this method returns.
232
                 *
233
                 * The caller of this method is responsible for handling the aborted()
234
                 * and finished() signals from the DeferredTask, and (if necessary) for
235
                 * cleaning it up once it has finished. Remember that a DeferredTask is
236
                 * automatically deleted when its parent is, if it hasn't already been
237
                 * deleted.
238
                 *
239
                 * FIXME: The above is probably utterly broken on win32.
240
                 *
241
                 * See the DeferredTask documentation for details on how it works.
242
                 *
243
                 * If your plugin implementation does not support asynchronous
244
                 * operation, you must return null. This is the default implementation,
245
                 * so simply ignore this method unless you wish to support it. It is
246
                 * recommended that all new plugins support this interface where
247
                 * possible, even if they can only do part of their work progressively.
248
                 *
249
                 * If you implement this, you may want to implement run(...) using the
250
                 * same deferred operation and a modal dialog. That'll permit the event
251
                 * loop to continue running for redraws, permit you to update the
252
                 * progress bar, etc.
253
                 *
254
                 * NOTE: In current Scribus code (August 2005), callers of this method
255
                 * will generally create a modal dialog - possibly with progress meter
256
                 * - then attach signals from the DeferredTask, and exec() the dialog.
257
                 *   A caller is not required to do this, but with the current (August
258
                 *   2005) core code it's the only way to operate safely. This is
259
                 *   likely to change in future and you should avoid relying on it if
260
                 *   at all posssible.
261
                 *
262
                 * If this method is used, the plugin must not be unloaded until all
263
                 * DeferredTask instances have been deleted.
264
                 */
2975 craig 265
                virtual DeferredTask* runAsync(QWidget* parent, ScribusApp* mainWindow, QString target = QString::null);
2972 craig 266
 
267
                /**
268
                 * @brief Run the plugin asynchronously
269
                 *
270
                 * This method is much the same as the above, but takes a QIODevice* as
271
                 * the target. Please see the documentation for run(..., QIODevice*
272
                 * target) and runAsync(..., QString target) for details.
273
                 */
2975 craig 274
                virtual DeferredTask* runAsync(QWidget* parent, ScribusApp* mainWindow, QIODevice* target);
2972 craig 275
 
3189 craig 276
                // Information about actions, to be returned by actionInfo()
277
                struct ActionInfo {
278
                        QString actionName;
279
                        QString actionKeySequence;
280
                        QString actionMenu;
281
                        QString actionMenuAfterName;
282
                        bool actionEnabledOnStartup;
283
                };
2972 craig 284
 
3189 craig 285
                // Return an ActionInfo instance to the caller
286
                virtual const ActionInfo & actionInfo() const;
287
 
288
        protected:
289
                ActionInfo m_actionInfo;
2972 craig 290
};
291
 
292
 
293
 
294
class SCRIBUS_API ScPersistentPlugin : public ScPlugin
295
{
296
        Q_OBJECT
297
 
298
        /**
299
         * @brief A plug-in that is resident for the lifetime of the app
300
         *
301
         * ScPersistentPlugin describes a plugin that is to be kept resident
302
         * for the lifetime of the app (or until unloaded by a request to
303
         * the plug-in manager).
304
         *
305
         * Such plug-ins have an init method and a cleanup method; they have
306
         * no "run" method as such.
307
         */
308
        public:
309
 
2975 craig 310
                /** @brief ctor
311
                 *
312
                 * @sa ScPlugin::ScPlugin()
313
                 */
314
                ScPersistentPlugin(int id, QString& name);
315
 
316
                // Pure virtual dtor for abstract class
317
                virtual ~ScPersistentPlugin() = 0;
318
 
2972 craig 319
                /**
320
                 * @brief Initialize the plugin
321
                 *
322
                 * This method must initialize the plugin. It is called at plug-in load
323
                 * time. This method will never be called twice without an intervening
324
                 * cleanupPlug call (but not necessarily unloading the plugin).
325
                 *
326
                 * It will usually instantiate a class and store a pointer to the
327
                 * instance in a static variable of the plugin or a member of its
328
                 * ScPersistentPlugin subclass, letting that class do the work of setup
329
                 * and integration into the app.
330
                 *
2975 craig 331
                 * Note that this is NOT the same as the init function of the plugin. That
332
                 * is always simple and lightweight, intended to just get an instance of this
333
                 * class back to the core app. This function is where any time-consuming or
334
                 * memory expensive init should be done.
335
                 *
336
                 * @param QWidget& parent Parent widget to this plugin.
337
                 *                        Usually the main window.
338
                 * @param ScribusApp& mainWindow The main application window.
339
                 * @returns bool True for success.
2972 craig 340
                 */
341
                virtual bool initPlug(QWidget& parent, ScribusApp& mainWindow) = 0;
342
 
343
                /**
344
                 * @brief Cleans up the plugin so it can be safely unloaded.
345
                 *
346
                 * This method will be called when the plug-in is about to be unloaded,
347
                 * or if the plug-in manager has been asked to disable the plug-in.
348
                 * This method will never be called unless initPlug has been called
349
                 * first, but there is no guarantee the plugin will be unloaded after
350
                 * this is called, or before initPlug is called again.
351
                 *
352
                 * @returns bool True for success.
353
                 */
354
                virtual bool cleanupPlug() = 0;
355
};
356
 
357
#endif