Tag: annotation

Custom markers and annotations – the bright side of Eclipse

Motto:

I have discovered a truly remarkable proof of this theorem which this margin is too small to contain.
Pierre de Fermat

During the development of editors it is often needed to display additional information next to the document, such as error markers, search results or various coverage metrics. However, it is not a good idea to hardcode the list of supported markers during development, as the best ideas will be introduced by others – who do not want to have anything to do with our editor.

Luckily, Eclipse provides a simple way to attach markers to documents without explicit support needed from the editor developer: the markers (and annotations) created by their corresponding extensions are stored independently from the document, so these additions can be made without disturbing any existing user of the files.

As I described it in my previous post about error markers, such markers can be defined creating an extension for the extension point org.eclipse.core.resources.marker, and then using the IResource.createMarker() method to create the marker instances as needed. Then using some magic it can be displayed as the yellow or red wriggly lines during the text.

Other markers (and annotations) can be created in similarly: we create our own marker type, and register an annotation type for it, and the platform manages the rest. In my case I wanted to represent a calculated set of program statements similar to the code coverage display used by the EclEmma tool: the covered statements are highlighted with the green background.

To support such a display, I created a new marker type, that is a text marker; and to make the lifecycle-management easier, I did not set it persistent. This has been reached using the following code:

<extension
    id="org.eclipse.viatra2.slicemarker"
    name="GTASM Slice"
    point="org.eclipse.core.resources.markers">
  <super
    type="org.eclipse.core.resources.textmarker">
  </super>
</extension>

The most important difference between this marker and the one defined in the previous Markers and Annotations post is that the newly defined marker is not a problem marker, but a simple text marker. This means, the created marker will not show in the Problems view (that is nice – we don’t want to display problems now), and no default annotation is created (that will need fixing).

In theory it is possible to create annotations programmatically together with the markers, but in practice it is really a bad idea. First of all, annotations are created for the document model (thus assuming an open editor and a code dependency to that document model), are never persisted, and the resulting code fails indeterministically (I once debugged a code like that, every annotation creation code ran correctly, but some annotations were missing; re-running the code re-added the missing ones, but sometimes removed others), so this idea will not work.

Luckily, the platform provides two extension points that can be used to automatically assign annotations to marker instances. To define an automatically generated annotation type for the markers, the org.eclipse.ui.editors.annotationTypes extension point is used: basically a marker and an annotation ID is stored this way.

 

   <extension
         point="org.eclipse.ui.editors.annotationTypes">
      <type
            markerType="org.eclipse.viatra2.slicemarker"
            name="org.eclipse.viatra2.slicemarker">
      </type>
   </extension>

 

To define the appearance of the created annotation the org.eclipse.ui.editors.markerAnnotationSpecification extension point can be used. In the extensions we have to specify the annotation display methods used together with color and formatting settings.

 

   <extension
         point="org.eclipse.ui.editors.markerAnnotationSpecification">
      <specification
            annotationType="org.eclipse.viatra2.slicemarker"
            colorPreferenceKey="org.eclipse.viatra2.slice.color"
            colorPreferenceValue="192,255,192"
            contributesToHeader="false"
            highlightPreferenceKey="org.eclipse.viatra2.slice.highlight"
            highlightPreferenceValue="true"
            includeOnPreferencePage="true"
            label="GTASM Slice Marker"
            overviewRulerPreferenceKey="org.eclipse.viatra2.slice.overview"
            overviewRulerPreferenceValue="true"
            presentationLayer="0"
            textPreferenceKey="org.eclipse.viatra2.slice.text"
            textPreferenceValue="true"
            textStylePreferenceValue="BOX"
            verticalRulerPreferenceKey="org.eclipse.viatra2.slice.ruler"
            verticalRulerPreferenceValue="true">
      </specification>
   </extension>

Even better, by assigning preference keys to the various settings the platform also offers the users the possibility to configure the annotations: the General/Editors/Text Editors/Annotations preference page will list our annotation, and allows setting its preference values. If the preference keys are unique (that is our responsibility 🙂 ), then creating this extension ends our work: annotations will be generated automatically, and they will be displayed in the opened text editors.

Annotation Preferences

The marker creation process is entirely the same as the creation of error markers: a new marker is initialized using the IResource.createMarker(String markerId) method, and the IMarker.CHAR_START and IMarker.CHAR_END markers are set for positioning the markers.

An editor opened with the annotated code

Alltogether, the markers and annotations provide an easy way to extend existing editors with meta-information (e.g. execution state, dependencies, coverage, etc.), that can be used with a very little amount of Java programming. Sadly, the content assists for extensions is not that discoverable as the Java APIs, so a lot of experimenting and/or documentation reading is needed. Luckily, documentation is available for these extension points, so knowing their name will be enough for most cases.

So, lets hope, Eclipse gives us a big enough margin to contain our proo metainformation.

Markers and Annotations in Eclipse for Error Feedback

Motto:

Ninety per cent of most magic merely consists of knowing one extra fact.
Terry Pratchett, Night Watch

Development in Eclipse keeps fascinating me, as there are a lot of very thoroughly designed services and features integrated to allow detailed customization – on the other hand, “with big power comes big responsibility”, but at least a steep learning curve. I had such an experience with the problem handling support not long ago.

We developed our own textual language, that provided error markers and editor annotations as error feedback. The problem was that the editor annotations were sometimes missing: our planned functionality worked like we like to add an annotation each time our marker was added, but the annotations were not always updated (so we got an inconsistent state between markers and annotations – but not every time).

Of course that was caused by the fact that we were rolling out our own implementation of marker/annotation synchronization – we were not aware that the JFace TextEditor provides such a service out of the box – and I did not found it documented on the various locations (that’s why this blog post is born 🙂 ).

Our requirements

First of all, lets assemble the various ways Eclipse editors can provide error feedback:

  • The most basic (and least usable) way is the use of pop-up windows – they are annoying, and not persistent (after pressing a button, they disappear, before the error could be solved).
  • Writing to the Error log view – a bit better, but the log could be overwhelmed, if the messages are too many, because they cannot be deleted when the problem is solved.
  • Displaying the error in the Problems view – that’s one of the standard places, where parse errors should be displayed. The problems view is generated by reading (and filtering) the error marker type (org.eclipse.core.resources.problemmarker).
  • Marking the files in the Project Navigator view with a small symbol, if they contain errors/warnings. This is also handled using the previously mentioned error marker.
  • Underlining the erroneous parts in the editor. For this reason annotations should be added to the JFace Document Model used by the JFace TextEditor component.

The basic idea is to create a marker and an annotation each time a problem is found. The problem with annotations, that creating them requires some connection with the editor object, or at least the document model, but our parser should not depend on the editor (core component should not depend on the GUI!).

Mark My Words!

The management of the markers is well described in the Mark My Words tutorial. Basically markers are attached to IResources, and provide a simple key-value interface with a freely definable key set (and the IMarker interface specifies some commonly used keys).

Following the tutorial we could create our own marker with the parent of the org.eclipse.core.resources.marker marker, after this adding the markers to the selected files managed the error display in the Problems and Project Navigator views.

So our marker definition looks as follows:

   <extension
         id="vtclparsermarker"
         name="VTCL Parsing Problems"
         point="org.eclipse.core.resources.markers">
      <super
            type="org.eclipse.core.resources.problemmarker">
      </super>
      <persistent
            value="true">
      </persistent>
   </extension>

The problem marker understands severity, error message and line number parameters, and is capable of displaying them in the Problems view.

IMarker marker = file.createMarker(markerId);
 marker.setAttribute(IMarker.SEVERITY, severity);
 marker.setAttribute(IMarker.MESSAGE, message);
 marker.setAttribute(IMarker.LINE_NUMBER, line);

Annotating the document manually

As stated before, markers could be added easily without knowing anything about who has opened the file currently, so they are really useful for error feedback, but this information should be also available in the open editors.

Our first idea may be to create some glue code, that listens to the marker changes, and updates our editor accordingly. The drawbacks of this approach are first the fact that we have to code something that trivial, and the second (as we saw in our project), that the editor update could be quite tricky (missing or not deleted annotations).

My theory is, that we have encountered some kind of race condition with our naive implementation, as the annotation creation code was always executed, but sometimes the results were lost. So, in the end, this listener is not so trivial. 🙁

Automatic annotation display

This was the part that gave us the most headache – we did not understand, what caused the inconsistent display problem. On the other hand, knowing one extra fact (“magic”) the problem is trivially solvable.

So, here comes the Eclipse magic: we don’t have to create this service manually, we should reuse the already existing one. For that, we would need that our marker also become a child marker of the org.eclipse.core.resources.textmarker, and a minimal set of position data should be added to the marker.

This position information is described by the start and end offset value – instead of the human-readable line/column position information a machine-readable single position is used: the number of characters that has to be read from the start of the string stream. Its lucky, that most parser generators provide such output that this information is trivially available from the AST level

   <extension
         id="vtclparsermarker"
         name="VTCL Parsing Problems"
         point="org.eclipse.core.resources.markers">
      <super
            type="org.eclipse.core.resources.problemmarker">
      </super>
      <persistent
            value="true">
      </persistent>
      <super
            type="org.eclipse.core.resources.textmarker">
      </super>
   </extension>

And the marker creator Java code looks as follows:

IMarker marker = file.createMarker(markerId);
marker.setAttribute(IMarker.SEVERITY, severity);
marker.setAttribute(IMarker.MESSAGE, message);
marker.setAttribute(IMarker.LINE_NUMBER, line);
if (pos.offset != 0) {
  marker.setAttribute(IMarker.CHAR_START,pos.offset);
  marker.setAttribute(IMarker.CHAR_END,pos.offset+pos.length);
}

After that, the platform uses a default implementation, that provides the well-known wriggly underline to annotate our text files with the associated markers.

Summary

Altogether, the following steps are needed to provide a simple error reporting for our existing editor:

  • Create a custom marker type
    • With a supertype of org.eclipse.core.resources.problemmarker to display the report in the problems view
    • With a supertype of org.eclipse.core.resources.textmarker to underline the errors in the textual editor
  • Create a marker instance
    • Setting the IMarker.SEVERITY, IMarker.MESSAGE and IMarker.LINE_NUMBER attributes for the Problems view.
    • Setting the IMarker.CHAR_START and IMarker.CHAR_END for the editor annotations.

Conclusion

The Eclipse text editors provide a well-defined, easy to use error reporting mechanism nearly for free. The main catch is, we have to be careful to set everything – if something is missing, we got the silent failure issue – no exception is thrown, but something is not shown.

The biggest issue in our implementation was that the IMarker.CHAR_START and IMarker.CHAR_END marker attributes are ignored, if the used marker is not a text attribute, making this problem hard to identify.

A fine thing with this error reporting mechanism is, that it is independent of the concrete text editor used: when we changed our implementation in the VIATRA framework, the resulting reports were visible in every text editor (e.g. the dedicated VIATRA text editor, or the default text editor in Eclipse) – thus helping error recovery.