Subversion Repositories Scribus

Rev

Rev 2975 | Go to most recent revision | Details | 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.
26
 */
27
 
28
class SCRIBUS_API ScPlugin : public QObject
29
{
30
        Q_OBJECT
31
 
32
        /**
33
         * @brief ScPlugin provides an interface to ask plugins for information
34
         * about themselves.
35
         *
36
         * Plugins return a pointer to their ScPlugin instance when
37
         * asked for it by the plugin manager. This class provides general
38
         * information about the plugin. It should not generally be inherited
39
         * directly by plugins - use one of the provided base classes instead.
40
         */
41
        public:
42
 
43
                // Return an instance of the plugin info class.
44
                virtual ScPlugin* instance();
45
 
46
                /** \brief Human readable enumertion of the plugin types */
47
                // FIXME: duplicated in pluginmanager
48
                enum PluginType {
49
                        Persistent = 4,
50
                        Import = 7,
51
                        Standard = 6, // WTF is this?
52
                };
53
 
54
                // A struct providing the information returned by getAboutData(), for
55
                // the "About Plug-ins" menu item.
56
                struct AboutData
57
                {
58
                        // Author name(s) and email address(es)
59
                        QString authors;
60
                        // One-liner description of the function of the plugin
61
                        QString shortDescription;
62
                        // Longer description of the plugin
63
                        QString description;
64
                        // Text plug-in version string
65
                        QString version;
66
                        // Date of the release of this version
67
                        QDateTime releaseDate;
68
                        // Copyright string
69
                        QString copyright;
70
                        // License text / name / URL / whatever. Please don't include
71
                        // the GPL here, just reference it. Remember that Scribus is
72
                        // licensed under the GPL, so plug-in authors must take that
73
                        // into account.
74
                        QString license;
75
                };
76
 
77
                // Plug-in type, inited by ctor.
78
                const PluginType pluginType;
79
 
80
                // Plug-in ID, inited by ctor. This must be unique across all plug-ins.
81
                const int m_id;
82
 
83
                // Plug-in's short name, for internal use. This MUST be a string that
84
                // could be used as part of a valid C identifier. Stick to [a-z], _,
85
                // and numbers please, with the first char being a letter. This must be
86
                // unique across all plug-ins.  Set up by ctor.
87
                const char* m_name;
88
 
89
                // Plug-in's human-readable, translated name. Please don't use this for
90
                // anything except display to the user. Set up by ctor.
91
                const QString m_fullTrName;
92
 
93
                // Information for prefs dialog, to be set up by ctor.
94
                const bool hasPrefsUI;
95
                const QPixmap prefsPanelIcon;
96
                const QString prefsPanelName();
97
 
98
                // Methods to create and destroy the UI pane for the plugin
99
                virtual QWidget* newPrefsPanelWidget() = 0;
100
                virtual void destroyPrefsPanelWidget(QWidget* prefsPanelWidget) = 0;
101
 
102
                // Returns a structure containing descriptive information about the
103
                // plug-in. This information is used in places like the Help->About
104
                // Plug-ins menu item. The stucture MUST be deleted using
105
                // deleteAboutData(AboutData* about) when finished with.
106
                //
107
                // Note: About data isn't stored as const members because (a) it can be
108
                // big, and (b) it isn't needed much.
109
                virtual AboutData* getAboutData();
110
                virtual void deleteAboutData(AboutData* about);
111
 
112
        protected:
113
                /**
114
                 * @brief ctor, returns a new ScPlugin instance
115
                 *
116
                 * @param int id          Unique plugin ID, usually a static
117
                 *                        const int defined in the plugin.
118
                 * @param QString name    Name of the plugin as shown in the
119
                 *                        Start-up dialog and plugin mgr. This is
120
                 *                        the "friendly" human-readable name.
121
                 *                        PluginManager should already know the
122
                 *                        internal name.
123
                 */
124
                ScPlugin(int id, QString& name);
125
 
126
                /** @brief Pure virtual destructor - this is an abstract class */
127
                virtual ~ScPlugin() = 0;
128
 
129
                // Singleton instance.
130
                static ScPlugin* m_instance;
131
};
132
 
133
 
134
class SCRIBUS_API ScImportExportPlugin : public ScPlugin
135
{
136
        Q_OBJECT
137
 
138
        /*
139
         * @brief A plug-in that's loaded for data import/export duties
140
         *
141
         * ScImportExportPlugin describes a plug-in that is loaded on demand
142
         * to perform a data import/export task such as importing an SVG
143
         * image or exporting a page to EPS format. It'll generally by unloaded
144
         * after being queried, then loaded on demand when it needs to run.
145
         */
146
 
147
        public:
148
 
149
                /**
150
                 * @brief Run the plug-in's main action.
151
                 *
152
                 * Run the plug-in's default action. That usually means prompting the
153
                 * user for a target (file to save as / file to import) then performing
154
                 * the import/export action the plug-in is written for. It should
155
                 * generally call run(..., QIODevice* target) or run(..., QString
156
                 * target) to do the work.
157
                 *
158
                 * The plug-in must clean up neatly after this method completes as it
159
                 * may be immediately unloaded. It should not assume it will be
160
                 * unloaded however
161
                 * - this method may be called multiple times without unloading the
162
                 *   plugin.  Some platforms may also not permit plugins to be
163
                 *   unloaded.
164
                 *
165
                 * The optional target argument is a plugin-defined string indicating
166
                 * what the plugin should operate on. It will typically be a filename
167
                 * to import from / export to. Nothing stops a plugin doing funky
168
                 * things like accepting a WebDAV URI, etc, however.
169
                 *
170
                 * Plug-in authors might want to consider implementing this using the
171
                 * DeferredTask subclass used in runAsync, if the plug-in supports it.
172
                 *
173
                 * @param QWidget& parent Parent widget to this plugin. Usually the
174
                 * main window.  @param ScribusApp& mainWindow The main application
175
                 * window.  @param QString target Optional target to operate on (see
176
                 * above) @returns bool True for success.
177
                 *
178
                 */
179
                virtual bool run(QWidget& parent, ScribusApp& mainWindow, QString target = QString::null);
180
 
181
                /**
182
                 * @brief Run the plugin on a QIODevice
183
                 *
184
                 * This method is essentially the same as the above, except that it
185
                 * accepts a QIODevice* to work with. This will generally be used for
186
                 * file I/O without the plugin having to know or care where from.
187
                 *
188
                 * A plug-in MUST return false if it cannot support this method or upon
189
                 * failure. A plug-in MUST supply a working version of this method if
190
                 * it accepts runWith(..., QString) on a local file, and should
191
                 * generally implement the former using this method.
192
                 *
193
                 * Remember that not all QIODevice*s are seekable, and try to write
194
                 * your code to handle a non-seekable stream.
195
                 */
196
                virtual bool run(QWidget& parent, ScribusApp& mainWindow, QIODevice* target);
197
 
198
                /**
199
                 * @brief Run the plugin asynchronously
200
                 *
201
                 * This call is similar to the one above, but instead of doing all the
202
                 * work in one big batch, it creates an instance of a DeferredTask
203
                 * subclass to keep track of the job, does some setup, and returns
204
                 * immediately. The DeferredTask, a pointer to which is returned, has
205
                 * already been started when this method returns.
206
                 *
207
                 * The caller of this method is responsible for handling the aborted()
208
                 * and finished() signals from the DeferredTask, and (if necessary) for
209
                 * cleaning it up once it has finished. Remember that a DeferredTask is
210
                 * automatically deleted when its parent is, if it hasn't already been
211
                 * deleted.
212
                 *
213
                 * FIXME: The above is probably utterly broken on win32.
214
                 *
215
                 * See the DeferredTask documentation for details on how it works.
216
                 *
217
                 * If your plugin implementation does not support asynchronous
218
                 * operation, you must return null. This is the default implementation,
219
                 * so simply ignore this method unless you wish to support it. It is
220
                 * recommended that all new plugins support this interface where
221
                 * possible, even if they can only do part of their work progressively.
222
                 *
223
                 * If you implement this, you may want to implement run(...) using the
224
                 * same deferred operation and a modal dialog. That'll permit the event
225
                 * loop to continue running for redraws, permit you to update the
226
                 * progress bar, etc.
227
                 *
228
                 * NOTE: In current Scribus code (August 2005), callers of this method
229
                 * will generally create a modal dialog - possibly with progress meter
230
                 * - then attach signals from the DeferredTask, and exec() the dialog.
231
                 *   A caller is not required to do this, but with the current (August
232
                 *   2005) core code it's the only way to operate safely. This is
233
                 *   likely to change in future and you should avoid relying on it if
234
                 *   at all posssible.
235
                 *
236
                 * If this method is used, the plugin must not be unloaded until all
237
                 * DeferredTask instances have been deleted.
238
                 */
239
                virtual DeferredTask* runAsync(QWidget& parent, ScribusApp& mainWindow, QString target = QString::null);
240
 
241
                /**
242
                 * @brief Run the plugin asynchronously
243
                 *
244
                 * This method is much the same as the above, but takes a QIODevice* as
245
                 * the target. Please see the documentation for run(..., QIODevice*
246
                 * target) and runAsync(..., QString target) for details.
247
                 */
248
                virtual DeferredTask* runAsync(QWidget& parent, ScribusApp& mainWindow, QIODevice* target);
249
 
250
                // const members defining information about actions, to be
251
                // populated by the ctor.
252
                const QString m_actionName;
253
                const QString m_actionKeySequence;
254
                const QString m_actionMenu;
255
                const QString m_actionMenuAfterName;
256
                const bool m_actionEnabledOnStartup;
257
 
258
        protected:
259
                // Protected ctor for singleton
260
                ScImportExportPlugin(int id, QString& name);
261
                // Pure virtual dtor - abstract class
262
                virtual ~ScImportExportPlugin() = 0;
263
 
264
};
265
 
266
 
267
 
268
class SCRIBUS_API ScPersistentPlugin : public ScPlugin
269
{
270
        Q_OBJECT
271
 
272
        /**
273
         * @brief A plug-in that is resident for the lifetime of the app
274
         *
275
         * ScPersistentPlugin describes a plugin that is to be kept resident
276
         * for the lifetime of the app (or until unloaded by a request to
277
         * the plug-in manager).
278
         *
279
         * Such plug-ins have an init method and a cleanup method; they have
280
         * no "run" method as such.
281
         */
282
        public:
283
 
284
                /**
285
                 * @brief Initialize the plugin
286
                 *
287
                 * This method must initialize the plugin. It is called at plug-in load
288
                 * time. This method will never be called twice without an intervening
289
                 * cleanupPlug call (but not necessarily unloading the plugin).
290
                 *
291
                 * It will usually instantiate a class and store a pointer to the
292
                 * instance in a static variable of the plugin or a member of its
293
                 * ScPersistentPlugin subclass, letting that class do the work of setup
294
                 * and integration into the app.
295
                 *
296
                 * @param QWidget& parent Parent widget to this plugin. Usually the
297
                 * main window.  @parem ScribusApp& mainWindow The main application
298
                 * window.  @returns bool True for success.
299
                 */
300
                virtual bool initPlug(QWidget& parent, ScribusApp& mainWindow) = 0;
301
 
302
                /**
303
                 * @brief Cleans up the plugin so it can be safely unloaded.
304
                 *
305
                 * This method will be called when the plug-in is about to be unloaded,
306
                 * or if the plug-in manager has been asked to disable the plug-in.
307
                 * This method will never be called unless initPlug has been called
308
                 * first, but there is no guarantee the plugin will be unloaded after
309
                 * this is called, or before initPlug is called again.
310
                 *
311
                 * @returns bool True for success.
312
                 */
313
                virtual bool cleanupPlug() = 0;
314
 
315
        protected:
316
 
317
                ScPersistentPlugin(int id, QString& name);
318
                // Pure virtual dtor for abstract class
319
                virtual ~ScPersistentPlugin() = 0;
320
 
321
};
322
 
323
#endif