1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="plugin-intro">
<title>Introducing the Plugin API</title>
<!-- :indentSize=1:tabSize=2:noTabs=true:wrap=soft:maxLineLen=0: -->
<!-- :xml.root=users-guide.xml: -->
<!-- jEdit buffer-local properties: -->
<indexterm>
<primary>Plugin API</primary>
<secondary>introduction</secondary>
</indexterm>
<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 an 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<footnote>
<para>You should test your plugin by loading and unloading
it from both the Plugin Manager, as well as the <emphasis
role="bold">Activator Plugin</emphasis>.</para>
</footnote>. Make sure you can continue to use both your plugin
and the editor after it has been reloaded.</para>
</listitem>
<listitem>
<para>Each Plugin has an ActionSet defined by jEdit, which is added
to the main ActionContext. The ActionSet is a container for
EditAction instances. The plugin may define
<firstterm>actions</firstterm> in a number of ways. One way is
explicitly, with an action definition file known as
<literal>actions.xml</literal>. Another is implicitly, by defining
dockable windows in <literal>dockables.xml</literal>.</para>
<para>Most EditActions 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. Plugin authors do not define specific
shortcuts - the user can/will assign EditActions to keyboard
shortcuts, toolbar buttons, or entries in the text area's Context
menu (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). These
plugins are dependent on the JEditTextArea class, which is currently
getting refactored.</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 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, and join the <literal>jedit-devel</literal> mailing list, to keep updated on changes and bug reports, so that you will know when your
plugin needs to be updated.
</para>
</sidebar>
</chapter>
|
