/jEdit/tags/jedit-4-2-pre4/doc/users-guide/plugin-intro.xml
XML | 143 lines | 114 code | 22 blank | 7 comment | 0 complexity | bf2a9d2237cad8b58d569d6b54aac10d MD5 | raw file
Possible License(s): BSD-3-Clause, AGPL-1.0, Apache-2.0, LGPL-2.0, LGPL-3.0, GPL-2.0, CC-BY-SA-3.0, LGPL-2.1, GPL-3.0, MPL-2.0-no-copyleft-exception, IPL-1.0
- <!-- jEdit 4.0 Plugin Guide, (C) 2001, 2002 John Gellene -->
- <!-- jEdit buffer-local properties: -->
- <!-- :indentSize=1:tabSize=2:noTabs=true:maxLineLen=72: -->
- <!-- :xml.root=users-guide.xml: -->
- <!-- This is the introduction of the jEdit 4.0 Plugin Guide -->
- <!-- $Id: plugin-intro.xml 4491 2003-02-18 01:46:35Z spestov $
- -->
- <chapter id="plugin-intro"> <title>
- <indexterm>
- <primary>Plugin API</primary>
- <secondary>introduction</secondary>
- </indexterm>
- Introducing the Plugin API</title>
- <para>
- The <firstterm>jEdit Plugin API</firstterm> provides a framework for
- hosting plugin applications without imposing any
- requirements on the design or function of the plugin itself. You could
- write a application that performs spell checking, displays a clock or
- plays chess and turn it into a jEdit plugin. There are currently over 50
- released plugins for jEdit. While none of them play chess,
- they perform a wide variety of editing and file management tasks.
- </para>
- <para>
- A detailed listing of available plugins is available at
- <ulink url="http://plugins.jedit.org">plugins.jedit.org</ulink>.
- You can also find beta versions of new plugins in the
- <quote>Downloads</quote> area of <ulink
- url="http://community.jedit.org">community.jedit.org</ulink>.
- </para>
- <para>
- Using the <quote>Plugin Manager</quote> feature of jEdit, users with an
- Internet connection can check for new or updated plugins and install
- and remove them without leaving jEdit. See <xref
- linkend="using-plugins" /> for details.
- </para>
- <para>
- Requirements for <quote>plugging in</quote> to jEdit are as follows:
- </para>
- <itemizedlist>
- <listitem><para>
- This plugin must supply information about itself, such as its name,
- version, author, and compatibility with versions of jEdit.
- </para></listitem>
- <listitem><para>
- The plugin must provide for activating, displaying and
- deactivating itself upon direction from jEdit,
- typically in response to user input.
- </para></listitem>
- <listitem><para>
- The plugin may define <firstterm>actions</firstterm>, both
- explicitly with an action definition file, or implicitly
- by providing dockable windows.
- Actions are small blocks of BeanShell code that
- jEdit will perform on behalf of the plugin upon
- user request. They provide the <quote>glue</quote> between user
- input and specific plugin routines.
- </para>
- <para>
- By convention, plugins display their available actions in submenus of
- jEdit's <guimenu>Plugins</guimenu> menu; each menu item corresponds to
- an action. The user can also assign actions to keyboard shortcuts,
- toolbar buttons or entries in the text area's right-click menu.
- </para>
- </listitem>
- <listitem><para>
- The plugin may, but need not, provide a user interface.
- </para>
- <para>
- If the plugin has a visible interface, it can be shown in any object
- derived from one of Java top-level container classes:
- <classname>JWindow</classname>, <classname>JDialog</classname>, or
- <classname>JFrame</classname>. jEdit also provides a dockable window
- API, which allows plugin windows derived from the
- <classname>JComponent</classname> class to be docked into views or shown in
- top-level frames, at the user's request.
- </para>
- <para>
- Plugins can also act directly upon jEdit's text area. They
- can add graphical elements to the text display (like error
- highlighting in the case of the <application>ErrorList</application>
- plugin) or decorations
- surrounding the text area (like the <application>JDiff</application>
- plugin's summary views).
- </para>
- </listitem>
- <listitem><para>
- Plugins may provide a range of options that the user can modify to
- alter their configuration.
- </para>
- <para>
- If a plugin provides configuration options in accordance with the plugin
- API, jEdit will make them available in the <guilabel>Global
- Options</guilabel> dialog box.
- </para>
- </listitem>
- <listitem><para>
- While it is not required, plugins are encouraged to provide
- documentation.
- </para></listitem>
- </itemizedlist>
- <para>
- As noted, many of these features are optional; it is possible to write
- a plugin that does not provide actions, configuration options, or dockable
- windows. The majority of plugins, however, provide most of these services.
- </para>
- <sidebar><title>Plugins and different jEdit versions</title>
- <para>
- As jEdit continues to evolve and improve, elements of the plugin API
- may change with a new jEdit release.
- </para>
- <para>
- On occasion an API change will break code used by plugins, although
- efforts are made to maintain or deprecate plugin-related code on a
- transitional basis. While the majority of plugins are
- unaffected by most changes and will continue working, it is a good idea
- to monitor the jEdit change log, the mailing lists and <ulink
- url="http://community.jedit.org">community.jedit.org</ulink> for API changes
- so that you can update your plugin if necessary.
- </para>
- </sidebar>
- </chapter>