editplugin.java

用java 编写的源码开放的文本编辑器。有很多有用的特性

/*
 * EditPlugin.java - Abstract class all plugins must implement
 * :tabSize=8:indentSize=8:noTabs=false:
 * :folding=explicit:collapseFolds=1:
 *
 * Copyright (C) 1999, 2000 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 java.util.Vector;
import java.util.zip.ZipFile;
import org.gjt.sp.jedit.gui.OptionsDialog;
import org.gjt.sp.util.Log;

/**
 * The abstract base class that every plugin must implement.<p>
 *
 * Each plugin must have the following properties defined in its property file:
 *
 * <ul>
 * <li><code>plugin.<i>class name</i>.name</code></li>
 * <li><code>plugin.<i>class name</i>.version</code></li>
 * <li><code>plugin.<i>class name</i>.jars</code> - 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.</li>
 * </ul>
 *
 * The following properties are optional but recommended:
 *
 * <ul>
 * <li><code>plugin.<i>class name</i>.author</code></li>
 * <li><code>plugin.<i>class name</i>.docs</code> - the path to plugin
 * documentation in HTML format within the JAR file.</li>
 * </ul>
 *
 * Plugin dependencies are also specified using properties.
 * Each dependency is defined in a property named with
 * <code>plugin.<i>class name</i>.depend.</code> followed by a number.
 * Dependencies must be numbered in order, starting from zero.<p>
 *
 * The value of a dependency property has one of the following forms:
 *
 * <ul>
 * <li><code>jdk <i>minimum Java version</i></code></li>
 * <li><code>jedit <i>minimum jEdit version</i></code> - note that this must be a
 * version number in the form returned by {@link jEdit#getBuild()},
 * not {@link jEdit#getVersion()}.</li>
 * <li><code>plugin <i>plugin</i> <i>version</i></code> - the fully quailified
 * plugin class name must be specified.</li>
 * </ul>
 *
 * Here is an example set of plugin properties:
 *
 * <pre>plugin.QuickNotepadPlugin.name=QuickNotepad
 *plugin.QuickNotepadPlugin.author=John Gellene
 *plugin.QuickNotepadPlugin.version=4.1
 *plugin.QuickNotepadPlugin.docs=QuickNotepad.html
 *plugin.QuickNotepadPlugin.depend.0=jedit 04.01.01.00</pre>
 *
 * 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.<p>
 *
 * Alternatively, instead of extending this class, a plugin core class can
 * extend {@link EBPlugin} to automatically receive EditBus messages.
 *
 * @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()
 *
 * @author Slava Pestov
 * @author John Gellene (API documentation)
 * @version $Id: EditPlugin.java,v 1.13 2003/02/11 02:31:06 spestov Exp $
 * @since jEdit 2.1pre1
 */
public abstract class EditPlugin
{
	//{{{ start() method
	/**
	 * The jEdit startup routine calls this method for each loaded
	 * plugin.
	 *
	 * This method should return as quickly as possible to avoid
	 * slowing down jEdit startup.<p>
	 *
	 * The default implementation does nothing.
	 *
	 * @since jEdit 2.1pre1
	 */
	public void start() {}
	//}}}

	//{{{ stop() method
	/**
	 * The jEdit exit routine calls this method fore ach loaded plugin.
	 *
	 * 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.<p>
	 *
	 * The default implementation does nothing.
	 *
	 * @since jEdit 2.1pre1
	 */
	public void stop() {} //}}}

	//{{{ createMenuItems() method
	/**
	 * When a {@link View} object is created, it calls this
	 * method on each plugin class to obtain entries to be displayed
	 * in the view's <b>Plugins</b> menu.
	 *
	 * The <code>menuItems</code> vector accumulates menu items and
	 * menus as it is passed from plugin to plugin.<p>
	 *
	 * The easiest way to provide menu items is to
	 * package them as entries in the plugin's property
	 * file and implement <code>createMenuItems()</code> with a
	 * call to the {@link GUIUtilities#loadMenu(String)}
	 * method:
	 * <pre>public void createMenuItems(Vector menuItems)
	 *{
	 *    menuItems.addElement(GUIUtilities.loadMenu(
	 *        "myplugin.menu"));
	 *}</pre>
	 *
	 * Alternatively, {@link GUIUtilities#loadMenuItem(String)} can
	 * be used if your plugin only defines one menu item.<p>
	 *
	 * The default implementation does nothing.
	 *
	 * @param menuItems Add menus and menu items here.
	 *
	 * @see GUIUtilities#loadMenu(String)
	 * @see GUIUtilities#loadMenuItem(String)
	 *
	 * @since jEdit 2.6pre5
	 */
	public void createMenuItems(Vector menuItems) {} //}}}

	//{{{ createOptionPanes() method
	/**
	 * When the <b>Global Options</b> dialog is opened, this method is
	 * called for each plugin in turn.
	 *
	 * To show an option pane, the plugin should define an
	 * option pane class and implement <code>createOptionPane()</code>
	 * as follows:
	 *
	 * <pre>public void createOptionPanes(OptionsDialog optionsDialog)
	 *{
	 *    dialog.addOptionPane(new MyPluginOptionPane());
	 *}</pre>
	 *
	 * Plugins can also define more than one option pane, grouped in an
	 * "option group". See the documentation for the {@link OptionGroup}
	 * class for information.<p>
	 *
	 * The default implementation does nothing.
	 *
	 * @param optionsDialog The plugin options dialog box
	 *
	 * @see OptionPane
	 * @see AbstractOptionPane
	 * @see OptionsDialog#addOptionPane(OptionPane)
	 * @see OptionGroup
	 * @see OptionsDialog#addOptionGroup(OptionGroup)
	 *
	 * @since jEdit 2.1pre1
	 */
	public void createOptionPanes(OptionsDialog optionsDialog) {} //}}}

	//{{{ getClassName() method
	/**
	 * Returns the plugin's class name.
	 *
	 * @since jEdit 2.5pre3
	 */
	public String getClassName()
	{
		return getClass().getName();
	} //}}}

	//{{{ getJAR() method
	/**
	 * Returns the JAR file containing this plugin.
	 * @since jEdit 3.1pre5
	 */
	public EditPlugin.JAR getJAR()
	{
		return jar;
	} //}}}

	//{{{ Broken class
	/**
	 * A placeholder for a plugin that didn't load.
	 */
	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;
	} //}}}

	//{{{ JAR class
	/**
	 * A JAR file.
	 */
	public static class JAR
	{
		public String getPath()
		{
			return path;
		}

		public ZipFile getZipFile()
		{
			return classLoader.getZipFile();
		}

		public JARClassLoader getClassLoader()
		{
			return classLoader;
		}

		public ActionSet getActions()
		{
			return actions;
		}

		public void addPlugin(EditPlugin plugin)
		{
			plugin.jar = JAR.this;

			long start = System.currentTimeMillis();

			try
			{
				// must be before the below two so that if an error
				// occurs during start, the plugin is not listed as
				// being active
				plugin.start();
			}
			finally
			{
				Log.log(Log.DEBUG,this,"-- startup took " +
					(System.currentTimeMillis() - start)
					+ " milliseconds");
			}

			if(plugin instanceof EBPlugin)
				EditBus.addToBus((EBPlugin)plugin);

			plugins.addElement(plugin);
		}

		public EditPlugin[] getPlugins()
		{
			EditPlugin[] array = new EditPlugin[plugins.size()];
			plugins.copyInto(array);
			return array;
		}

		public JAR(String path, JARClassLoader classLoader)
		{
			this.path = path;
			this.classLoader = classLoader;
			plugins = new Vector();
			actions = new ActionSet();
		}

		// package-private members
		void getPlugins(Vector vector)
		{
			for(int i = 0; i < plugins.size(); i++)
			{
				vector.addElement(plugins.elementAt(i));
			}
		}

		// private members
		private String path;
		private JARClassLoader classLoader;
		private Vector plugins;
		private ActionSet actions;
	} //}}}

	//{{{ Private members
	private EditPlugin.JAR jar;
	//}}}
}