# 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.