Best practices for developing Eclipse plug-ins

Part 1: Create your own tag

What is Mark?

Tags are used to link information to a resource without changing the resource. Common examples of marked information include breakpoints, bookmarks, and compilation errors. Taking compilation errors as an example, each time a compilation job is executed, the job will browse the source and highlight the error by creating a new tag.

 

Back to Top

Extension tag

In the first part of this tutorial, we will create our own tag. You only need to mark the extension point and write a line of code to complete this task.

You canIMarkerExpand org. Eclipse. Core. Resources. Markers to create your own tag. First, add the code in Listing 1 to the plugin. xml file. That is, you will create a tag named my marker with the ID com. IBM. mymarkers. mymarker. Its super type is org. Eclipse. Core. Resources. Marker. This is the most basic tag type. You can expand other super types that provide slightly more specific functions. Other super types include:

• Org. Eclipse. Core. Resources. problemmarker
• Org. Eclipse. Core. Resources. textmarker

Note:You can use any number of these supertypes as needed.

Listing 1. Listing 1 tag extension definitions from plugin. xml

<extension point="org.eclipse.core.resources.markers" id="com.ibm.mymarkers.mymarker" name="My Marker"><super type="org.eclipse.core.resources.marker"/><persistent value="false"/><attribute name="description"/></extension>

 

Note the two elements in Listing 1persistentAndattribute. These are all allocatedmymarkerTag attributes. Persistent indicates whether the tag should be stored in the workspace. Another one is assignedmymarkerNew attributedescription.

 

Back to Top

Use new tag

You can callcreateMarkerMethod To create a tag. You can also set attributes for these attributes.

The method shown in Listing 2 can also be used to create a tag. Just enterIResource, Link it to the tag. After creation, you can set its attributes.

Listing 2. Listing 2 creating Java code with a new tag type

public static IMarker createMarker(IResource res)throws CoreException { IMarker marker = null; //note: you use the id that is defined in your plugin.xml marker = res.createMarker("com.ibm.mymarkers.mymarker"); marker.setAttribute("description," "this is one of my markers"); //note: you can also use attributes from your supertype marker.setAttribute(IMarker.MESSAGE, "My Marker"); return marker;}

 

 

Back to Top

Find your tag

To search for andIResourceRelated tags, You can query resources to obtain all tags with a specified ID, and specify whether to search for related resources. To search for tags, callfindMarkersMethod. Specify parameters such as tag type and search depth.

Use the code in listing 3IResource.DEPTH_ZEROSearch for tags that are directly linked to the resource.

Listing 3. Search for Java code of the new tag type

public static final String MARKER = "com.ibm.mymarkers.mymarker";public static List<IMarker> findMarkers(IResource resource) { try { return Arrays.asList(resource.findMarkers(MARKER, true, IResource.DEPTH_ZERO)); } catch (CoreException e) { return new ArrayList<IMarker>(); } }

 

Change the resource depthIResource.DEPTH_INFINITEThe associated tags or any sub-resources are returned. For example, you can pass in a package and obtain all the tags linked to the resources in the package.

Part 1: Use annotations to display and update tags

What is annotation?

Annotation is used to mark a text area in the editor. They are widely used to display information in eclipse, such as errors, warnings, build problems, tasks, or breakpoints. Annotations are displayed on the editor ruler and text. Figure 1 lists comments with syntax errors.

Figure 1. Example of a comment

A common annotation implementation is to generate a tag when parsing a file and selecting tags such as errors and "Todo. This is usually done during build. Link other links to persistent tags, such as breakpoints. This example uses a persistent tag.

You can use the menu to view comments.General>Editors>Text editors>AnnotationsThe preference panel under is customized. In other words, you do not need to perform additional work for custom annotations.

Figure 2. Figure 2 comment on the screen of the preference panel

View the big chart.

 

Back to Top

Attributes of a tag extension point

In section 1st of this tutorial, the tag only extends the default tag type. In section 2nd, we will extend the text markup type to mark the text location. This type defines two key attributes:charStartAndcharEnd. We also want to mark the session as persistent, So we change the persistent valuetrue. To this end, we need to update the tag defined in Listing 4.

Listing 4. Listing 4 tag extension definitions from plugin. xml

<extension point="org.eclipse.core.resources.markers" id="com.ibm.mymarkers.mymarker" name="My Marker"><super type="org.eclipse.core.resources.textmarker"/><super type="org.eclipse.core.resources.marker"/><persistent value="true"/></extension>

 

Back to Top

Define Your annotation specification Extension

To create your own annotations, use the extension pointsorg.eclipse.ui.editors.markerAnnotationSpecification(See listing 5 ). It defines the annotation attributes and its default display options.

Listing 5. Listing 5 annotation extension definitions from plugin. xml

<extension point="org.eclipse.ui.editors.markerAnnotationSpecification"id="myannotationspecification" name="MyAnnotation"><specification annotationType="com.ibm.example.myannotation"label="MyAnnotation"icon="icons/sample.gif"overviewRulerPreferenceKey="clruler"overviewRulerPreferenceValue="true"colorPreferenceKey="clcolor"colorPreferenceValue="255,255,0"textPreferenceKey="cltext"textPreferenceValue="true"verticalRulerPreferenceKey="clvertical"verticalRulerPreferenceValue="true"textStylePreferenceKey="clstyle"textStylePreferenceValue="BOX"></specification></extension>

The section in XML that we will use to link to the specification isidAndannotationTypeAttribute. Eclipse.org records other attributes used for customization (see references ).

The next step is to use the extension pointorg.eclipse.ui.editors.annotationTypesLink existing tags to the New Annotation specification. We use the annotation type from the specification and the ID from the tag definition to link the specification.

Listing 6. Listing 6 annotation type definitions from plugin. xml

<extension point="org.eclipse.ui.editors.annotationTypes"> <type markerSeverity="0" super="org.eclipse.ui.workbench.texteditor.info" name="com.ibm.example.myannotation"markerType="com.ibm.mymarkers.mymarker"/></extension>

See references to find more information about this extension point on eclipse.org.

 

Back to Top

Create and add a comment to the editor

The code in listing 7 is used to create and add comments to the editor.

Listing 7. Listing 7 Add a new comment to the editor

public static void addAnnotation(IMarker marker, ITextSelection selection, ITextEditor editor) { //The DocumentProvider enables to get the document currently loaded in the editor IDocumentProvider idp = editor.getDocumentProvider(); //This is the document we want to connect to. This is taken from //the current editor input. IDocument document = idp.getDocument(editor.getEditorInput()); //The IannotationModel enables to add/remove/change annotation to a Document //loaded in an Editor IAnnotationModel iamf = idp.getAnnotationModel(editor.getEditorInput()); //Note: The annotation type id specify that you want to create one of your //annotations SimpleMarkerAnnotation ma = new SimpleMarkerAnnotation(“com.ibm.example.myannotation”,marker); //Finally add the new annotation to the model iamf.connect(document); iamf.addAnnotation(ma,newPosition(selection.getOffset(),selection.getLength())); iamf.disconnect(document);}

 

Back to Top

Keep tags and comments synchronized

The comment mode is used to move the comment when the document is edited. However, when the annotation is moved, it does not update the tag attributes. In this case, we need to update the markedcharStartAndcharEndAttribute. The last extension point is the Updater ). It defines a class for updating tags when moving comments.

Listing 8. Listing 8 tag Updater definitions from plugin. xml

<extension point="org.eclipse.ui.editors.markerUpdaters"> <updater id="com.ibm.example.MarkerUpdater" class="com.ibm.example.mymarker.MarkerUpdater" markerType="com.ibm.mymarkers.mymarker"> </updater></extension>:

We use the imarkerupdater interface to provide the code we want to execute when moving comments. The class shown in listing 9 is our tag Updater. The code we are interested in is inupdateMarkerMethod. Here, we use it to update the markedcharStartAndcharEndAttribute.

Listing 9. Listing 9 marking the Updater code

public class MarkerUpdater implements IMarkerUpdater { /* *Returns the attributes for which this updater is responsible. *If the result is null, the updater assumes responsibility for any attributes. */ @Override public String[] getAttribute() { return null; } @Override public String getMarkerType() { //returns the marker type that we are interested in updating return "com.ibm.mymarkers.mymarker"; } @Override public boolean updateMarker(IMarker marker, IDocument doc, Position position) { try { int start = position.getOffset(); int end = position.getOffset() + position.getLength(); marker.setAttribute(IMarker.CHAR_START, start); marker.setAttribute(IMarker.CHAR_END, end); return true; } catch (CoreException e) { return false; } }}

Part 1: Use modifiers to identify marked iresources

What is a modifier?

In eclipse, modifiers are used to add visual information to objects in the workspace. They usually display the object type and any important attributes related to the object. Figure 3 shows how to display modifiers to users in package explorer. This modifier displays the Java source files or packages and the markup icons for the source packages that contain warnings or errors. Here, the modifier is also used to add details, such as whether the file is synchronized with the repository.

Figure 3. Figure 3 package and source modified with symbol icons

 

Back to Top

Define your own Modifier

The first step to add our modifier is to expandorg.eclipse.ui.decoratorsExtension point. It enables the definition of the new modifier and selects the object to be modified.

The important fields here are:

• Class, It must be an implementationILightweightLabelDecoratorClass (set lightweight to true ).
• EnablementContains the list of eclipse objects to which the modifier applies.

Listing 10. Listing 10 modifier definitions from plugin. xml

<extension point="org.eclipse.ui.decorators"> <decorator id="com.ibm.example.filedecorator" label="MyMarker Decorator" state="true" class= "com.ibm.example.mymarker.FileDecorator" adaptable="true" lightweight="true"> <enablement><objectClass name="org.eclipse.core.resources.IResource"/> </enablement> </decorator></extension>

See references to find more extension Point files on eclipse.org.

Note:Lightweight and non-lightweight: According to the API, non-lightweight modifiers may be discarded in the new release of javase.

 

Back to Top

Our file modifier class

We need to implementFileDecoratorClass to determine the modifier behavior. This type must be implementedILightweightLabelDecorator. Use it to expandLabelProviderThe idea is very good, because it allows us to rewrite only the methods we are interested in, that isdecorate().

decorate()As shown in listing 11.

Listing 11. Listing 11decorate()Simple implementation

public void decorate(Object resource, IDecoration decoration) {decoration.addOverlay(ImageDescriptor.createFromFile(FileDecorator.class, "/icons/sample.gif"), IDecoration.TOP_RIGHT);decoration.addPrefix("My Prefix ");decoration.addSuffix(" My Suffix");}

IDecorationObjects can also be used to customize the font, text, or background color.

Figure 4. Code screen used to modify iresources in listing 11

decorate()The first parameter can be used to filter the resources to be modified. If you only want to modify the resource that contains the specified tag, use the code shown in listing 12.

Listing 12. Listing 12 modifying resources with the specified tag

public void decorate(Object resource, IDecoration decoration) {if(resource instanceof IResource){List<IMarker> markers = MyMarkerFactory.findMarkers((IResource) resource);if (markers.size() > 0) {decoration.addSuffix(" Marker !!");}}}

You have followed the steps in this tutorial. What should you do next?

Further improvements include:

• Add editable attributes for the tag.Allows you to change the flag status.
• Automatically create and delete tags.Use the background processing job to automatically create, update, and delete tags.
• The hover of the custom tag.Use the advanced flag hover to support HTML or multimedia content.

In this tutorial, we use eclipse to easily create and customize tags and perform advanced resource tagging. Developers are encouraged to use this simple and powerful tool to perfectly integrate their plug-ins into Eclipse IDE. However, note that if this feature is used too widely, it will be abrupt for users. In addition, it is the responsibility of developers to take into account the eclipse User Interface Guide to maintain the eclipse appearance and style. For more information, see references.

Publish via wiz