Project Notes

Project:	SWL Brace Highlighting
Version:	0.4
Author:	Gillmer J. Derge, <me@gillmerderge.com>

Description

Whenever the carat is immediately preceded by a parenthesis (or brace or bracket), this tool places a highlight on the matching element. The highlighting can be controlled separately for each type of brace via the Editor properties tab under Editor Options....

The "Highlight text enclosed by ..." properties enable highlighting of the text that occurs between the elements.

"Expire highlights" automatically removes the highlights after a fixed delay period (currently 800ms). This makes the tool function more similarly to emacs.

The color of the highlight can be configured in the Color properties tab by changing the background color of the "Brace highlight" style. Note that only the background color setting of that style is actually used.

"'Fix' brace matching actions" alters the built-in JBuilder actions that move to the brace matching the one to the right of the caret. If the fix is enabled, which is the default, then the actions are modified to use the brace to the left of the caret.

The name of the tool refers to the Scheme Widget Library (SWL), a part of Chez Scheme. Although I'm sure SWL did not "invent" the concept of highlighting matching parentheses, that is where I first encountered and fell in love with this particular visual style of displaying the matches.

Installation

Installation is quite simple. Put the Jar file, SwlBrace.jar, into the lib/ext subdirectory of your JBuilder installation. On Windows, this will typically be C:\JBuilder4\lib\ext. JBuilder will need to be restarted before SWL Brace begins working.

Troubleshooting

If SWL Brace does not appear to be working, there are a few things you can check.

First, make sure it truly isn't working. Maybe you just have the Editor Options... set to values that turn off the highlighting. The easiest way to check this is to open the Editor Options... dialog either from the Tools menu or by right-clicking in a Java source code pane. On the Editor tab of that dialog, "SWL brace options" should be listed on the tree of Editor options. If it is listed, then it has installed properly. Make sure the settings show the values you want.

If it is not listed, then the initialization procedure did not work correctly. Run JBuilder with the -verbose command line argument. This will produce a large amount of output, so you may wish to redirect it to a file. The output should include something about initializing com.gillmerderge.jbuilder.ide.SwlBraceCaretListener and com.gillmerderge.jbuilder.ide.SwlBraceMatchAction. If it doesn't, then you need to return to the section on installation and try again: SWL Brace is not installed properly. On the other hand, if there is an error or exception listed, please let me know: you have discovered a bug.

Changes since Version 0.3...

Added support for "fixing" the brace matching actions that are normally bound to Alt-] and Alt-Shift-] (among other keys) in the CUA map. These actions are named match-brace and selection-match-brace. The normal JBuilder operation is for those actions to show the brace that matches the one to the right of the caret. The "fixed" version uses the one to the left of the caret, which is more frequently useful, since that one is the character that was most recently typed. This can be configured via Editor Options. By default it is turned on.
Mostly fixed the problems with split views. When the view is split, the new pane will not immediately display the brace highlights. This unfortunately appears to be unavoidable. However, if you view another file, when you return to the file with the split view, all panes will properly display the highlights.

Changes since Version 0.2...

Added independent control of "Highlight text enclosed by ..." for each type of grouping element. As before, the default value is false.
Fixed a bug that occurred when the caret was at the beginning of the document.

Changes since Version 0.1...

Fixed the problem with jumpiness when the match is outside the visible window. Consequently, highlighting of braces is now enabled by default.
Added a new option, at the suggestion of Anders Norlin, that highlights the text enclosed by the braces, in addition to the braces themselves. This is turned off by default.
Added an option to automatically remove the highlight after a fixed delay period (currently 800ms).
Enabled highlighting for all text files rather than only Java source code.
Highlighting only occurs when a matching parenthesis is actually found.
Documented and released the tool's source code.

Known bugs...

When the view is split, the new pane will not immediately display the brace highlights. This unfortunately appears to be unavoidable. However, if you view another file, when you return to the file with the split view, all panes will properly display the highlights.

Things to do...

These items are not necessarily in any order. Do not assume that the first items are higher priority.

Make a version for JBuilder 3.5 (or ideally make one version that supports both).
The delay period for "Expire highlights" should be configurable. Unfortunately the EditorOptions API doesn't really allow non-Boolean options (despite an obvious attempt to make it look like it does).
Look into using Styles instead of Highlights to display the braces. This would allow more than just the background color to be configured.
The test for whether a real match is found could probably be improved.
Consider highlighting nested sets of matching parentheses in different colors, ala Microsoft Excel. This is a good idea, but possibly difficult.
Consider highlighting matching tags in HTML/XML. This may be difficult, since it would not be able to leverage the built-in brace matching actions.
Try to make the default color choice dependent on the scheme that is in place. For example, yellow is a bad choice with non-Default schemes.
Consider highlighting unmatched braces (perhaps in a different color) as an aid to locating them. This may be harder, since you probably want to highlight all unmatched braces rather than just the one near the caret. Also, this functionality might be handled adequately by the Errors folder in the structure pane.
Change the initOpenTools sequence so things are packaged more neatly. For example, consider putting the option initialization into a separate class.
Probably should change the package name to editor instead of ide.
Should each brace type get a separate highlight style, or is that overkill?
Currently the tool is enabled for all text source files. Is there any reason to make it configurable which file types support the highlight?