Scribus Developer Documentation - API
logo-pen

Scribus Developer Documentation - API

scplugin.h

Go to the documentation of this file.
00001 /*
00002 For general Scribus (>=1.3.2) copyright and licensing information please refer
00003 to the COPYING file provided with the program. Following this notice may exist
00004 a copyright and/or license notice that predates the release of Scribus 1.3.2
00005 for which a new license (GPL+exception) is in place.
00006 */
00007 #ifndef _SCPLUGIN_H
00008 #define _SCPLUGIN_H
00009 
00010 #include <QObject>
00011 #include <QWidget>
00012 #include <QString>
00013 #include <QPixmap>
00014 #include <QDateTime>
00015 #include <QIcon>
00016 #include "scribusapi.h"
00017 
00018 class ScribusDoc;
00019 class ScribusMainWindow;
00020 class DeferredTask;
00021 class PrefsPanel;
00022 
00089 class SCRIBUS_API ScPlugin : public QObject
00090 {
00091     Q_OBJECT
00092 
00098     public:
00099 
00102         struct AboutData
00103         {
00105             QString authors;
00107             QString shortDescription;
00109             QString description;
00111             QString version;
00113             QDateTime releaseDate;
00115             QString copyright;
00120             QString license;
00121         };
00122 
00129         ScPlugin();
00130 
00138         virtual ~ScPlugin() = 0;
00139 
00146         virtual const QString fullTrName() const = 0;
00147 
00173         virtual bool newPrefsPanelWidget(QWidget* parent, PrefsPanel*& panel,
00174                                          QString& caption, QPixmap& icon);
00175 
00187         virtual const AboutData* getAboutData() const = 0;
00188         virtual void deleteAboutData(const AboutData* about) const = 0;
00189 
00197         const QString & lastError() const;
00198 
00210         virtual void languageChange() = 0;
00211 
00213         const QString pluginTypeName() const;
00214 
00216         virtual void addToMainWindowMenu(ScribusMainWindow *) = 0;
00217     protected:
00219         QString m_lastError;
00220 };
00221 
00222 
00234 class SCRIBUS_API ScActionPlugin : public ScPlugin
00235 {
00236     Q_OBJECT
00237 
00238     public:
00239 
00244         ScActionPlugin();
00245 
00247         virtual ~ScActionPlugin() = 0;
00248 
00249         // Information about actions, to be returned by actionInfo()
00250         struct ActionInfo {
00251             QString name;  // name of action
00252             QString text;  // text to display to user
00253             QString keySequence;
00254             QString menu;
00255             QString menuAfterName;
00256             QString parentMenu;
00257             QString subMenuName;
00258             QString toolbar;            // Name of the ToolBar the action is to be inserted, if that toolbar doesn't exits it will be created
00259             QString toolBarName;        // translateable ToolBar title
00260             QPixmap icon1;
00261             QPixmap icon2;
00262             QList<int> notSuitableFor;      // a list of PageItem type values which the plugin can *not* handle
00263             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
00264             int needsNumObjects;            // plugin needs this number of selected Objects. -1 = needs no Object, num > 2 any number of Objects is allowed
00265             QList<int> firstObjectType;     // when needsNumObjects is 2 this list contains the Object Types of the first object on the selection
00266             QList<int> secondObjectType;    // when needsNumObjects is 2 this list contains the Object Types of the second object on the selection
00267                                             // -1 indicates that any kind of object is possible. Otherwise the selection must contain the 2 Object Types
00268                                             // for the Plugin Action to be enabled
00269             bool enabledOnStartup;
00270         };
00271 
00272         // Return an ActionInfo instance to the caller
00273         const ActionInfo & actionInfo() const;
00274 
00275     public slots:
00302         virtual bool run(ScribusDoc* doc, QString target = QString::null) = 0;
00303 
00311         virtual bool run(QWidget* parent, ScribusDoc* doc, QString target = QString::null);
00312 
00328         virtual bool run(ScribusDoc* doc, QIODevice* target);
00329 
00370         virtual DeferredTask* runAsync(QString target = QString::null);
00371 
00379         virtual DeferredTask* runAsync(QIODevice* target);
00380 
00381         // Compat kludge ... we store a QString result from any successful
00382         // run(...) call in m_runResult and let callers retrive it here.
00383         // DO NOT USE THIS INTERFACE FOR NEW PLUG-INS; you should
00384         // dynamic_cast<> to the plugin type then call a plug-in specific
00385         // method instead.
00387         const QString & runResult() const;
00388 
00389     protected:
00390         // Action info. To be set up by ctor.
00391         ActionInfo m_actionInfo;
00392         // Obsolete - see runResult()
00393         QString m_runResult;
00394         ScribusDoc* m_Doc;
00395 };
00396 
00410 class SCRIBUS_API ScPersistentPlugin : public ScPlugin
00411 {
00412     Q_OBJECT
00413 
00414     public:
00415 
00420         ScPersistentPlugin();
00421 
00423         virtual ~ScPersistentPlugin() = 0;
00424 
00449         virtual bool initPlugin() = 0;
00450 
00462         virtual bool cleanupPlugin() = 0;
00463 };
00464 
00465 // Plug-in API version used to check if we can load the plug-in. This
00466 // does *NOT* ensure that the plug-in will be compatible with the internal
00467 // Scribus APIs, only that the ScPlugin class and its standard subclasses
00468 // will be compatible with what we expect, and that "extern C" functions
00469 // we need will be present and work as expected. It's a preprocessor directive
00470 // to make sure that it's compiled into each plugin rather than referenced
00471 // from the main code.
00472 //
00473 // The API version is currently simply incremented with each incompatible
00474 // change. Future versions may introduce a minor/major scheme if necessary.
00475 #define PLUGIN_API_VERSION 0x00000008
00476 
00477 
00478 #endif
Created with personalized Doxygen. This is documentation for GPL software Scribus - Open Source Desktop Publishing.