Module jEdit
Package org.gjt.sp.jedit

Class EditPlugin

java.lang.Object
org.gjt.sp.jedit.EditPlugin
Direct Known Subclasses:
EBPlugin, EditPlugin.Broken, EditPlugin.Deferred
public abstract class EditPlugin extends Object
The abstract base class that every plugin must implement. Alternatively, instead of extending this class, a plugin core class can extend EBPlugin to automatically receive EditBus messages.

Basic plugin information properties

Note that in all cases above where a className is needed, the fully qualified class name, including the package name, if any, must be used.

The following properties are required for jEdit to load the plugin:

  • plugin.className.activate - set this to defer if your plugin only needs to be loaded when it is first invoked; set it to startup if your plugin must be loaded at startup regardless; set it to a whitespace-separated list of property names if your plugin should be loaded if at least one of these properties is set. Note that if this property is not set, the plugin will not work with jEdit 4.3final.
  • plugin.className.name
  • plugin.className.version
  • plugin.className.jars - only needed if your plugin bundles external JAR files. Contains a whitespace-separated list of JAR file names. Without this property, the plugin manager will leave behind the external JAR files when removing the plugin.
  • plugin.className.files - only needed if your plugin bundles external files like libraries which MUST reside in the local filesystem. Contains a whitespace-separated list of file names. Without this property, the plugin manager will leave behind the external files when removing the plugin.
  • plugin.className.description - the short description associated with the plugin. The short description is used by the Plugin Manager and on the list pages on Plugin Central.
The following properties are optional but recommended:
  • plugin.className.author
  • plugin.className.usePluginHome - whether the plugin uses the EditPlugin.getPluginHome API or not. Even if the plugin doesn't store any data, this property should be set so that the plugin manager can tell that there is no data stored.
  • plugin.className.docs - the path to plugin documentation in HTML format.
  • plugin.className.longdescription - the path to the long description in XHTML (no fancy stuff here, please - just proper XHTML subset with the basic tags: html, h1, h2, p, li, ul, ol, a, b, i, u, br)

    The long description is extracted from the plugin at various times, primarily at plugin packaging time to update the data on the plugin detail pages of Plugin Central.

    If this property is left out, the default will be to look in a file called <description.html>.

For the previous two properties, if a relative path is supplied, it should be both

  1. relative to the location of the .props file (when it is in the source tree)
  2. relative to the root of the JAR (when it is packaged in the JAR file)

Both conditions are easily satisfied if the .props file as well as description.html are both located in the root directory of the plugin, as well as the generated JAR.

Plugin dependency properties

Plugin dependencies are also specified using properties. Each dependency is defined in a property named with plugin.className.depend. followed by a number. Dependencies must be numbered in order, starting from zero. This determines the order that dependent plugins get loaded and activated, so order is very important.

The value of a dependency property has one of the following forms:

  • jdk minimumJavaVersion
  • jedit minimumjEditVersion - note that this must be a version number in the form returned by jEdit.getBuild(), not jEdit.getVersion(). Note that the documentation here describes the jEdit 4.2 plugin API, so this dependency must be set to at least 04.02.99.00 (4.2final).
  • pluginClassName pluginVersion - the fully quailified plugin class name with package must be specified.
  • optional plugin pluginClassName pluginVersion - an optional dependency, indicating that the plugin will work without it, but that the dependency should be loaded before this plugin.

In this example, the ProjectViewer plugin is an optional dependency of the Console, beacause the Console only listens to events from the ProjectViewer. It requires Jedit 4.2 final. 

plugin.console.ConsolePlugin.depend.0=jedit 04.02.99.00
plugin.console.ConsolePlugin.depend.1=jdk 1.5
plugin.console.ConsolePlugin.depend.2=plugin errorlist.ErrorListPlugin 1.4
plugin.console.ConsolePlugin.depend.3=optional plugin projectviewer.ProjectPlugin 2.1.0.92

Plugin menu item properties

To add your plugin to the view's Plugins menu, define one of these two properties:

  • plugin.className.menu-item - if this is defined, the action named by this property is added to the Plugins menu.
  • plugin.className.menu - if this is defined, a sub-menu is added to the Plugins menu whose content is the whitespace-separated list of action names in this property. A separator may be added to the sub-menu by listing - in the property.

If you want the plugin's menu items to be determined at runtime, define a property plugin.className.menu.code to be BeanShell code that evaluates to an implementation of DynamicMenuProvider.

To add your plugin to the file system browser's Plugins menu, define one of these two properties:

  • plugin.className.browser-menu-item - if this is defined, the action named by this property is added to the Plugins menu.
  • plugin.className.browser-menu - if this is defined, a sub-menu is added to the Plugins menu whose content is the whitespace-separated list of action names in this property. A separator may be added to the sub-menu by listing - in the property.

Again, if the browser menu items need to be determined at runtime, define a property plugin.className.browser-menu.code to be BeanShell code that evaluates to an implementation of DynamicMenuProvider.

In all cases, each action's menu item label is taken from the actionName.label property. View actions are defined in an actions.xml file, file system browser actions are defined in a browser.actions.xml file; see ActionSet.

Plugin option pane properties

To add your plugin to the Plugin Options dialog box, define one of these two properties:

  • plugin.className.option-pane=paneName - if this is defined, a single option pane with this name is added to the Plugin Options menu.
  • plugin.className.option-group=paneName1 [paneName2 paneName3 ...] - if this is defined, a branch node is added to the Plugin Options dialog box whose content is the whitespace-separated list of paneNames in this property.
Then for each option paneName, define these two properties:
  • options.paneName.label - the label to show for the pane in the dialog box.
  • options.paneName.code - BeanShell code that evaluates to an instance of the OptionPane class.

Example

Here is an example set of plugin properties: 
# jEdit only needs to load the plugin the first time the user accesses it
# the presence of this property also tells jEdit the plugin is using the new API
plugin.QuickNotepadPlugin.activate=defer
plugin.QuickNotepadPlugin.name=QuickNotepad
plugin.QuickNotepadPlugin.author=John Gellene
plugin.QuickNotepadPlugin.usePluginHome=true
plugin.QuickNotepadPlugin.version=4.5
plugin.QuickNotepadPlugin.docs=index.html
# see jEdit.getBuild() to understand jEdit's version convention:
plugin.QuickNotepadPlugin.depend.0=jedit 04.05.99.00
plugin.QuickNotepadPlugin.depend.1=jdk 1.7
plugin.QuickNotepadPlugin.description=This plugin provides a dockable "scratch pad" for writing and displaying notes, to do lists or similar items as unformatted text.
# plugin menu
plugin.QuickNotepadPlugin.menu=quicknotepad \
        - \
        quicknotepad.choose-file \
        quicknotepad.save-file \
        quicknotepad.copy-to-buffer

quicknotepad.label=QuickNotepad
plugin.QuickNotepadPlugin.option-pane=quicknotepad
options.quicknotepad.code=new QuickNotepadOptionPane();
options.quicknotepad.label=QuickNotepad
Note that action and option pane labels are not shown in the above example.
Since:
jEdit 2.1pre1
Author:
Slava Pestov, John Gellene (API documentation), Alan Ezust (API documentation)
See Also: