PageRenderTime 18ms CodeModel.GetById 11ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

/jEdit/tags/jedit-4-5-pre1/doc/users-guide/plugin-tips.xml

#
XML | 160 lines | 149 code | 8 blank | 3 comment | 0 complexity | 4ccd8c54139f16f1b0aab8ed7f16f98a MD5 | raw file
  1<?xml version="1.0" encoding="UTF-8"?>
  2<chapter id="plugin-tips">
  3    <title>Plugin Tips and Techniques</title>
  4    <!-- jEdit buffer-local properties: -->
  5    <!-- :tabSize=1:indentSize=1:noTabs=true: -->
  6    <!-- :xml.root=users-guide.xml: -->
  7
  8    <section id="plugin-tips-libraries">
  9        <title>Bundling Additional Class Libraries</title>
 10
 11        <para>Recall that any class whose name ends with
 12        <classname>Plugin.class</classname> is called a plugin core class. JAR
 13        files with no plugin core classes are also loaded by jEdit; the classes
 14        they contain are made available to other plugins. Many plugins that rely
 15        on third-party class libraries ship them as separate JAR files. The
 16        libraries will be available inside the jEdit environment but are not
 17        part of a general classpath or library collection when running other
 18        Java applications.</para>
 19
 20        <para>A plugin that bundles extra JAR files must list them in the
 21        <filename>plugin.<replaceable>class name</replaceable>.jars</filename>
 22        property. See the documentation for the <ulink
 23        url="../api/org/gjt/sp/jedit/EditPlugin.html">
 24        <classname>EditPlugin</classname></ulink> class for details.</para>
 25    </section>
 26
 27    <section id="plugin-tips-non-java-libraries">
 28        <title>Bundling Additional Non-Java Libraries</title>
 29
 30        <para>If your plugin bundles non-Java files, like native libraries, you
 31        need to list them in the <filename>plugin.<replaceable>class
 32        name</replaceable>.files</filename> property. If you don't do so, they
 33        don't get deleted if the plugin is uninstalled. See the documentation
 34        for the <ulink url="../api/org/gjt/sp/jedit/EditPlugin.html">
 35        <classname>EditPlugin</classname></ulink> class for details.</para>
 36    </section>
 37
 38    <section id="plugin-tips-plugin-data">
 39        <title>Storing plugin data</title>
 40
 41        <para>If your plugin needs to create files and store data in the
 42        filesystem, you should use the <methodname>getPluginHome()</methodname>
 43        API of the <classname>EditPlugin</classname> class. To signal that you
 44        use the plugin home API you have to set the
 45        <filename>plugin.<replaceable>class
 46        name</replaceable>.usePluginHome</filename> property to
 47        <constant>true</constant>. Even if your plugin doesn't create any files,
 48        you should set the property to <constant>true</constant>, so that e. g.
 49        the plugin manager knows that there is actually no data in favor of not
 50        knowing if there is any data and thus displaying that it doesn't know
 51        the data size. See the documentation for the <ulink
 52        url="../api/org/gjt/sp/jedit/EditPlugin.html"><classname>EditPlugin</classname></ulink>
 53        class for details.</para>
 54    </section>
 55
 56    <section id="plugin-tips-colors">
 57     <title>Plugin colors</title>
 58     <para>There are a number of colors used by the View that should also be
 59        used by plugins where possible.  This helps promote a consistent color
 60        scheme throughout jEdit.
 61        </para><para>
 62        The main color properties are:
 63         </para>
 64         <itemizedlist>
 65          <listitem><para><literal>view.bgColor</literal> - the background color of the main text area</para></listitem>
 66          <listitem><para><literal>view.fgColor</literal> - the base foreground color for text in the main text area</para></listitem>
 67          <listitem><para><literal>view.lineHighlightColor</literal> - color of the current line highlight</para></listitem>
 68          <listitem><para><literal>view.selectionColor</literal> - the color of selected text in the main text area</para></listitem>
 69          <listitem><para><literal>view.caretColor</literal> - the color of the caret in the main text area</para></listitem>
 70          <listitem><para><literal>view.eolMarkerColor</literal> - the color of the end-of-line marker</para></listitem>
 71         </itemizedlist>
 72         <para>
 73        To use these colors in your plugin, use
 74        <programlisting>jEdit.getColorProperty("view.whatever", default_color)</programlisting>
 75        </para>
 76        <para>
 77        For example, the QuickNotepad example should have lines like this:
 78        </para>
 79        <programlisting>
 80        textarea.setBackground(jEdit.getColorProperty("view.bgColor", Color.WHITE);
 81        textarea.setForeground(jEdit.getColorProperty("view.fgColor", Color.BLACK);
 82        </programlisting><para>
 83        This sets the foreground and background colors of QuickNotepad to be the same
 84        as those in the View.
 85        </para>
 86        <para>
 87        There are other color properties that may be useful, depending on what your
 88        plugin displays.
 89        </para>
 90        <para>
 91        Gutter colors:
 92        </para><itemizedlist>
 93         <listitem><para><literal>view.gutter.bgColor</literal></para></listitem>
 94         <listitem><para><literal>view.gutter.currentLineColor</literal></para></listitem>
 95         <listitem><para><literal>view.gutter.fgColor</literal></para></listitem>
 96         <listitem><para><literal>view.gutter.focusBorderColor</literal></para></listitem>
 97         <listitem><para><literal>view.gutter.foldColor</literal></para></listitem>
 98         <listitem><para><literal>view.gutter.highlightColor</literal></para></listitem>
 99         <listitem><para><literal>view.gutter.markerColor</literal></para></listitem>
100         <listitem><para><literal>view.gutter.noFocusBorderColor</literal></para></listitem>
101         <listitem><para><literal>view.gutter.registerColor</literal></para></listitem>
102         <listitem><para><literal>view.gutter.structureHighlightColor</literal></para></listitem>
103         </itemizedlist>
104         <para>
105        Status bar colors:
106        </para>
107        <itemizedlist>
108          <listitem><para><literal>view.status.background</literal></para></listitem>
109          <listitem><para><literal>view.status.foreground</literal></para></listitem>
110          <listitem><para><literal>view.status.memory.background</literal></para></listitem>
111          <listitem><para><literal>view.status.memory.foreground</literal></para></listitem>
112         </itemizedlist>
113         <para>
114        </para><para>
115        Structure highlight colors:
116        </para><itemizedlist>
117         <listitem><para><literal>view.structureHighlightColor</literal></para></listitem>
118         <listitem><para><literal>view.structureHighlightColor</literal></para></listitem>
119         </itemizedlist>
120        <para>
121        Style colors.  Use <classname>GUIUtilities.parseStyle</classname> for these.
122        </para>
123        <itemizedlist>
124          <listitem><para><literal>view.style.comment1</literal></para></listitem>
125          <listitem><para><literal>view.style.comment2</literal></para></listitem>
126          <listitem><para><literal>view.style.comment3</literal></para></listitem>
127          <listitem><para><literal>view.style.comment4</literal></para></listitem>
128          <listitem><para><literal>view.style.digit</literal></para></listitem>
129          <listitem><para><literal>view.style.foldLine.0</literal></para></listitem>
130          <listitem><para><literal>view.style.foldLine.1</literal></para></listitem>
131          <listitem><para><literal>view.style.foldLine.2</literal></para></listitem>
132          <listitem><para><literal>view.style.foldLine.3</literal></para></listitem>
133          <listitem><para><literal>view.style.function</literal></para></listitem>
134          <listitem><para><literal>view.style.invalid</literal></para></listitem>
135          <listitem><para><literal>view.style.keyword1</literal></para></listitem>
136          <listitem><para><literal>view.style.keyword2</literal></para></listitem>
137          <listitem><para><literal>view.style.keyword3</literal></para></listitem>
138          <listitem><para><literal>view.style.keyword4</literal></para></listitem>
139          <listitem><para><literal>view.style.label</literal></para></listitem>
140          <listitem><para><literal>view.style.literal1</literal></para></listitem>
141          <listitem><para><literal>view.style.literal2</literal></para></listitem>
142          <listitem><para><literal>view.style.literal3</literal></para></listitem>
143          <listitem><para><literal>view.style.literal4</literal></para></listitem>
144          <listitem><para><literal>view.style.markup</literal></para></listitem>
145          <listitem><para><literal>view.style.operator</literal></para></listitem>
146          <listitem><para><literal>view.wrapGuideColor</literal></para></listitem>
147          </itemizedlist>
148          <para>
149        For example, here is a setting for a fold line color:
150        </para>
151        <programlisting>
152         view.style.foldLine.0=color\:\#000000 bgColor\:\#f5deb8 style\:b
153         </programlisting>
154         <para>
155        Passing the value to <classname>GUIUtilities.parseStyle</classname> will
156        return a SyntaxStyle object, which you can query for background color,
157        foreground color, and font.
158        </para>
159     </section>
160</chapter>