Decoradores

Identificador: org.eclipse.ui.decorators

A partir del: Release 2.0

Descripción: este punto de extensión sirve para añadir decoradores a las vistas que estén suscritas a un gestor de decoradores. A partir del release 2.1, se introducirá la noción de decorador ligero, que manejará la gestión de imagen del decorador. También es posible declarar un decorador ligero que, cuando se habilita, recubre simplemente un icono que no requiere implementación del conector.

La habilitación y/o visibilidad de una acción puede definirse mediante los elementos enablement y visibility, respectivamente. Estos dos elementos contienen una expresión booleana que se evalúa para determinar la habilitación y/o visibilidad.

La sintaxis es la misma para ambos elementos, enablement y visibility. Ambos contienen sólo un subelemento de expresión booleana. En el caso más simple, se tratará de un elemento objectClass, objectState, pluginState o systemProperty. En el caso más complejo, pueden combinarse los elementos and, or y not para formar una expresión booleana. Tanto lo elementos and como los elementos or deben contener 2 subelementos. El elemento not debe contener sólo 1 subelemento.

Códigos XML de configuración:

   <!ELEMENT extension (decorator*)>

   <!ATTLIST extension
     point CDATA #REQUIRED
     id    CDATA #IMPLIED
     name  CDATA #IMPLIED
   >

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

   <!ATTLIST decorator
      id          CDATA #REQUIRED
      label       CDATA #REQUIRED
     class       CDATA #IMPLIED
     objectClass CDATA #IMPLIED
     adaptable   (true | false)
     state       (true | false)
     quadrant    (TOP_LEFT|TOP_RIGHT|BOTTOM_RIGHT|BOTTOM_LEFT)
     lightweight (true|false)
      icon        CDATA #IMPLIED
     location    (TOP_LEFT|TOP_RIGHT|BOTTOM_LEFT|BOTTOM_RIGHT|UNDERLAY)
   >

   <!ELEMENT description (#CDATA)>

   subelemento opcional cuyo cuerpo debe contener un texto descriptivo corto del decorador. Es aconsejable incluir este subelemento, porque se mostrará en la página Decoradores de las preferencias. El valor por omisión es una serie vacía.

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

   Este elemento se utiliza para definir la habilitación de la acción.

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

   Este elemento se utiliza para definir la visibilidad de la acción.

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

   Este elemento representa una operación booleana AND en el resultado de evaluar sus dos expresiones de subelemento.

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

   Este elemento representa una operación booleana OR en el resultado de evaluar sus dos expresiones de subelemento.

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

   Este elemento representa una operación booleana NOT en el resultado de evaluar sus dos expresiones de subelemento.

   <!ELEMENT objectClass EMPTY>

   Este elemento se utiliza para evaluar la clase o interfaz de cada objeto de la selección actual. Si cada objeto de la selección implementa la clase o interfaz especificada, la expresión se evalúa como true.

   <!ATTLIST objectClass
     name CDATA #REQUIRED
   >

   <!ELEMENT objectState EMPTY>

   Este elemento se utiliza para evaluar el estado de atributo de cada objeto de la selección actual. Si cada objeto de la selección tiene el estado de atributo especificado, la expresión se evalúa como true. Para evaluar este tipo de expresión, cada objeto de la selección debe implementar o adaptarse a la interfaz org.eclipse.ui.IActionFilter.

   <!ATTLIST objectState
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >

   <!ELEMENT pluginState EMPTY>

   Este elemento se utiliza para evaluar el estado de un conector. El estado del conector puede ser una de los siguientes: instalado (installed) o activado (activated).

   <!ATTLIST pluginState
      id    CDATA #REQUIRED
     value (installed|activated) "installed"
   >

   <!ELEMENT systemProperty EMPTY>

   Este elemento se utiliza para evaluar el estado de alguna propiedad del sistema. El valor de propiedad se recupera de java.lang.System.

   <!ATTLIST systemProperty
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >
Ejemplos: a continuación figura un ejemplo de decoradores:

Un decorador completo. El desarrollador del conector debe manejar su propio soporte de imagen.

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

Un decorador ligero. Existe una clase concreta, pero dado que se trata de un decorador de tipo ILightweightLabelDecorator, sólo necesita suministrar texto y un ImageDescriptor y, por tanto, no necesita manejo de recursos.

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

Un decorador ligero declarativo. No existe ninguna clase concreta, y por tanto suministra un icono y un cuadrante al que aplicar ese icono.

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

Información sobre las API: el valor del atributo class debe ser el nombre totalmente calificado de una clase que implemente org.eclipse.jface.viewers.ILabelDecorator (si lightweight es false) o org.eclipse.jface.viewers.ILightweightLabelDecorator. Esta clase se cargará lo más tarde posible para evitar que se cargue todo el conector antes de que sea realmente necesario. Los decoradores declarativos no implican la activación de ningún conector, y deben utilizarse siempre que sea posible. Con el tiempo, los decoradores no ligeros quedarán obsoletos.

Implementación suministrada: los conectores pueden utilizar este punto de extensión para añadir decoradores nuevos a las vistas que utilizan el gestor de decoradores como decorador de etiquetas. Para utilizar el gestor de decoradores, emplee el resultado del método IViewPart.getDecoratorManager() como decorador de una instancia de DecoratingLabelProvider. Esto se está utilizando actualmente en el navegador de recursos.

Copyright (c) 2002, 2003 IBM Corporation y otros. Reservados todos los derechos. Este programa y sus materiales adjuntos están disponibles bajo los términos de la licencia pública común (Common Public License) v1.0 que acompaña a esta distribución, y está disponible en http://www.eclipse.org/legal/cpl-v10.html