PageRenderTime 105ms CodeModel.GetById 80ms app.highlight 7ms RepoModel.GetById 13ms app.codeStats 0ms

/bundles/plugins-trunk/SideKick/users-guide.xml

#
XML | 448 lines | 368 code | 78 blank | 2 comment | 0 complexity | 543b9903c13a2895538c8516f388b37c MD5 | raw file
  1<?xml version="1.0" encoding="utf-8"?>
  2<book xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  3    xsi:noNamespaceSchemaLocation='http://www.docbook.org/xsd/4.4/docbook.xsd' >
  4<!-- jEdit buffer-local properties: -->
  5<!-- :indentSize=2:noTabs=true:folding=sidekick: -->
  6  <bookinfo>
  7    <title>SideKick plugin user's guide</title>
  8
  9
 10    <authorgroup>
 11      <author>
 12        <firstname>Slava</firstname>
 13        <surname>Pestov</surname>
 14      </author>
 15      <author>
 16        <firstname>Dale</firstname>
 17        <surname>Anson</surname>
 18      </author>
 19      <author>
 20        <firstname>Martin</firstname>
 21        <surname>Raspe</surname>
 22      </author>
 23      <author>
 24        <firstname>Alan</firstname>
 25        <surname>Ezust</surname>
 26      </author>
 27      <author>
 28        <firstname>Shlomy</firstname>
 29        <surname>Reinstein</surname>
 30      </author>
 31    </authorgroup>
 32
 33    <legalnotice>
 34      <title>Legal Notice</title>
 35      <para>
 36   Permission is granted to copy, distribute and/or modify this document
 37   under the terms of the GNU Free Documentation License, Version 1.1 or
 38   any later version published by the Free Software Foundation; with no
 39   <quote>Invariant Sections</quote>, <quote>Front-Cover Texts</quote> or
 40   <quote>Back-Cover Texts</quote>, each as defined in the license. A copy of
 41   the license can be found in the file <filename>COPYING.DOC.txt</filename>
 42   included with jEdit.
 43  </para>
 44      <para>
 45   The SideKick plugin itself is released under the GNU General Public License.
 46   A copy of the GPL can be found in the jEdit online help.
 47  </para>
 48    </legalnotice>
 49  </bookinfo>
 50
 51  <chapter id="browser">
 52    <title>The SideKick dockable</title>
 53
 54    <para>
 55  The SideKick plugin provides a dockable in which other plugins can
 56  display buffer structure.
 57 </para>
 58
 59    <para>
 60      <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>SideKick</guimenuitem> displays the current buffer's structure in a dockable window. This window is floating by default, but it can be docked into the view 2 ways.
 61  </para>
 62    <orderedlist>
 63      <listitem>
 64        <para> Choosing a docking area from the docking menu (a little arrow in the upper left corner of each floating dockable)</para>
 65      </listitem>
 66      <listitem>
 67        <para> Go to the <guibutton>Docking</guibutton>
 68  pane of the <guimenuitem>Global Options</guimenuitem> dialog box </para>
 69      </listitem>
 70    </orderedlist>
 71
 72    <para> On the top of the window, you will see a combobox which lists all installed SideKick parsers. You can switch to another parser temporarily for a buffer by selecting it from the combo box. </para>
 73
 74    <para>
 75  The SideKick plugin can automatically parse your buffer depending on various events, such as: Buffer Switch, Buffer Save, or on the fly (after it is idle for a period of time). The last option is rarely used since it can eat up CPU time, so it is disabled by default. </para>
 76    <para>
 77      <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>Parse
 78  on Keystroke</guimenuitem> is a checkbox menu item that toggles on-the-fly  parsing, for the current buffer only.
 79 </para>
 80
 81
 82    <para> You can also manually parse a buffer by clicking on the "Parse" button in the Sidekick dockable, or through a keyboard shortcut, if you bind Sidekick's "parse buffer" action to a keystroke. <footnote><para>
 83  global options - jedit - Shortcuts - Plugin: Sidekick (combo) - Parse Buffer</para>
 84      </footnote>
 85    </para>
 86
 87    <para>
 88  The current buffer can be parsed at any other time by clicking the parse
 89  button in the <guimenuitem>Sidekick</guimenuitem> window, or by
 90  invoking the
 91  <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>Parse
 92  Buffer</guimenuitem> command.
 93 </para>
 94
 95    <tip>
 96      <title> Parse button menu </title>
 97      <para> A popup menu is available in JDK 1.5 which
 98 appears when you right-click the "Parse" button.
 99 From there, you can set some auto-parse options
100 without going to the plugin options. </para>
101    </tip>
102
103    <tip>
104      <title> Mode Options </title>
105      <para> SideKick supports what are called "Mode Options". Certain properties can be set on an edit-mode basis, such as the SideKick parser, tree expansion depth, etc. Other plugins (such as CtagsSideKick) added their own optionpane to this dialog, via the
106 services API. </para>
107    </tip>
108
109    <tip>
110      <title> Filter textfield </title>
111      <para>
112 Also at the top of the window is a "Filter" box.  Entering text into the box will cause the tree to collapse to show only those items in the tree whose names contain the text in the filter box.  This makes it easy to quickly locate items in the tree.  By default, clicking on an item in the tree clears the filter, but this can be changed in the SideKick plugin option settings by using the "Filter persists after tree selection" checkbox.
113 </para>
114
115      <para>
116 You don't have to click into the filter box to begin typing. As long as SideKick has focus, keystrokes are automatically sent to the box to make locating items even faster.
117 </para>
118    </tip>
119
120    <para>
121  Any errors found while parsing the buffer are sent to the
122  <application>ErrorList</application> plugin, which means they are highlighted
123  in the text area, and shown in the
124  <guimenu>Plugins</guimenu>&gt;<guisubmenu>Error
125  List</guisubmenu>&gt; window. See the
126  documentation for the <application>ErrorList</application> plugin for details.
127 </para>
128
129    <para>
130  Clicking on a node in the tree will move the caret to its location in the
131  buffer;
132  conversely, moving the caret in the buffer will select the corresponding
133  node.
134 </para>
135
136    <para>
137      <keycap>Shift</keycap>-clicking on a node will select that node in the text
138  area. <keycap>Alt</keycap>-clicking on a node will narrow the text area
139  display to that node.
140 </para>
141
142    <para>
143  If SideKick is docked into the current view, hovering the mouse
144  over a node will display its attributes in the status bar.
145 </para>
146
147  </chapter>
148
149  <chapter id="moving-around">
150    <title>Moving around</title>
151
152    <para>
153      <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>Go
154  to Previous Asset</guimenuitem> moves the caret to start of the structure
155  element (<quote>asset</quote>).
156 </para>
157
158    <para>
159      <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>Go
160  to Next Asset</guimenuitem> moves the caret to start of the next asset. 
161 </para>
162
163 <para>
164      <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>Select
165  Asset at Caret</guimenuitem> selects the asset at the caret position.
166 </para>
167
168  <bridgehead> Keyboard Shortcuts </bridgehead>
169    <itemizedlist>
170      <listitem><para> Up and Down arrow keys let you navigate between sibling nodes,
171      or to parents/children of exploded nodes. </para></listitem>
172      <listitem><para> Ctrl+Up and Ctrl+Down keys go to previous/next asset. 
173      </para></listitem>
174      <listitem><para> Right and Left arrow keys expand and collapse tree nodes. 
175      </para></listitem>  
176    </itemizedlist>
177  </chapter>
178
179  <chapter id="toolbar">
180    <title>Toolbar</title>
181    
182    <para>
183  SideKick can optionally display the structure of the buffer in a toolbar, using
184  one or more combo-boxes. This option is useful where screen real-estate is
185  important and the tree takes too much of the screen. To use this option, select
186      <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;
187      <guisubmenu>General</guisubmenu>&gt;<guimenuitem>Show the assets in a
188      combo-box (inside a toolbar)</guimenuitem>.
189  By default, a single combo-box is shown, which can be used to jump to various
190  positions inside the buffer.
191    </para>
192    <para>
193  There is also an option to show a separate check-box for each level in the
194  SideKick tree. To use this option, select
195      <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;
196      <guisubmenu>General</guisubmenu>&gt;<guimenuitem>Use a separate combo-box
197      for each level of the tree</guimenuitem>.
198    </para>
199    <para>
200  To make the combo-box (or multiple combo-boxes) show the asset where the caret is
201  currently located, select
202      <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;
203      <guisubmenu>General</guisubmenu>&gt;<guimenuitem>Tree/combo-box selection
204      follows caret position</guimenuitem>.
205    </para>
206  
207  </chapter>
208
209  <chapter id="folding">
210    <title>Folding</title>
211
212    <para>
213  The SideKick plugin adds a new <quote>sidekick</quote> fold handler that
214  folds the buffer according to the structure tree. See the jEdit user's guide
215  for general details about folding.
216</para>
217
218    <para>
219      <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>Narrow to
220  Asset at Caret</guimenuitem> hides all text except that of the asset at the
221  caret location. This works in any folding mode, not just the <quote>sidekick</quote>
222  mode.
223 </para>
224  </chapter>
225
226  <chapter id="completion">
227    <title>Completion</title>
228
229    <para>
230  A completion popup can be shown at any time
231  by invoking the
232  <guimenu>Plugins</guimenu>&gt;<guisubmenu>SideKick</guisubmenu>&gt;<guimenuitem>Show
233  Completion Popup</guimenuitem> command. Each plugin that uses SideKick
234  implements its own specific completion behavior; see the plugin documentation
235  for details.
236 </para>
237
238  </chapter>
239
240  <chapter id="other-plugins">
241    <title>Developing SideKick back-ends</title>
242
243    <para>
244  By itself the SideKick plugin is not very useful; it relies on other plugins to
245  provide buffer structure information. This chapter gives a brief overview of
246  how it's done.
247 </para>
248
249    <sect1 id="preliminaries">
250      <title>Preliminaries</title>
251
252      <para>
253  First you will also need to add a dependency for the SideKick plugin in your plugin's
254  property file:
255 </para>
256
257      <programlisting>plugin.MyPlugin.depend.<replaceable>n</replaceable>=plugin sidekick.SideKickPlugin 0.1</programlisting>
258
259      <para>
260  Note that you must replace <replaceable>n</replaceable> with the
261  appropriate number, as dependency properties must have consecutive numbers.
262 </para>
263
264      <para>
265  All SideKick plugin classes are in the <classname>sidekick</classname> package;
266  you will need to add <literal>import</literal> statements where appropriate.
267 </para>
268
269      <para>
270   Parser instances must be registered using the
271   <literal>services.xml</literal> file. With this, you define a service which
272   returns a derived instance of <ulink url="jeditresource:/Sidekick.jar!/docs/api/sidekick/SideKickParser.html">
273      <classname>SideKickParser</classname>
274        </ulink>
275      </para>
276
277      <programlisting>
278&lt;?xml version=&quot;1.0&quot;?&gt;
279
280&lt;!DOCTYPE SERVICES SYSTEM &quot;services.dtd&quot;&gt;
281
282&lt;SERVICES&gt;
283        &lt;SERVICE CLASS=&quot;sidekick.SideKickParser&quot; NAME=&quot;xml&quot;&gt;
284                new xml.parser.SAXParserImpl();
285        &lt;/SERVICE&gt;
286&lt;/SERVICES&gt;
287</programlisting>
288
289    </sect1>
290
291    <sect1 id="class-sidekickparser">
292      <title>The SideKickParser class</title>
293
294      <para>
295        <ulink url="jeditresource:/Sidekick.jar!/docs/api/sidekick/SideKickParser.html">
296          <classname>SideKickParser</classname>
297        </ulink> is an abstract class. The constructor takes one string parameter. This string is used in several properties:
298 </para>
299
300      <itemizedlist>
301        <listitem>
302          <para>
303            <literal>sidekick.parser.<replaceable>name</replaceable>.label</literal>
304  - specifies a human-readable label for the parser, shown in status messages. </para>
305          <para> Your derived parser class should return this same name from the <literal>getName()</literal> function.
306  </para>
307        </listitem>
308        <listitem>
309          <para>
310            <literal>mode.<replaceable>mode</replaceable>.sidekick.parser</literal>
311  - properties of this form are used to associate a parser with an edit mode.
312 </para>
313        </listitem>
314      </itemizedlist>
315
316      <para>
317  For example, the XML plugin, which used to provide two <classname>SideKickParser</classname>
318  implementations, had these properties:
319 </para>
320
321      <programlisting>sidekick.parser.xml.label=XML
322mode.xml.sidekick.parser=xml
323mode.xsl.sidekick.parser=xml
324sidekick.parser.html.label=HTML
325mode.asp.sidekick.parser=html
326mode.coldfusion.sidekick.parser=html
327mode.html.sidekick.parser=html
328mode.jhtml.sidekick.parser=html
329mode.jsp.sidekick.parser=html
330mode.php.sidekick.parser=html
331mode.shtml.sidekick.parser=html
332mode.sgml.sidekick.parser=html
333mode.velocity.sidekick.parser=html</programlisting>
334
335    </sect1>
336
337    <sect1 id="implement-structure-tree">
338      <title>Implementing a structure tree</title>
339
340      <para>
341 The <ulink url="jeditresource:/Sidekick.jar!/docs/api/sidekick/SideKickParser.html">
342      <classname>SideKickParser</classname>
343        </ulink> has one abstract method that all
344  subclasses must implement:
345 </para>
346
347      <funcsynopsis>
348        <funcprototype>
349
350          <funcdef>public
351
352   SideKickParsedData <function>parse</function>
353          </funcdef>
354          <paramdef>Buffer <parameter>buffer</parameter>
355          </paramdef>
356          <paramdef>DefaultErrorSource <parameter>errorSource</parameter>
357          </paramdef>
358        </funcprototype>
359      </funcsynopsis>
360
361      <para>
362  The <literal>errorSource</literal> is an instance of a class provided by the
363  <application>ErrorList</application> plugin; consult its documentation for
364  details.
365 </para>
366
367      <para>
368  The method is called from a thread, so care must be taken to access the
369  buffer in a thread-safe manner; the API documentation for the
370  <classname>Buffer</classname> class describes how this is done.
371 </para>
372
373      <para>
374  Your implementation of the <function>parse()</function> method should create and return
375an instance of
376   <ulink url="jeditresource:/Sidekick.jar!/docs/api/sidekick/SideKickParsedData.html">SideKickParsedData </ulink>.   Its constructor of the takes one parameter, which is the file name (to be shown at the root of the structure tree). Your method should
377add  structure elements to the <varname>root</varname> field of the instance.
378<varname>root</varname> is an instance of Java's <classname>DefaultMutableTreeNode</classname> class,
379and is given an initial value by the <classname>SideKickParsedData</classname> constructor.
380 </para>
381
382      <formalpara id="optionalPanel">
383        <title> getPanel() </title>
384        <para> Some SideKick parsers, such as CtagsSideKick, offer an additional toolbar to provide a convenient interface to change certain mode options such as sort by, and group by. They achieve this by overriding the <literal>getPanel()</literal> method of SideKickParser. </para>
385      </formalpara>
386
387    </sect1>
388
389    <sect1 id="implement-completion">
390      <title>Implementing completion popups</title>
391
392      <para> Your derived instance of
393     <ulink url="jeditresource:/Sidekick.jar!/docs/api/sidekick/SideKickParser.html">
394       SideKickParser</ulink> can implement additional
395       methods to tell Sidekick that your parser supports completions.
396   </para>
397
398      <programlisting>
399        /* @return true if plugin supports completion */
400        public boolean supportsCompletion();
401        /* @return true if we show completions after a period of inactivity. */
402    public boolean canCompleteAnywhere() ;
403        /* @return a list of characters which trigger completion immediately. */
404    public String getInstantCompletionTriggers();
405
406
407        /* @return all completions at a given caret position for this
408        editpane */
409        public SideKickCompletion complete(EditPane editPane, int caret)
410      </programlisting>
411
412
413      <para> If your SideKickParser does support completion, the actual
414     brains of the plugin goes in the last method, <literal>complete()</literal>,
415     which must construct an instance of    <ulink url="jeditresource:/Sidekick.jar!/docs/api/sidekick/SideKickCompletion.html">
416     SideKickCompletion</ulink>, given an <literal>EditPane</literal> and a caret position.
417   </para>
418
419      <para>
420   The constructor for <literal>SideKickCompletion</literal> accepts a list (or array) of possible values, these are the values that are displayed in the dropdown.
421   This is an abstract class, so you'll need to derive a specific implementation.  You may want to override the 'insert(int)' method to
422   support language specifics, like "dot" completion.
423   </para>
424
425      <para>How you actually create the completion depends on the specific language and support classes, and the information provided by the parser for the current file. </para>
426
427
428    </sect1>
429
430  </chapter>
431
432  <appendix id="futureplans">
433    <title> Future Plans </title>
434    <itemizedlist>
435      <listitem>
436        <para> Adding a Help tooltip to the CompletionPopup window and methods to the CompletinoInfo for getting/setting help.
437  </para>
438      </listitem>
439
440
441    </itemizedlist>
442  </appendix>
443
444  <appendix id="changes">
445    <title>Changes</title>
446    <para> Click <ulink url="CHANGES.txt">here</ulink> to see the detailed changes. </para>
447    </appendix>
448</book>