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