Modifying plugins for jEdit 4.0
Submitted by Monday, 12 November, 2001 - 07:10on
- Under jEdit 3.2.2 and prior versions, the QuickNotepad plugin had a separate class, QuickNotepadDockable, implementing the DockableWindow interface. The class's methods delegated actions to the plugin's top-level visible component, a class derived from JPanel called QuickNotepad. The DockableWindow interface is deprecated in jEdit 4.0, so this class was eliminated. If the top-level component had implemented the DockableWindow interface, it would have been necessary to remove the implements statement and eliminate the getName() and getComponent() methods of that in the plugin class (unless, of course, the plugin itself requires them).
- A new file, dockables.xml, was created containing XML markup for the constructor of a plugin component. Under the new plugin API, this file is read to determine the method call or calls for construcuting a new instance of a dockable plugin component. The file is quite short:
<!DOCTYPE DOCKABLES SYSTEM "dockables.dtd">
<!-- QuickNotepad dockable window -->
new QuickNotepad(view, position);
The parameters are those found in the existing version of the QuickNotepadconstructor. Both view and position are defined by the new plugin API in the namespace in which the constructor is called. The value of position is taken from optional properties set by the user. In the absence of a user setting, the position parameter is set to place the plugin component in a floating window.
The NAME attribute is taken to conform to the value of the static variable QuickNotepadPlugin.NAME, which is also used to identify the plugin in the user action code contained in actions.xml.
By default, the plugin API adds two actions for a plugin. The first is entitled [name of plugin] (in this case, quicknotepad), and simply activates the plugin by executing the code contained in the DOCKABLE element. The second action toggles the plugin's visible component, the title of the action is [name of plugin]-toggle (in this case, quicknotepad-toggle). The plugin API handles this action internally.
To prevent these actions from being created, you can add a NO_ACTIONS="true" attribute to the DOCKABLE element. The NAME and NO_ACTIONS attributes are the only attributes defined for a DOCKABLE entry. A NAME is required; NO_ACTIONS is set to "false" by default.
- In the actions.xml file, the user action definitions were revised to call DockableWindowManager.getDockable() instead of DockableManager.getDockableWindow(). In addition, the actions for toggling the plugin docking window and bringing the QuickNotepad window to the foreground were eliminated. The toggle action was duplicative of the built-in action supplied through dockables.xml, and the "bring to front" action had become redundant.
- There were two deletions made in QuickNotepadPlugin, the main plugin class.
The handleMessage() method was eliminated because it was only necessary for the plugin to listen for the CreateDockableWindow message. As a result, it is no longer necessary for this plugin to connect to the EditBus, so its derivation was changed from EBPlugin to EditPlugin. Individual instances of the QuickNotepad class still need to listen for a PropertiesChanged message, so that class continues to implement EBComponent.
In addition, since the EditBus no longer maintains an active list of windows, the call to EditBus.addToNamedList() is no longer needed in the class's start() method and so was eliminated, leaving an empty start() method.
- No changes were required in the option pane class, QuickNotepadOptionsPane, or the other other classes defining components of the plugin.
- Finally, several changes were made to the properties file of the plugin, QuickNotepad.props. First, the plugin's dependency properties were changed to make the plugin dependent upon version 4.0 or greater of jEdit:
Next, the "label" properties for the docking window and plugin menu were reorganized into two categories: labels for action created by dockable.xml (quicknotepad.label and quicknotepad-toggle.label), and labels for actions created by actions.xml (the remaining user actions: "choose-file", "save-file" and "copy-to-buffer").
The plugin was built using the standard build.xml supplied for plugins, after checking to make sure that the name of the plugin and the location of jedit.jar were correct. It was also necessary to add dockables.xml to the list of files to be archived by the jar utility. Iterations of the build process helped to uncover deprecated API elements.
The help file was built from DocBook XML source using xsltproc. The build.xml Ant build file and the users-guide.xsl customization file contain annotations which may be helpful in building plugin documentation. In particular, a few <indexterm> tags were added to the documentation source to provide references for the index to be generated for all plugin files.
These changes should be made to all current plugins. Most of them will then only require recompilation. The few plugins requiring more will announce themselves when they are compiled against the jEdit 4.0 codebase.