O plug-in pode utilizar decoradores para anotar as imagens de recursos e outros objectos que aparecem nas vistas da área de trabalho. Os decoradores são úteis quando o plug-in adiciona funcionalidades aos tipos de recursos existentes. Muitas das vistas de área de trabalho padrão participam na mostra de decorações.
Por exemplo, o PDE contribui com decoradores que permitem distinguir entre projectos binários e origem.
O projecto com.example.helloworld é o único projecto origem mostrado no navegador. Repare em como todos os outros projectos binários mostram o decorador binário no topo esquerdo do ícone de projectos Java. Este decorador é contributo do PDE através do 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>
Há muitas maneiras diferentes de facultar uma implementação de decorador. Esta marcação utiliza a maneira mais simples, conhecida como decorador ligeiro declarativo. Quando um decorador ligeiro declarativo é definido, a marcação contém uma descrição completa das condições de ícone, colocação e activação do decorador. Os decoradores declarativos são úteis quando só se utiliza um ícone para decorar a etiqueta. O plug-in só tem de especificar o quadrante onde se deve sobrepor o decorador no ícone regular e o ícone para a sobreposição. Tal como se mostra na figura, o ícone binário PDE é sobreposto no quadrante superior esquerdo do ícone de pacote.
Se o plug-in necessitar de manipular o texto da etiqueta além do ícone ou se o tipo de ícone for determinado dinamicamente, poderá utilizar um decorador ligeiro não declarativo. Neste caso, deve ser definida uma classe de implementação que implemente ILightweightLabelDecorator. A classe designada é responsável por facultar prefixo, sufixo e imagem de sobreposição durante a execução, os quais são aplicados à etiqueta. A mecânica da concatenação de prefixo e sufixo com o texto da etiqueta e da realização da sobreposição é tratada pelo código da área de trabalho num módulo em segundo plano. Por conseguinte, o trabalho realizado pelo plug-in na sua implementação de ILightweightLabelDecorator deve estar protegido contra módulos de UI. (Consulte Executar código a partir de um módulo alheio à UI para mais detalhes.)
A marcação seguinte mostra como o cliente CVS define o seu decorador através desta 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 acabam por ser controlados pelo utilizador por via da página de preferências Decorações de Etiqueta da área de trabalho. Os decoradores individuais podem ser ligados e desligados. Mesmo assim, é boa ideia conceber os decoradores de maneira a não se sobreporem nem colidirem com decoradores de SDK de plataforma existentes. Se houver vários plug-ins a contribuir com decoradores ligeiros para o mesmo quadrante, os conflitos são resolvidos de maneira não determinista.
O plug-in também pode encarregar-se da gestão de imagens e etiquetas. Neste caso, o atributo ligeiro deve ser definido como false e o atributo classe deve denominar uma classe que implemente ILabelDecorator. Esta classe permite decorar a imagem e o texto da etiqueta original com as suas próprias anotações. Dá-lhe assim grande flexibilidade, dado que não fica limitado a prefixos, sufixos e simples sobreposições de quadrantes.
Os outros atributos de um decorador são independentes de determinado estilo de implementação. Os atributos etiqueta e descrição designam o texto que é usado para denominar e descrever o decorador no diálogo de preferências. A objectClass denomina a classe de objectos aos quais deve ser aplicado o decorador. O atributo activação permite descrever as condições nas quais o objecto deve ser decorado. O sinalizador adaptável indica se os objectos que se adaptam a IResource devem ou não ser também decorados. O sinalizador estado controla se o decorador fica ou não visível por predefinição.
Se os decoradores incluírem informações que sejam dispendiosas de calcular ou potencialmente dispersoras, poderá ser útil contribuir com preferências próprias que permitem ao utilizador refinar e ajustar mais o decorador assim que estiver ligado. Esta técnica é utilizada pelo cliente CVS.
Ciclo de Actualização do Decorador
A decoração é iniciada por renovação dos fornecedores de etiquetas que usam o DecoratorManager para facultar decoração. À medida que o processamento de decoração decorre em segundo plano, haverá um período entre o pedido de etiqueta e o desencadear do evento labelProviderChanged que será assumido pelo cálculo da decoração. Durante este tempo, a decoração num Objecto só será calculada uma vez por questões de eficiência. Se o decorador for alterado durante este tempo é possível que seja difundido um resultado desactualizado quando a segunda e subsequentes chamadas para decorar um elemento forem ignoradas.
Os contribuintes de decoradores devem evitar alterar os seus enquanto decorrer a decoração. Se isto não for possível, será necessária segunda chamada para decorar um elemento após o processamento de labelProviderChanged.