alvinalexander.com | career | drupal | java | mac | mysql | perl | scala | uml | unix  

What this is

This file is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" TM.

Other links

The source code

/*
 * EditPlugin.java - Abstract class all plugins must implement
 * :tabSize=8:indentSize=8:noTabs=false:
 * :folding=explicit:collapseFolds=1:
 *
 * Copyright (C) 1999, 2003 Slava Pestov
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */

package org.gjt.sp.jedit;

import javax.swing.JMenuItem;
import java.util.*;
import org.gjt.sp.jedit.browser.VFSBrowser;
import org.gjt.sp.jedit.gui.OptionsDialog;
import org.gjt.sp.jedit.menu.EnhancedMenu;

/**
 * The abstract base class that every plugin must implement.
 * Alternatively, instead of extending this class, a plugin core class can
 * extend {@link EBPlugin} to automatically receive EditBus messages.
 *
 * 

Basic plugin information properties

* * Note that in all cases above where a class name 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.class name.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.class name.name
  • *
  • plugin.class name.version
  • *
  • plugin.class name.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.class name.author
  • *
  • plugin.class name.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.class name.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 minimum Java version
  • *
  • jedit minimum jEdit version - note that this must be * a version number in the form returned by {@link jEdit#getBuild()}, * not {@link 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.
  • *
  • plugin plugin version - the fully quailified * plugin class name must be specified.
  • *
* *

Plugin menu item properties

* * To add your plugin to the view's Plugins menu, define one of these two * properties: * *
    *
  • plugin.class name.menu-item - if this is defined, * the action named by this property is added to the Plugins menu.
  • *
  • plugin.class name.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.class name.menu.code to be BeanShell * code that evaluates to an implementation of * {@link org.gjt.sp.jedit.menu.DynamicMenuProvider}.

* * To add your plugin to the file system browser's Plugins menu, define * one of these two properties: * *

    *
  • plugin.class name.browser-menu-item - if this is * defined, the action named by this property is added to the Plugins * menu.
  • *
  • plugin.class name.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 action name.label * property. View actions are defined in an actions.xml * file, file system browser actions are defined in a * browser.actions.xml file; see {@link ActionSet}. * *

Plugin option pane properties

* * To add your plugin to the Plugin Options dialog box, define one of * these two properties: * *
    *
  • plugin.class name.option-pane - if this is defined, * the option pane named by this property is added to the Plugin Options * menu.
  • *
  • plugin.class name.option-group - if this is defined, * a branch node is added to the Plugin Options dialog box whose content * is the whitespace-separated list of option pane names in this property.
  • *
* * Then for each option pane name, define these two properties: * *
    *
  • options.option pane name.label - the label to show * for the pane in the dialog box.
  • *
  • options.option pane name.code - BeanShell code that * evaluates to an instance of the {@link 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
    * * Note that action and option pane labels are not shown in the above example. * * @see org.gjt.sp.jedit.jEdit#getProperty(String) * @see org.gjt.sp.jedit.jEdit#getPlugin(String) * @see org.gjt.sp.jedit.jEdit#getPlugins() * @see org.gjt.sp.jedit.jEdit#getPluginJAR(String) * @see org.gjt.sp.jedit.jEdit#getPluginJARs() * @see org.gjt.sp.jedit.jEdit#addPluginJAR(String) * @see org.gjt.sp.jedit.jEdit#removePluginJAR(PluginJAR,boolean) * @see org.gjt.sp.jedit.ActionSet * @see org.gjt.sp.jedit.gui.DockableWindowManager * @see org.gjt.sp.jedit.OptionPane * @see org.gjt.sp.jedit.PluginJAR * @see org.gjt.sp.jedit.ServiceManager * * @author Slava Pestov * @author John Gellene (API documentation) * @version $Id: EditPlugin.java,v 1.31 2003/05/03 20:34:25 spestov Exp $ * @since jEdit 2.1pre1 */ public abstract class EditPlugin { //{{{ start() method /** * 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 */ public void start() {} //}}} //{{{ stop() method /** * 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 */ public void stop() {} //}}} //{{{ getClassName() method /** * 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 */ public String getClassName() { return getClass().getName(); } //}}} //{{{ getPluginJAR() method /** * Returns the JAR file containing this plugin. * @since jEdit 4.2pre1 */ public PluginJAR getPluginJAR() { return jar; } //}}} //{{{ createMenuItems() method /** * 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 */ public final JMenuItem createMenuItems() { if(this instanceof Broken) return null; String menuItemName = jEdit.getProperty("plugin." + getClassName() + ".menu-item"); if(menuItemName != null) return GUIUtilities.loadMenuItem(menuItemName); String menuProperty = "plugin." + getClassName() + ".menu"; String codeProperty = "plugin." + getClassName() + ".menu.code"; if(jEdit.getProperty(menuProperty) != null || jEdit.getProperty(codeProperty) != null) { String pluginName = jEdit.getProperty("plugin." + getClassName() + ".name"); return new EnhancedMenu(menuProperty,pluginName); } return null; } //}}} //{{{ createBrowserMenuItems() method /** * 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 */ public final JMenuItem createBrowserMenuItems() { if(this instanceof Broken) return null; String menuItemName = jEdit.getProperty("plugin." + getClassName() + ".browser-menu-item"); if(menuItemName != null) { return GUIUtilities.loadMenuItem( VFSBrowser.getActionContext(), menuItemName, false); } String menuProperty = "plugin." + getClassName() + ".browser-menu"; if(jEdit.getProperty(menuProperty) != null) { String pluginName = jEdit.getProperty("plugin." + getClassName() + ".name"); return new EnhancedMenu(menuProperty,pluginName, VFSBrowser.getActionContext()); } return null; } //}}} //{{{ Deprecated methods //{{{ createMenuItems() method /** * @deprecated Instead of overriding this method, define properties * as specified in the description of this class. */ public void createMenuItems(Vector menuItems) {} //}}} //{{{ createOptionPanes() method /** * @deprecated Instead of overriding this method, define properties * as specified in the description of this class. */ public void createOptionPanes(OptionsDialog optionsDialog) {} //}}} //{{{ getJAR() method /** * @deprecated Call getPluginJAR() instead. */ public EditPlugin.JAR getJAR() { return jar; } //}}} //}}} //{{{ Package-private members EditPlugin.JAR jar; //}}} //{{{ Broken class /** * A placeholder for a plugin that didn't load. * @see jEdit#getPlugin(String) * @see PluginJAR#getPlugin() * @see PluginJAR#activatePlugin() */ public static class Broken extends EditPlugin { public String getClassName() { return clazz; } // package-private members Broken(String clazz) { this.clazz = clazz; } // private members private String clazz; } //}}} //{{{ Deferred class /** * A placeholder for a plugin that hasn't been loaded yet. * @see jEdit#getPlugin(String) * @see PluginJAR#getPlugin() * @see PluginJAR#activatePlugin() */ public static class Deferred extends EditPlugin { public String getClassName() { return clazz; } // package-private members Deferred(String clazz) { this.clazz = clazz; } EditPlugin loadPluginClass() { return null; } public String toString() { return "Deferred[" + clazz + "]"; } // private members private String clazz; } //}}} //{{{ JAR class /** * @deprecated Use PluginJAR instead. */ public static class JAR extends PluginJAR { JAR(java.io.File file) { super(file); } } //}}} }

... this post is sponsored by my books ...

#1 New Release!

FP Best Seller

 

new blog posts

 

Copyright 1998-2021 Alvin Alexander, alvinalexander.com
All Rights Reserved.

A percentage of advertising revenue from
pages under the /java/jwarehouse URI on this website is
paid back to open source projects.