The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerworks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

All information submitted is secure.

My developerWorks:

My notifications:

Sign out

Select a language:

Best practices for developing Eclipse plugins

Using markers, annotations, and decorators

Andy Flatt (aflatt@uk.ibm.com), Software Developer, IBM

Andy Flatt is a developer at the IBM UK Software Development Laboratory in Hursley. His background includes Java, Java Performance, OSGi, and integration test. Prior to software development, Andy studied at the University of Hertfordshire where he holds a first class BSc(Hons) degree in Computer Science. He may be reached at aflatt@uk.ibm.com.

Mickael Maison (mimaison@uk.ibm.com), Software Developer, IBM

Since joining IBM in mid-2009, Mickael has been working in the Runtime Deliveries department of the IBM Java Technology Center. After working on the L3 Support team for the IBM Java SDK, he moved to a developer role. In his spare time, Mickael enjoys music and traveling.

Summary: This tutorial highlights best practices when marking information to resources using markers, and then introduces annotations and decorators that you use to highlight markers within the workbench. By extending extension points, you can reuse and adapt the built-in functions in Eclipse and perform advanced resource marking, such as moving a text marker when editing text. We discuss methods that take advantage of the plugin model, which allows for an efficient, high performance, and integrated look and feel plugin.

Date: 16 Aug 2011
Level: Intermediate
PDF: A4 and Letter (99 KB | 14 pages)Get Adobe® Reader®

Activity: 56432 views
Comments:

Part 3: Use decorators to identify marked IResources

What are decorators?

Within Eclipse, decorators are used to add visual information to objects in the workbench. Usually, they display the object type and any key properties currently associated with that object. Figure 3 shows how decorators are displayed in the package explorer to the user. The decorators show which items are Java source files or packages, and shows marker icons for source and packages that contain warnings or errors. Here decorators are also used to add team details, such as whether the files are in or out of sync with the repository.

Figure 3. Packages and source decorated with symbolic icons
Screenshot shows little symbols such as yellow circles and blue arrows added to the file icons

Screenshot shows little symbols such as yellow circles and blue arrows added to the file icons

Define your own decorator

The first step to add our decorator is to extend the org.eclipse.ui.decorators extension point. It enables the definition of a new decorator, and selects what kind of objects it will decorate.

The important fields here are:

class, — which must be the fully qualified name of a class that implements ILightweightLabelDecorator (as lightweight is set to true).
enablement, — which contains the list of Eclipse objects to which the decorator applies.

Listing 10. Decorator definition from the 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 Resources for more documentation on extension point from Eclipse.org.

Note: Lightweight vs. Non-Lightweight: According to the API, non-lightweight decorators may become deprecated in future versions of Eclipse.

Our file decorator class

We need to implement the class FileDecorator to determine the behavior of our decorator. This class has to implement ILightweightLabelDecorator. It is good idea to have it extend LabelProvider as this will allow us to only override the method in which we are interested, that is, decorate().

A basic implementation of decorate() is shown in Listing 11.

Listing 11. Basic implementation of decorate()

                    
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");
}

The IDecoration object also allows customization of the font and text/background color.

Figure 4. A screenshot of the code in Listing 11 decorating IResources
Screenshot shows the results of the executed code, placing decorations on the file icons

Screenshot shows the results of the executed code, placing decorations on the file icons

The first argument of decorate() can be used to filter the resources we want to decorate. If we only want to decorate resources that contain specific markers, we use code exampled in Listing 12.

Listing 12. Decorate resources with specific markers


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 this tutorial, what's next?

Advanced improvements can include:

Add editable properties to markers. Allow the user to change the state of the markers
Automate the creation and deletion of markers. Use background processing jobs to create, update, and delete markers automatically.
Customize the marker hovers. Use advance marker hovers to support HTML or multimedia content

In this tutorial, we used Eclipse to easily create and customize markers and perform advanced resource marking. Developers are encouraged to use this simple, yet powerful tool to perfectly integrate their plugins into the Eclipse IDE. Keep in mind, however, that this feature can become obtrusive to the user if implemented too extensively. Furthermore, it is the responsibility of the developer to maintain the Eclipse look and feel by taking into consideration the Eclipse User Interface Guidelines, see Resources.