Decoradores

org.eclipse.ui.decorators

Edição 2.0

Este ponto de extensão é utilizado para adicionar decoradores a vistas que estão subscritas num gestor de decoradores. A partir da edição 2.1, existe o conceito de decorador leve que processará a gestão de imagem em nome do decorador. Também é possível declarar um decorador leve que, quando activado, simplesmente sobrepõe um ícone que não requer qualquer implementação do plug-in.

A activação e/ou visibilidade de uma acção pode ser definida utilizando os elementos enablement e visibility, respectivamente. Estes dois elementos contêm uma expressão booleana que é avaliada para determinar a activação e/ou visibilidade.

A sintaxe é igual para os elementos enablement e visibility. Ambos contêm apenas um subelemento de expressão booleana. No caso mais simples, este será um elemento objectClass, objectState, pluginState ou systemProperty. No caso mais complexo, os elementos and, or e not podem ser combinados para formar uma expressão booleana. Tanto o elemento and como o elemento or têm de conter dois subelementos. O elemento not tem de conter apenas um subelemento.

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

classe       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) >


<!ELEMENT description (#PCDATA)>

um subelemento opcional cujo corpo contém um breve texto descritivo do decorador. Este será mostrado na página de preferências Decoradores e, por isso, recomenda-se que seja incluído. O valor predefinido é uma cadeia vazia.



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

Este elemento é utilizado para definir a activação da extensão.



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

Este elemento é utilizado para definir a visibilidade da extensão.



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

Este elemento representa uma operação AND booleana no resultado de avaliação das duas expressões de subelemento respectivas.



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

Este elemento representa uma operação OR booleana no resultado de avaliação das duas expressões de subelemento respectivas.



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

Este elemento representa uma operação NOT booleana no resultado de avaliação das expressões de subelemento respectivas.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

Este elemento é utilizado para avaliar a classe ou interface de cada objecto na selecção actual. Se cada objecto da selecção implementar a classe ou interface especificadas, a expressão é avaliada como true.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Este elemento é utilizado para avaliar o estado do atributo de cada objecto na selecção actual. Se cada objecto da selecção possuir o estado de atributo especificado, a expressão é avaliada como true. Para avaliar este tipo de expressão, cada objecto na selecção tem de implementar ou adaptar-se à interface org.eclipse.ui.IActionFilter.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Este elemento é utilizado para avaliar o estado de um conector. O estado do conector pode ser um dos seguintes: installed (equivalente ao conceito OSGi de "resolved") ou activated (equivalente ao conceito OSGi de "active").



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Este elemento é utilizado para avaliar o estado de alguma propriedade do sistema. O valor property é obtido a partir de java.lang.System.



De seguida é apresentado um exemplo de decoradores:

Um decorador completo. O programador de plug-ins tem de processar o seu próprio suporte de imagem.

 

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

Um decorador leve. Existe uma classe concreta, mas devido ao facto de ser um decorador de tipo ILightweightLabelDecorator, só precisa de facultar texto e um ImageDescriptor, dispensando assim qualquer processamento de recursos.

 

<extension point=

"org.eclipse.ui.decorators"

>

<decorator id=

"com.xyz.lightweight.decorator"

label=

"Decorador Leve XYZ"

state=

"false"

class=

"com.xyz.LightweightDecoratorContributor"

lightweight=

"true"

>

<enablement>

<objectClass name=

"org.eclipse.core.resources.IResource"

/>

</enablement>

</decorator>

</extension>

Um decorador leve declarativo. Não existe qualquer classe concreta e, consequentemente, faculta um ícone e um quadrante para aplicar esse ícone.

 

<extension point=

"org.eclipse.ui.decorators"

>

<decorator id=

"com.xyz.lightweight.declarative.decorator"

label=

"Decorador Leve Declarativo XYZ"

state=

"false"

lightweight=

"true"

icon=

"icons/full/declarative.gif"

location=

"TOP_LEFT"

>

<enablement>

<objectClass name=

"org.eclipse.core.resources.IResource"

/>

</enablement>

</decorator>

</extension>

O valor do atributo class tem de ser o nome totalmente qualificado de uma classe que implemente org.eclipse.jface.viewers.ILabelDecorator (caso lightweight seja false) ou org.eclipse.jface.viewers.ILightweightLabelDecorator. Esta classe é carregada o mais tarde possível, para evitar carregar a totalidade do conector antes que seja realmente necessário. Os decoradores declarativos não implicam a activação de qualquer plug-in e devem ser utilizados sempre que possível. Os decoradores que não sejam leves acabarão por se tornar obsoletos.

Os plug-ins podem utilizar este ponto de extensão para adicionar novos decoradores a aplicar a vistas que utilizem o gestor de decoradores como seu decorador de etiquetas. Para utilizar o gestor de decoradores, utilize o resultado de IViewPart.getDecoratorManager() como o decorador de uma instância-objecto DecoratingLabelProvider. Esta implementação é actualmente utilizada pelo Navegador de Recursos.