Bug 322050

Description Alan Mising name 2010-08-07 11:55:47 EDT

Build Identifier: 20100617-1415

There's an inconsistency in the AnnotationPainter API that makes it harder to use than it need be. One uses the #addAnnotationType(Object annotationType) method to tell the AnnotationPainter to paint an annotation using squigglies. This is typically done during the creation of a new SourceViewer instance, as follows:

SourceViewer sourceViewer = new SourceViewer( /* etc */ );
AnnotationPainter ap = new AnnotationPainter( sourceViewer, new MyAnnotationAccess());
ap.addAnnotationType( annotationType);
ap.setAnnotationTypeColor( annotationType, COLOR_RED);
sourceViewer.addPainter(ap);

That's all it takes to have the annotations of the specified type underlined with red squigglies. But suppose one wants them to be highlighted instead? No problem, one might think, because there's a method AnnotationPainter#addHighlightAnnotationType( Object) that seems to be the exact parallel of #addAnnotationType. So one would expect to be able to use the code snippet above, except of course substituting #addHighlightAnnotationType.

Not so. The code with #addHighlightAnnotationType doesn't work. Unless that is, one adds the additional line

sourceViewer.addTextPresentationListener( ap);

Two methods that look the same, but the second one doesn't work as the first one does unless that extra line of code is inserted. To me that seems like a bug. And that extra line is a well-kept secret. It's not mentioned in the Javadocs. You have to find out about it by trolling through the code of, for example, SourceViewerDecorationSupport. So the bug is a significant issue for the usability of the API of AnnotationPainter.

It's actually a bit worse than that, because all the AnnotationPainter methods that install various kinds of highlighting using an IDrawingStrategy or an ITextStyleStrategy also require that that the AnnotationPainter is a TextPresentationListener to the SourceViewer. So that undocumented and hard-to-discover extra line is needed for those as well.

To fix this bug, I suggest a mod to the implementation of SourceViewer#addPainter so that the AnnotationPainter is installed as a TextPresentationListener of the SourceViewer automatically. This change would be backwards compatible.

Lastly, let me point out that the connection between an AnnotationPainter and a SourceViewer is established 2 or 3 times: in the AnnotationPainter constructor, in SourceViewer#addPainter, and yet again when the AnnotationPainter is installed as a listener on the SourceViewer. It would be nice if this connection had to be established only once, but reducing the count from 3 to 2 would be a start.



Reproducible: Always

Steps to Reproduce:
See description details.