PageRenderTime 45ms CodeModel.GetById 19ms RepoModel.GetById 1ms app.codeStats 0ms

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

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