As part of its startup routine, jEdit's main method calls various methods to load and initialize plugins. This occurs after the application has done the following:
parsed command line options;
started the edit server (unless instructed not to do so by a command line option) and;
loaded application properties, any user-supplied properties, and the application's set of actions that will be available from jEdit's menu bar (as well as the toolbar and keyboard shortcuts);
Plugin loading occurs before jEdit creates any windows or loads any files for editing. It also occurs before jEdit runs any startup scripts.
Plugins are loaded from files with the .jar filename extension located in the jars subdirectories of the jEdit installation and user settings directories (see the section called "The jEdit Settings Directory").
For each JAR archive file it finds, jEdit creates an instance of the JARClassLoader class. This is a jEdit-specific class that implements the Java platform's abstract class ClassLoader. The constructor for the JARClassLoader object does the following:
Reads action definitions from any file named actions.xml in the archive (the file need not be at the top level). See the section called "The Action Catalog".
Parses and loads the contents of any file named dockables.xml in the archive (the file need not be at the top level). This file contains BeanShell code for creating docking or floating windows that will contain the visible components of the plugin. Not all plugins define dockable windows, but those that do need a dockables.xml file. See the section called "The Dockable Definition File".
Loads any properties defined in files ending with the extension .props that are contained in the archive. See the section called "Plugin Properties".
Adds any class file with a name ending with Plugin.class to an internal collection of plugin class names maintained by the JARClassLoader. See the section called "The EditPlugin Class".
Adds to a collection maintained by jEdit a new object of type EditPlugin.JAR. This is a data structure holding the name of the JAR archive file, a reference to the JARClassLoader and a collection, initially empty, of plugins found in the archive file.
Once all JAR files have been examined for the above resources, jEdit initializes all class files whose names end in Plugin.class, as identified in the first pass through the JAR archive. We will call these classes plugin core classes. They provide the principal point of contact between jEdit and the plugin. A plugin core class must extend jEdit's abstract EditPlugin class. Use of a class name ending in Plugin is also required.
For each plugin core class, the initialization routine first checks the plugin's properties to see if it is subject to any dependencies. For example, a plugin may require that the version of the Java runtime environment or of jEdit itself be equal to or above some threshold version. A plugin can also require the presence of another plugin or a particular class from another archive. If any dependency is not satisfied, the loader marks the plugin as "broken" and logs an error message.
If all dependencies are satisfied, a new instance of the plugin core class is created and added to the collection maintained by the appropriate EditPlugin.JAR object. By accessing that object, jEdit can keep track of plugins it has successfully loaded, and call methods or perform routines on them.
After creating and storing the plugin core object, jEdit calls the start() method of the plugin core class. The start() method can perform initialization of the object's data members. Because this method is defined as an empty "no-op" in the EditPlugin abstract class, a plugin need not provide an implementation if no unique initialization is required.
Recall that this abstract class is the base for every plugin core class. Its methods provide for basic interaction between the plugin and jEdit. The class has four methods which are called by jEdit at various times. None of these methods are required to be implemented, but most plugins will override at least one.
public void start(
)
;
The jEdit startup routine calls this method for each loaded plugin. Plugins typically use this method to register information with the EditBus and perform other initialization.
public void stop(
)
;
When jEdit is exiting, it calls this method on each plugin. If a plugin uses or creates 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 you use jEdit's properties API to hold "key-value" type settings for your plugins, no special processing is needed for them, since jEdit loads application properties automatically at startup and writes them to the properties file in the user's settings directory when the application exits. Most plugins find this approach sufficient for saving settings.
public void createMenuItems( | Vector | menuItems) ; |
When a View object is created, it calls this method on each plugin core class to obtain entries to be displayed in the view's Plugins menu. The menuItems parameter is a Vector that accumulates menu items and menus as it is passed from plugin to plugin.
While jEdit does not require a plugin to supply menu items, a plugin's usefulness would be extremely limited without them. The easiest way to provide menu items is to package them as entries in the plugin's property file and implement createMenuItems() with a call to jEdit's GUIUtilities.loadMenu() method. The following code illustrates this approach:
public void createMenuItems(Vector menuItems) { menuItems.addElement(GUIUtilities.loadMenu( "myplugin.menu")); } |
The parameter passed to loadMenu() is the name of a property defined in the plugin's own property file that contains menu data. The form of the property entry is a list of labels that in turn correspond to other property names and ultimately to the actual text for menu items as well as implementation code. We will detail the format of the menu data in the section called "Action Labels and Menu Items"
The GUIUtilities.loadMenuItem() method is also available for plugins that only wish to add a single menu item to the Plugins menu. The parameter names a property that points to label text in the plugin's properties file and implementing code in the plugin's actions.xml file.
public void createOptionPanes( | OptionsDialog | dialog) ; |
This method is called for each plugin during the creation of the Global Options dialog box. To show an option pane, the plugin should define an option pane class and implement createOptionPane() as follows:
dialog.addOptionPane(new MyPluginOptionPane()); |
Plugins can also define more than one option pane, grouped in an "option group".
This class defines two other methods which may be useful to some plugins or for debugging purposes. They are fully implemented in the parent class and used mainly by jEdit's core code.
public String getClassName(
void)
;
This shortcut method returns getClass().getName().
public EditPlugin.JAR getJAR(
void)
;
This method returns the EditPlugin.JAR data object associated with the plugin.