/jEdit/tags/jedit-4-2-pre4/doc/users-guide/plugin-intro.xml

  1<!-- jEdit 4.0 Plugin Guide, (C) 2001, 2002 John Gellene          -->
  2
  3<!-- jEdit buffer-local properties:                         -->
  4<!-- :indentSize=1:tabSize=2:noTabs=true:maxLineLen=72:     -->
  5<!-- :xml.root=users-guide.xml: -->
  6
  7<!-- This is the introduction of the jEdit 4.0 Plugin Guide -->
  8<!-- $Id: plugin-intro.xml 4491 2003-02-18 01:46:35Z spestov $
  9-->
 10
 11<chapter id="plugin-intro"> <title>
 12<indexterm>
 13	<primary>Plugin API</primary>
 14	<secondary>introduction</secondary>
 15</indexterm>
 16Introducing the Plugin API</title>
 17
 18<para>
 19  The <firstterm>jEdit Plugin API</firstterm> provides a framework for
 20  hosting plugin applications without imposing any
 21  requirements on the design or function of the plugin itself. You could
 22  write a application that performs spell checking, displays a clock or
 23  plays chess and turn it into a jEdit plugin. There are currently over 50
 24  released plugins for jEdit. While none of them play chess,
 25  they perform a wide variety of editing and file management tasks.
 26</para>
 27
 28<para>
 29  A detailed listing of available plugins is available at
 30  <ulink url="http://plugins.jedit.org">plugins.jedit.org</ulink>.
 31  You can also find beta versions of new plugins in the
 32  <quote>Downloads</quote> area of <ulink
 33  url="http://community.jedit.org">community.jedit.org</ulink>.
 34</para>
 35
 36<para>
 37  Using the <quote>Plugin Manager</quote> feature of jEdit, users with an
 38  Internet connection can check for new or updated plugins and install
 39  and remove them without leaving jEdit. See <xref
 40  linkend="using-plugins" /> for details.
 41</para>
 42
 43<para>
 44  Requirements for <quote>plugging in</quote> to jEdit are as follows:
 45</para>
 46
 47<itemizedlist>
 48	<listitem><para>
 49    This plugin must supply information about itself, such as its name,
 50    version, author, and compatibility with versions of jEdit.
 51  </para></listitem>
 52
 53	<listitem><para>
 54    The plugin must provide for activating, displaying and
 55    deactivating itself upon direction from jEdit,
 56    typically in response to user input.
 57  </para></listitem>
 58
 59  <listitem><para>
 60    The plugin may define <firstterm>actions</firstterm>, both
 61    explicitly with an action definition file, or implicitly
 62    by providing dockable windows. 
 63    Actions are small blocks of BeanShell code that
 64    jEdit will perform on behalf of the plugin upon
 65    user request. They provide the <quote>glue</quote> between user
 66    input and specific plugin routines.
 67  </para>
 68
 69  <para>
 70    By convention, plugins display their available actions in submenus of
 71    jEdit's <guimenu>Plugins</guimenu> menu; each menu item corresponds to
 72    an action. The user can also assign actions to keyboard shortcuts,
 73    toolbar buttons or entries in the text area's right-click menu.
 74  </para>
 75
 76  </listitem>
 77
 78  <listitem><para>
 79    The plugin may, but need not, provide a user interface.
 80  </para>
 81  <para>
 82    If the plugin has a visible interface, it can be shown in any object
 83    derived from one of Java top-level container classes:
 84    <classname>JWindow</classname>, <classname>JDialog</classname>, or
 85    <classname>JFrame</classname>. jEdit also provides a dockable window
 86    API, which allows plugin windows derived from the
 87    <classname>JComponent</classname> class to be docked into views or shown in
 88    top-level frames, at the user's request.
 89  </para>
 90
 91  <para>
 92    Plugins can also act directly upon jEdit's text area.  They
 93    can add graphical elements to the text display (like error
 94    highlighting in the case of the <application>ErrorList</application>
 95    plugin) or decorations
 96    surrounding the text area (like the <application>JDiff</application>
 97    plugin's summary views).
 98  </para>
 99  </listitem>
100
101	<listitem><para>
102    Plugins may provide a range of options that the user can modify to
103    alter their configuration.
104  </para>
105
106  <para>
107    If a plugin provides configuration options in accordance with the plugin
108    API, jEdit will make them available in the <guilabel>Global
109    Options</guilabel> dialog box.
110  </para>
111  </listitem>
112
113  <listitem><para>
114    While it is not required, plugins are encouraged to provide
115    documentation.
116  </para></listitem>
117
118</itemizedlist>
119
120<para>
121  As noted, many of these features are optional; it is possible to write
122  a plugin that does not provide actions, configuration options, or dockable
123  windows. The majority of plugins, however, provide most of these services.
124</para>
125
126<sidebar><title>Plugins and different jEdit versions</title>
127  <para>
128    As jEdit continues to evolve and improve, elements of the plugin API
129    may change with a new jEdit release.
130  </para>
131  <para>
132    On occasion an API change will break code used by plugins, although
133    efforts are made to maintain or deprecate plugin-related code on a
134    transitional basis. While the majority of plugins are
135    unaffected by most changes and will continue working, it is a good idea
136    to monitor the jEdit change log, the mailing lists and <ulink
137    url="http://community.jedit.org">community.jedit.org</ulink> for API changes
138    so that you can update your plugin if necessary.
139  </para>
140</sidebar>
141
142</chapter>
143