/*
 * 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);
		}
	}
	//}}}
}