Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
The API
My first take on writing a syntax highlighter centered around creating a View for the Document that would display parentheses differently from other characters, and depending on the current position of the caret. That turns out to involve a fair amount of effort, because the View classes are responsible for a lot of things: breaking the text into paragraphs, and then into lines. However, it doesn't break lines into words (at least not for the plain views I was interested in); and getting words to display in order, and properly communicating their position afterwards, would be a lot of work.
It also involved creating an EditorKit, which doesn't quite fit cleanly into the whole model/view/controller paradigm. It's kind of a way of moderating the interaction between the view and the controller allowing customization. Clearly, we're making a very complicated task out of what I'd hoped would be a simple one.
It turns out that the JTextComponent designers anticipated my needs, although I've never seen their trick used anywhere. JTextComponent is the base class of the commonly used JEditorPane, JTextArea, and JTextField classes. It's an odd bit of package design: The JEditorPane, JTextArea, and JTextField classes are in the javax.swing package, where they're highly visible, while JTextComponent is "hidden" in the sub-package javax.swing.text. Ordinarily, base classes are considered more general, and therefore belong in higher-level packages. The implication is that JTextComponent bears common abstract and low-level functions, but is less interesting than the particular implementations that provide more complete functionality. You can use JTextField, for example, without ever using any of the JTextComponent methods.
JTextComponent provides a number of features common to all text components, but they remain somewhat obscure because they're in a base class with dozens of methods. I didn't know that JTextComponent has a NavigationFilter designed to prevent you from clicking in certain places, and until I began this project I didn't know that they'd anticipated the need for a highlighter.
Highlighting is represented by a Highlighter object, obtained by calling getHighlighter on the JTextComponent. A default highlighter is provided for you; you don't have to call setHighlighter first. Which is good, because it saves us having to figure out what kind of Highlighter we want. This same highlighter is also responsible for highlighting text that has been selected.
The most immediately relevant method of Highlighter is shown here:
public Object addHighlight(int p0,
int p1,
Highlighter.HighlightPainter p)
throws BadLocationException
This adds a highlight from p0 to p1, using p to paint the highlighting background.
An Aside: API Design and Strong Typing
The object that's returned is an arbitrary, featureless tag. That's kind of odd, and the corresponding code to remove a highlight is as follows:
public void removeHighlight(Object tag)
This is prone to all sorts of misuse; it's easy to pass in the wrong object. You could pass in any object, even a String, although that would be meaningless. Usually, an API designer would use a typed object to prevent that kind of mistake, perhaps called Highlight. There would still be ways to get it wrong (for example, using a Highlight from a different Highlighter), but it would prevent some mistakes.
Even odder, there's already a Highlighter.Highlight class that could have been used, and if you poke around in the code for the DefaultHighlighter you'll find that addHighlight does in fact return a Highlighter.Highlight object (by way of LayeredHighlightInfo, an internal class).
I'm not the first person to discover this oddity; it was dealt with more than two years ago in Java's Bug Parade as bug ID 4200254. (Note: Requires login.) They provided the rather weak excuse that it was to allow flexibility in the implementations (an interface would have allowed strong typing without limiting flexibility). They also make the much better excuse that changing it at this point would break binary compatibility. It may not be the best design, but it works, and functioning code is usually to be preferred to reengineered code that breaks your existing code base.
If you don't keep an eye on the Bug Parade, you should. If you think that something is wrong that can be blamed on the Java APIs, or even if you just think that a design is odd, the odds are good that somebody has already complained. The Bug Parade may be able to give you a workaround you hadn't considered. It may reveal nothing more than a case like this, where Sun has looked at the problem and chosen not to fix it, but at least you'll know you aren't crazy. It may reveal a known bug that's going to be fixed someday, but not now. It won't solve your problem, but it'll allow you to pick a different route to achieving your goal rather than beating your head against a wall. Or it may just be the proof you need to tell your boss to end an ill-considered project entirely.
The addHighlight method takes three arguments. The first two identify the characters you want lit. They form a range, where 0 is the first character. The second argument is the first character that you don't want lit. So, to highlight just the first character, the arguments should be (0, 1).
The numbers might make more sense if you look at them the way Document wants you to, where the numbers refer to the positions between characters rather than the characters themselves, as in Figure 2 (from the Document documentation):
)
Figure 2 Offsets in Documents.
The addHighlight method also takes a Highlighter.HighlightPainter. Highlighter.HighlightPainter is an interface, containing only a single method:
/* Renders the highlight. */
public void paint(Graphics g,
int p0,
int p1,
Shape bounds,
JTextComponent c)
Fortunately, we don't have to implement it. Java has provided a default implementation: DefaultHighlighter.DefaultHighlightPainter. It takes a Color, such as Color.green. It highlights the characters by painting their background to the color you provide. We're going to want two different painters: one for when the parentheses match, and another for when they don't:
Highlighter.HighlightPainter goodPainter = new DefaultHighlighter.DefaultHighlightPainter(Color.cyan); Highlighter.HighlightPainter badPainter = new DefaultHighlighter.DefaultHighlightPainter(Color.magenta);