A plug-in that performs a single action. More...

#include <scplugin.h>

Inheritance diagram for ScActionPlugin:

Collaboration diagram for ScActionPlugin:

Classes
struct	ActionInfo

Public Slots
virtual bool	cleanupPlugin ()
	Deactivates the plugin for unloading / program quit. More...

virtual bool	run (ScribusDoc *doc, QString target=QString::null)=0
	Run the plug-in's main action. More...

virtual bool	run (QWidget parent, ScribusDoc doc, QString target=QString::null)
	Run the plug-in's main action. More...

virtual bool	run (ScribusDoc doc, QIODevice target)
	Run the plugin on a QIODevice. More...

virtual DeferredTask *	runAsync (QString target=QString::null)
	Run the plugin asynchronously. More...

virtual DeferredTask *	runAsync (QIODevice *target)
	Run the plugin asynchronously. More...

const QString &	runResult () const
	! Obsolete method - do not use this or rely on it in new code.

Public Member Functions
	ScActionPlugin ()
	ctor More...

virtual	~ScActionPlugin ()=0
	Pure virtual dtor - abstract class.

const ActionInfo &	actionInfo () const

virtual bool	handleSelection (ScribusDoc *doc, int SelectedType=-1)
	handle the documents selection. More...

Public Member Functions inherited from ScPlugin
	ScPlugin ()
	ctor, returns a new ScPlugin instance More...

virtual	~ScPlugin ()=0
	Destroy the ScPlugin instance. More...

virtual const QString	fullTrName () const =0
	Plug-in's human-readable, translated name. More...

virtual bool	newPrefsPanelWidget (QWidget parent, PrefsPanel &panel, QString &caption, QPixmap &icon)
	Create and return a prefs UI panel for the plugin. More...

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

virtual const AboutData *	getAboutData () const =0
	Return descriptive information about the plug-in. More...

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

const QString &	lastError () const
	Text summary of last error encountered. More...

bool	hasLastError () const
	Returns if lastError message is not empty.

void	clearLastError ()
	Clear last error message.

virtual void	languageChange ()=0
	Update all user-visible text to reflect current UI language. More...

const QString	pluginTypeName () const
	Returns human readable plugin type from plug-in's pluginType.

virtual void	addToMainWindowMenu (ScribusMainWindow *)=0
	Allow plugins to add to a main menu.

virtual void	setDoc (ScribusDoc *doc)
	hooks that plugins can use to detect if the current document was closed etc..

virtual void	unsetDoc ()

virtual void	changedDoc (ScribusDoc *doc)

Protected Attributes
ActionInfo	m_actionInfo

QString	m_runResult

ScribusDoc *	m_Doc

Protected Attributes inherited from ScPlugin
QString	m_lastError
	Human readable, translated version of last error to occur.

Detailed Description

A plug-in that performs a single action.

ScActionPlugin describes a plug-in that is used to perform a single well defined action. Uses include data import/export, displaying a dialog, or doing a single batch task. It is automatically connected to the user interface and has simple methods to trigger the plug-in's supported action.

If you need more complex user interface integration, persistent operation, etc, you may be better off with ScPersistentPlugin.

Constructor & Destructor Documentation

ScActionPlugin::ScActionPlugin ( )

ctor

See also: ScPlugin::ScPlugin()

Member Function Documentation

virtual bool ScActionPlugin::cleanupPlugin ( )

inlinevirtualslot

Deactivates the plugin for unloading / program quit.

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 initPlugin has been called first, but there is no guarantee the plugin will actually be unloaded after this is called, or before initPlugin is called again.

Returns: bool True for success.

Reimplemented in PictureBrowserPlugin.

bool ScActionPlugin::handleSelection	(	ScribusDoc *	doc,
		int	SelectedType = `-1`
	)

virtual

handle the documents selection.

This function is dedicated for handling the documents selection By default this uses the notSuitableFor, forAppMode, needsNumObjects, firstObjectType and secondObjectType variables. If you need more control over the selection reimplement this function.

Returns: bool true when the Action should be enabled.

Reimplemented in PathAlongPathPlugin.

virtual bool ScActionPlugin::run	(	ScribusDoc *	doc,
		QString	target = `QString::null`
	)

pure virtualslot

Run the plug-in's main action.

Run the plug-in's default action synchronously, blocking the rest of the application until this method returns.

This method should generally call run(..., QIODevice* target) or run(..., QString target) to do the work. This is done by default, with the assumption that the target is a file. The argument is opened as QFile with IO_ReadOnly or IO_WriteOnly mode, depending on plugin type, and passed to run(..., QIODevice*). Override this if you need more flexibility.

The optional target argument is a plugin-defined string indicating what the plugin should operate on. It will typically be a filename to import from / export to. Nothing stops a plugin doing funky things like accepting a WebDAV URI, etc, however.

Plug-in authors might want to consider implementing this using the DeferredTask subclass used in runAsync, if the plug-in supports it.

Parameters

target Optional target to operate on (see above)

Returns: bool True for success.

Implemented in PathAlongPathPlugin, PathConnectPlugin, XPSExportPlugin, MeshDistortionPlugin, PathFinderPlugin, SVGExportPlugin, LensEffectsPlugin, PathCutPlugin, PathStrokerPlugin, SubdividePlugin, FlattenPathPlugin, SmoothPathPlugin, ImpositionPlugin, ColorWheelPlugin, ShortWordsPlugin, PictureBrowserPlugin, Barcode, PixmapExportPlugin, MyPlugin, HunspellPlugin, AspellPlugin, NewFromTemplatePlugin, FontPreviewPlugin, and SaveAsTemplatePlugin.

bool ScActionPlugin::run	(	QWidget *	parent,
		ScribusDoc *	doc,
		QString	target = `QString::null`
	)

virtualslot

Run the plug-in's main action.

This method behaves as the previous one. Except there is a parent widget reference. It's useful e.g. when you need to open a dialog on a specific parent one.

Reimplemented in ImpositionPlugin, HunspellPlugin, and FontPreviewPlugin.

bool ScActionPlugin::run	(	ScribusDoc *	doc,
		QIODevice *	target
	)

virtualslot

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.

Remember that not all QIODevice*s are seekable, and try to write your code to handle a non-seekable stream.

DeferredTask * ScActionPlugin::runAsync ( QString target = QString::null )

virtualslot

Run the plugin asynchronously.

This call is similar to the one above, but instead of doing all the work in one big batch, it creates an instance of a DeferredTask subclass to keep track of the job, does some setup, and returns immediately. The DeferredTask, a pointer to which is returned, has already been started when this method returns.

The caller of this method is responsible for handling the aborted() and finished() signals from the DeferredTask, and (if necessary) for cleaning it up using deleteLater(...) once it has finished. Remember that a DeferredTask is automatically deleted when its parent is, if it hasn't already been deleted. This approach is preferred where possible.

See the DeferredTask documentation for details on how it works.

If your plugin implementation does not support asynchronous operation, you must return null. This is the default implementation, so simply ignore this method unless you wish to support it. It is recommended that all new plugins support this interface where possible, even if they can only do part of their work progressively.

If you implement this, you may want to implement run(...) using the same deferred operation and a modal dialog. That'll permit the event loop to continue running for redraws, permit you to update the progress bar, etc.

NOTE: In current Scribus code (August 2005), callers of this method will generally create a modal dialog - possibly with progress meter

then attach signals from the DeferredTask, and exec() the dialog. A caller is not required to do this, but with the current (August 2005) core code it's the only way to operate safely. This is likely to change in future and you should avoid relying on it if at all posssible.

If this method is used, the plugin must not be unloaded until all DeferredTask instances have been deleted.

DeferredTask * ScActionPlugin::runAsync ( QIODevice * target )

virtualslot

Run the plugin asynchronously.

This method is much the same as the above, but takes a QIODevice* as the target. Please see the documentation for run(..., QIODevice* target) and runAsync(..., QString target) for details.

The documentation for this class was generated from the following files:

/Users/ale/src/Scribus/scribus/scplugin.h
/Users/ale/src/Scribus/scribus/scplugin.cpp

Classes

Public Slots

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation