Decorators

Identifier:

org.eclipse.ui.decorators

Since:

2.0

Description:

This extension point is used to add decorators to views that subscribe to a decorator manager. As of 2.1 there is the concept of a lightweight decorator that will handle the image management for the decorator. It is also possible to declare a lightweight decorator that simply overlays an icon when enabled that requires no implementation from the plug-in.

Configuration Markup:

<!ELEMENT extension (decorator*)>

<!ATTLIST extension

point CDATA #REQUIRED

id CDATA #IMPLIED

name CDATA #IMPLIED>

point - a fully qualified identifier of the target extension point
id - an optional identifier of the extension instance
name - an optional name of the extension instance

<!ELEMENT decorator (description? , enablement?)>

<!ATTLIST decorator

id CDATA #REQUIRED

label CDATA #REQUIRED

class CDATA #IMPLIED

objectClass CDATA #IMPLIED

adaptable (true | false)

state (true | false)

lightweight (true|false)

icon CDATA #IMPLIED

id - a unique name that will be used to identify this decorator.
label - a translatable name that will be used in the workbench window menu to represent this decorator.
class - a fully qualified name of a class which implements org.eclipse.jface.viewers.ILabelDecorator if lightweight is false or org.eclipse.jface.viewers.ILightweightLabelDecorator if lightweight is true. The default value is false. If there is no class element it is assumed to be lightweight. In the case where there is no decorator class this is said to be declarative. Declarative decorators with an enablement based on session properties, persistant properties or project description values (such as natures) will need to be updated explicitly when these values change using IDecoratorManager#update().
If the label decorator creates image descriptors for decorations, it must either ensure that the same instance is used for the same decorated object, or use an image descriptor implementation that implements #equals and #hashCode accordingly.
Deprecated objectClass - a fully qualified name of a class which this decorator will be applied to. Deprecated in 2.1. Make this value part of the enablement.
adaptable - a flag that indicates if types that can adapt to objects other than their objectClass should use this object contribution. For non-lightweight decorators, this flag only has an effect if objectClass adapts to IResource. For lightweight decorators, adaptability to any objectClass is supported as long as adaptability is defined through the adapter manager (see the class org.eclipse.runtime.IAdapterManager). Default value is false.
state - a flag that indicates if the decorator is on by default. Default value is false.
lightweight - The lightweight flag indicates that the decorator is either declarative or implements org.eclipse.jface.viewers.ILightweightLabelDecorator.
icon - if the decorator is lightweight and the class is not specified this is the path to the overlay image to apply
location - if the decorator is lightweight this is the location to apply the decorator to. Defaults to BOTTOM_RIGHT. A new possible value REPLACE was added in 3.4.

<!ELEMENT description (#PCDATA)>

an optional subelement whose body should contain text providing a short description of the decorator. This will be shown in the Decorators preference page so it is recommended that this is included. Default value is an empty String.

Examples:

The following are example of decorators:

A full decorator. The plug-in developer must handle their own image support.


 <extension point="org.eclipse.ui.decorators"> 
        <decorator
            id="com.xyz.decorator" 
            label="XYZ Decorator" 
            state="true" 
            class="com.xyz.DecoratorContributor">
            <enablement>
                <objectClass name="org.eclipse.core.resources.IResource"/> 
            </enablement>
        </decorator>
    </extension>

A lightweight decorator. There is a concrete class but as it is an ILightweightLabelDecorator it only needs to supply text and an ImageDescriptor and therefore needs no resource handling.


 <extension point="org.eclipse.ui.decorators"> 
        <decorator
            id="com.xyz.lightweight.decorator" 
            label="XYZ Lightweight Decorator"                 
            state="false" 
            class="com.xyz.LightweightDecoratorContributor" 
            lightweight="true" >
            <enablement>
                <objectClass name="org.eclipse.core.resources.IResource"/> 
            </enablement>
        </decorator>
    </extension>

A declarative lightweight decorator. There is no concrete class so it supplies an icon and a quadrant to apply that icon.


 <extension point="org.eclipse.ui.decorators"> 
        <decorator
            id="com.xyz.lightweight.declarative.decorator" 
            label="XYZ Lightweight Declarative Decorator" 
            state="false" 
            lightweight="true" 
            icon="icons/full/declarative.png"
            location="TOP_LEFT"> 
            <enablement>
                <objectClass name="org.eclipse.core.resources.IResource"/> 
            </enablement>
        </decorator>
    </extension>

API Information:

The value of the class attribute must be the fully qualified name of a class that implements org.eclipse.jface.viewers.ILabelDecorator (if lightweight is false) or org.eclipse.jface.viewers.ILightweightLabelDecorator. This class is loaded as late as possible to avoid loading the entire plug-in before it is really needed. Declarative decorators do not entail any plug-in activation and should be used whenever possible. Non-lightweight decorators will eventually be deprecated.

Supplied Implementation:

Plug-ins may use this extension point to add new decorators to be applied to views that use the decorator manager as their label decorator. To use the decorator manager, use the result of IViewPart.getDecoratorManager() as the decorator for an instance of DecoratingLabelProvider. This is currently in use by the Resource Navigator.

Copyright (c) 2002, 2014 IBM Corporation and others.
This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-v20.html/ SPDX-License-Identifier: EPL-2.0