www.gillmerderge.com

Table of Contents

Links

Project Notes

Project:SWL Brace Highlighting
Author: Gillmer J. Derge, <me@gillmerderge.com>
Version:0.52
JBuilder Version:4.0 (All)
Announcements List:

(enter email address)

Description

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

Screenshot
Highlight parentheses
Determines whether parentheses ("(" and ")") are highlighted. Enabled by default.
Highlight braces
Determines whether braces ("{" and "}") are highlighted. Enabled by default.
Highlight brackets
Determines whether brackets ("[" and "]") are highlighted. Enabled by default.
Highlight text enclosed by parentheses
Determines whether the text between matching parentheses is highlighted is highlighted when Highlight parentheses is also enabled. Disabled by default.
Highlight text enclosed by braces
Determines whether the text between matching braces is highlighted is highlighted when Highlight braces is also enabled. Disabled by default.
Highlight text enclosed by brackets
Determines whether the text between matching brackets is highlighted is highlighted when Highlight brackets is also enabled. Disabled by default.
Delay highlights
Only adds a highlight if the caret remains in the same location for a fixed delay period (currently 800ms). This potentially improves performance.
Expire highlights
Automatically removes the highlights after a fixed delay period (currently 800ms). This makes the tool function more similarly to emacs.
"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 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.

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.

Acknowledgements

Thanks are due to the following people for contributing to this tools development:

  • Jean-Baptiste Bugeaud and Adriano Labate for the French language translation.
  • A number of other people who pointed out bugs or suggested features before I began keeping track of their names. Sorry. I didn't forget the help, just your names.

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.

FAQ

  1. Is there/will there be a version of this tool for JBuilder 3.5?

    It is not likely that there will ever be a version of SWL Brace for JBuilder 3.5. There are a number of reasons for this, but the most significant is that the tool uses the built-in action selection-match-brace (EditorActions.ACTION_SelectionMatchBrace) to actually locate the matching brace. That action is new to JBuilder 4.

    One alternative would be to use the similar match-brace action instead. In fact, one of the earlier versions of the tool did exactly that. Unfortunately, that causes the window to jump around when the matching brace is out of the visible viewport.

    Another option would be to implement that action directly myself, as an additional extension. While that would be a nice feature for JBuilder 3.5 users, it's just not something I want to get into.

    So the bottom line is that unless I receive some strong encouragement (threats or money), I don't plan to provide support for JBuilder 4.

  2. Can this tool be extended to highlight matching tags in HTML/XML?

    It isn't really practical to extend the tool to match anything other than braces, brackets, and parentheses. The reason for this is that it uses the built-in action selection-match-brace (EditorActions.ACTION_SelectionMatchBrace) to actually locate the matching brace. Since that action supports only those three types of matching, that is all SWL Brace can reasonably support.

    For the specific case of matching tags in HTML/XML tags, the JBuilder structure pane already does a fairly adequate job of that. It's not the same thing, but if used properly it provides similar utility.

Known bugs...

If you find any please let me know.

  • 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.
  • If the highlight is activated via a timer (with delay highlights turned on) and a CodeInsight window is open, CodeInsight will be dismissed.

Changes since Version 0.51...

  • Added a resource file with localized text for the French language. Note that to see this you need to set your default locale to a French-speaking locale. Thanks to Jean-Baptiste Bugeaud and Adriano Labate for the translation.

Changes since Version 0.5...

  • Fixed a bug that caused the highlight delay timer to fire repeatedly. One strange consquence of this was that expire highlights stopped working.

Changes since Version 0.4...

  • Added an option to highlight only when the caret remains in the same location for a fixed delay period. The default is for this option to be enabled.
  • Added internationalization support. All property names and other user-visible strings are loaded from the com.gillmerderge.jbuilder.editor.Res resource bundle. Currently only U.S. English values are provided, since that is my native language. If you create settings for another locale, please send them to me, so I can include them in future versions.
  • Added a message that displays the version number and is printed when JBuilder is given the -verbose options.
  • Changed the package to com.gillmerderge.jbuilder.editor and moved editor options initialization to the SwlBraceOptions class. This obviously has no user-level impact.
  • Changed the highlight style's property name to be more consistent with other styles. Users with a customized highlight color may need to reset the color.

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.

Things to do...

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

  • Make non-boolean options be global properties, so they can be configured.
  • Figure out how to add highlighting capability to decompiled class file nodes.
  • Add an option for "Keep braces highlighted, but expire the body highlighting."
  • 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.
  • 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.
  • 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?