1 | <?xml version="1.0" ?> |
---|
2 | <!-- SideKick user's guide --> |
---|
3 | <!-- (C) 2003 Slava Pestov --> |
---|
4 | <!-- jEdit buffer-local properties: --> |
---|
5 | <!-- :indentSize=1:noTabs=true:folding=sidekick: --> |
---|
6 | <book> |
---|
7 | <bookinfo> |
---|
8 | <title>SideKick plugin user's guide |
---|
9 | </title> |
---|
10 | <authorgroup> |
---|
11 | <author> |
---|
12 | <firstname>Slava |
---|
13 | </firstname> |
---|
14 | <surname>Pestov |
---|
15 | </surname> |
---|
16 | </author> |
---|
17 | </authorgroup> |
---|
18 | <legalnotice> |
---|
19 | <title>Legal Notice |
---|
20 | </title> |
---|
21 | <para> Permission is granted to copy, distribute and/or modify this document |
---|
22 | under the terms of the GNU Free Documentation License, Version 1.1 or |
---|
23 | any later version published by the Free Software Foundation; with no |
---|
24 | |
---|
25 | <quote>Invariant Sections |
---|
26 | </quote>, |
---|
27 | <quote>Front-Cover Texts |
---|
28 | </quote> or |
---|
29 | |
---|
30 | <quote>Back-Cover Texts |
---|
31 | </quote>, each as defined in the license. A copy of |
---|
32 | the license can be found in the file |
---|
33 | <filename>COPYING.DOC.txt |
---|
34 | </filename> included with jEdit. |
---|
35 | |
---|
36 | </para> |
---|
37 | <para> The SideKick plugin itself is released under the GNU General Public License. |
---|
38 | A copy of the GPL can be found in the jEdit online help. |
---|
39 | |
---|
40 | </para> |
---|
41 | </legalnotice> |
---|
42 | </bookinfo> |
---|
43 | <chapter id="browser"> |
---|
44 | <title>The structure browser window |
---|
45 | </title> |
---|
46 | <para> The SideKick plugin provides a dockable window in which other plugins can |
---|
47 | display buffer structure. |
---|
48 | |
---|
49 | </para> |
---|
50 | <para> |
---|
51 | <guimenu>Plugins |
---|
52 | </guimenu>> |
---|
53 | <guisubmenu>SideKick |
---|
54 | </guisubmenu>> |
---|
55 | <guimenuitem>Structure |
---|
56 | Browser |
---|
57 | </guimenuitem> displays the current buffer's structure in a |
---|
58 | dockable window. This window is floating by |
---|
59 | default, but it can be docked into the view in the |
---|
60 | <guibutton>Docking |
---|
61 | </guibutton> pane of the |
---|
62 | <guimenuitem>Global Options |
---|
63 | </guimenuitem> dialog box. |
---|
64 | |
---|
65 | </para> |
---|
66 | <para> The SideKick plugin automatically parses buffers |
---|
67 | when they are loaded or saved, where possible. |
---|
68 | Optionally, buffers can also be parsed on the fly, but this uses a fair bit of |
---|
69 | memory and processor power so it is disabled by default. |
---|
70 | |
---|
71 | </para> |
---|
72 | <para> |
---|
73 | <guimenu>Plugins |
---|
74 | </guimenu>> |
---|
75 | <guisubmenu>SideKick |
---|
76 | </guisubmenu>> |
---|
77 | <guimenuitem>Parse |
---|
78 | on Keystroke |
---|
79 | </guimenuitem> is a checkbox menu item that toggles on-the-fly |
---|
80 | parsing, for the current buffer only. |
---|
81 | |
---|
82 | </para> |
---|
83 | <para> The current buffer can be parsed at any other time by clicking the parse |
---|
84 | button in the |
---|
85 | <guimenuitem>Structure Browser |
---|
86 | </guimenuitem> window, or by |
---|
87 | invoking the |
---|
88 | |
---|
89 | <guimenu>Plugins |
---|
90 | </guimenu>> |
---|
91 | <guisubmenu>SideKick |
---|
92 | </guisubmenu>> |
---|
93 | <guimenuitem>Parse |
---|
94 | Buffer |
---|
95 | </guimenuitem> command. |
---|
96 | |
---|
97 | </para> |
---|
98 | <para> Any errors found while parsing the buffer are sent to the |
---|
99 | |
---|
100 | <application>ErrorList |
---|
101 | </application> plugin, which means they are highlighted |
---|
102 | in the text area, and shown in the |
---|
103 | |
---|
104 | <guimenu>Plugins |
---|
105 | </guimenu>> |
---|
106 | <guisubmenu>Error |
---|
107 | List |
---|
108 | </guisubmenu>> |
---|
109 | <guimenuitem>Error List |
---|
110 | </guimenuitem> window. See the |
---|
111 | documentation for the |
---|
112 | <application>ErrorList |
---|
113 | </application> plugin for details. |
---|
114 | |
---|
115 | </para> |
---|
116 | <para> Clicking on a node in the tree will move the caret to its location in the |
---|
117 | buffer; |
---|
118 | conversely, moving the caret in the buffer will select the corresponding |
---|
119 | node. |
---|
120 | |
---|
121 | </para> |
---|
122 | <para> |
---|
123 | <keycap>Shift |
---|
124 | </keycap>-clicking on a node will select that node in the text |
---|
125 | area. |
---|
126 | <keycap>Alt |
---|
127 | </keycap>-clicking on a node will narrow the text area |
---|
128 | display to that node. |
---|
129 | |
---|
130 | </para> |
---|
131 | <para> If the structure browser window is docked into the current view, hovering the mouse |
---|
132 | over a node will display its attributes in the status bar. |
---|
133 | |
---|
134 | </para> |
---|
135 | </chapter> |
---|
136 | <chapter id="moving-around"> |
---|
137 | <title>Moving around |
---|
138 | </title> |
---|
139 | <para> |
---|
140 | <guimenu>Plugins |
---|
141 | </guimenu>> |
---|
142 | <guisubmenu>SideKick |
---|
143 | </guisubmenu>> |
---|
144 | <guimenuitem>Go |
---|
145 | to Previous Asset |
---|
146 | </guimenuitem> moves the caret to start of the structure |
---|
147 | element ( |
---|
148 | <quote>asset |
---|
149 | </quote>). |
---|
150 | |
---|
151 | </para> |
---|
152 | <para> |
---|
153 | <guimenu>Plugins |
---|
154 | </guimenu>> |
---|
155 | <guisubmenu>SideKick |
---|
156 | </guisubmenu>> |
---|
157 | <guimenuitem>Go |
---|
158 | to Next Asset |
---|
159 | </guimenuitem> moves the caret to start of the next asset. |
---|
160 | |
---|
161 | </para> |
---|
162 | <para> |
---|
163 | <guimenu>Plugins |
---|
164 | </guimenu>> |
---|
165 | <guisubmenu>SideKick |
---|
166 | </guisubmenu>> |
---|
167 | <guimenuitem>Select |
---|
168 | Asset at Caret |
---|
169 | </guimenuitem> selects the asset at the caret position. |
---|
170 | |
---|
171 | </para> |
---|
172 | </chapter> |
---|
173 | <chapter id="folding"> |
---|
174 | <title>Folding |
---|
175 | </title> |
---|
176 | <para> The SideKick plugin adds a new |
---|
177 | <quote>sidekick |
---|
178 | </quote> fold handler that |
---|
179 | folds the buffer according to the structure tree. See the jEdit user's guide |
---|
180 | for general details about folding. |
---|
181 | |
---|
182 | </para> |
---|
183 | <para> |
---|
184 | <guimenu>Plugins |
---|
185 | </guimenu>> |
---|
186 | <guisubmenu>SideKick |
---|
187 | </guisubmenu>> |
---|
188 | <guimenuitem>Narrow to |
---|
189 | Asset at Caret |
---|
190 | </guimenuitem> hides all text except that of the asset at the |
---|
191 | caret location. This works in any folding mode, not just the |
---|
192 | <quote>sidekick |
---|
193 | </quote> mode. |
---|
194 | |
---|
195 | </para> |
---|
196 | </chapter> |
---|
197 | <chapter id="completion"> |
---|
198 | <title>Completion |
---|
199 | </title> |
---|
200 | <para> A completion popup can be shown at any time |
---|
201 | by invoking the |
---|
202 | |
---|
203 | <guimenu>Plugins |
---|
204 | </guimenu>> |
---|
205 | <guisubmenu>SideKick |
---|
206 | </guisubmenu>> |
---|
207 | <guimenuitem>Show |
---|
208 | Completion Popup |
---|
209 | </guimenuitem> command. Each plugin that uses SideKick |
---|
210 | implements its own specific completion behavior; see the plugin documentation |
---|
211 | for details. |
---|
212 | |
---|
213 | </para> |
---|
214 | </chapter> |
---|
215 | <chapter id="other-plugins"> |
---|
216 | <title>Developing SideKick back-ends |
---|
217 | </title> |
---|
218 | <para> By itself the SideKick plugin is not very useful; it relies on other plugins to |
---|
219 | provide buffer structure information. This chapter gives a brief overview of |
---|
220 | how it's done. |
---|
221 | |
---|
222 | </para> |
---|
223 | <sect1 id="preliminaries"> |
---|
224 | <title>Preliminaries |
---|
225 | </title> |
---|
226 | <para> First you will also need to add a dependency for the SideKick plugin in your plugin's |
---|
227 | property file: |
---|
228 | |
---|
229 | </para> |
---|
230 | <programlisting>plugin.MyPlugin.depend. |
---|
231 | <replaceable>n |
---|
232 | </replaceable>=plugin sidekick.SideKickPlugin 0.1 |
---|
233 | </programlisting> |
---|
234 | <para> Note that you must replace |
---|
235 | <replaceable>n |
---|
236 | </replaceable> with the |
---|
237 | appropriate number, as dependency properties must have consecutive numbers. |
---|
238 | |
---|
239 | </para> |
---|
240 | <para> All SideKick plugin classes are in the |
---|
241 | <classname>sidekick |
---|
242 | </classname> package; |
---|
243 | you will need to add |
---|
244 | <literal>import |
---|
245 | </literal> statements where appropriate. |
---|
246 | |
---|
247 | </para> |
---|
248 | <para> Parser instances must be registered in your plugin's |
---|
249 | <function>start() |
---|
250 | </function> method using the following method in the |
---|
251 | <classname>SideKickPlugin |
---|
252 | </classname> class: |
---|
253 | |
---|
254 | </para> |
---|
255 | <funcsynopsis> |
---|
256 | <funcprototype> |
---|
257 | <funcdef>public void |
---|
258 | <function>registerParser |
---|
259 | </function> |
---|
260 | </funcdef> |
---|
261 | <paramdef>SideKickParser |
---|
262 | <parameter>parser |
---|
263 | </parameter> |
---|
264 | </paramdef> |
---|
265 | </funcprototype> |
---|
266 | </funcsynopsis> |
---|
267 | <para> A corresponding method must be called from your plugin's |
---|
268 | <function>stop() |
---|
269 | </function> method: |
---|
270 | |
---|
271 | </para> |
---|
272 | <funcsynopsis> |
---|
273 | <funcprototype> |
---|
274 | <funcdef>public void |
---|
275 | <function>unregisterParser |
---|
276 | </function> |
---|
277 | </funcdef> |
---|
278 | <paramdef>SideKickParser |
---|
279 | <parameter>parser |
---|
280 | </parameter> |
---|
281 | </paramdef> |
---|
282 | </funcprototype> |
---|
283 | </funcsynopsis> |
---|
284 | </sect1> |
---|
285 | <sect1 id="class-sidekickparser"> |
---|
286 | <title>The SideKickParser class |
---|
287 | </title> |
---|
288 | <para> |
---|
289 | <classname>SideKickParser |
---|
290 | </classname> is an abstract class. The constructor |
---|
291 | takes one string parameter. This string is used in several properties: |
---|
292 | |
---|
293 | </para> |
---|
294 | <itemizedlist> |
---|
295 | <listitem> |
---|
296 | <para> |
---|
297 | <literal>sidekick.parser. |
---|
298 | <replaceable>name |
---|
299 | </replaceable>.label |
---|
300 | </literal> - specifies a human-readable label for the parser, shown in status messages. |
---|
301 | |
---|
302 | </para> |
---|
303 | </listitem> |
---|
304 | <listitem> |
---|
305 | <para> |
---|
306 | <literal>mode. |
---|
307 | <replaceable>mode |
---|
308 | </replaceable>.sidekick.parser |
---|
309 | </literal> - properties of this form are used to associate a parser with an edit mode. |
---|
310 | |
---|
311 | </para> |
---|
312 | </listitem> |
---|
313 | </itemizedlist> |
---|
314 | <para> For example, the XML plugin, which provides two |
---|
315 | <classname>SideKickParser |
---|
316 | </classname> implementations, defines these properties: |
---|
317 | |
---|
318 | </para> |
---|
319 | <programlisting>sidekick.parser.xml.label=XML |
---|
320 | mode.xml.sidekick.parser=xml |
---|
321 | mode.xsl.sidekick.parser=xml |
---|
322 | sidekick.parser.html.label=HTML |
---|
323 | mode.asp.sidekick.parser=html |
---|
324 | mode.coldfusion.sidekick.parser=html |
---|
325 | mode.html.sidekick.parser=html |
---|
326 | mode.jhtml.sidekick.parser=html |
---|
327 | mode.jsp.sidekick.parser=html |
---|
328 | mode.php.sidekick.parser=html |
---|
329 | mode.shtml.sidekick.parser=html |
---|
330 | mode.sgml.sidekick.parser=html |
---|
331 | mode.velocity.sidekick.parser=html |
---|
332 | </programlisting> |
---|
333 | </sect1> |
---|
334 | <sect1 id="implement-structure-tree"> |
---|
335 | <title>Implementing a structure tree |
---|
336 | </title> |
---|
337 | <para> The |
---|
338 | <classname>SideKickParser |
---|
339 | </classname> has one abstract method that all |
---|
340 | subclasses must implement: |
---|
341 | |
---|
342 | </para> |
---|
343 | <funcsynopsis> |
---|
344 | <funcprototype> |
---|
345 | <funcdef>public SideKickParsedData |
---|
346 | <function>parse |
---|
347 | </function> |
---|
348 | </funcdef> |
---|
349 | <paramdef>Buffer |
---|
350 | <parameter>buffer |
---|
351 | </parameter> |
---|
352 | </paramdef> |
---|
353 | <paramdef>DefaultErrorSource |
---|
354 | <parameter>errorSource |
---|
355 | </parameter> |
---|
356 | </paramdef> |
---|
357 | </funcprototype> |
---|
358 | </funcsynopsis> |
---|
359 | <para> The latter parameter is an instance of a class provided by the |
---|
360 | |
---|
361 | <application>ErrorList |
---|
362 | </application> plugin; consult its documentation for |
---|
363 | details. |
---|
364 | |
---|
365 | </para> |
---|
366 | <para> The method is called from a thread, so care must be taken to access the |
---|
367 | buffer in a thread-safe manner; the API documentation for the |
---|
368 | |
---|
369 | <classname>Buffer |
---|
370 | </classname> class describes how this is done. |
---|
371 | |
---|
372 | </para> |
---|
373 | <para> The constructor of the |
---|
374 | <classname>SideKickParsedData |
---|
375 | </classname> class takes |
---|
376 | one parameter, which is the file name (to be shown at the root of the structure |
---|
377 | tree). |
---|
378 | |
---|
379 | </para> |
---|
380 | <para> Your implementation of the |
---|
381 | <function>parse() |
---|
382 | </function> method should add |
---|
383 | structure elements to the |
---|
384 | <varname>root |
---|
385 | </varname> field of the |
---|
386 | |
---|
387 | <classname>SideKickParsedData |
---|
388 | </classname> instance. This field is an |
---|
389 | instance of Java's |
---|
390 | <classname>DefaultMutableTreeNode |
---|
391 | </classname> class, |
---|
392 | and is given a value by the |
---|
393 | <classname>SideKickParsedData |
---|
394 | </classname> constructor. |
---|
395 | |
---|
396 | </para> |
---|
397 | </sect1> |
---|
398 | <sect1 id="implement-completion"> |
---|
399 | <title>Implementing completion popups |
---|
400 | </title> |
---|
401 | |
---|
402 | <para> This part has not been written yet. Use the source, Luke! |
---|
403 | |
---|
404 | </para> |
---|
405 | </sect1> |
---|
406 | </chapter> |
---|
407 | <appendix id="changes"> |
---|
408 | <title>Change log |
---|
409 | </title> |
---|
410 | <itemizedlist> |
---|
411 | <listitem> |
---|
412 | <para> |
---|
413 | <emphasis role="bold">Version 0.1 |
---|
414 | </emphasis> requires |
---|
415 | jEdit 4.1pre11. |
---|
416 | </para> |
---|
417 | <itemizedlist> |
---|
418 | <listitem> |
---|
419 | <para>Initial release. |
---|
420 | |
---|
421 | </para> |
---|
422 | </listitem> |
---|
423 | </itemizedlist> |
---|
424 | </listitem> |
---|
425 | </itemizedlist> |
---|
426 | </appendix> |
---|
427 | </book> |
---|