Dekoratoren

Ihr Plug-in kann Dekoratoren verwenden, um die Images für Ressourcen und andere Objekte in Workbench-Sichten durch Anmerkungen zu ergänzen. Dekoratoren sind nützlich, wenn das Plug-in Funktionskomponenten für vorhandene Ressourcentypen hinzufügt. Viele der standardmäßigen Workbench-Sichten unterstützen die Anzeige von Dekoratoren.  

PDE ergänzt beispielsweise Dekoratoren, mit denen eine Unterscheidung nach Binär- und Quellenprojekten getroffen werden kann.

Sicht 'Paket-Explorer' mit PDE-Dekoratoren

Das Projekt com.example.sourceProject  ist das einzige Quellenprojekt, das im Navigator angezeigt wird.  Beachten Sie hierbei, dass alle anderen binären Projekte die binären Dekorationen oben links im Java-Projektsymbol anzeigen. Dieser Dekorator wird durch PDE mit Hilfe des Erweiterungspunktes org.eclipse.ui.decorators ergänzt.

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

Es gibt verschiedene Möglichkeiten, eine Dekoratorimplementierung bereitzustellen. Dieses Befehlsformat verwendet die einfachste Art, die als deklarativer Lightweight-Dekorator bezeichnet wird. Wenn ein deklarativer Lightweight-Dekorator definiert wird, enthält das Befehlsformat eine vollständige Beschreibung mit Symbol, Platzierung und Aktivierungskonditionen des Dekorators. Deklarationsdekoratoren sind nützlich, wenn lediglich ein Symbol als Dekorator einer Bezeichnung verwendet wird. Das Plug-in muss lediglich den Quadranten definieren, in dem der Dekorator das normale Symbol überschreiben soll, sowie das hierfür zu verwendende Symbol. Wie in der Abbildung dargestellt, wird das PDE-Binärsymbol im oberen linken Quadranten des Paketsymbols überschrieben.

Wenn Ihr Plug-in nicht nur das Symbol, sondern auch die Bezeichnungstext bearbeiten muss, oder wenn die Art des Symbols dynamisch bestimmt wird, können Sie einen nicht-deklarativen Lightweight-Dekorator verwenden. In diesem Fall muss eine Implementierungsklasse definiert werden, die ILightweightLabelDecorator implementiert. Die bestimmte Klasse ist dafür verantwortlich, bei Laufzeit Präfix, Suffix und Formularschablonenmaske bereitzustellen, die auf die Bezeichnung angewendet werden. Der Workbench-Code übernimmt die Verknüpfung von Präfix und Suffix mit dem Bezeichnungstext, sowie die Durchführung der Überschreibung in einem Thread im Hintergrund. Dies bedeutet, dass die Verarbeitungsschritte, die von Ihrem Plug-in an seiner Implementierung von ILightweightLabelDecorator durchgeführt werden, UI-Thread-sicher sein müssen.  (Weitere Details finden Sie unter Code aus einem Nicht-UI-Thread ausführen.)

  Die folgenden Befehle zeigen, wie der CVS-Client seine Dekoratoren unter Verwendung dieses Verfahrens definiert:

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

Dekoratoren werden in letzter Instanz vom Benutzer über die Benutzervorgabenseite Dekoratoren für Bezeichnungen der Workbench gesteuert. Einzelne Dekoratoren können ein- und ausgeschaltet werden. Trotzdem sollte beim Entwurf von Dekoratoren darauf geachtet werden, dass diese sich nicht mit Dekoratoren der SDK-Plattform überschneiden oder mit diesen in Konflikt stehen. Wenn mehrere Plug-ins Lightweight-Dekoratoren für den gleichen Quadranten bereitstellen, werden die Konflikte auf nicht-deterministische Weise aufgelöst.  

Ihr Plug-in kann auch die Verwaltung von Images und Bezeichnungen selbst übernehmen. In diesem Fall sollte das Attribut Lightweight auf den Wert 'false' gesetzt werden und das Attribut class sollte eine Klasse bestimmen, die ILabelDecorator implementiert. Über diese Klasse können Sie einen Dekorator mit Ihren eigenen Anmerkungen für Image und Text der ursprünglichen Beschreibung setzen.  Dies erhöht Ihre Flexibilität, da Sie nicht auf Präfixe, Suffixe und einfache Quadrantenschablonen beschränkt sind.

Andere Attribute eines Dekorators sind unabhängig vom gewählten Implementierungsstil. Die Attribute label und description bestimmen den Text, der für den Namen und die Beschreibung des Dekorators im Dialog für Benutzervorgaben verwendet wird. Die Klasse objectClass bestimmt die Objektklasse, auf die der Dekorator angewendet werden soll. Über das Attribut enablement können Sie die Bedingungen beschreiben, unter denen für das Objekt ein Dekorator gesetzt werden soll.  Die Markierung adaptable zeigt an, ob Objekte, die sich an IResource anpassen, auch einen Dekorator bekommen sollen. Die Markierung state steuert, ob der Dekorator standardmäßig sichtbar ist.

Wenn Ihre Dekoratoren Informationen enthalten, deren Berechnung sehr aufwendig ist oder zu unerwünschten Nebeneffekten führen kann, ist es möglicherweise sinnvoll, eigene Benutzervorgaben zu ergänzen, überdie der Benutzer einen aktivierten Dekorator weiter anpassen kann. Dieses Verfahren wird vom CVS-Client eingesetzt.

Benutzervorgabenseite 'CVS-Dekoratoren'

 

Dekorator-Aktualisierungszyklus

Dekoration wird initiiert durch Aktualisierung von Label-Providern, die den DecoratorManager zur Bereitstellung von Dekoration verwenden. Da der Dekorationsprozess im Hintergrund abläuft, vergeht eine zeit zwischen der Anforderung des Labels und dem Auslösen des Ereignisses labelProviderChanged, das durch die Dekorationsberechnung aufgenommen wird. Während dieser zeit wird die Dekoration an einem Objekt aus Leistungsgründen nur einmal berechnet. Wenn sich der Dekorator während dieser Zeit ändert, ist es möglich, dass ein veraltetes Ergebnis mitgeteilt wird, da der zweite und die nachfolgenden Aufrufe, ein Element zu dekorieren, ignoriert werden.

Dekorator-Ergänzungselemente sollten eine Änderung ihrer Dekorators während der Ausführung der Dekoration vermeiden. Wenn dies nicht möglich ist, ist ein zweiter Aufruf zur Dekoration eines Elements nachdem der labelProviderChanged verarbeitet worden ist erforderlich.