SideKick plugin user's guide
Slava
Pestov
Legal Notice
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections
,
Front-Cover Texts
or
Back-Cover Texts
, each as defined in the license. A copy of
the license can be found in the file
COPYING.DOC.txt
included with jEdit.
The SideKick plugin itself is released under the GNU General Public License.
A copy of the GPL can be found in the jEdit online help.
The structure browser window
The SideKick plugin provides a dockable window in which other plugins can
display buffer structure.
Plugins
>
SideKick
>
Structure
Browser
displays the current buffer's structure in a
dockable window. This window is floating by
default, but it can be docked into the view in the
Docking
pane of the
Global Options
dialog box.
The SideKick plugin automatically parses buffers
when they are loaded or saved, where possible.
Optionally, buffers can also be parsed on the fly, but this uses a fair bit of
memory and processor power so it is disabled by default.
Plugins
>
SideKick
>
Parse
on Keystroke
is a checkbox menu item that toggles on-the-fly
parsing, for the current buffer only.
The current buffer can be parsed at any other time by clicking the parse
button in the
Structure Browser
window, or by
invoking the
Plugins
>
SideKick
>
Parse
Buffer
command.
Any errors found while parsing the buffer are sent to the
ErrorList
plugin, which means they are highlighted
in the text area, and shown in the
Plugins
>
Error
List
>
Error List
window. See the
documentation for the
ErrorList
plugin for details.
Clicking on a node in the tree will move the caret to its location in the
buffer;
conversely, moving the caret in the buffer will select the corresponding
node.
Shift
-clicking on a node will select that node in the text
area.
Alt
-clicking on a node will narrow the text area
display to that node.
If the structure browser window is docked into the current view, hovering the mouse
over a node will display its attributes in the status bar.
Moving around
Plugins
>
SideKick
>
Go
to Previous Asset
moves the caret to start of the structure
element (
asset
).
Plugins
>
SideKick
>
Go
to Next Asset
moves the caret to start of the next asset.
Plugins
>
SideKick
>
Select
Asset at Caret
selects the asset at the caret position.
Folding
The SideKick plugin adds a new
sidekick
fold handler that
folds the buffer according to the structure tree. See the jEdit user's guide
for general details about folding.
Plugins
>
SideKick
>
Narrow to
Asset at Caret
hides all text except that of the asset at the
caret location. This works in any folding mode, not just the
sidekick
mode.
Completion
A completion popup can be shown at any time
by invoking the
Plugins
>
SideKick
>
Show
Completion Popup
command. Each plugin that uses SideKick
implements its own specific completion behavior; see the plugin documentation
for details.
Developing SideKick back-ends
By itself the SideKick plugin is not very useful; it relies on other plugins to
provide buffer structure information. This chapter gives a brief overview of
how it's done.
Preliminaries
First you will also need to add a dependency for the SideKick plugin in your plugin's
property file:
plugin.MyPlugin.depend.
n
=plugin sidekick.SideKickPlugin 0.1
Note that you must replace
n
with the
appropriate number, as dependency properties must have consecutive numbers.
All SideKick plugin classes are in the
sidekick
package;
you will need to add
import
statements where appropriate.
Parser instances must be registered in your plugin's
start()
method using the following method in the
SideKickPlugin
class:
public void
registerParser
SideKickParser
parser
A corresponding method must be called from your plugin's
stop()
method:
public void
unregisterParser
SideKickParser
parser
The SideKickParser class
SideKickParser
is an abstract class. The constructor
takes one string parameter. This string is used in several properties:
sidekick.parser.
name
.label
- specifies a human-readable label for the parser, shown in status messages.
mode.
mode
.sidekick.parser
- properties of this form are used to associate a parser with an edit mode.
For example, the XML plugin, which provides two
SideKickParser
implementations, defines these properties:
sidekick.parser.xml.label=XML
mode.xml.sidekick.parser=xml
mode.xsl.sidekick.parser=xml
sidekick.parser.html.label=HTML
mode.asp.sidekick.parser=html
mode.coldfusion.sidekick.parser=html
mode.html.sidekick.parser=html
mode.jhtml.sidekick.parser=html
mode.jsp.sidekick.parser=html
mode.php.sidekick.parser=html
mode.shtml.sidekick.parser=html
mode.sgml.sidekick.parser=html
mode.velocity.sidekick.parser=html
Implementing a structure tree
The
SideKickParser
has one abstract method that all
subclasses must implement:
public SideKickParsedData
parse
Buffer
buffer
DefaultErrorSource
errorSource
The latter parameter is an instance of a class provided by the
ErrorList
plugin; consult its documentation for
details.
The method is called from a thread, so care must be taken to access the
buffer in a thread-safe manner; the API documentation for the
Buffer
class describes how this is done.
The constructor of the
SideKickParsedData
class takes
one parameter, which is the file name (to be shown at the root of the structure
tree).
Your implementation of the
parse()
method should add
structure elements to the
root
field of the
SideKickParsedData
instance. This field is an
instance of Java's
DefaultMutableTreeNode
class,
and is given a value by the
SideKickParsedData
constructor.
Implementing completion popups
This part has not been written yet. Use the source, Luke!
Change log
Version 0.1
requires
jEdit 4.1pre11.
Initial release.