Décorateurs

Votre plug-in peut utiliser des décorateurs pour annoter des images pour des images et d'autres objets apparaissant dans les vues du plan de travail. Les décorateurs sont utiles lorsque votre décorateur ajoute des fonctionnalités à des types de ressources existants. De nombreuses vues standard du plan de travail participent à l'affichage des décorations.  

Par exemple, PDE ajoute des décorateurs vous permettant de faire la distinction entre des projets binaires et des projets source.

Vue du Package explorer avec les décorateurs PDE

Le projet com.example.helloworld  est le seul projet source affiché dans le navigateur. Notez que tous les autres projets binaires affichent le décorateur binaire dans la partie supérieure gauche de l'icône de projet Java. Ce décorateur est fourni par l'environnement PDE à laide du point d'extension 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>

Il existe différents moyens d'offrir une implémentation de décorateur. Ces marques optent pour celui le plus simple, à savoir le décorateur déclaratif abrégé. Lorsque celui-ci est défini, les marques comportent une description complète de l'icône, de la position et des conditions d'activation du décorateur. Les décorateurs déclaratifs sont utiles lorsqu'une seule icône sert à décorer le libellé. Le plug-in doit uniquement spécifier le quadrant où le décorateur doit être recouvert, sur l'icône standard et celle pour la marque. Comme l'illustre l'image, l'icône binaire PDE est recouverte dans le quadrant supérieur gauche de l'icône de package.

Si votre plug-in doit manipuler le texte du libellé en plus de l'icône, ou si le type d'icône est déterminé de façon dynamique, vous pouvez employer un décorateur non déclaratif abrégé. Dans ce cas, une classe d'implémentation pour ILightweightLabelDecorator doit être définie. la classe spécifiée est chargée de fournir pour le libellé un préfixe, un suffixe et une image de remplacement lors de l'exécution. la concaténation du préfixe et du suffixe avec le texte du libellé et le recouvrement sont gérés par le code du plan de travail dans une unité d'exécution en arrière-plan. Ainsi, tout travail effectué par votre dans l'implémentation de ILightweightLabelDecorator doit être indépendant de toute unité d'exécution. Reportez-vous à la section Exécution du code à partir d'une unité d'exécution sans interface utilisateur pour en savoir plus.

 Les marques suivantes illustrent comment le client CVS définit son décorateur à l'aide de cette technique :

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

Les décorateurs sont finalement contrôlés par l'utilisateur via la page de préférences Décorations d'intitulés du plan de travail. Des décorateurs individuels peuvent être activés ou désactivés. Même dans ce cas, il est préférable de concevoir vos décorateurs afin qu'ils ne chevauchent pas ou n'entrent pas en conflit avec ceux SDK de la plate-forme. Si plusieurs plug-ins ajoutent des décorateurs abrégés au même quadrant, les conflits sont résolus de façon indéterminée.  

Votre plug-in peut également assumer toute la gestion des images et des libellés. Dans ce cas, l'attribut lightweight doit posséder la valeur false et celui class doit nommer une classe implémentant ILabelDecorator. Cette classe vous permet de décorer le texte et l'image du libellé d'origine avec vos propres annotations.  Elle vous offre une flexibilité accrue car vous n'êtes pas limité aux préfixes, suffixes et recouvrement simples de quadrants.

D'autres attributs d'un décorateur sont indépendants du style d'implémentation. Les attributs label et description par exemple désignent le texte employé pour nommer et décrire le décorateur dans la boîte de dialogue de préférences. L'attribut objectClass nomme la classe d'objets à laquelle le décorateur doit s'appliquer. L'attribut enablement vous permet de décrire les conditions dans lesquelles l'objets doit être décoré. L'indicateur adaptable indique si les objets s'adaptant à IResource doivent être décorés. L'indicateur state contrôle si le décorateur est par défaut visible.

Si vos décorateurs incluent des informations délicates à traiter ou éventuellement perturbantes, vous pouvez ajouter vos propres préférences pour que l'utilisateur puisse modifier le décorateur appliqué. Cette technique est employée par le client CVS.

Page Préférences de décorateurs CVS

 

Cycle de mise à jour du décorateur

La décoration est initiée par les fournisseurs de libellé de régénération utilisant DecoratorManager pour la décoration. Etant donné que la décoration est réalisée en arrière-plan, la période durant laquelle le libellé est demandé et l'événement labelProviderChanged est mis en application sera utilisée pour le calcul de la décoration. Pendant cette période, la décoration d'un objet sera calculé seulement une fois pour des raisons d'efficacité. Si le décorateur change pendant cette période, il est possible qu'un résultat périmé soit émis car le deuxième appel de décoration d'un élément ainsi que les suivants seront ignorés.

Les contributeurs du décorateur doivent éviter de changer leurs décorateur lors de la décoration. Si cela n'est pas possible, il faudra effectuer un second appel pour décorer un élément après l'exécution de labelProviderChanged.