scplugin.h

/*
For general Scribus (>=1.3.2) copyright and licensing information please refer
to the COPYING file provided with the program. Following this notice may exist
a copyright and/or license notice that predates the release of Scribus 1.3.2
for which a new license (GPL+exception) is in place.
*/
#ifndef _SCPLUGIN_H
#define _SCPLUGIN_H

#include <QObject>
#include <QWidget>
#include <QString>
#include <QPixmap>
#include <QDateTime>
#include <QIcon>
#include "scribusapi.h"

class ScribusDoc;
class ScribusMainWindow;
class DeferredTask;
class PrefsPanel;
class Prefs_Pane;

class SCRIBUS_API ScPlugin : public QObject
{
    Q_OBJECT

    public:

        struct AboutData
        {
            QString authors;
            QString shortDescription;
            QString description;
            QString version;
            QDateTime releaseDate;
            QString copyright;
            QString license;
        };

        ScPlugin();

        virtual ~ScPlugin() = 0;

        virtual const QString fullTrName() const = 0;

        virtual bool newPrefsPanelWidget(QWidget* parent, PrefsPanel*& panel,
                                         QString& caption, QPixmap& icon);
        virtual bool newPrefsPanelWidget(QWidget* parent, Prefs_Pane*& panel,
                                 QString& caption, QPixmap& icon);

        virtual const AboutData* getAboutData() const = 0;
        virtual void deleteAboutData(const AboutData* about) const = 0;

        const QString & lastError() const;

        bool hasLastError() const;

        void clearLastError();

        virtual void languageChange() = 0;

        const QString pluginTypeName() const;

        virtual void addToMainWindowMenu(ScribusMainWindow *) = 0;

        virtual void setDoc(ScribusDoc* doc);
        virtual void unsetDoc();
        virtual void changedDoc(ScribusDoc* doc);
    protected:
        QString m_lastError;
};


class SCRIBUS_API ScActionPlugin : public ScPlugin
{
    Q_OBJECT

    public:

        ScActionPlugin();

        virtual ~ScActionPlugin() = 0;

        // Information about actions, to be returned by actionInfo()
        struct ActionInfo {
            QString name;                   // name of action
            QString text;                   // text to display to user
            QString helpText;               // help text for ToolTips and StatusTips
            QString keySequence;
            QString menu;
            QString menuAfterName;
            QString parentMenu;
            QString subMenuName;
            QString toolbar;                // Name of the ToolBar the action is to be inserted, if that toolbar doesn't exits it will be created
            QString toolBarName;            // translateable ToolBar title
            QPixmap icon1;
            QPixmap icon2;
            QList<int> notSuitableFor;      // a list of PageItem type values which the plugin can *not* handle
            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
            int needsNumObjects;            // plugin needs this number of selected Objects. -1 = needs no Object, num > 2 any number of Objects is allowed
            QList<int> firstObjectType;     // when needsNumObjects is 2 this list contains the Object Types of the first object on the selection
            QList<int> secondObjectType;    // when needsNumObjects is 2 this list contains the Object Types of the second object on the selection
                                            // -1 indicates that any kind of object is possible. Otherwise the selection must contain the 2 Object Types
                                            // for the Plugin Action to be enabled
            bool enabledOnStartup;
            bool enabledForStoryEditor;
            QString seMenu;
            QString seParentMenu;
            QString seKeySequence;
        };

        // Return an ActionInfo instance to the caller
        const ActionInfo & actionInfo() const;
        virtual bool handleSelection(ScribusDoc* doc, int SelectedType = -1);

    public slots:
        virtual bool cleanupPlugin() { return false; }

        virtual bool run(ScribusDoc* doc, QString target = QString::null) = 0;

        virtual bool run(QWidget* parent, ScribusDoc* doc, QString target = QString::null);

        virtual bool run(ScribusDoc* doc, QIODevice* target);

        virtual DeferredTask* runAsync(QString target = QString::null);

        virtual DeferredTask* runAsync(QIODevice* target);

        // Compat kludge ... we store a QString result from any successful
        // run(...) call in m_runResult and let callers retrive it here.
        // DO NOT USE THIS INTERFACE FOR NEW PLUG-INS; you should
        // dynamic_cast<> to the plugin type then call a plug-in specific
        // method instead.
        const QString & runResult() const;

    protected:
        // Action info. To be set up by ctor.
        ActionInfo m_actionInfo;
        // Obsolete - see runResult()
        QString m_runResult;
        ScribusDoc* m_Doc;
};

class SCRIBUS_API ScPersistentPlugin : public ScPlugin
{
    Q_OBJECT

    public:

        ScPersistentPlugin();

        virtual ~ScPersistentPlugin() = 0;

        virtual bool initPlugin() = 0;

        virtual bool cleanupPlugin() = 0;
};

// Plug-in API version used to check if we can load the plug-in. This
// does *NOT* ensure that the plug-in will be compatible with the internal
// Scribus APIs, only that the ScPlugin class and its standard subclasses
// will be compatible with what we expect, and that "extern C" functions
// we need will be present and work as expected. It's a preprocessor directive
// to make sure that it's compiled into each plugin rather than referenced
// from the main code.
//
// The API version is currently simply incremented with each incompatible
// change. Future versions may introduce a minor/major scheme if necessary.
#define PLUGIN_API_VERSION 0x00000106


#endif