PageRenderTime 65ms CodeModel.GetById 61ms app.highlight 1ms RepoModel.GetById 1ms app.codeStats 0ms

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

#
XML | 146 lines | 120 code | 20 blank | 6 comment | 0 complexity | f621f71e9773a85e3e631fdd4fe20b5e MD5 | raw file
  1<!-- jEdit 4.0 Plugin Guide, (C) 2001 John Gellene          -->
  2
  3<!-- jEdit buffer-local properties:                         -->
  4<!-- :indentSize=1:tabSize=2:noTabs=true:maxLineLen=72:     -->
  5
  6<!-- This is the introduction of the jEdit 4.0 Plugin Guide -->
  7<!-- $Id: plugin-intro.xml 3897 2001-11-13 15:11:42Z jgellene $
  8-->
  9
 10<chapter id="plugin-intro"> <title>
 11<indexterm>
 12	<primary>Plugin API</primary>
 13	<secondary>introduction</secondary>
 14</indexterm>
 15Introducing the Plugin API</title>
 16
 17<para>
 18  The <firstterm>jEdit Plugin API</firstterm> provides a framework for
 19  hosting plugin applications without imposing any
 20  requirements on the design or function of the plugin itself. You could
 21  write a application that performs spell checking, displays a clock or
 22  plays chess and turn it into a jEdit plugin. There are currently over 40
 23  released plugins for jEdit. While none of them play chess,
 24  they perform a wide variety of editing and file management tasks. A
 25  detailed listing of available plugins is available at the jEdit
 26  <ulink url="http://plugins.jedit.org">Plugin Central</ulink> web site.
 27</para>
 28
 29<para>
 30  Using the plugin manager feature of jEdit, users with an
 31  Internet connnection can check for new or updated plugins and install
 32  and remove them without leaving jEdit. See <xref
 33  linkend="using-plugins" /> for details.
 34</para>
 35
 36<para>
 37  In order to <quote>plug in</quote> to jEdit, a plugin must implement
 38  interfaces or data that deal with the following matters:
 39</para>
 40
 41<itemizedlist>
 42	<listitem><para>
 43    Ths plugin must supply information about itself, such as its name,
 44    version, author, and compatibility with versions of jEdit.
 45  </para></listitem>
 46
 47	<listitem><para>
 48    The plugin must provide for activating, displaying and
 49    deactivating itself upon direction from jEdit,
 50    typically in response to user input.
 51  </para></listitem>
 52
 53  <listitem><para>
 54    The plugin may, but need not, provide a user interface.
 55  </para>
 56  <para>
 57    If the plugin has a visible interface, it can be shown in any object
 58    derived from one of Java top-level container classes:
 59    <classname>JWindow</classname>, <classname>JDialog</classname>, or
 60    <classname>JFrame</classname>. jEdit also provides a dockable window
 61    API, which allows plugin windows derived from the
 62    <classname>JComponent</classname>to be docked into views or shown in
 63    top-level frames, at the user's request.
 64  </para>
 65
 66  <para>
 67    Plugins can also act directly upon jEdit's text area.  They
 68    can add graphical elements to the text display (like error
 69    highlighting in the case of the <application>ErrorList</application>
 70    plugin) or decorations
 71    surrounding the text area (like the <application>JDiff</application>
 72    plugin's summary views).
 73  </para>
 74  </listitem>
 75
 76  <listitem><para>
 77    Plugins may (and typically do) define <firstterm>actions</firstterm>
 78    that jEdit will perform on behalf of the plugin upon
 79    user request. Actions are small blocks of BeanShell code that
 80    provide the <quote>glue</quote> between user input and
 81    specifc plugin routines.
 82  </para>
 83
 84  <para>
 85    By convention, plugins display their available actions in submenus of
 86    jEdit's <guimenu>Plugins</guimenu> menu; each menu item corresponds to
 87    an action. The user can also assign actions to keyboard shortcuts,
 88    toolbar buttons or entries in the text area's right-click menu.
 89  </para>
 90
 91  </listitem>
 92
 93	<listitem><para>
 94    Plugins may provide a range of options that the user can modify to
 95    alter its configuration.
 96  </para>
 97
 98  <para>
 99    If a plugin provides configuration options in accordance with the plugin
100    API, jEdit will make them available in the <guilabel>Global
101    Options</guilabel> dialog. Each plugin with options is listed in the
102    tree view in that dialog under <guilabel>Plugin Options</guilabel>.
103    Clicking on the tree node for a plugin causes the corresponding set
104    of options to be displayed.
105  </para>
106  </listitem>
107</itemizedlist>
108
109<para>
110  As noted, many of these features are optional; it is possible to write
111  a plugin that does not provide actions, configuration options, or dockable
112  windows. The majority of plugins, however, provide most of these services.
113</para>
114
115<para>
116  In the following chapters, we will begin by briefly describing jEdit's
117  host capabilities, which includes the loading and display of plugins.
118  Next we will describe the principal classes and data structures that a
119  plugin must implement. Finally, we will outline the building of a modest
120  plugin, <quote>QuickNotepad</quote>, that illustrates the requirements and
121  some of the techniques of jEdit plugin design.
122</para>
123
124<sidebar><title>Plugins and different jEdit versions</title>
125  <para>
126    As jEdit continues to evolve and improve, elements of the plugin API or
127    jEdit's general API may change with a new jEdit release. For example,
128    version 4.0 of jEdit has simplified the design of a plugin by
129    placing code for the activation of a plugin's docking window in an
130    XML file rather than in a Java class. The use of a Java interface for
131    docking windows has been deprecated. We will explain this and other changes
132    in the plugin API for jEdit 4.0 when discussing the model QuickNotepad plugin.
133  </para>
134  <para>
135    On occasion an API change will break code used by plugins, although
136    efforts are made to maintain or deprecate plugin-related code on a
137    trasisional basis. possible. While the majority of plugins are
138    unaffected by most changes and will continue working, it is a good idea
139    to monitor the jEdit changelog, the mailing lists or <ulink
140    url="http://community.jedit.org">jEdit Community</ulink> for API changes
141    and update your plugin as necessary.
142  </para>
143</sidebar>
144
145</chapter>
146