PageRenderTime 96ms CodeModel.GetById 77ms app.highlight 10ms RepoModel.GetById 1ms app.codeStats 1ms

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

#
XML | 909 lines | 752 code | 106 blank | 51 comment | 0 complexity | dd4d520aeca86e841725ecadaad60c9b 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 chapter of the jEdit 3.2 Plugin Guide               -->
  7<!-- describes the principal elements of the jEdit Plugin API -->
  8
  9<!-- $Id: plugin-api.xml 3898 2001-11-13 15:22:32Z jgellene $
 10-->
 11
 12
 13<chapter id="plugin-api"><title>The jEdit Plugin API</title>
 14
 15<sect1 id="plugin-classes"><title>Plugin Core Classes</title>
 16
 17<para>
 18    As mentioned earlier, a plugin must provide a
 19    <quote>plugin core class</quote>, otherwise it will not do anything
 20    useful (but recall that a class library intended for use by other
 21    plugins need not provide a plugin core class).
 22    That class must extend
 23    either <classname>EditPlugin</classname> or its convinience subclass,
 24    <classname>EBPlugin</classname>. We begin our review of the jEdit
 25    plugin API with these two classes.
 26</para>
 27
 28<sect2 id="class-EditPlugin"><title>Class EditPlugin</title>
 29
 30<para>
 31  This abstract class is the base for every plugin core class.  Its methods
 32  provide for basic interaction between the plugin and jEdit. The class
 33  has four methods which are called by jEdit at various times. None of
 34  these methods are required to be implemented, but most plugins will
 35  override at least one.
 36</para>
 37
 38<itemizedlist>
 39
 40  <listitem>
 41    <funcsynopsis>
 42      <funcprototype>
 43        <funcdef>public void <function>start</function></funcdef>
 44        <paramdef></paramdef>
 45      </funcprototype>
 46    </funcsynopsis>
 47    <para>
 48      The jEdit startup routine calls this method for each loaded
 49      plugin.  Plugins typically use this method to register information
 50      with the EditBus and perform other initialization.
 51    </para>
 52  </listitem>
 53
 54  <listitem>
 55    <funcsynopsis>
 56      <funcprototype>
 57        <funcdef>public void <function>stop</function></funcdef>
 58        <paramdef></paramdef>
 59      </funcprototype>
 60    </funcsynopsis>
 61    <para>
 62      When jEdit is exiting, it calls this method on each plugin. If a
 63      plugin uses
 64      or creates state information or other persistent data that should
 65      be stored in a special format, this would be a good place to write
 66      the data to storage. Note that most plugins will use jEdit's
 67      properties API to save settings, and the persistance of properties
 68      is handled automatically by jEdit and requires no special
 69      processing in the <function>stop()</function> method.
 70    </para>
 71  </listitem>
 72
 73  <listitem>
 74    <funcsynopsis>
 75      <funcprototype>
 76        <funcdef>public void <function>createMenuItems</function></funcdef>
 77        <paramdef>Vector <parameter>menuItems</parameter></paramdef>
 78      </funcprototype>
 79    </funcsynopsis>
 80    <para>
 81      When a <classname>View</classname> object is created, it calls this
 82      method on each plugin to obtain entries to be displayed in the view's
 83      <guimenu>Plugins</guimenu> menu. The
 84      <parameter>menuItems</parameter> parameter is a
 85      <classname>Vector</classname> that accumilates menu items and
 86      menus as it is passed from plugin to plugin.
 87    </para>
 88    <para>
 89      jEdit does not require a plugin to supply menu items. If menu
 90      items are desired, the easiest way to provide for them is to
 91      package the desired menu items as entries in the plugin's property
 92      file and implement <function>createMenuItems()</function> with a
 93      call to jEdit's <function>GUIUtilities.loadMenu()</function>
 94      method; for example:
 95    </para>
 96<informalexample><programlisting>public void createMenuItems(Vector menuItems)
 97{
 98    menuItems.addElement(GUIUtilities.loadMenu(
 99        "myplugin.menu"));
100}</programlisting></informalexample>
101
102    <para>
103      The parameter passed to <function>loadMenu()</function> is
104      the name of a property containing menu data.  We will explain the format
105      of the menu data in <xref linkend="plugin-implement-menu"/>
106    </para>
107
108    <para>
109      The <function>GUIUtilities.loadMenuItem()</function> method is also
110      available for plugins that only wish to add a single menu item to
111      the <guimenu>Plugins</guimenu> menu.
112    </para>
113  </listitem>
114
115  <listitem>
116    <funcsynopsis>
117      <funcprototype>
118        <funcdef>public void <function>createOptionPanes</function></funcdef>
119        <paramdef>OptionsDialog <parameter>dialog</parameter></paramdef>
120      </funcprototype>
121    </funcsynopsis>
122    <para>
123      This method is called for each plugin during the creation of
124      the <guilabel>Global Options</guilabel> dialog box.
125      To show an option pane, the plugin should define an
126      option pane class and implement <function>createOptionPane()</function>
127      as follows:
128    </para>
129<informalexample><programlisting>dialog.addOptionPane(new MyPluginOptionPane());</programlisting></informalexample>
130    <para>
131      Plugins can also define more than one option pane, grouped in an
132      <quote>option group</quote>.
133      We will discuss the design and elements of the option pane API
134      in <xref linkend="api-option-classes"/>.
135    </para>
136  </listitem>
137
138</itemizedlist>
139
140<para>
141 This class defines two other methods which may be useful to some
142 plugins, but are mainly of use to the jEdit core:
143</para>
144
145<itemizedlist>
146
147  <listitem>
148    <funcsynopsis>
149      <funcprototype>
150        <funcdef>public String <function>getClassName</function></funcdef>
151        <void/>
152      </funcprototype>
153    </funcsynopsis>
154    <para>
155      This shortcut method returns <function>getClass().getName()</function>.
156    </para>
157  </listitem>
158
159  <listitem>
160    <funcsynopsis>
161      <funcprototype>
162        <funcdef>public EditPlugin.JAR <function>getJAR</function></funcdef>
163        <void/>
164      </funcprototype>
165    </funcsynopsis>
166    <para>
167      This method returns the <classname>EditPlugin.JAR</classname> data
168      object associated with the plugin.
169    </para>
170  </listitem>
171
172</itemizedlist>
173
174</sect2>
175
176<sect2 id="class-EBPlugin"><title>Class EBPlugin</title>
177
178<para>
179  Every plugin core class class that uses the EditBus for receiving
180  messages
181  must extend this class. This class implements the
182  <classname>EBComponent</classname> interface, required for any
183  object that wishes to receive EditBus messages.
184</para>
185
186<para>
187  The <classname>EBComponent</classname> interface contains a single
188  method that an implementing class (including any class derived from
189  <classname>EBPlugin</classname>) must provide:
190</para>
191
192<itemizedlist>
193  <listitem>
194    <funcsynopsis>
195      <funcprototype>
196        <funcdef>public void <function>handleMessage</function></funcdef>
197        <paramdef>EBMessage <parameter>message</parameter></paramdef>
198      </funcprototype>
199    </funcsynopsis>
200  </listitem>
201</itemizedlist>
202
203<para>
204  The parameter's type, <classname>EBMessage</classname>, is another
205  abstract class which establishes the core elements of any message that
206  is published to the EditBus. It has two attributes: an
207  <classname>EBComponent</classname> that is the source of the message
208  (the source will be <type>null</type> in some cases),
209  and a <type>boolean</type> data member, <varname>vetoed</varname>. This
210  flag indicates whether a prior recipient of the message has determined
211  that the message has been handled and need not be passed on to other
212  subscribers. The flag is set by a call
213  to the <function>veto()</function> method of the
214  <classname>EBMessage</classname>. Some message classes, however,
215  are configured so that they cannot be vetoed, to ensure they are
216  received by all subscribers.
217</para>
218
219<para>
220  Message classes extending <classname>EBMessage</classname> typically add
221  other data members and methods to provide subscribers with whatever is
222  needed to handle the message appropriately. Descriptions of specific
223  message classes can be found in <xref linkend="api-message"/>.
224</para>
225
226<para>
227  The <function>handleMessage()</function> method
228  must specify the type of responses
229  the plugin will have for various subclasses of the
230  <classname>EBMessage</classname> class. Typically this is done with
231  one or more <function>if</function> blocks that test whether the message
232  is an instance of a derived message class in which the plugin has an
233  interest, for example like so:
234</para>
235
236<informalexample><programlisting>if(msg instanceof CreateDockableWindow)
237    // create dockable window, if necessary
238else if(msg instanceof BufferUpdate)
239    // a buffer's state has changed!
240else if(msg instanceof ViewUpdate)
241    // a view's state has changed!
242// ... and so on</programlisting></informalexample>
243
244<para>
245  If a plugin defines dockable windows, it should respond to a
246  <classname>CreateDockableWindow</classname> message by creating the
247  appropriate user interface objects and setting the relevant data
248  field in the message, for example like so:
249</para>
250
251<informalexample><programlisting>if(msg instanceof CreateDockableWindow)
252{
253    CreateDockableWindow cmsg = (CreateDockableWindow)msg;
254    if(cmsg.getDockableWindowName().equals("myplugin"))
255        cmsg.setDockableWindow(new MyPluginWindow());
256}</programlisting></informalexample>
257<para>
258  Note that any object, whether or not derived from
259  <classname>EBComponent</classname>, can send a message to the EditBus
260  by calling the static method <function>EditBus.send()</function>.
261  This method takes a single parameter, an <classname>EBMessage</classname>
262  object that is the message being sent. Most plugins, however, will
263  only concern themselves with receiving, not sending, messages.
264</para>
265
266</sect2>
267
268</sect1>
269
270<sect1 id="class-dockablewindow"><title>Interface DockableWindow</title>
271
272<para>
273  The dockable plugin API consists of a single interface,
274  <classname>DockableWindow</classname>. It links the visible
275  components of a plugin with the dockable window management facility. The
276  interface gives developers flexibility and minimizes code refactoring,
277  for it can be implemented as part of the plugin's top-level display
278  window or in a separate lightweight class. The dockable window API
279  handles the display of windows as either docked or floating
280  without specific direction from the plugin.
281</para>
282
283<!-- <para>
284  The <classname>DockableWindowContainer</classname> class is also used
285  by the API behind the scenes. Most plugins will not need to know about this
286  class.
287</para>
288
289<sect2 id="class-DockableWindow"><title>Interface DockableWindow</title> -->
290
291<para>
292  This interface provides the connection between the plugin's visible
293  components and a top-level <classname>View</classname> object of the
294  host application. As mentioned earlier, the plugin window class
295  implementing this interface must be created by the plugin core class in
296  response to a <classname>CreateDockableWindow</classname> message.
297  After its creation, the plugin window object is attached to the
298  message for routing back to jEdit.
299</para>
300
301<para>
302  The <classname>DockableWindow</classname> interface contains two
303  methods that must be implemented by a derived plugin window class:
304</para>
305
306<itemizedlist>
307
308<listitem>
309  <funcsynopsis>
310    <funcprototype>
311      <funcdef>String <function>getName</function></funcdef>
312      <paramdef></paramdef>
313    </funcprototype>
314  </funcsynopsis>
315  <para>
316    This method should return the internal working name of the
317    plugin window, used to key various properties.
318  </para>
319</listitem>
320
321<listitem>
322  <funcsynopsis>
323    <funcprototype>
324      <funcdef>Component <function>getComponent</function></funcdef>
325      <paramdef></paramdef>
326    </funcprototype>
327  </funcsynopsis>
328  <para>
329    This method should return the top-level visible component of the
330    plugin.
331    Typically this component is a <classname>JPanel</classname> containing
332    other components, but any object derived from the Java
333    <classname>Component</classname> class will suffice. If the
334    top-level component implements the <classname>DockableWindow</classname>
335    interface, so that the plugin window and the top-level visible window
336    are implemented in the same class, the implementation of
337    <function>getComponent()</function> would simply return
338    <varname>this</varname>.
339  </para>
340</listitem>
341
342</itemizedlist>
343
344<!-- <sect2 id="class-DockableDindowContainer">
345<title>Interface DockableWindowContainer</title>
346
347<para>
348  Depending upon the settings chosen by the user, the jEdit Plugin API
349  will place the <classname>Component</classname> returned by the
350  <function>DockableWindow.getComponent()</function> method in a floating frame
351  window or in a tabbed window at the designated docking location. Both
352  types of containing windows implement the interface
353  <classname>DockableWindowContainer</classname> and are managed entirely
354  by the host application.
355</para>
356
357<itemizedlist>
358
359  <listitem>
360    <para>
361      The <classname>DockableWindowContainer.Floating</classname> class is
362      derived from <classname>JFrame</classname> and uses a
363      <classname>BorderLayout</classname>.  The plugin window's component is
364      placed in the center position of the frame's content pane.
365    </para>
366  </listitem>
367
368  <listitem>
369    <para>
370      The <classname>DockableWindowContainer.TabbedPane</classname> class is
371      derived from <classname>JTabbedPane</classname>. Here the plugin
372      window's component is added to the container's collection of tabbed
373      components.
374    </para>
375  </listitem>
376
377</itemizedlist>
378
379</sect2> -->
380
381</sect1>
382
383<sect1 id="api-option-classes"><title>Plugin Option Pane Classes</title>
384
385<para>
386  The plugin API provides a mechanism for displaying a plugin's
387  configuration options in the <guilabel>Global
388  Options</guilabel> dialog. A plugin that allows user configuration
389  should provide one or more implementations of
390  jEdit's <classname>OptionPane</classname> interface to have
391  configuration options displayed in a manner consistent wth the rest of
392  the application.
393</para>
394
395<sect2 id="class-AbstractOptionPane"><title>Class AbstractOptionPane</title>
396
397<para>
398  Most plugin option panes extend this implementation of
399  <classname>OptionPane</classname>, instead of implementing
400  <classname>OptionPane</classname> directly. It provides
401  a convenient default framework for laying out configuration options in
402  a manner similar to the option panes created by jEdit itself.
403  It is derived from Java's <classname>JPanel</classname> class and
404  contains a <classname>GridBagLayout</classname> object for component
405  management. It also contains shortcut methods to simplify layout.
406</para>
407
408<para>
409  The constructor for a class derived from
410  <classname>AbstractOptionPane</classname> should
411  call the parent constructor and pass the option pane's <quote>internal
412  name</quote> as a
413  parameter. The internal name is used to key a property where the
414  option pane's label is stored; see
415  <xref linkend="api-resource-properties" />.
416  It should also implement two methods:
417</para>
418
419<itemizedlist>
420  <listitem>
421    <funcsynopsis>
422      <funcprototype>
423        <funcdef>protected void <function>_init</function></funcdef>
424        <paramdef></paramdef>
425      </funcprototype>
426    </funcsynopsis>
427    <para>
428      This method should create and arrange the components of the option pane
429      and initialize the option data displayed to the user. This method
430      is called when the option pane is first displayed, and is not
431      called again for the lifetime of the object.
432    </para>
433  </listitem>
434
435  <listitem>
436    <funcsynopsis>
437      <funcprototype>
438        <funcdef>protected void <function>_save</function></funcdef>
439        <paramdef></paramdef>
440      </funcprototype>
441    </funcsynopsis>
442    <para>
443      This method should save any settings, to the jEdit properties or
444      other data store.
445    </para>
446  </listitem>
447
448</itemizedlist>
449
450<para>
451  <classname>AbstractOptionPane</classname> also contains three shortcut
452  methods, typically called from <function>_init()</function>,
453  for adding components to the option pane:
454</para>
455
456<itemizedlist>
457    <listitem>
458      <funcsynopsis>
459        <funcprototype>
460          <funcdef>protected void <function>addComponent</function></funcdef>
461          <paramdef>String <parameter>label</parameter></paramdef>
462          <paramdef>Component <parameter>comp</parameter></paramdef>
463        </funcprototype>
464      </funcsynopsis>
465    </listitem>
466
467    <listitem>
468      <funcsynopsis>
469        <funcprototype>
470          <funcdef>protected void <function>addComponent</function></funcdef>
471          <paramdef>Component <parameter>comp</parameter></paramdef>
472        </funcprototype>
473      </funcsynopsis>
474      <para>
475        These shortcut methods add components to the option pane in a
476        single vertical column, running top to bottom.  The first
477        displays the text of the <parameter>label</parameter> parameter
478        to the left of the <classname>Component</classname> represented
479        by <parameter>comp</parameter>.
480      </para>
481    </listitem>
482
483    <listitem>
484      <funcsynopsis>
485        <funcprototype>
486          <funcdef>protected void <function>addSeparator</function></funcdef>
487          <paramdef>String <parameter>label</parameter></paramdef>
488        </funcprototype>
489      </funcsynopsis>
490      <para>
491        This is another shortcut method that adds a text label between
492        two horizontal separators to the option pane.
493        The <parameter>label</parameter> parameter represents the name
494        of a property (typically a property defined in the plugin's
495        property file) whose value will be used as the separator text.
496      </para>
497    </listitem>
498
499</itemizedlist>
500
501
502</sect2>
503
504<sect2 id="class-OptionGroup"><title>Class OptionGroup</title>
505
506<para>
507  In those cases where a single option pane is inadequate to present all
508  of a plugin's configuration options, this class can be used to create a
509  group of options panes. The group will appear as a single node in the
510  options dialog tree-based index. The member option panes will appear as
511  leaf nodes under the group's node.  Threee simple methods create and
512  populate an option pane:
513</para>
514
515<itemizedlist>
516
517  <listitem>
518    <funcsynopsis>
519      <funcprototype>
520        <funcdef>public <function>OptionGroup</function></funcdef>
521        <paramdef>String <parameter>name</parameter></paramdef>
522      </funcprototype>
523    </funcsynopsis>
524    <para>
525      The constructor's single parameter represents the internal
526      name of the option group. The internal name is used to key a
527      property where the option group's label is stored; see
528      <xref linkend="api-resource-properties" />.
529    </para>
530  </listitem>
531
532  <listitem>
533    <funcsynopsis>
534      <funcprototype>
535        <funcdef>public void <function>addOptionPane</function></funcdef>
536        <paramdef>OptionPane <parameter>pane</parameter></paramdef>
537      </funcprototype>
538    </funcsynopsis>
539  </listitem>
540
541  <listitem>
542    <funcsynopsis>
543      <funcprototype>
544        <funcdef>public void <function>addOptionGroup</function></funcdef>
545        <paramdef>OptionGroup <parameter>group</parameter></paramdef>
546      </funcprototype>
547    </funcsynopsis>
548    <para>
549      This pair of methods adds members to the option group.  The second
550      method enables option groups to be nested, for plugins with a
551      particularly large set of configurable options.
552    </para>
553  </listitem>
554
555</itemizedlist>
556
557</sect2>
558
559</sect1>
560
561<sect1 id="api-other-resources"><title>Other Plugin Resources</title>
562
563<para>
564  There are four other types of files containing resources used by a
565  plugin:
566</para>
567
568<itemizedlist>
569  <listitem>
570    <para>
571      a file named <filename>dockables.xml</filename> contained the
572      name of the plugin and the code for costructing an instance of the
573      plugin's docking window component, set forth in a specified XML
574      format;
575    </para>
576  </listitem>
577  <listitem>
578    <para>
579      a catalog of the plugin's user actions in a specified XML format,
580      contained in a file named <filename>actions.xml</filename>;
581    </para>
582  </listitem>
583  <listitem>
584    <para>
585      one or more properties files named with a <filename>.props</filename>
586      extension, each containing key-value pairs in conventional Java
587      format; and
588    </para>
589  </listitem>
590  <listitem>
591    <para>
592      a help file written in HTML format. The name of this file must be
593      specified in a property; see <xref
594      linkend="api-resource-properties" />.
595    </para>
596  </listitem>
597</itemizedlist>
598
599<!-- open sect2 -->
600<sect2 id="api-resources-activation"><title>The Activation Data File</title>
601
602<para>
603  [To be supplied]
604</para>
605
606
607</sect2>
608
609<sect2 id="api-resources-action"><title>The Action Catalog</title>
610
611<para>
612  Actions define procedures that can be bound to a menu
613  item, a toolbar button or a keyboard shortcut. They can perform any
614  task encompassed in a public method of any class currently loaded in
615  jEdit, including plugin classes and classes of the host application.
616  Among other things, they can cause the appearance and disappearance of
617  plugin windows.
618</para>
619
620<para>
621  To manage user actions, jEdit maintains a lookup table of actions
622  using descriptive strings as keys.  The values in the table are
623  sets of statements written in BeanShell, jEdit's macro scripting
624  language.  These scripts either direct the action themselves,
625  delegate to a method in one of the plugin's classes that
626  encapsulates the action, or do a little of both.  The scripts are
627  usually short; elaborate action protocols are usually contained in
628  compiled code, rather than an interpreted macro script, to speed
629  execution.
630</para>
631
632<para>
633  Actions are defined by creating an XML file entitled
634  <filename>actions.xml</filename> at the top level of the plugin JAR
635  file. A sample action catalog looks like so:
636</para>
637
638<informalexample><programlisting>&lt;!DOCTYPE ACTIONS SYSTEM "actions.dtd"&gt;
639
640&lt;ACTIONS&gt;
641    &lt;ACTION NAME="quicknotepad.toggle"&gt;
642        &lt;CODE&gt;
643            view.getDockableWindowManager()
644                .toggleDockableWindow(QuickNotepadPlugin.NAME);
645        &lt;/CODE&gt;
646        &lt;IS_SELECTED&gt;
647            return view.getDockableWindowManager()
648                .isDockableWindowVisible(QuickNotepadPlugin.NAME);
649        &lt;/IS_SELECTED&gt;
650    &lt;/ACTION&gt;
651
652    &lt;ACTION NAME="quicknotepad-to-front"&gt;
653    &lt;CODE&gt;
654      view.getDockableWindowManager()
655                .addDockableWindow(QuickNotepadPlugin.NAME);
656        &lt;/CODE&gt;
657    &lt;/ACTION&gt;
658&lt;/ACTIONS&gt;</programlisting></informalexample>
659
660<para>
661  The defined elements have the following functions:
662</para>
663
664<itemizedlist>
665  <listitem>
666    <para>
667      <varname>ACTIONS</varname> is the top-level element and refers
668      to the set of actions used by the plugin.
669    </para>
670  </listitem>
671  <listitem>
672    <para>
673      An <varname>ACTION</varname> contains the data for a particular action.
674      It has three attributes: a required <varname>NAME</varname>;
675      an optional <varname>NO_REPEAT</varname>, which is a flag
676      indicating whether the action should not be repeated with the
677      <keycombo><keycap>Control</keycap><keycap>Enter</keycap></keycombo>
678      command (see <xref linkend="repeat" />); and an optional
679      <varname>NO_RECORD</varname> which is a a flag indicating whether the
680      action should be recorded if it is invoked while a user is recording a
681      macro. The two flag attributes
682      can have two possible values, <quote>TRUE</quote> or
683      <quote>FALSE</quote>. In both cases, <quote>FALSE</quote> is the
684      default if the attribute is not specified.
685    </para>
686  </listitem>
687  <listitem>
688    <para>
689      An <varname>ACTION</varname> can have two child elements
690      within it: a required <varname>CODE</varname> element which
691      specifies the
692      BeanShell code that will be executed when the action is invoked,
693      and an optional <varname>IS_SELECTED</varname> element, used for
694      checkbox
695      menu items.  The <varname>IS_SELECTED</varname> element contains
696      BeanShell code that returns a boolean flag that will
697      determine the state of the checkbox.
698    </para>
699  </listitem>
700</itemizedlist>
701
702<para>
703 More discussion of the action catalog can be found in <xref
704 linkend="plugin-implement-actions" />.
705</para>
706
707</sect2>
708
709<sect2 id="api-resource-properties"><title>Plugin Properties</title>
710
711<para>
712  jEdit maintains a list of <quote>properties</quote>, which are
713  name/value pairs used to store human-readable strings, user settings,
714  and various other forms of meta-data. During startup, jEdit loads the
715  default set of properties, followed by plugin properties stored in
716  plugin JAR files, finally followed by user properties. Plugins can
717  access properties from all three sources.
718</para>
719
720<para>
721  Property files contained in plugin JARs must end with the filename
722  extension <filename>.props</filename>, and have a very simple syntax,
723  which the following example suffices to describe:
724</para>
725
726<informalexample><programlisting># Lines starting with '#' are ignored.
727name=value
728another.name=another value
729long.property=Long property value, split over \
730    several lines
731escape.property=Newlines and tabs can be inserted \
732    using the \t and \n escapes
733backslash.property=A backslash can be inserted by writing \\.</programlisting>
734</informalexample>
735
736<para>
737  The following types of plugin information
738  are supplied using properties:
739</para>
740
741<itemizedlist>
742  <listitem>
743    <para>
744      Information regarding the name, author, and version of the plugin.
745      This information is required. Here is an example:
746    </para>
747    <informalexample><programlisting>plugin.MyPlugin.name=My Plugin
748plugin.MyPlugin.author=Joe Random Hacker
749plugin.MyPlugin.version=1.0.3</programlisting></informalexample>
750    <para>
751      Note that each property is prefixed with
752      <literal>plugin.</literal>, followed by the fully qualified name
753      of the plugin core class (including a package name, if there is
754      one).
755    </para>
756  </listitem>
757  <listitem>
758    <para>
759      Identification of any dependencies the plugin may have on a
760      particular version of a Java runtime environment, the jEdit
761      application, or other plugins.
762    </para>
763    <para>
764      Each dependency is defined in a property prefixed with
765      <literal>plugin.<replaceable>class name</replaceable>.depend.</literal>,
766      followed by a number. Dependencies must be numbered in order,
767      starting from zero.
768    </para>
769    <para>
770      The value of a dependency property is one of the words
771      <literal>jdk</literal>, <literal>jedit</literal>,
772      <literal>class</literal> or <literal>plugin</literal>,
773      followed by a Java version number, a jEdit build number, a class
774      name, or plugin class name and plugin version number,
775      respectively.
776    </para>
777    <para>
778      Here are some examples:
779    </para>
780    <informalexample><programlisting>plugin.MyPlugin.depend.0=jdk 1.2
781plugin.MyPlugin.depend.1=jedit 03.02.97.00
782plugin.MyPlugin.depend.2=class com.ice.tar.tar
783plugin.MyPlugin.depend.3=plugin console.ConsolePlugin 3.0</programlisting>
784</informalexample>
785
786  </listitem>
787
788  <listitem>
789    <para>
790      A list of external class library JARs shipped with the plugin.
791      If your plugin bundles extra JARs, this property is required
792      for the plugin manager to be able to remove the plugin completely.
793    </para>
794    <para>
795      The property is a space-separated list of filenames. Here is an
796      example:
797    </para>
798    <informalexample><programlisting>plugin.AntFarmPlugin.jars=crimson.jar jaxp.jar</programlisting></informalexample>
799  </listitem>
800
801  <listitem>
802    <para>
803      The titles of dockable windows, as displayed in a tabbed or
804      floating container.
805    </para>
806    <para>
807      These labels are specified in properties named by the return value
808      of the dockable window's <function>getName()</function> method,
809      suffixed with <literal>.title</literal>. For example:
810    </para>
811<informalexample><programlisting>quick-notepad.title=QuickNotepad</programlisting>
812</informalexample>
813  </listitem>
814  <listitem>
815    <para>
816      Labels for user actions for inclusion in menus and option panes
817      relating to toolbars and keyboard shortcuts.
818    </para>
819    <para>
820      Action labels are defined in properties named by the
821      action's internal name as specified in the action catalog,
822      followed by <literal>.label</literal>:
823    </para>
824<informalexample><programlisting>myplugin.label=My Plugin
825myplugin-grok.label=Grok Current Buffer</programlisting>
826</informalexample>
827  </listitem>
828  <listitem>
829    <para>
830      The list of menu items contained in plugin menus, if any.
831    </para>
832    <para>
833      This is discussed in detail in <xref
834      linkend="plugin-implement-menu" />.
835    </para>
836  </listitem>
837  <listitem>
838    <para>
839      Labels and other information regarding the controls contained in
840      the plugin's windows. These properties can be named any way you
841      like, however take care not to choose names which may conflict
842      with those in other plugins.
843    </para>
844  </listitem>
845</itemizedlist>
846
847</sect2>
848
849<sect2 id="api-resources-help"><title>Plugin Documentation</title>
850
851<para>
852  While not required by the plugin API, a help file is an essential
853  element of any plugin written for public release. A single web page is
854  often all that is required. There are no specific requirements on
855  layout, but because of the design of jEdit's help viewer, the use of
856  frames should be avoided. Topics that would be useful include
857  the following:
858</para>
859
860<itemizedlist>
861  <listitem>
862    <para>
863      a description of the purpose of the plugin;
864    </para>
865  </listitem>
866  <listitem>
867    <para>
868      an explanation of the type of input the user can supply through its
869      visible interface (such as mouse action or text entry in controls);
870    </para>
871  </listitem>
872  <listitem>
873    <para>
874      a listing of available user actions that can be taken when the
875      plugin does not have input focus;
876    </para>
877  </listitem>
878  <listitem>
879    <para>
880      a summary of configuration options;
881    </para>
882  </listitem>
883  <listitem>
884    <para>
885      information on development of the plugin (such as a change log,
886      a list of <quote>to do</quote> items, and contact information for
887      the plugin's author); and
888    </para>
889  </listitem>
890  <listitem>
891    <para>
892      licensing information, including acknowledgements for any library
893      software used by the plugin.
894    </para>
895  </listitem>
896</itemizedlist>
897
898<para>
899 The location of the plugin's help file should be stored in the
900 <literal>plugin.<replaceable>class name</replaceable>.docs</literal>
901 property.
902</para>
903
904</sect2>
905
906</sect1>
907
908</chapter>
909