The dockables.xml Window Catalog

A Dockable is a window that can float like a dialog, or dock into jEdit's docking area. Each dockable needs a label (for display in menus, and on small buttons) and a title (for display in the floating window's title bar).

The jEdit API uses BeanShell to create the top-level visible container of a plugin's interface. The BeanShell code is contained in a file named dockables.xml. It usually is quite short, providing only a single BeanShell expression used to create a visible plugin window.

The following example from the QuickNotepad plugin illustrates the requirements of the data file:

<?xml version="1.0"?>

<!DOCTYPE DOCKABLES SYSTEM "dockables.dtd">

<DOCKABLES>
	<DOCKABLE NAME="quicknotepad">
		new QuickNotepad(view, position);
	</DOCKABLE>
</DOCKABLES>

In this example, the <DOCKABLE> element has a single attribute, the dockable window's identifier. This attribute is used to key a property where the window title is stored; see the section called “The Property Files”.

For each dockable, jedit defines an action with the same name. This means you do not need to define an explicit action to create your dockable - in fact, jEdit defines three actions: "toggle", "get" and "new floating instance" for each.

The contents of the <DOCKABLE> element itself is a BeanShell expression that constructs a new QuickNotepad object. The view and position are predefined by the plugin API as the view in which the plugin window will reside, and the docking position of the plugin. You can use position to customize the layout of your plugin depending on whether it appears on the sides, or the top/bottom, or as a floating dockable.

A formal description of each element of the dockables.xml file can be found in the documentation of the DockableWindowManager class. This class also contains the public interface you should use for getting, showing, hiding, and other interactions with the plugin's top-level windows.

jEdit's dockables

jEdit has its own dockables.xml file that you can inspect to see how jEdit creates its own dockables.