#
Decorators

###### Identifier:

org.eclipse.ui.decorators

###### Since:

Release 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.

An action's enablement and/or visibility can be defined using the elements `enablement` and `visibility` respectively. These two elements contain a boolean expression that is evaluated to determine the enablement and/or visibility.

The syntax is the same for the `enablement` and `visibility` elements. Both contain only one boolean expression sub-element. In the simplest case, this will be an `objectClass`, `objectState`, `pluginState`, or `systemProperty` element. In the more complex case, the `and`, `or`, and `not` elements can be combined to form a boolean expression. Both the `and`, and `or` elements must contain 2 sub-elements. The `not` element must contain only 1 sub-element.

###### 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

location (TOP_LEFT|TOP_RIGHT|BOTTOM_LEFT|BOTTOM_RIGHT|UNDERLAY) >

- 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 true.
- 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 adapt to IResource should use this object contribution. This flag is used only if objectClass adapts to IResource. 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.

<!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.

<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element is used to define the enablement for the extension.

<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element is used to define the visibility for the extension.

<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element represent a boolean AND operation on the result of evaluating it's two sub-element expressions.

<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element represent a boolean OR operation on the result of evaluating it's two sub-element expressions.

<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>

This element represent a boolean NOT operation on the result of evaluating it's sub-element expressions.

<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

This element is used to evaluate the class or interface of each object in the current selection. If each object in the selection implements the specified class or interface, the expression is evaluated as true.

- name - a fully qualified name of a class or interface. The expression is evaluated as true only if all objects within the selection implement this class or interface.

<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name CDATA #REQUIRED

value CDATA #REQUIRED>

This element is used to evaluate the attribute state of each object in the current selection. If each object in the selection has the specified attribute state, the expression is evaluated as true. To evaluate this type of expression, each object in the selection must implement, or adapt to, `org.eclipse.ui.IActionFilter` interface.

- name - the name of an object's attribute. Acceptable names reflect the object type, and should be publicly declared by the plug-in where the object type is declared.
- value - the required value of the object's attribute. The acceptable values for the object's attribute should be publicly declared.

<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id CDATA #REQUIRED

value (installed|activated) "installed">

This element is used to evaluate the state of a plug-in. The state of the plug-in may be one of the following: `installed` or `activated`.

- id - the identifier of a plug-in which may or may not exist in the plug-in registry.
- value - the required state of the plug-in. The state of the plug-in may be one of the following: `installed` or `activated`.

<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name CDATA #REQUIRED

value CDATA #REQUIRED>

This element is used to evaluate the state of some system property. The property value is retrieved from the `java.lang.System`.

- name - the name of the system property.
- value - the required value of the system property.

###### 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.gif"
                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, 2004 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html