/jEdit/tags/jedit-4-0-pre5/doc/users-guide/plugin-intro.xml

<!-- jEdit 4.0 Plugin Guide, (C) 2001 John Gellene          -->

<!-- jEdit buffer-local properties:                         -->
<!-- :indentSize=1:tabSize=2:noTabs=true:maxLineLen=72:     -->

<!-- This is the introduction of the jEdit 4.0 Plugin Guide -->
<!-- $Id: plugin-intro.xml 3897 2001-11-13 15:11:42Z jgellene $
-->

<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 40
  released plugins for jEdit. While none of them play chess,
  they perform a wide variety of editing and file management tasks. A
  detailed listing of available plugins is available at the jEdit
  <ulink url="http://plugins.jedit.org">Plugin Central</ulink> web site.
</para>

<para>
  Using the plugin manager feature of jEdit, users with an
  Internet connnection can check for new or updated plugins and install
  and remove them without leaving jEdit. See <xref
  linkend="using-plugins" /> for details.
</para>

<para>
  In order to <quote>plug in</quote> to jEdit, a plugin must implement
  interfaces or data that deal with the following matters:
</para>

<itemizedlist>
	<listitem><para>
    Ths 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, 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>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 (and typically do) define <firstterm>actions</firstterm>
    that jEdit will perform on behalf of the plugin upon
    user request. Actions are small blocks of BeanShell code that
    provide the <quote>glue</quote> between user input and
    specifc 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>
    Plugins may provide a range of options that the user can modify to
    alter its 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. Each plugin with options is listed in the
    tree view in that dialog under <guilabel>Plugin Options</guilabel>.
    Clicking on the tree node for a plugin causes the corresponding set
    of options to be displayed.
  </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>

<para>
  In the following chapters, we will begin by briefly describing jEdit's
  host capabilities, which includes the loading and display of plugins.
  Next we will describe the principal classes and data structures that a
  plugin must implement. Finally, we will outline the building of a modest
  plugin, <quote>QuickNotepad</quote>, that illustrates the requirements and
  some of the techniques of jEdit plugin design.
</para>

<sidebar><title>Plugins and different jEdit versions</title>
  <para>
    As jEdit continues to evolve and improve, elements of the plugin API or
    jEdit's general API may change with a new jEdit release. For example,
    version 4.0 of jEdit has simplified the design of a plugin by
    placing code for the activation of a plugin's docking window in an
    XML file rather than in a Java class. The use of a Java interface for
    docking windows has been deprecated. We will explain this and other changes
    in the plugin API for jEdit 4.0 when discussing the model QuickNotepad plugin.
  </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
    trasisional basis. possible. While the majority of plugins are
    unaffected by most changes and will continue working, it is a good idea
    to monitor the jEdit changelog, the mailing lists or <ulink
    url="http://community.jedit.org">jEdit Community</ulink> for API changes
    and update your plugin as necessary.
  </para>
</sidebar>

</chapter>