| java.lang.Object
 org.gjt.sp.jedit.EditPlugin
All known Subclasses: jars.QuickNotepad.QuickNotepadPlugin, jars.LatestVersion.LatestVersionPlugin, org.gjt.sp.jedit.EBPlugin,
| EditPlugin | | abstract public class EditPlugin (Code) | | The abstract base class that every plugin must implement.
Alternatively, instead of extending this class, a plugin core class can
extend
EBPlugin to automatically receive EditBus messages.
Basic plugin information properties
Note that in all cases above where a className 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.className.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 will not work with
jEdit 4.3final.
plugin.className.nameplugin.className.versionplugin.className.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.plugin.className.files - only needed if your plugin
bundles external files like libraries which MUST reside in the local
filesystem. Contains a whitespace-separated list of file names.
Without this property, the plugin manager will leave behind the
external files when removing the plugin.plugin.className.description - the short description
associated with the plugin. The short description is used by the Plugin
Manager and on the list pages on Plugin Central.
The following properties are optional but recommended:
plugin.className.authorplugin.className.usePluginHome - whether
the plugin uses the EditPlugin.getPluginHome API or not. Even
if the plugin doesn't store any data, this property should be set
so that the plugin manager can tell that there is no data stored.plugin.className.docs - the path to plugin
documentation in HTML format. plugin.className.longdescription - the path to
the long description in XHTML (no fancy stuff here, please - just proper
XHTML subset with the basic tags: html, h1, h2, p, li, ul, ol, a href,b ,i, u, br/ )
The long description is extracted from the plugin at various times,
primarily at plugin packaging time to update the data on the
plugin detail pages of Plugin Central.
If this property is left out, the default will be to look in a file
called <description.html>.
For the previous two properties, if a relative path is supplied,
it should be both
- relative to the location of the .props file (when it is in the source tree)
- relative to the root of the JAR (when it is packaged in the JAR file)
Both conditions are easily satisfied if the .props file as well as
description.html are both located in the root directory of the plugin,
as well as the generated JAR.
Plugin dependency properties
Plugin dependencies are also specified using properties.
Each dependency is defined in a property named with
plugin.className.depend. followed by a number.
Dependencies must be numbered in order, starting from zero.
This determines the order that dependent plugins get loaded and activated,
so order is very important.
The value of a dependency property has one of the following forms:
-
jdk minimumJavaVersion
-
jedit minimumjEditVersion - note that this must be
a version number in the form returned by
jEdit.getBuild ,
not
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.99.00 (4.2final).
pluginClassName pluginVersion - the fully quailified
plugin class name with package must be specified.optional plugin pluginClassName pluginVersion -
an optional dependency, indicating that the plugin will work without it,
but that the dependency should be loaded before this plugin.
In this example, the ProjectViewer plugin is an optional dependency of
the Console, beacause the Console only listens to events from the ProjectViewer.
It requires Jedit 4.2 final.
plugin.console.ConsolePlugin.depend.0=jedit 04.02.99.00
plugin.console.ConsolePlugin.depend.1=jdk 1.5
plugin.console.ConsolePlugin.depend.2=plugin errorlist.ErrorListPlugin 1.4
plugin.console.ConsolePlugin.depend.3=optional plugin projectviewer.ProjectPlugin 2.1.0.92
Plugin menu item properties
To add your plugin to the view's Plugins menu, define one of these two
properties:
plugin.className.menu-item - if this is defined,
the action named by this property is added to the Plugins menu.plugin.className.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.className.menu.code to be BeanShell
code that evaluates to an implementation of
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.className.browser-menu-item - if this is
defined, the action named by this property is added to the Plugins
menu.plugin.className.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 actionName.label
property. View actions are defined in an actions.xml
file, file system browser actions are defined in a
browser.actions.xml file; see
ActionSet .
Plugin option pane properties
To add your plugin to the Plugin Options dialog box, define one of
these two properties:
plugin.className.option-pane=paneName - if this is defined,
a single option pane with this name is added to the Plugin Options
menu.plugin.className.option-group=paneName1 [paneName2 paneName3 ...] - if this is defined,
a branch node is added to the Plugin Options dialog box whose content
is the whitespace-separated list of paneNames in this property.
Then for each option paneName, define these two properties:
options.paneName.label - the label to show
for the pane in the dialog box.options.paneName.code - BeanShell code that
evaluates to an instance of the
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
plugin.QuickNotepadPlugin.option-pane=quicknotepad
plugin.QuickNotepadPlugin.usePluginHome=false
options.quicknotepad.code=new QuickNotepadOptionPane();
options.quicknotepad.label=QuickNotepad
options.quicknotepad.file=File:
options.quicknotepad.choose-file=Choose
options.quicknotepad.choose-file.title=Choose a notepad file
options.quicknotepad.choose-font=Font:
options.quicknotepad.show-filepath.title=Display notepad file path
Note that action and option pane labels are not shown in the above example.
See Also: org.gjt.sp.jedit.jEdit.getProperty(String)
See Also: org.gjt.sp.jedit.jEdit.getPlugin(String)
See Also: org.gjt.sp.jedit.jEdit.getPlugins
See Also: org.gjt.sp.jedit.jEdit.getPluginJAR(String)
See Also: org.gjt.sp.jedit.jEdit.getPluginJARs
See Also: org.gjt.sp.jedit.jEdit.addPluginJAR(String)
See Also: org.gjt.sp.jedit.jEdit.removePluginJAR(PluginJARboolean)
See Also: org.gjt.sp.jedit.ActionSet
See Also: org.gjt.sp.jedit.gui.DockableWindowManager
See Also: org.gjt.sp.jedit.OptionPane
See Also: org.gjt.sp.jedit.PluginJAR
See Also: org.gjt.sp.jedit.ServiceManager
author:
Slava Pestov
author:
John Gellene (API documentation)
author:
Alan Ezust (API documentation)
since:
jEdit 2.1pre1 |
| Inner Class :public static class Broken extends EditPlugin | |
| Inner Class :public static class Deferred extends EditPlugin | |
| Method Summary | |
| final public JMenuItem | createBrowserMenuItems()
Called by the filesystem browser when constructing its
Plugins menu. | | final public JMenuItem | createMenuItems()
Called by the view when constructing its Plugins menu. | | public void | createMenuItems(Vector menuItems)
| | public void | createOptionPanes(OptionsDialog optionsDialog)
| | public String | getClassName()
Returns the plugin's class name. | | public File | getPluginHome()
Returns the home of your plugin.
the plugin home. | | public static File | getPluginHome(Class<? extends EditPlugin> clazz)
Returns the home of the specified plugin.
Since the first parameter is a reference to the
Class instance for the plugin,
this method requires the plugin to be activated.
See
EditPlugin.getPluginHome(EditPlugin) method, as
an alternate, for when the plugin doesn't need
to be activated, or when you do not have the
Class instance available.
Parameters:
clazz - the class of the plugin the plugin home. | | public static File | getPluginHome(EditPlugin plugin)
Returns the home of the specified plugin.
This method doesn't need the plugin to be activated. | | public PluginJAR | getPluginJAR()
Returns the JAR file containing this plugin. | | public static OutputStream | getResourceAsOutputStream(Class<? extends EditPlugin> clazz, String path)
Returns an output stream to the specified resource, or
null if access to that resource is denied.
Since the first parameter is a reference to the
Class instance for the plugin,
this method requires the plugin to be activated.
See
EditPlugin.getResourceAsOutputStream(EditPlugin,String) method, as
an alternate, for when the plugin doesn't need
to be activated, or when you do not have the
Class instance available.
Parameters:
clazz - the plugin class
Parameters:
path - The path to the resource to be returned, relative tothe plugin's resource path. | | public static OutputStream | getResourceAsOutputStream(EditPlugin plugin, String path)
Returns an output stream to the specified resource, or null if access
to that resource is denied.
This method doesn't need the plugin to be activated. | | public static InputStream | getResourceAsStream(Class<? extends EditPlugin> clazz, String path)
Returns an input stream to the specified resource, or
null if none is found.
Since the first parameter is a reference to the
Class instance for the plugin,
this method requires the plugin to be activated.
See
EditPlugin.getResourceAsStream(EditPlugin,String) method, as
an alternate, for when the plugin doesn't need
to be activated, or when you do not have the
Class instance available.
Parameters:
clazz - the plugin class
Parameters:
path - The path to the resource to be returned, relative tothe plugin's resource path. | | public static InputStream | getResourceAsStream(EditPlugin plugin, String path)
Returns an input stream to the specified resource, or null
if none is found.
This method doesn't need the plugin to be activated. | | public static File | getResourcePath(Class<? extends EditPlugin> clazz, String path)
Returns the full path of the specified plugin resource.
Since the first parameter is a reference to the
Class instance for the plugin,
this method requires the plugin to be activated.
See
EditPlugin.getResourcePath(EditPlugin,String) method, as
an alternate, for when the plugin doesn't need
to be activated, or when you do not have the
Class instance available.
Parameters:
clazz - the plugin class
Parameters:
path - The relative path to the resource from the plugin'sresource path. | | public static File | getResourcePath(EditPlugin plugin, String path)
Returns the full path of the specified plugin resource.
This method doesn't need the plugin to be activated. | | public void | start()
jEdit calls this method when the plugin is being activated, either
during startup or at any other time. | | public void | stop()
jEdit calls this method when the plugin is being unloaded. |
| createBrowserMenuItems | | final public JMenuItem createBrowserMenuItems()(Code) | | 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 |
| createMenuItems | | final public JMenuItem createMenuItems()(Code) | | 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 |
| createMenuItems | | public void createMenuItems(Vector menuItems)(Code) | | |
| getClassName | | public String getClassName()(Code) | | 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 |
| getPluginHome | | public static File getPluginHome(EditPlugin plugin)(Code) | | Returns the home of the specified plugin.
This method doesn't need the plugin to be activated. You can pass
an
EditPlugin.Deferred instance that you get from
jEdit.getPlugin(String) or
jEdit.getPlugins() if
the plugin in question is not activated yet and this method doesn't
cause the plugin to get activated. If you have a reference to the
plugins
Class instance available, consider using the
Class method.
Parameters:
plugin - the plugin the plugin home. It can be null if there is no settings directory
since:
4.3pre10
See Also: EditPlugin.getPluginHome(Class)
See Also: EditPlugin.getResourceAsStream
See Also: EditPlugin.getResourceAsOutputStream
See Also: EditPlugin.getResourcePath |
| getPluginJAR | | public PluginJAR getPluginJAR()(Code) | | Returns the JAR file containing this plugin.
since:
jEdit 4.2pre1 |
| getResourceAsOutputStream | | public static OutputStream getResourceAsOutputStream(Class<? extends EditPlugin> clazz, String path)(Code) | | Returns an output stream to the specified resource, or
null if access to that resource is denied.
Since the first parameter is a reference to the
Class instance for the plugin,
this method requires the plugin to be activated.
See
EditPlugin.getResourceAsOutputStream(EditPlugin,String) method, as
an alternate, for when the plugin doesn't need
to be activated, or when you do not have the
Class instance available.
Parameters:
clazz - the plugin class
Parameters:
path - The path to the resource to be returned, relative tothe plugin's resource path. An output stream for the resource, or null.
since:
4.3pre10
See Also: EditPlugin.getPluginHome
See Also: EditPlugin.getResourceAsOutputStream(EditPlugin,String)
See Also: EditPlugin.getResourceAsStream
See Also: EditPlugin.getResourcePath |
| getResourceAsOutputStream | | public static OutputStream getResourceAsOutputStream(EditPlugin plugin, String path)(Code) | | Returns an output stream to the specified resource, or null if access
to that resource is denied.
This method doesn't need the plugin to be activated. You can pass
an
EditPlugin.Deferred instance that you get from
jEdit.getPlugin(String) or
jEdit.getPlugins() if
the plugin in question is not activated yet and this method doesn't
cause the plugin to get activated. If you have a reference to the
plugins
Class instance available, consider using the
Class method.
Parameters:
plugin - the plugin
Parameters:
path - The path to the resource to be returned, relative tothe plugin's resource path. An output stream for the resource, or null.
since:
4.3pre10
See Also: EditPlugin.getPluginHome
See Also: EditPlugin.getResourceAsOutputStream(Class,String)
See Also: EditPlugin.getResourceAsStream
See Also: EditPlugin.getResourcePath |
| getResourceAsStream | | public static InputStream getResourceAsStream(Class<? extends EditPlugin> clazz, String path)(Code) | | Returns an input stream to the specified resource, or
null if none is found.
Since the first parameter is a reference to the
Class instance for the plugin,
this method requires the plugin to be activated.
See
EditPlugin.getResourceAsStream(EditPlugin,String) method, as
an alternate, for when the plugin doesn't need
to be activated, or when you do not have the
Class instance available.
Parameters:
clazz - the plugin class
Parameters:
path - The path to the resource to be returned, relative tothe plugin's resource path. An input stream for the resource, or null.
since:
4.3pre10
See Also: EditPlugin.getPluginHome
See Also: EditPlugin.getResourceAsStream(EditPlugin,String)
See Also: EditPlugin.getResourceAsOutputStream
See Also: EditPlugin.getResourcePath |
| getResourceAsStream | | public static InputStream getResourceAsStream(EditPlugin plugin, String path)(Code) | | Returns an input stream to the specified resource, or null
if none is found.
This method doesn't need the plugin to be activated. You can pass
an
EditPlugin.Deferred instance that you get from
jEdit.getPlugin(String) or
jEdit.getPlugins() if
the plugin in question is not activated yet and this method doesn't
cause the plugin to get activated. If you have a reference to the
plugins
Class instance available, consider using the
Class method.
Parameters:
plugin - the plugin
Parameters:
path - The path to the resource to be returned, relative tothe plugin's resource path. An input stream for the resource, or null.
since:
4.3pre10
See Also: EditPlugin.getPluginHome
See Also: EditPlugin.getResourceAsStream(Class,String)
See Also: EditPlugin.getResourceAsOutputStream
See Also: EditPlugin.getResourcePath |
| getResourcePath | | public static File getResourcePath(EditPlugin plugin, String path)(Code) | | Returns the full path of the specified plugin resource.
This method doesn't need the plugin to be activated. You can pass
an
EditPlugin.Deferred instance that you get from
jEdit.getPlugin(String) or
jEdit.getPlugins() if
the plugin in question is not activated yet and this method doesn't
cause the plugin to get activated. If you have a reference to the
plugins
Class instance available, consider using the
Class method.
Parameters:
plugin - the plugin
Parameters:
path - The relative path to the resource from the plugin'sresource path. The absolute path to the resource or null if there is no plugin home.
since:
4.3pre10
See Also: EditPlugin.getPluginHome
See Also: EditPlugin.getResourceAsOutputStream
See Also: EditPlugin.getResourceAsStream
See Also: EditPlugin.getResourcePath(Class,String) |
| start | | public void start()(Code) | | 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 |
| stop | | public void stop()(Code) | | 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 |
|
|