Draft header file

This is the draft scplugin.h . Plugins will need to provide a subclass of ScPersistentPlugin or ScInputOutputPlugin and return an instance of it when their getPlugin() function is called. See Plugin API for an overview of the plugin interface design.

#ifndef PLUGIN_H
#define PLUGIN_H

#include "qstring.h"

class QWidget;
class ScribusApp;

/*
 * TODO: Error code lookup functions
 * TODO: Interfaces for getting help data a-la Acrobat Reader 7's 
 *       "about plugins" display. Should be as simple as a series
 *       of getter methods, some static virtual data, or a method
 *       to return a simple struct/class with the info in it.
 * TODO: Prefs GUI API. Scripts need to be able to register so they can
 *       have their own prefs pane displayed in the prefs, with a callback
 *       to save the prefs when the panel is OK'd. The general idea is to 
 *       have two functions on the plugin - one a simple flag that reports
 *       whether or not the plugin will want to provide a prefs pane. The
 *       second would return some sort of QWidget containing all the prefs
 *       UI. That widget could have slots to be connected up to signals
 *       from the dialog like saveprefs(), defaults(), etc.
 *
 * Open question:
 * What's the relationship between these objects and the plug-ins?
 * Are they fairly disposable, cheap "info" objects, or are they
 * more complete? Should they store any state for the plug-in?
 *
 * Proposed usage: lightweight, no state, info objects. The creation
 * and deletion of these objects has no relationship with the loading and
 * unloading of the plug-in - these objects provide access to the plug-in
 * but do not in any way embody the plugin.
 *
 * Plug-ins should never keep these around. They must be instantiated,
 * set up, and returned by reference to the caller. They may be deleted
 * then, or stored for an indefinite period - the plugin must not care.
 *
 * Another issue:
 * What's the best way to make per-plugin info data availible to this class?
 * virtual method to be overridden like in the current sample below?
 * members initialized by constructor? Members initialized by setter later
 * (I don't like this one)? Virtual static data to be overridden?
 * I'm currently favouring using constructor arguments and const members.
 * This question is mostly about the various action info for import/export
 * plugins.
 *
 * Third issue:
 * Should some of the pure virtual methods below actually have default
 * implementations?
 *
 * Note that the implementation below really creates two quite different
 * kinds of plugins. One for import/export of data which is generally
 * loaded, run, and unloaded. A second for persistent plugins that are loaded
 * (generally when the app starts) and remain resident.
 */

class ScPlugin
{

	/**
	 * @brief ScPlugin provides an interface to ask plugins for information
	 * about themselves.
	 *
	 * Plugins return an instance of a derived class based on ScPlugin when
	 * asked for it by the plugin manager. This class provides general
	 * information about the plugin. It should not generally be inherited
	 * directly by plugins - use one of the provided base classes instead.
	 */
public:

	/** \brief Human readable enumertion of the plugin types */
	// FIXME: duplicated in pluginmanager
        // FIXME: probably not needed when we can just use QMetaObject::inherits() but might simplify things anyway
	enum PluginType {
		Persistent = 4,
		Import = 7,
		Standard = 6,
	};

	/**
	 * @brief ctor, returns a new ScPlugin instance
	 *
	 * @param int iD          Unique plugin ID, usually a static
	 *                        const int defined in the plugin.
	 * @param PluginType type Plugin type code
	 * @param QString name    Name of the plugin as shown in the
	 *                        Start-up dialog and plugin mgr. This is
         *                        the "friendly" human-readable name.
         *                        PluginManager should already know the
         *                        internal name.
	 */
	ScPlugin(int id, PluginType type, QString& name);

	/** @brief Uninteresting dtor */
	virtual ~ScPlugin();

	// Public methods

	// Accessors

protected:
	const int m_id;			// Plugin ID as passed to ctor
	const PluginType m_type;	// Plugin type as passed to ctor
	const QString m_name;		// Plugin name as passed to ctor
};





class ScImportExportPlugin : public ScPlugin
{
	/*
	 * @brief A plug-in that's loaded for data import/export duties
	 *
	 * ScImportExportPlugin describes a plug-in that is loaded on demand
	 * to perform a data import/export task such as importing an SVG
	 * image or exporting a page to EPS format. It'll generally by unloaded
         * after being queried, then loaded on demand when it needs to run.
	 */

public:

	ScImportExportPlugin(int id, PluginType type, QString& name);
	virtual ~ScImportExportPlugin();

	/**
	 * @brief Run the plug-in's main action.
	 *
	 * Run the plug-in's default action. That usually means prompting the user for
	 * a target (file to save as / file to import) then performing the import/export
	 * action the plug-in is written for.
	 *
	 * The plug-in should clean up neatly after this method completes as it may
	 * be immediately unloaded. It should not assume it will be unloaded however
	 * - this method may be called multiple times. Some platforms may
         * also not permit plugins to be unloaded.
	 *
	 * @param QWidget& parent Parent widget to this plugin. Usually the main window.
	 * @param ScribusApp& mainWindow The main application window.
	 * @returns bool True for success.
	 *
	 */
	virtual bool run(QWidget& parent, ScribusApp& mainWindow) = 0;

	/**
	 * @brief Run the plug-in on a target, specified as a string
	 *
	 * This method is essentially the same as the above, except that it takes
	 * an additional argument - a target string. The meaning of this string
	 * is plug-in specific, but in most cases it will refer to a file path
	 * (save target, file to import, etc).
	 *
	 * Nothing stops a plug-in doing funky things like accepting a WebDAV
	 * URI via this argument, assuming it knows how to handle it. The form
	 * of the argument is up to the plugin. Plugins MUST handle invalid
	 * input by returning false (failure).
	 *
	 * @sa ScImportExportPlugin::run()
	 */
	virtual bool runWith(QWidget& parent, ScribusApp& mainWindow, QString target) = 0;

        /**
         * @brief Run the plugin on a QIODevice
         *
         * This method is essentially the same as the above, except that
         * it accepts a QIODevice to work with. This will generally be used
         * for file I/O without the plugin having to know or care where from.
         *
         * A plug-in MUST return false if it cannot support this method or
         * upon failure. A plug-in MUST supply a working version of this method
         * if it accepts runWith(..., QString) on a local file, and should
         * generally implement the former using this method.
         */
	virtual bool runWith(QWidget& parent, ScribusApp& mainWindow, QIODevice& target) = 0;

	/** @brief Return action name
	 *
	 * This method is used to get the name to give the QAction that will be created
	 * for this plug-in. It is usually called when the plug-in is initially loaded.
	 * (the plug-in is often subsequently unloaded until needed).
	 *
	 * Return the name of the action associated with this plug-in.
         *
         * Rather than having these virtual and overriding them, it might be
         * better to make them use const member data initilized in the ctor.
	 *
	 * @returns action name
	 */
	virtual QString actionName() const = 0;
	/** @brief return action key sequence
	 *  @sa scplugin::actionname() */
	virtual QString actionKeySequence() const = 0;
	/** @brief return action menu identifier string
	 *  @sa scplugin::actionname() */
	virtual QString actionMenu() const = 0;
	/** @brief er...
	 *  @sa scplugin::actionname() */
	virtual QString actionMenuAfterName() const = 0;
	/** @brief return true if action should be enabled on startup
	 *  @sa scplugin::actionname() */
	virtual bool actionEnabledOnStartup() const = 0;
};






class ScPersistentPlugin : public ScPlugin
{
	/**
	 * @brief A plug-in that is resident for the lifetime of the app
	 *
	 * ScPersistentPlugin describes a plugin that is to be kept resident
	 * for the lifetime of the app (or until unloaded by a request to
	 * the plug-in manager).
	 *
	 * Such plug-ins have an init method and a cleanup method; they have
	 * no "run" method as such.
	 */
public:
	ScPersistentPlugin(int id, PluginType type, QString& name);
	virtual ~ScPersistentPlugin();

	/**
	 * @brief Initialize the plugin
	 *
	 * This method must initialize the plugin. It is called at plug-in load
	 * time. This method will never be called twice without an intervening
	 * cleanupPlug call.
	 *
	 * It will usually instantiate a class and store the instance in a static
	 * variable in the plugin, letting that class do the work of setup and
	 * integration into the app.
	 *
	 * @param QWidget& parent Parent widget to this plugin. Usually the main window.
	 * @parem ScribusApp& mainWindow The main application window.
	 * @returns bool True for success.
	 */
	virtual bool initPlug(QWidget& parent, ScribusApp& mainWindow) = 0;

	/**
	 * @brief Cleans up the plugin so it can be safely unloaded.
	 *
	 * This method will be called when the plug-in is about to be unloaded,
	 * or if the plug-in manager has been asked to disable the plug-in. This method
	 * will never be called unless initPlug has been called first.
	 *
	 * @returns bool True for success.
	 */
	virtual bool cleanupPlug() = 0;

};

#endif