X

Geertjan's Blog

  • December 4, 2006

Creating Error Annotations in NetBeans IDE (Part 3)

Geertjan Wielenga
Product Manager
Here's how to create a simple annotation, which despite its simplicity gives a complete overview of how annotations work in NetBeans IDE. Here we add bold tags around selected text, as described elsewhere in this blog, and then highlight the whole line in green (see illustration at the end of this blog entry to see the result).

  1. In your module project (which here has the code name base org.netbeans.modules.yourfirstannotation), create an XML file called "HTMLAnnotation.xml". Here's the content:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE type PUBLIC
    "-//NetBeans//DTD annotation type 1.1//EN"
    "http://www.netbeans.org/dtds/annotation-type-1_1.dtd">
    <type name="org-netbeans-modules-yourfirstannotation"
    description_key="yourfirstannotation"
    localizing_bundle="org.netbeans.modules.yourfirstannotation.Bundle"
    visible="true"
    glyph="nbresloc:/org/netbeans/modules/java/resources/error-glyph.gif"
    highlight="#66CC33"
    type="line"
    browseable="false"
    severity="ok"
    />

    Note 1: The value of visible determines whether the annotation will be visible in the Advanced section of the Options window. In the Advanced section, the value of description_key determines the display name of the annotation. The display name is defined in the bundle specified by localizing_bundle.

    Note 2: Here we reuse the error glyph, even though it isn't really relevant to what we're doing. We're just adding a highlight to the changed line, so that isn't really an error. There are various other glyphs we could use instead. The highlight here is green. Instead of, or in addition to highlight, we could use foreground (to change the font) and waveunderline (to create the squiggly red underline marking typical to the NetBeans editors).

    Note 3: Here we're not creating an error, despite the misleading glyph, and therefore the severity is set to ok, which will add a green mark to the right sidebar. Alternatives are warning (yellow mark), error (red mark), and none (no mark).

    Further reading: http://www.netbeans.org/dtds/annotation-type-1_1.dtd

  2. Register the XML file in your Layer XML file:

    <folder name="Editors">
    <folder name="AnnotationTypes">
    <file name="org-netbeans-modules-yourfirstannotation.xml"
    url="HTMLAnnotation.xml">
    </file>
    </folder>
    </folder>

  3. Now lets describe the annotation in Java code. All we really need in this simple example is for the annotation to be retrieved via its name in the Layer XML file, together with a short description that will be displayed when the mouse hovers over the glyph. So, here's our annotation:

    private static final class InsertAnnotation extends Annotation {
    static final InsertAnnotation DEFAULT = new InsertAnnotation();
    public String getAnnotationType() {
    return "org-netbeans-modules-yourfirstannotation";
    }
    public String getShortDescription() {
    return "Bold tags were added around \\"" + selection + "\\"!";
    }
    }

    Further reading: org.openide.text.Annotation

  4. Now lets use our annotation in the code. The important thing, as pointed out in the previous blog entries on this subject, is that you need to identify an instance of org.openide.text.Line or org.openide.text.Line.Part. Once you have defined a line or a part of a line, you simply attach the annotation to it.

    So, lets set things up by following the steps in Module development for web developers. At the end, you'll be able to select text in a JSP file and use a menu item to add bold tags around the selected text. We're going to enhance that functionality by also highlighting the changed line.

    protected void performAction(Node[] activatedNodes) {
    JTextComponent editor = Registry.getMostActiveComponent();
    selection = editor.getSelectedText();
    if (selection.length() > 0) {
    editor.replaceSelection("<b>" + selection + "</b>");
    //We use the very powerful NbEditorUtilities.getLine()
    //to extract a line from the current document and offset,
    //for which we need a DocumentListener, as described in the next step:

    Line myLine = NbEditorUtilities.getLine(doc, myDocumentListener.getOffset(), false);//Here we attach our annotation to the line:
    InsertAnnotation.DEFAULT.attach(myLine);
    }
    }

    We could also get the line from the JTextComponent, but we need the DocumentListener anyway, for detaching the annotation when the user undoes the insertion.

    Two global variable are needed:

    MyDocumentListener myDocumentListener = new MyDocumentListener();
    static String selection;

    Further reading: Annotation.attach, NbEditorUtilities.getLine, org.openide.text.Line.

  5. We need a DocumentListener, otherwise we won't know the offset at the location of the inserted text. We also need the DocumentListener for detaching the annotation if "Undo" is used to undo the insertion.

    private class MyDocumentListener implements DocumentListener {
    int offset;
    /\*\* Creates a new instance of MyDocumentListener \*/
    public MyDocumentListener() {
    }//We get the offset when inserting the changed text:
    public void insertUpdate(DocumentEvent e) {
    offset = e.getOffset();
    }//When/if we remove the inserted text,
    //we detach the annotation:

    public void removeUpdate(DocumentEvent e) {
    InsertAnnotation.DEFAULT.detach();
    }
    public void changedUpdate(DocumentEvent e) {
    }
    public int getOffset() {
    return offset;
    }
    }

    Further reading: Annotation.detach

  6. Install the module and use the menu item as before. The difference is that the line is now highlighted and the glyph appears in the left margin (and an error mark in the right margin, for navigation to the line):

    Now play around with the definition of the annotation in the XML fle you defined at the start. Also go to the Advanced section of the Options window and look in the Annotation Types section (within "Editing") and notice that the user can change some of the attributes that you defined in the XML file.

    Further reading: http://www.netbeans.org/dtds/annotation-type-1_1.dtd

Join the discussion

Comments ( 1 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha
Oracle

Integrated Cloud Applications & Platform Services