 |
Scribus
Open source desktop publishing at your fingertips
|
|
Scribus
Open source desktop publishing at your fingertips
|
Abstract super class for all Scribus plug-ins. More...
#include <scplugin.h>
Classes | |
| struct | AboutData |
| ScPlugin provides an interface to ask plugins for information about themselves. More... | |
Public Member Functions | |
| 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 | |
| QString | m_lastError |
| Human readable, translated version of last error to occur. | |
Abstract super class for all Scribus plug-ins.
ScPlugin is a class that provides information about a plug-in, and a gateway into any plugin-specific functionality. It should not generally be inherited directly by actual plugin implementations - use one of the provided base classes instead. See below for info on the creation of new types of plugin.
Plugins create and return a instance of a subclass of ScPlugin when asked for it by the plugin manager. The plugin manager is responsible for tracking these instances. The ScPlugin instance is used by the plugin manager for tasks such as hooking the plugin up to the UI where appropriate. It's also used by other code that talks to plugins, usually by dynamic_cast<>ing it to a more specific subclass and working with that. The file loader system will provide an example of this.
A given plugin implementation's ScPlugin subclass is not the best place to implement the bulk of the plugin's functionality. It must be lightweight and maintain as little state as possible. Most functionality should be implemented in a private subclass that is not exposed in the header of the scplugin subclass defined by the plugin. That helps keep the plugin's implementation separate from its inteface to Scribus.
Note that the two subclases ScActionPlugin and ScPersistentPlugin, defined below, create two quite different kinds of plugins. One is for import/export of data and for single function actions (like providing a particular dialog or function) which generally do nothing when not in active use. A second for persistent plugins that are loaded (generally when the app starts) and remain resident, possibly active in the background or hooked into many parts of the user interface.
More plugin classes - such as plugins for text import and document import
New types of plugin can be created by subclassing ScPlugin or one of its subclasses and adding the additional interfaces required. The two existing subclasses provide examples of how this can work. Of course, once you have the plugin interface, you still need to actually use the plugins. You'll need to extend pluginmanager.cpp a little to handle any low-level init required by the new plugin type (please keep this minimal!). You'll then need to extend the appropriate classes to make use of the new plugin type where required. The new file loader mechanism will provide a good example of this.
In addition to the API described here, a plugin is expected to implement the following "extern C" functions, where 'pluginname' is the base name of the plug-in (where the filename is libpluginname.so on UNIX):
int pluginname_getPluginAPIVersion(); Return an integer indicating the plug-in API version implemented. If the version does not exactly match the running plugin API version, the plugin will not be initialised.
ScPlugin* pluginname_getPlugin(); Create and return an instance of the plug-ins ScPlugin subclass. Nothing should be done here that's overly slow or uses much memory, and the plugin should not initialize its self here beyond what is required to return a ScPlugin instance.
void pluginname_freePlugin(ScPlugin* plugin); Free the scplugin instance returned earlier.
TODO: better discovery of what plug-ins can import / export what formats, file exts, names, etc.
| ScPlugin::ScPlugin | ( | ) |
ctor, returns a new ScPlugin instance
Only pluginname_getPlugin(...) may call this. Calls by other code will have undefined results.
|
pure virtual |
Destroy the ScPlugin instance.
Pure virtual destructor - this is an abstract class.
Only pluginname_freePlugin(...) may call this. Calls by other code will have undefined results.
|
pure virtual |
Plug-in's human-readable, translated name.
Please don't use this for anything except display to the user. The results of testing the value of this can not be guaranteed, as its value may change depending on locale and change at runtime.
Implemented in PathAlongPathPlugin, PathConnectPlugin, XPSExportPlugin, MeshDistortionPlugin, PathFinderPlugin, SVGExportPlugin, LensEffectsPlugin, PathCutPlugin, PathStrokerPlugin, SubdividePlugin, Scribus150Format, ImportIdmlPlugin, ImportOdgPlugin, ImportPagesPlugin, ImportVivaPlugin, ImportXpsPlugin, FlattenPathPlugin, SmoothPathPlugin, Scribus134Format, ImpositionPlugin, ImportCgmPlugin, ImportDrwPlugin, SVGImportPlugin, ImportEmfPlugin, ImportSvmPlugin, Scribus12Format, ImportIdml, ScriptPlugin, ColorWheelPlugin, ShapePlugin, ShortWordsPlugin, Scribus13Format, ImportAIPlugin, ImportCdrPlugin, ImportCvgPlugin, ImportFhPlugin, OODrawImportPlugin, ImportPctPlugin, ImportPdfPlugin, ImportPmPlugin, ImportPSPlugin, ImportPubPlugin, ImportShapePlugin, ImportSmlPlugin, ImportVsdPlugin, ImportWpgPlugin, ImportXarPlugin, ImportXfigPlugin, UniconvImportPlugin, PictureBrowserPlugin, Barcode, WMFImportPlugin, HunspellPlugin, PixmapExportPlugin, MyPlugin, AspellPlugin, NewFromTemplatePlugin, FontPreviewPlugin, SaveAsTemplatePlugin, Scripter, and OldScribusFormat.
|
pure virtual |
Return descriptive information about the plug-in.
Returns a structure containing descriptive information about the plug-in. This information is used in places like the Help->About Plug-ins menu item. The stucture MUST be deleted using deleteAboutData(AboutData* about) when finished with.
Every plugin MUST reimplement getAboutData(...) and deleteAboutData(...).
Implemented in PathAlongPathPlugin, PathConnectPlugin, XPSExportPlugin, MeshDistortionPlugin, PathFinderPlugin, SVGExportPlugin, LensEffectsPlugin, PathCutPlugin, PathStrokerPlugin, SubdividePlugin, Scribus150Format, ImportIdmlPlugin, ImportOdgPlugin, ImportPagesPlugin, ImportVivaPlugin, ImportXpsPlugin, FlattenPathPlugin, SmoothPathPlugin, Scribus134Format, ImpositionPlugin, ImportCgmPlugin, ImportDrwPlugin, SVGImportPlugin, ImportEmfPlugin, ImportSvmPlugin, Scribus12Format, ImportIdml, ScriptPlugin, ColorWheelPlugin, ShapePlugin, ShortWordsPlugin, Scribus13Format, ImportAIPlugin, ImportCdrPlugin, ImportCvgPlugin, ImportFhPlugin, OODrawImportPlugin, ImportPctPlugin, ImportPdfPlugin, ImportPmPlugin, ImportPSPlugin, ImportPubPlugin, ImportShapePlugin, ImportSmlPlugin, ImportVsdPlugin, ImportWpgPlugin, ImportXarPlugin, ImportXfigPlugin, UniconvImportPlugin, PictureBrowserPlugin, Barcode, WMFImportPlugin, HunspellPlugin, PixmapExportPlugin, MyPlugin, AspellPlugin, NewFromTemplatePlugin, FontPreviewPlugin, SaveAsTemplatePlugin, Scripter, and OldScribusFormat.
|
pure virtual |
Update all user-visible text to reflect current UI language.
Updates the text on all widgets on the plug-in to reflect the new language. You should generally use this method to set all the widget text during construction. That ensures that text is not duplicated, and that when this method is called the text of all persistent widgets is correctly changed.
This method only needs to affect text in widgets that currently exists (displayed or otherwise).
Implemented in PathAlongPathPlugin, PathConnectPlugin, XPSExportPlugin, MeshDistortionPlugin, PathFinderPlugin, SVGExportPlugin, LensEffectsPlugin, PathCutPlugin, PathStrokerPlugin, SubdividePlugin, Scribus150Format, ImportIdmlPlugin, ImportOdgPlugin, ImportPagesPlugin, ImportVivaPlugin, ImportXpsPlugin, FlattenPathPlugin, SmoothPathPlugin, Scribus134Format, ImportCgmPlugin, ImportDrwPlugin, SVGImportPlugin, ImpositionPlugin, ImportEmfPlugin, ImportSvmPlugin, Scribus12Format, ImportIdml, ScriptPlugin, ColorWheelPlugin, ShapePlugin, ShortWordsPlugin, Scribus13Format, ImportAIPlugin, ImportCdrPlugin, ImportCvgPlugin, ImportFhPlugin, OODrawImportPlugin, ImportPctPlugin, ImportPdfPlugin, ImportPmPlugin, ImportPSPlugin, ImportPubPlugin, ImportShapePlugin, ImportSmlPlugin, ImportVsdPlugin, ImportWpgPlugin, ImportXarPlugin, ImportXfigPlugin, UniconvImportPlugin, PictureBrowserPlugin, Barcode, WMFImportPlugin, HunspellPlugin, PixmapExportPlugin, MyPlugin, AspellPlugin, NewFromTemplatePlugin, FontPreviewPlugin, SaveAsTemplatePlugin, Scripter, and OldScribusFormat.
| const QString & ScPlugin::lastError | ( | ) | const |
Text summary of last error encountered.
Return the human readable, translated text of last error to be encountered by this plugin. DO NOT ATTEMPT TO USE THIS VALUE TO MAKE DECISIONS IN PROGRAM CODE. The value returned for a given error may change depending on locale, and may change at runtime.
|
virtual |
Create and return a prefs UI panel for the plugin.
Override this method if you want to provide a panel for the preferences dialog.
The caller takes ownership of the panel. Qt is responsible for deleting it when it's parent is deleted. `parent' must be the dialog the widget will be added to or a child of it, otherwise the panel won't be deleted correctly when the dialog is.
See prefspanel.h for info on implementing the panel.
This method must return false (the default) if the plugin does not provide a prefs panel. If true is returned, caption, panel, and icon MUST have been assigned.
| parent | Parent widget, to be passed to panel ctor |
| panel | (out) the panel created |
| caption | (out) caption for icon in panel list |
| icon | (out) icon for use in panel list |
By default, returns 0 to indicate no prefs UI.
Reimplemented in ShortWordsPlugin, and ScriptPlugin.
1.8.9.1 
