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
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 2 ways.
Choosing a docking area from the docking menu (a little arrow in the upper left corner of each floating dockable)
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 "reload" button in the Sidekick Structure browser, 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 Structure Browser window, or by invoking the Plugins>SideKick>Parse Buffer command.
A popup menu is available in JDK 1.5 which appears when you right-click the "reload" button. From there, you can set some auto-parse options without going to the plugin options.
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 the structure browser window is docked into the current view, hovering the mouse over a node will display its attributes in the status bar.
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.
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.
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.
Table of Contents
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.
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 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>
SideKickParser
is an abstract class. The constructor takes one string parameter. This string is used in several properties:
sidekick.parser.
- specifies a human-readable label for the parser, shown in status messages. name
.label
Your derived parser class should return this same name from the getName()
function.
mode.
- properties of this form are used to associate a parser with an edit mode.
mode
.sidekick.parser
For example, the XML plugin, which used to provide two SideKickParser
implementations, had 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
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.
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.
Adding a Help tooltip to the CompletionPopup window and methods to the CompletinoInfo for getting/setting help.
Version 0.7.4 requires JDK 1.5, jEdit 4.3pre8 and ErrorListPlugin 1.4.
Fixed "can't determine mode of buffer" ( 1744627 - Shlomy Reinstein )
Added support for SideKick Parser Services to offer a JPanel for inserting above the SideKickTree. (Shlomy Reinstein, # 1744797 )
Preserve horizontal scroll position (Vladimir Avondin # 1746146)
Version 0.7.3 requires JDK 1.5, jEdit 4.3pre8 and ErrorListPlugin 1.4.
Added parser setting from mode options pane. (ezust)
NPE after install from plugin manager fixed. (kpouer)
Bug 1643614 fixed (reparse on mode change)
Version 0.7.2 requires JDK 1.5, jEdit 4.3pre8 and ErrorListPlugin 1.4.
Bugs 1617620,1624552 - Can't get rid of wrong parser. (hertzhaft, ezust)
NPE fixed when a jEdit mode had no parser. (kpouer)
Added a dynamic parser switcher menu to a new ActionSet, allowing you to switch parsers via keyboard shortcuts. (ezust)
Rewrote and simplified fold handler code (kpouer).
Version 0.7.1 requires JDK 1.5, jEdit 4.3pre8 and ErrorListPlugin 1.4.
SF.net bugs 1072043, 1553554, 1506964 - Sidekick FoldHandler bugs fixed.
SF.net bug # 1593604 - reparse on save happens only in the active view.
Sf.net bug # 1595835 - can't switch to default parser
Version 0.7 requires JDK 1.5, jEdit 4.3pre8 and ErrorListPlugin 1.4.
Added a mode-specific option pane, so that settings can be customized on a mode basis by SideKick and its parser service plugins. (ezust).
Made the completion popup accept-characters configurable. Prevented the completion popup from showing when the word at the caret is the same as a completion list entry. (hertzhaft)
Recuses into non-asset nodes #1571697, 1573034. (shlomy)
Version 0.6.6 requires JDK 1.5, jEdit 4.3pre5 and ErrorListPlugin 1.4.
Added sidekick.util package. This contains classes to help integrate javacc-generated parsers with sidekick. (danson)
Some work on the popup for code completion. It still doesn't work right with picking from the list with a mouse. (danson)
Fix for a null pointer exception. (danson)
Version 0.6.4 requires JDK 1.5, jEdit 4.3pre5 and ErrorListPlugin 1.4.
Emits new EBMessage msg.CaretChanging
when an asset is selected in the tree. (ezust)
Mouse Clicks, PgUp and PgDn keys work from completion popups. Arrow keys don't wrap around anymore. (ezust)
Popup menu on parse button for conveniently changing auto parse settings/caret follow settings (requires JDK 1.5). (ezust)
Parse event bugfixes (ezust)
Version 0.6.2 requires JDK 1.4, jEdit 4.3pre3 and ErrorListPlugin 1.4.
Broke up options "parse on buffer switch/save" into 2 separate options. Now you can parse on switch, or on save, or on both, and when you switch buffers with parse-on-switch off, the tree keeps its state. (Alan Ezust)
Added option setting to turn off tool tips. Tool tips can be annoying on slower systems as they are not necessarily drawn quickly. (Dale Anson)
Added option setting to be able to display a status window at the bottom of the tree. This window is larger than the jEdit status bar, so the full display of tree node can be shown. This is nice when tool tips are off and the node details are shown on more than one line. (Dale Anson)
Version 0.6.1 requires jEdit 4.3pre3 and ErrorListPlugin 1.4.
Made SideKickParser.name
protected
.
Bug 1504746 fixed [combobox].
Version 0.6 requires jEdit 4.3pre3 and ErrorListPlugin 1.4.
Added a combo box to let you switch parsers on an individual buffer basis. (Alan Ezust)
Improved Documentation. (Alan Ezust)
No more multi-line StatusBar messages. Using getShortString()
instead of getLongString()
. (Alan Ezust)
Version 0.5 requires jEdit 4.3pre3 and ErrorListPlugin 1.2.
SideKick now auto-expands the proper depth of the tree, and properly follows the textarea's caret as the selected node in the sidekick. (Dale Anson)
A new context menu exists in Structure Browser permitting the user to set and view markers. (Martin Raspe)
Version 0.4 requires jEdit 4.3pre3 and ErrorListPlugin 1.2.
Moved 4 classes from the PerlSideKick plugin into this plugin. The classes are in package sidekick.enhanced
.
This is so that we can break the dependency between
JavaScriptSideKick and PerlSideKick.
Patched for 4.3pre3 API
Version 0.3.4 requires jEdit 4.2final.
Added a new IAsset
interface that can be
used instead of the Asset
abstract class to realize more flexible
inheritance relationships.
Added a new option pane to associate edit modes with SideKick parsers.
Version 0.3.3 requires jEdit 4.2final.
The completion popup is now positioned within the screen bounds.
The SideKickCompletion
class is now much more full-featured (but backwards-compatible, if you ignore the new features).
Some changes were made to the way the parser works to improve perceived responsiveness.
The SideKickParsedData
associated with a buffer was not unset when the SideKick plugin was unloaded, and as a result, reloading the
SideKick plugin would horribly break buffers using the "sidekick" fold handler.
The option to delay parsing after a keystroke did not work; the timeout was always fixed at 1.5 seconds.
Version 0.3.2 requires jEdit 4.2final and ErrorListPlugin 1.2.
Fixed NullPointerException in Select Asset.
Sometimes a buffer would be parsed more than once in a row.
Fixed a bug that would show the completion popup twice if the Show completion popups where possible option was on andthe popup trigger delay was larger than 0 seconds and the user invoked the complete action before the trigger delay run out. (Dirk Moebius)
Fixed a bug where typing with the completion popup open would not insert keys if there were no completions available.
Version 0.3.1 requires jEdit 4.2pre3 and ErrorListPlugin 1.2.
SideKickCompletion
implementations can now disable automatic completion popups.
Fix a problem in buffer listener handling.
Various other minor fixes.
Version 0.3 requires jEdit 4.2pre3 and ErrorListPlugin 1.1.
Updated for jEdit 4.2 API changes.
Added getParseTriggers()
method
to SideKickParser
class.
Added getErrorSource()
method
to SideKickPlugin
class.
Cleaned up and debugged completion code.
Previously if the parse on keystroke option was on, an in-progress parse was not stopped. This resulted in poor performance. Now, an API has been added for stopping parsing (although only the XML plugin uses it at the moment). Combined with the position optimization in jEdit 4.2pre3, this should result in improved responsiveness when editing large XML files.
Version 0.2 requires jEdit 4.1pre11 and ErrorListPlugin 1.0.
Fixed a thread safety problem.
Added activate()
and
deactivate()
methods to
SideKickParser
class. These methods are called when
a buffer using this parser is selected and deselected in a given view.
The priority of the thread used by SideKick to parse files is now the minimum priority.
jEdit keyboard shortcuts now work when invoked while a completion popup is open.
Version 0.1 requires jEdit 4.1pre11.
Initial release.