Chapter 17. Introducing the Plugin API

The jEdit Plugin API provides a framework for
hosting plugin applications without imposing any requirements on the design
or function of the plugin itself. You could write an application that
performs spell checking, displays a clock or plays chess and turn it into a
jEdit plugin. There are currently over 50 released plugins for jEdit. While
none of them play chess, they perform a wide variety of editing and file
management tasks.

Using the “Plugin Manager” feature of jEdit, users with
an Internet connection can check for new or updated plugins and install and
remove them without leaving jEdit. See Chapter 9, Installing and Using Plugins for
details.

Requirements for “plugging in” to jEdit are as
follows:

This plugin must supply information about itself, such as its
name, version, author, and compatibility with versions of
jEdit.

The plugin must provide for activating, displaying and
deactivating itself upon direction from jEdit, typically in response
to user input[2]. Make sure you can continue to use both your plugin
and the editor after it has been reloaded.

Each Plugin has an ActionSet defined by jEdit, which is added
to the main ActionContext. The ActionSet is a container for
EditAction instances. The plugin may define
actions in a number of ways. One way is
explicitly, with an action definition file known as
actions.xml. Another is implicitly, by defining
dockable windows in dockables.xml.

Most EditActions are small blocks of BeanShell code that jEdit
will perform on behalf of the plugin upon user request. They provide
the “glue” between user input and specific plugin
routines.

By convention, plugins display their available actions in
submenus of jEdit's Plugins menu; each menu item
corresponds to an action. Plugin authors do not define specific
shortcuts - the user can/will assign EditActions to keyboard
shortcuts, toolbar buttons, or entries in the text area's Context
menu (right-click menu).

The plugin may, but need not, provide a user interface.

If the plugin has a visible interface, it can be shown in any
object derived from one of Java top-level container classes:
JWindow, JDialog, or
JFrame. jEdit also provides a dockable window
API, which allows plugin windows derived from the
JComponent class to be docked into views or
shown in top-level frames, at the user's request.

Plugins can also act directly upon jEdit's text area. They can
add graphical elements to the text display (like error highlighting
in the case of the ErrorList plugin) or
decorations surrounding the text area (like the
JDiff plugin's summary views). These
plugins are dependent on the JEditTextArea class, which is currently
getting refactored.

Plugins may provide a range of options that the user can
modify to alter their configuration.

If a plugin provides configuration options in accordance with
the plugin API, jEdit will make them available in the
Global Options dialog box.

While it is not required, plugins are encouraged to provide
documentation.

As noted, many of these features are optional; it is possible to write
a plugin that does not provide actions, configuration options, or dockable
windows. The majority of plugins, however, provide most of these
services.

Plugins and different jEdit versions

As jEdit continues to evolve and improve, elements of the API may
change with a new jEdit release.

On occasion an API change will break code used by plugins,
although efforts are made to maintain or deprecate plugin-related code
on a transitional basis. While the majority of plugins are unaffected by
most changes and will continue working, it is a good idea to monitor the
jEdit change log, and join the jedit-devel mailing list, to keep updated on changes and bug reports, so that you will know when your
plugin needs to be updated.

[2] You should test your plugin by loading and unloading
it from both the Plugin Manager, as well as the Activator Plugin.