Seu plug-in pode utilizar decoradores para anotar as imagens de recursos e outros objetos que aparecem nas exibições do workbench. Os decoradores são úteis quando seu plug-in inclui funcionalidade para tipos de recursos existentes. Muitas das exibições padrão do workbench participam na visualização de decorações.
Por exemplo, o PDE contribui com decoradores que permitem a distinção entre projetos binários e de origem.
O projeto com.example.helloworld é o único projeto de origem mostrado no navegador. Observe como todos os outros projetos binários mostram o decorador binário no lado superior esquerdo do ícone do projeto Java. Esse decorador recebe contribuição do PDE utilizando o ponto de extensão org.eclipse.ui.decorators.
<extension point="org.eclipse.ui.decorators"> <decorator lightweight="true" quadrant="TOP_LEFT" adaptable="true" label="%decorator.label" icon="icons/full/ovr16/binary_co.png" state="false" id="org.eclipse.pde.ui.binaryProjectDecorator"> <description> %decorator.desc </description> <enablement> ... </enablement> </decorator> </extension>
Existem várias maneiras diferentes de fornecer a implementação de um decorador. Essa marcação utiliza a maneira mais simples, conhecida como decorador declarativo leve. Quando um decorador declarativo leve é definido, a marcação contém uma descrição completa do ícone, posicionamento e condições de ativação do decorador. Os decoradores declarativos são úteis apenas quando um ícone é utilizado para decorar o rótulo. O plug-in precisa especificar apenas o quadrante em que o decorador deve ser sobreposto no ícone regular e o ícone para a sobreposição. Como mostrado na imagem, o ícone binário do PDE é sobreposto no quadrante superior esquerdo do ícone do pacote.
Se o seu plug-in precisar manipular o texto do rótulo além do ícone, ou se o tipo do ícone for determinado dinamicamente, é possível utilizar um decorador não-declarativo leve. Nesse caso uma classe de implementação que implemente ILightweightLabelDecorator deve ser definida. A classe designada é responsável pelo fornecimento de um prefixo, um sufixo e uma imagem de sobreposição em tempo de execução que são aplicados ao rótulo. A mecânica da concatenação do prefixo e do sufixo com o texto do rótulo e a execução da sobreposição são tratadas pelo código do workbench em um encadeamento de segundo plano. Assim, qualquer trabalho realizado pelo plug-in em sua implementação de ILightweightLabelDecorator deve ser seguro de encadeamento da UI. (Consulte Executando código de um encadeamento que não é da UI para obter detalhes adicionais.)
A marcação a seguir mostra como o cliente do CVS define seu decorador utilizando essa técnica:
<extension point="org.eclipse.ui.decorators"> <decorator objectClass="org.eclipse.core.resources.IResource" adaptable="true" label="%DecoratorStandard.name" state="false" lightweight= "true" quadrant = "BOTTOM_RIGHT" class="org.eclipse.team.internal.ccvs.ui.CVSLightweightDecorator" id="org.eclipse.team.cvs.ui.decorator"> <description> %DecoratorStandard.desc </description> </decorator> </extension>
Os decoradores são basicamente controlados pelo usuário por meio da página de preferências Decorações de Rótulo do workbench. Os decoradores individuais podem ser ativados e desativados. Ainda assim, é uma boa idéia fazer o design dos decoradores de forma que eles não sobreponham ou conflitem com decoradores existentes do SDK da plataforma. Se vários plug-ins contribuírem com decoradores leves no mesmo quadrante, os conflitos serão resolvidos de forma não determinística.
Seu plug-in também pode fazer ele próprio todo o gerenciamento da imagem e do rótulo. Nesse caso, o atributo lightweight deve ser definido como false e o atributo class deve nomear uma classe que implemente ILabelDecorator. Essa classe permite decorar a imagem e o texto originais do rótulo com suas próprias anotações. Ela fornece grande flexibilidade pois você não está limitado a prefixos, sufixos e sobreposições simples de quadrantes.
Outros atributos de um decorador são independentes do estilo específico de implementação. Os atributos label e description designam o texto que é utilizado para nomear e descrever o decorador no diálogo de preferências. O objectClass nomeia a classe de objetos para a qual o decorador deve ser aplicado. O atributo enablement permite descrever as condições sob as quais o objeto deve ser decorado. O sinalizador adaptable indica se objetos que se adaptam a IResource também devem ser decorados. O sinalizador state controla se o decorador é visível por padrão.
Se seus decoradores incluírem informações que sejam caras de calcular ou muito confusas, é possível que você queira contribuir com suas próprias preferências que permitem que o usuário ajuste com precisão o decorador quando está ativo. Esta técnica é utilizada pelo cliente CVS.
Ciclo de Atualização do Decorador
A decoração é iniciada atualizando provedores de etiqueta que utilizam o DecoratorManager para fornecer decoração. Como o processamento da decoração é feito em segundo plano, haverá um período entre o momento em que a etiqueta é pedida e o evento labelProviderChanged é disparado que será utilizado pelo cálculo da decoração. Durante esse tempo, a decoração em um Objeto será calculada apenas por razões de eficiência. Se o decorador for alterado durante esse tempo, é possível que um resultado stale seja difundido enquanto a segunda chamada e chamadas subseqüentes para decorar um elemento são ignoradas.
Os contribuidores do decorador devem evitar alterar seus decoradores enquanto uma decoração estiver ocorrendo. Se isso não for possível, uma segunda chamada para decorar um elemento após o labelProviderChanged ser processado será necessária.