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 java.lang.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 is loaded like an old-style jEdit 4.1 plugin.
• 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.

The following properties are optional but recommended:

• plugin.className.author
• plugin.className.docs - the path to plugin documentation in HTML format within the JAR file.

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. 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.01.00.
• pluginClassName pluginVersion - the fully quailified plugin class name with package must be specified.
• optional 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.

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:

plugin.QuickNotepadPlugin.activate=defer
plugin.QuickNotepadPlugin.name=QuickNotepad
plugin.QuickNotepadPlugin.author=John Gellene
plugin.QuickNotepadPlugin.version=4.2
plugin.QuickNotepadPlugin.docs=QuickNotepad.html
plugin.QuickNotepadPlugin.depend.0=jedit 04.02.01.00
plugin.QuickNotepadPlugin.menu=quicknotepad \
    - \
    quicknotepad.choose-file \
    quicknotepad.save-file \
    quicknotepad.copy-to-buffer
plugin.QuickNotepadPlugin.option-pane=quicknotepad

 plugin.QuickNotepadPlugin.option-pane=quicknotepad
 options.quicknotepad.code=new QuickNotepadOptionPane();
 options.quicknotepad.label=QuickNotepad
 options.quicknotepad.file=File:
 options.quicknotepad.choose-file=Choose
 options.quicknotepad.choose-file.title=Choose a notepad file
 options.quicknotepad.choose-font=Font:
 options.quicknotepad.show-filepath.title=Display notepad file path

Note that action and option pane labels are not shown in the above example.

Since:

jEdit 2.1pre1

See Also:

jEdit.getProperty(String), jEdit.getPlugin(String), jEdit.getPlugins(), jEdit.getPluginJAR(String), jEdit.getPluginJARs(), jEdit.addPluginJAR(String), jEdit.removePluginJAR(PluginJAR,boolean), ActionSet, DockableWindowManager, OptionPane, PluginJAR, ServiceManager

Nested Class Summary

static class	EditPlugin.Broken A placeholder for a plugin that didn't load.
static class	EditPlugin.Deferred A placeholder for a plugin that hasn't been loaded yet.

Constructor Summary

EditPlugin()


Method Summary

javax.swing.JMenuItem	createBrowserMenuItems() Called by the filesystem browser when constructing its Plugins menu.
javax.swing.JMenuItem	createMenuItems() Called by the view when constructing its Plugins menu.
void	createMenuItems(java.util.Vector menuItems) Deprecated. Instead of overriding this method, define properties as specified in the description of this class.
void	createOptionPanes(OptionsDialog optionsDialog) Deprecated. Instead of overriding this method, define properties as specified in the description of this class.
java.lang.String	getClassName() Returns the plugin's class name.
PluginJAR	getPluginJAR() Returns the JAR file containing this plugin.
void	start() jEdit calls this method when the plugin is being activated, either during startup or at any other time.
void	stop() jEdit calls this method when the plugin is being unloaded.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EditPlugin

public EditPlugin()

Method Detail

start

public void start()

jEdit calls this method when the plugin is being activated, either during startup or at any other time. A plugin can get activated for a number of reasons:

• The plugin is written for jEdit 4.1 or older, in which case it will always be loaded at startup.
• The plugin has its activate property set to startup, in which case it will always be loaded at startup.
• One of the properties listed in the plugin's activate property is set to true, in which case it will always be loaded at startup.
• One of the plugin's classes is being accessed by another plugin, a macro, or a BeanShell snippet in a plugin API XML file.

Note that this method is always called from the event dispatch thread, even if the activation resulted from a class being loaded from another thread. A side effect of this is that some of your plugin's code might get executed before this method finishes running.

When this method is being called for plugins written for jEdit 4.1 and below, no views or buffers are open. However, this is not the case for plugins using the new API. For example, if your plugin adds tool bars to views, make sure you correctly handle the case where views are already open when the plugin is loaded.

If your plugin must be loaded on startup, take care to have this method return as quickly as possible.

The default implementation of this method does nothing.

Since:

jEdit 2.1pre1

stop

public void stop()

jEdit calls this method when the plugin is being unloaded. This can be when the program is exiting, or at any other time.

If a plugin uses state information or other persistent data that should be stored in a special format, this would be a good place to write the data to storage. If the plugin uses jEdit's properties API to hold settings, no special processing is needed for them on exit, since they will be saved automatically.

With plugins written for jEdit 4.1 and below, this method is only called when the program is exiting. However, this is not the case for plugins using the new API. For example, if your plugin adds tool bars to views, make sure you correctly handle the case where views are still open when the plugin is unloaded.

To avoid memory leaks, this method should ensure that no references to any objects created by this plugin remain in the heap. In the case of actions, dockable windows and services, jEdit ensures this automatically. For other objects, your plugin must clean up maually.

The default implementation of this method does nothing.

Since:

jEdit 2.1pre1

getClassName

public java.lang.String getClassName()

Returns the plugin's class name. This might not be the same as the class of the actual EditPlugin instance, for example if the plugin is not loaded yet.

Since:

jEdit 2.5pre3

getPluginJAR

public PluginJAR getPluginJAR()

Returns the JAR file containing this plugin.

Since:

jEdit 4.2pre1

createMenuItems

public final javax.swing.JMenuItem createMenuItems()

Called by the view when constructing its Plugins menu. See the description of this class for details about how the menu items are constructed from plugin properties.

Since:

jEdit 4.2pre1

createBrowserMenuItems

public final javax.swing.JMenuItem createBrowserMenuItems()

Called by the filesystem browser when constructing its Plugins menu. See the description of this class for details about how the menu items are constructed from plugin properties.

Since:

jEdit 4.2pre1

createMenuItems

public void createMenuItems(java.util.Vector menuItems)

Deprecated. Instead of overriding this method, define properties as specified in the description of this class.

createOptionPanes

public void createOptionPanes(OptionsDialog optionsDialog)

Deprecated. Instead of overriding this method, define properties as specified in the description of this class.