SideKick plugin user's guide

Version 1.4 (May 31 2013)

Slava Pestov

Dale Anson

Martin Raspe

Alan Ezust

Shlomy Reinstein

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.


Table of Contents

Chapter 1. The SideKick dockable

The SideKick plugin provides a dockable in which other plugins can display buffer structure.

Plugins>SideKick>SideKick 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.

  1. Choosing a docking area from the docking menu (a little arrow in the upper left corner of each floating dockable)

  2. Go to the Docking pane of the Global Options dialog box

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.

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.

Plugins>SideKick>Parse on Keystroke is a checkbox menu item that toggles on-the-fly parsing, for the current buffer only.

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. [1]

The current buffer can be parsed at any other time by clicking the parse button in the Sidekick window, or by invoking the Plugins>SideKick>Parse Buffer command.

Parse button menu

A popup menu is available in JDK 1.5 which appears when you right-click the "Parse" button. From there, you can set some auto-parse options without going to the plugin options.

Mode Options

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 services API.

Filter textfield

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.

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.

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> 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 SideKick is docked into the current view, hovering the mouse over a node will display its attributes in the status bar.



[1] global options - jedit - Shortcuts - Plugin: Sidekick (combo) - Parse Buffer

Chapter 2. 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.

Keyboard Shortcuts

  • Up and Down arrow keys let you navigate between sibling nodes, or to parents/children of exploded nodes.

  • Ctrl+Up and Ctrl+Down keys go to previous/next asset.

  • Right and Left arrow keys expand and collapse tree nodes.

Chapter 3. Toolbar

SideKick can optionally display the structure of the buffer in a toolbar, using one or more combo-boxes. This option is useful where screen real-estate is important and the tree takes too much of the screen. To use this option, select Plugins>SideKick> General>Show the assets in a combo-box (inside a toolbar). By default, a single combo-box is shown, which can be used to jump to various positions inside the buffer.

There is also an option to show a separate check-box for each level in the SideKick tree. To use this option, select Plugins>SideKick> General>Use a separate combo-box for each level of the tree.

To make the combo-box (or multiple combo-boxes) show the asset where the caret is currently located, select Plugins>SideKick> General>Tree/combo-box selection follows caret position.

Chapter 4. Folding

The SideKick plugin adds a new "sidekick" fold handler that folds the buffer according to the sidekick 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.

Chapter 5. 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.

Chapter 6. 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 1.4

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 using the services.xml file. With this, you define a service which returns a derived instance of SideKickParser

<?xml version="1.0"?>

<!DOCTYPE SERVICES SYSTEM "services.dtd">

<SERVICES>
        <SERVICE CLASS="sidekick.SideKickParser" NAME="xml">
                new xml.parser.SAXParserImpl();
        </SERVICE>
</SERVICES>
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.

    Your derived parser class should return this same name from the getName() function.

  • 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 many SideKickParser implementations, has 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 Sidekick parser

The SideKickParser has one abstract method that all subclasses must implement:

public SideKickParsedData parse (Buffer buffer ,
 DefaultErrorSource errorSource );
 

The errorSource 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.

Your implementation of the parse() method should create and return an instance of SideKickParsedData . 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 add structure elements to the root field of the instance. root is an instance of Java's DefaultMutableTreeNode class, and is given an initial value by the SideKickParsedData constructor.

getPanel() .  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 getPanel() method of SideKickParser.

Implementing completion popups

Your derived instance of SideKickParser can implement additional methods to tell Sidekick that your parser supports completions.

        /* @return true if plugin supports completion */
        public boolean supportsCompletion();
        /* @return true if we show completions after a period of inactivity. */
    public boolean canCompleteAnywhere() ;
        /* @return a list of characters which trigger completion immediately. */
    public String getInstantCompletionTriggers();


        /* @return all completions at a given caret position for this
        editpane */
        public SideKickCompletion complete(EditPane editPane, int caret)
      

If your SideKickParser does support completion, the actual brains of the plugin goes in the last method, complete(), which must construct an instance of SideKickCompletion, given an EditPane and a caret position.

The constructor for SideKickCompletion accepts a list (or array) of possible values, these are the values that are displayed in the dropdown. This is an abstract class, so you'll need to derive a specific implementation. You may want to override the 'insert(int)' method to support language specifics, like "dot" completion.

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.

Appendix A.  Future Plans
  • Adding a Help tooltip to the CompletionPopup window and methods to the CompletinoInfo for getting/setting help.

Appendix B. Changes

Click here to see the detailed changes.