Subversion Repositories Scribus

Rev

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

Rev Author Line No. Line
4430 cbradney 1
/*
2
For general Scribus (>=1.3.2) copyright and licensing information please refer
3
to the COPYING file provided with the program. Following this notice may exist
4
a copyright and/or license notice that predates the release of Scribus 1.3.2
5
for which a new license (GPL+exception) is in place.
6
*/
2972 craig 7
#ifndef _SCPLUGIN_H
8
#define _SCPLUGIN_H
9
 
11325 cbradney 10
#include <QObject>
11
#include <QWidget>
12
#include <QString>
13
#include <QPixmap>
14
#include <QDateTime>
15
#include <QIcon>
2972 craig 16
#include "scribusapi.h"
17
 
5781 cbradney 18
class ScribusDoc;
4026 craig 19
class ScribusMainWindow;
2972 craig 20
class DeferredTask;
3213 craig 21
class PrefsPanel;
14657 cbradney 22
class Prefs_Pane;
2972 craig 23
 
3214 craig 24
/**
25
 * \brief Abstract super class for all Scribus plug-ins
2972 craig 26
 *
3214 craig 27
 * ScPlugin is a class that provides information about a plug-in, and a gateway
28
 * into any plugin-specific functionality.  It should not generally be
3486 craig 29
 * inherited directly by actual plugin implementations - use one of the
30
 * provided base classes instead. See below for info on the creation of
31
 * new types of plugin.
2972 craig 32
 *
3486 craig 33
 * Plugins create and return a instance of a subclass of ScPlugin when asked
34
 * for it by the plugin manager. The plugin manager is responsible for tracking
35
 * these instances. The ScPlugin instance is used by the plugin manager for
36
 * tasks such as hooking the plugin up to the UI where appropriate. It's also
37
 * used by other code that talks to plugins, usually by dynamic_cast<>ing it to
38
 * a more specific subclass and working with that. The file loader system will
39
 * provide an example of this.
3214 craig 40
 *
3486 craig 41
 * A given plugin implementation's ScPlugin subclass is *not* the best place
42
 * to implement the bulk of the plugin's functionality. It must be lightweight
43
 * and maintain as little state as possible. Most functionality should be
44
 * implemented in a private subclass that is not exposed in the header of the
45
 * scplugin subclass defined by the plugin. That helps keep the plugin's
46
 * implementation separate from its inteface to Scribus.
3214 craig 47
 *
3486 craig 48
 * Note that the two subclases ScActionPlugin and ScPersistentPlugin, defined
49
 * below, create two quite different kinds of plugins. One is for import/export
50
 * of data and for single function actions (like providing a particular dialog
51
 * or function) which generally do nothing when not in active use. A second for
52
 * persistent plugins that are loaded (generally when the app starts) and
53
 * remain resident, possibly active in the background or hooked into many
54
 * parts of the user interface.
55
 *
2972 craig 56
 * More plugin classes - such as plugins for text import and document import
57
 * - may be added in future.
2975 craig 58
 *
3486 craig 59
 * New types of plugin can be created by subclassing ScPlugin or one of its
60
 * subclasses and adding the additional interfaces required. The two existing
61
 * subclasses provide examples of how this can work. Of course, once you have
62
 * the plugin interface, you still need to actually use the plugins. You'll need
63
 * to extend pluginmanager.cpp a little to handle any low-level init required by
64
 * the new plugin type (please keep this minimal!). You'll then need to extend
65
 * the appropriate classes to make use of the new plugin type where required.
66
 * The new file loader mechanism will provide a good example of this.
67
 *
2975 craig 68
 * In addition to the API described here, a plugin is expected to implement
69
 * the following "extern C" functions, where 'pluginname' is the base name
3214 craig 70
 * of the plug-in (where the filename is libpluginname.so on UNIX):
2975 craig 71
 *
3207 craig 72
 * int pluginname_getPluginAPIVersion();
2975 craig 73
 *    Return an integer indicating the plug-in API version implemented.
74
 *    If the version does not exactly match the running plugin API version,
75
 *    the plugin will not be initialised.
76
 *
77
 * ScPlugin* pluginname_getPlugin();
78
 *    Create and return an instance of the plug-ins ScPlugin subclass.
79
 *    Nothing should be done here that's overly slow or uses much memory,
80
 *    and the plugin should not initialize its self here beyond what is
81
 *    required to return a ScPlugin instance.
82
 *
83
 * void pluginname_freePlugin(ScPlugin* plugin);
84
 *    Free the scplugin instance returned earlier.
85
 *
3193 craig 86
 * TODO: better discovery of what plug-ins can import / export what formats, file exts, names, etc.
87
 *
2972 craig 88
 */
89
 
90
class SCRIBUS_API ScPlugin : public QObject
91
{
92
        Q_OBJECT
93
 
94
        /**
95
         * @brief ScPlugin provides an interface to ask plugins for information
96
         * about themselves.
97
         *
98
         */
99
        public:
100
 
4448 subik 101
                /*! \brief A struct providing the information returned by getAboutData(), for
102
                the "About Plug-ins" menu item. */
2972 craig 103
                struct AboutData
104
                {
4448 subik 105
                        //! Author name(s) and email address(es)
2972 craig 106
                        QString authors;
4448 subik 107
                        //! One-liner description of the function of the plugin
2972 craig 108
                        QString shortDescription;
4448 subik 109
                        //! Longer description of the plugin
2972 craig 110
                        QString description;
4448 subik 111
                        //! Text plug-in version string
2972 craig 112
                        QString version;
4448 subik 113
                        //! Date of the release of this version
2972 craig 114
                        QDateTime releaseDate;
4448 subik 115
                        //! Copyright string
2972 craig 116
                        QString copyright;
4448 subik 117
                        //! License text / name / URL / whatever. Please don't include
118
                        //! the GPL here, just reference it. Remember that Scribus is
119
                        //! licensed under the GPL, so plug-in authors must take that
120
                        //! into account.
2972 craig 121
                        QString license;
122
                };
123
 
2975 craig 124
                /**
125
                 * @brief ctor, returns a new ScPlugin instance
126
                 *
3486 craig 127
                 * Only pluginname_getPlugin(...) may call this. Calls by other code
128
                 * will have undefined results.
2975 craig 129
                 */
3487 craig 130
                ScPlugin();
2975 craig 131
 
3486 craig 132
                /** @brief Destroy the ScPlugin instance
133
                 *
134
                 * Pure virtual destructor - this is an abstract class.
135
                 *
136
                 * Only pluginname_freePlugin(...) may call this. Calls by other code
137
                 * will have undefined results.
138
                 */
2975 craig 139
                virtual ~ScPlugin() = 0;
140
 
3486 craig 141
                /** @brief Plug-in's human-readable, translated name.
142
                 *
143
                 * Please don't use this for anything except display to the user.
144
                 * The results of testing the value of this can not be guaranteed,
145
                 * as its value may change depending on locale and change at runtime.
146
                 */
3207 craig 147
                virtual const QString fullTrName() const = 0;
2972 craig 148
 
3214 craig 149
                /**
150
                 * \brief Create and return a prefs UI panel for the plugin.
151
                 *
152
                 * Override this method if you want to provide a panel for the
153
                 * preferences dialog.
154
                 *
155
                 * The caller takes ownership of the panel. Qt is responsible for
3486 craig 156
                 * deleting it when it's parent is deleted. `parent' must be the dialog
3214 craig 157
                 * the widget will be added to or a child of it, otherwise the panel
158
                 * won't be deleted correctly when the dialog is.
159
                 *
160
                 * See prefspanel.h for info on implementing the panel.
161
                 *
162
                 * This method must return false (the default) if the plugin does
163
                 * not provide a prefs panel. If true is returned, caption, panel,
164
                 * and icon MUST have been assigned.
165
                 *
166
                 * \param parent Parent widget, to be passed to panel ctor
167
                 * \param panel (out) the panel created
168
                 * \param caption (out) caption for icon in panel list
169
                 * \param icon (out) icon for use in panel list
170
                 * \return true if panel was created, false if not.
171
                 *
172
                 * By default, returns 0 to indicate no prefs UI.
173
                */
174
                virtual bool newPrefsPanelWidget(QWidget* parent, PrefsPanel*& panel,
175
                                                                                 QString& caption, QPixmap& icon);
14657 cbradney 176
                virtual bool newPrefsPanelWidget(QWidget* parent, Prefs_Pane*& panel,
14621 cbradney 177
                                                                 QString& caption, QPixmap& icon);
2972 craig 178
 
3994 subik 179
                /*! @brief Return descriptive information about the plug-in
3486 craig 180
                 *
181
                 * Returns a structure containing descriptive information about the
182
                 * plug-in. This information is used in places like the Help->About
183
                 * Plug-ins menu item. The stucture MUST be deleted using
184
                 * deleteAboutData(AboutData* about) when finished with.
185
                 *
186
                 * Every plugin MUST reimplement getAboutData(...) and deleteAboutData(...).
187
                 *
188
                 * @sa ScPlugin::deleteAboutData
189
                 */
3189 craig 190
                virtual const AboutData* getAboutData() const = 0;
191
                virtual void deleteAboutData(const AboutData* about) const = 0;
2972 craig 192
 
3994 subik 193
                /*! @brief Text summary of last error encountered
3486 craig 194
                 *
195
                 * Return the human readable, translated text of last error to be
196
                 * encountered by this plugin. DO NOT ATTEMPT TO USE THIS VALUE TO MAKE
197
                 * DECISIONS IN PROGRAM CODE. The value returned for a given error
198
                 * may change depending on locale, and may change at runtime.
199
                 */
2975 craig 200
                const QString & lastError() const;
201
 
14392 jghali 202
                //! \brief Returns if lastError message is not empty
203
                bool hasLastError() const;
204
 
205
                //! \brief Clear last error message
206
                void clearLastError();
207
 
3994 subik 208
                /*! @brief Update all user-visible text to reflect current UI language
3486 craig 209
                 *
210
                 * Updates the text on all widgets on the plug-in to reflect the new
211
                 * language. You should generally use this method to set all the widget
212
                 * text during construction. That ensures that text is not duplicated,
213
                 * and that when this method is called the text of all persistent
214
                 * widgets is correctly changed.
215
                 *
216
                 * This method only needs to affect text in widgets that currently
217
                 * exists (displayed or otherwise).
218
                 */
3193 craig 219
                virtual void languageChange() = 0;
220
 
3994 subik 221
                //! \brief Returns human readable plugin type from plug-in's pluginType
3193 craig 222
                const QString pluginTypeName() const;
7155 subik 223
 
224
                //! \brief Allow plugins to add to a main menu
5243 cbradney 225
                virtual void addToMainWindowMenu(ScribusMainWindow *) = 0;
12846 fschmid 226
 
227
                //! \brief hooks that plugins can use to detect if the current document was closed etc..
228
                virtual void setDoc(ScribusDoc* doc);
229
                virtual void unsetDoc();
230
                virtual void changedDoc(ScribusDoc* doc);
2972 craig 231
        protected:
3994 subik 232
                //! \brief Human readable, translated version of last error to occur.
2975 craig 233
                QString m_lastError;
2972 craig 234
};
235
 
236
 
3994 subik 237
/*!
3486 craig 238
 * @brief A plug-in that performs a single action
239
 *
240
 * ScActionPlugin describes a plug-in that is used to perform a single well
241
 * defined action. Uses include data import/export, displaying a dialog, or
242
 * doing a single batch task. It is automatically connected to the user
243
 * interface and has simple methods to trigger the plug-in's supported action.
244
 *
245
 * If you need more complex user interface integration, persistent operation,
246
 * etc, you may be better off with ScPersistentPlugin.
247
 */
3207 craig 248
class SCRIBUS_API ScActionPlugin : public ScPlugin
2972 craig 249
{
250
        Q_OBJECT
251
 
252
        public:
253
 
2975 craig 254
                /** @brief ctor
255
                 *
256
                 * @sa ScPlugin::ScPlugin()
257
                 */
3487 craig 258
                ScActionPlugin();
3207 craig 259
 
3994 subik 260
                //! \brief Pure virtual dtor - abstract class
3207 craig 261
                virtual ~ScActionPlugin() = 0;
2975 craig 262
 
3193 craig 263
                // Information about actions, to be returned by actionInfo()
264
                struct ActionInfo {
15637 fschmid 265
                        QString name;                                   // name of action
266
                        QString text;                                   // text to display to user
267
                        QString helpText;                               // help text for ToolTips and StatusTips
3193 craig 268
                        QString keySequence;
269
                        QString menu;
270
                        QString menuAfterName;
11050 fschmid 271
                        QString parentMenu;
272
                        QString subMenuName;
15637 fschmid 273
                        QString toolbar;                                // Name of the ToolBar the action is to be inserted, if that toolbar doesn't exits it will be created
274
                        QString toolBarName;                    // translateable ToolBar title
8586 cbradney 275
                        QPixmap icon1;
276
                        QPixmap icon2;
11055 fschmid 277
                        QList<int> notSuitableFor;              // a list of PageItem type values which the plugin can *not* handle
278
                        QList<int> forAppMode;                  // a list of AppMode values for which the plugin will be active, an empty list indicates that the plugin is always active
279
                        int needsNumObjects;                    // plugin needs this number of selected Objects. -1 = needs no Object, num > 2 any number of Objects is allowed
280
                        QList<int> firstObjectType;             // when needsNumObjects is 2 this list contains the Object Types of the first object on the selection
281
                        QList<int> secondObjectType;    // when needsNumObjects is 2 this list contains the Object Types of the second object on the selection
282
                                                                                        // -1 indicates that any kind of object is possible. Otherwise the selection must contain the 2 Object Types
283
                                                                                        // for the Plugin Action to be enabled
3193 craig 284
                        bool enabledOnStartup;
17501 craig 285
                        bool enabledForStoryEditor;
286
                        QString seMenu;
287
                        QString seParentMenu;
288
                        QString seKeySequence;
3193 craig 289
                };
290
 
291
                // Return an ActionInfo instance to the caller
3207 craig 292
                const ActionInfo & actionInfo() const;
12552 fschmid 293
                /**
294
                * @brief handle the documents selection.
295
                *
296
                * This function is dedicated for handling the documents selection
297
                * By default this uses the notSuitableFor, forAppMode, needsNumObjects,
298
                * firstObjectType and secondObjectType variables.
299
                * If you need more control over the selection reimplement this function.
300
                *
301
                * @returns bool true when the Action should be enabled.
302
                *
303
                */
304
                virtual bool handleSelection(ScribusDoc* doc, int SelectedType = -1);
3193 craig 305
 
306
        public slots:
2972 craig 307
                /**
308
                 * @brief Run the plug-in's main action.
309
                 *
3486 craig 310
                 * Run the plug-in's default action synchronously, blocking the rest of
311
                 * the application until this method returns.
2972 craig 312
                 *
3486 craig 313
                 * This method should generally call run(..., QIODevice* target) or
314
                 * run(..., QString target) to do the work. This is done by default,
315
                 * with the assumption that the target is a file. The argument is
316
                 * opened as QFile with IO_ReadOnly or IO_WriteOnly mode, depending on
317
                 * plugin type, and passed to run(..., QIODevice*). Override this if
318
                 * you need more flexibility.
2972 craig 319
                 *
320
                 * The optional target argument is a plugin-defined string indicating
321
                 * what the plugin should operate on. It will typically be a filename
322
                 * to import from / export to. Nothing stops a plugin doing funky
323
                 * things like accepting a WebDAV URI, etc, however.
324
                 *
325
                 * Plug-in authors might want to consider implementing this using the
326
                 * DeferredTask subclass used in runAsync, if the plug-in supports it.
327
                 *
4645 subik 328
                 * @param target Optional target to operate on (see
3193 craig 329
                 *                above)
330
                 * @returns bool True for success.
2972 craig 331
                 *
332
                 */
5781 cbradney 333
                virtual bool run(ScribusDoc* doc, QString target = QString::null) = 0;
2972 craig 334
 
335
                /**
7155 subik 336
                 * @brief Run the plug-in's main action.
337
                 *
338
                 * This method behaves as the previous one. Except there is
339
                 * a parent widget reference. It's useful e.g. when you need to
340
                 * open a dialog on a specific parent one.
341
                 */
342
                virtual bool run(QWidget* parent, ScribusDoc* doc, QString target = QString::null);
343
 
344
                /**
2972 craig 345
                 * @brief Run the plugin on a QIODevice
346
                 *
347
                 * This method is essentially the same as the above, except that it
348
                 * accepts a QIODevice* to work with. This will generally be used for
349
                 * file I/O without the plugin having to know or care where from.
350
                 *
351
                 * A plug-in MUST return false if it cannot support this method or upon
352
                 * failure. A plug-in MUST supply a working version of this method if
353
                 * it accepts runWith(..., QString) on a local file, and should
354
                 * generally implement the former using this method.
355
                 *
356
                 * Remember that not all QIODevice*s are seekable, and try to write
357
                 * your code to handle a non-seekable stream.
358
                 */
5781 cbradney 359
                virtual bool run(ScribusDoc* doc, QIODevice* target);
2972 craig 360
 
361
                /**
362
                 * @brief Run the plugin asynchronously
363
                 *
364
                 * This call is similar to the one above, but instead of doing all the
365
                 * work in one big batch, it creates an instance of a DeferredTask
366
                 * subclass to keep track of the job, does some setup, and returns
367
                 * immediately. The DeferredTask, a pointer to which is returned, has
368
                 * already been started when this method returns.
369
                 *
370
                 * The caller of this method is responsible for handling the aborted()
371
                 * and finished() signals from the DeferredTask, and (if necessary) for
3486 craig 372
                 * cleaning it up using deleteLater(...) once it has finished. Remember
373
                 * that a DeferredTask is automatically deleted when its parent is, if
374
                 * it hasn't already been deleted. This approach is preferred where
375
                 * possible.
2972 craig 376
                 *
377
                 * See the DeferredTask documentation for details on how it works.
378
                 *
379
                 * If your plugin implementation does not support asynchronous
380
                 * operation, you must return null. This is the default implementation,
381
                 * so simply ignore this method unless you wish to support it. It is
382
                 * recommended that all new plugins support this interface where
383
                 * possible, even if they can only do part of their work progressively.
384
                 *
385
                 * If you implement this, you may want to implement run(...) using the
386
                 * same deferred operation and a modal dialog. That'll permit the event
387
                 * loop to continue running for redraws, permit you to update the
388
                 * progress bar, etc.
389
                 *
390
                 * NOTE: In current Scribus code (August 2005), callers of this method
391
                 * will generally create a modal dialog - possibly with progress meter
392
                 * - then attach signals from the DeferredTask, and exec() the dialog.
393
                 *   A caller is not required to do this, but with the current (August
394
                 *   2005) core code it's the only way to operate safely. This is
395
                 *   likely to change in future and you should avoid relying on it if
396
                 *   at all posssible.
397
                 *
398
                 * If this method is used, the plugin must not be unloaded until all
399
                 * DeferredTask instances have been deleted.
400
                 */
3193 craig 401
                virtual DeferredTask* runAsync(QString target = QString::null);
2972 craig 402
 
403
                /**
404
                 * @brief Run the plugin asynchronously
405
                 *
406
                 * This method is much the same as the above, but takes a QIODevice* as
407
                 * the target. Please see the documentation for run(..., QIODevice*
408
                 * target) and runAsync(..., QString target) for details.
409
                 */
3193 craig 410
                virtual DeferredTask* runAsync(QIODevice* target);
2972 craig 411
 
3193 craig 412
                // Compat kludge ... we store a QString result from any successful
413
                // run(...) call in m_runResult and let callers retrive it here.
414
                // DO NOT USE THIS INTERFACE FOR NEW PLUG-INS; you should
415
                // dynamic_cast<> to the plugin type then call a plug-in specific
416
                // method instead.
3994 subik 417
                ///! Obsolete method - do not use this or rely on it in new code.
3193 craig 418
                const QString & runResult() const;
2972 craig 419
 
3189 craig 420
        protected:
3207 craig 421
                // Action info. To be set up by ctor.
3189 craig 422
                ActionInfo m_actionInfo;
3486 craig 423
                // Obsolete - see runResult()
3193 craig 424
                QString m_runResult;
5781 cbradney 425
                ScribusDoc* m_Doc;
2972 craig 426
};
427
 
3486 craig 428
/**
429
 * @brief A plug-in that is resident for the lifetime of the app
430
 *
431
 * ScPersistentPlugin describes a plugin that is to be kept resident for the
432
 * lifetime of the app (or until unloaded by a request to the plug-in manager).
433
 * Persistent plugins are useful where the plugin author needs to retain state,
434
 * needs more control of how they integrate with the Scribus user interface,
435
 * and/or wants to perform tasks in the background.
436
 *
437
 * Such plug-ins have an init method and a cleanup method; they have
438
 * no "run" method as such. It is up to the plugin to determine how
439
 * best to interfact with the user.
440
 */
2972 craig 441
class SCRIBUS_API ScPersistentPlugin : public ScPlugin
442
{
443
        Q_OBJECT
444
 
445
        public:
446
 
2975 craig 447
                /** @brief ctor
448
                 *
449
                 * @sa ScPlugin::ScPlugin()
450
                 */
3207 craig 451
                ScPersistentPlugin();
2975 craig 452
 
3994 subik 453
                //! \brief Pure virtual dtor for abstract class
2975 craig 454
                virtual ~ScPersistentPlugin() = 0;
455
 
2972 craig 456
                /**
457
                 * @brief Initialize the plugin
458
                 *
459
                 * This method must initialize the plugin. It is called at plug-in load
460
                 * time. This method will never be called twice without an intervening
3486 craig 461
                 * cleanupPlugin call, but there is no guarantee the plugin will actually
462
                 * be unloaded between initPlugin() and cleanupPlugin().
2972 craig 463
                 *
464
                 * It will usually instantiate a class and store a pointer to the
465
                 * instance in a static variable of the plugin or a member of its
466
                 * ScPersistentPlugin subclass, letting that class do the work of setup
467
                 * and integration into the app.
468
                 *
2975 craig 469
                 * Note that this is NOT the same as the init function of the plugin. That
470
                 * is always simple and lightweight, intended to just get an instance of this
471
                 * class back to the core app. This function is where any time-consuming or
3486 craig 472
                 * memory expensive init should be triggered, generally by the instantiation
473
                 * of the class that does the real work for the plugin.
2975 craig 474
                 *
3193 craig 475
                 * If this method returns failure, the plugin will be treated as dead and
476
                 * cleanupPlug() will not be called.
477
                 *
2975 craig 478
                 * @returns bool True for success.
2972 craig 479
                 */
3193 craig 480
                virtual bool initPlugin() = 0;
2972 craig 481
 
482
                /**
3486 craig 483
                 * @brief Deactivates the plugin for unloading / program quit
2972 craig 484
                 *
485
                 * This method will be called when the plug-in is about to be unloaded,
486
                 * or if the plug-in manager has been asked to disable the plug-in.
3486 craig 487
                 * This method will never be called unless initPlugin has been called
488
                 * first, but there is no guarantee the plugin will actually be
489
                 * unloaded after this is called, or before initPlugin is called again.
2972 craig 490
                 *
491
                 * @returns bool True for success.
492
                 */
3207 craig 493
                virtual bool cleanupPlugin() = 0;
2972 craig 494
};
495
 
3256 craig 496
// Plug-in API version used to check if we can load the plug-in. This
497
// does *NOT* ensure that the plug-in will be compatible with the internal
498
// Scribus APIs, only that the ScPlugin class and its standard subclasses
499
// will be compatible with what we expect, and that "extern C" functions
500
// we need will be present and work as expected. It's a preprocessor directive
501
// to make sure that it's compiled into each plugin rather than referenced
502
// from the main code.
503
//
504
// The API version is currently simply incremented with each incompatible
505
// change. Future versions may introduce a minor/major scheme if necessary.
17501 craig 506
#define PLUGIN_API_VERSION 0x00000103
3256 craig 507
 
508
 
2972 craig 509
#endif