Decorators

De plugin kan decorators gebruiken om de afbeeldingen te annoteren van resources en andere objecten die in de workbenchviews worden afgebeeld. Gebruik een decorator wanneer u functionaliteit toevoegt voor bestaande resourcetypen. Tal van standaardworkbenchviews bieden ondersteuning voor decoraties.

Zo levert PDE bijvoorbeeld decorators aan waarmee u binaire en broncodeprojecten van elkaar kunt onderscheiden.

Pakketverkenner met PDE-decorators

Het project com.example.helloworld is het enige broncodeproject dat in de navigator wordt afgebeeld. Merk op dat bij alle andere binaire projecten de binaire decorator wordt afgebeeld in de linkerbovenhoek van het Java-projectpictogram. Deze decorator wordt door PDE aangeleverd met het extensiepunt 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>

U kunt een decorator op diverse manieren implementeren. In deze markup wordt de eenvoudigste manier uitgelegd door middel van een declaratieve lightweight-decorator. In de definitiemarkup van dit type decorator zijn het pictogram, gegevens met betrekking tot de plaatsing en voorwaarden voor inschakeling van de decorator vastgelegd. U kunt een declaratieve decorator gebruiken wanneer u een label alleen met een pictogram opmaakt. U hoeft in de plugin alleen een pictogram (icon) te verstrekken en het kwadrant (quadrant) op te geven waar het standaardpictogram wordt overlapt op de decorator. Zoals u in de afbeelding ziet, wordt het pakketpictogram in de linkerbovenhoek overlapt door het PDE-pictogram dat een binair project aanduidt.

Als u met een plugin ook de tekst van het label wilt manipuleren of het pictogram dynamisch wordt bepaald, kunt u een niet-declaratieve lightweight-decorator toepassen. U moet dan een implementatieklasse (class) definiëren waarmee ILightweightLabelDecorator wordt geïmplementeerd. De aangewezen klasse zorgt voor een prefix, een suffix en een afbeelding die tijdens runtime op het label wordt toegepast. Het samenvoegen van het prefix en het suffix met de tekst van het label en het toepassen van het pictogram worden door de workbenchcode afgehandeld in een achtergrond-thread. U moet er dan ook voor zorgen dat de instructies die in de implementatie van ILightweightLabelDecorator worden uitgevoerd door de plugin geschikt zijn voor gebruikersinterface-threads. (Raadpleeg Code uitvoeren via een thread die niet van de gebruikersinterface is voor meer informatie.)

In de volgende markup ziet u hoe de CVS-client een decorator definieert met deze techniek:

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

Decorators worden uiteindelijk door de gebruiker ingesteld via de voorkeursintellingenpagina Labeldecoraties van de workbench. Afzonderlijke decorators kunt u in- en uitschakelen. Het is dan ook verstandig de decorators zodanig te ontwerpen dat er geen overlappingen of conflicten onstaan met bestaande SDK-decorators van het platform. Als lightweight-decorators door meerdere plugins worden aangeleverd voor hetzelfde kwadrant, worden de conflicten niet-deterministisch opgelost.

De afbeelding en het label kunnen ook door de plugin zelf worden afgehandeld. Stel het kenmerk lightweight dan in op "false" en geef een klasse op voor het kenmerk class waarmee ILabelDecorator wordt geïmplemeteerd. Met deze klase kunt u de afbeelding en de tekst van het oorspronkelijke label wijzigen in uw eigen annotaties. U beschikt zo over extra flexibiliteit, omdat u niet alleen prefixen, suffixen en eenvoudige kwadranten hoeft te gebruiken.

Andere kenmerken van decorators zijn onafhankelijk van de implementatiestijl. De kenmerken label en description (beschrijving) geven de tekst aan die wordt gebruikt om de decorator te benoemen en te beschrijven in het dialoogvenster met voorkeursinstellingen. Het kenmerk objectClass duidt de klasse aan van objecten waarop de decorator moet worden toegepast. Het kenmerk enablement biedt de mogelijkheid voorwaarden op te geven waaraan moet worden voldaan om de decorator in te schakelen. Het kenmerk adaptable geeft aan of de decorator ook moet worden toegepast op IResource-objecten. Het kenmerk state bepaalt of de decorator standaard zichtbaar is.

Als de decorators gegevens bevatten die lastig te berekenen zijn of voor mogelijke verwarring zorgen, kunt u zelf voorkeursinstellingen aanleveren, zodat de decorators verder kunnen worden aangepast nadat ze zijn ingeschakeld. Deze methode geldt voor de CVS-client.

Voorkeursinstellingen voor CVS-decorators

 

Bijwerkcyclus van decorators

De decoratie vindt plaats door vernieuwing van de labelproviders die op DecoratorManager gebaseerd zijn. Aangezien de de decoratie op de achtergrond wordt verwerkt, is er een periode tussen het opvragen van het label en het initiëren van de event labelProviderChanged (als gevolg van de verwerking van de decoratie). Tijdens deze periode worden objecten slechts één keer berekend omwille van de efficiëntie. Indien de decorator ondertussen wordt gewijzigd, kan verouderde informatie worden overgebracht doordat vervolgaanroepen voor het decoreren van elementen worden genegeerd.

Deelnemers van decorators moeten ervoor zorgen dat de decorators niet worden bijgewerkt tijdens het decoreren. Als dit niet kan worden voorkomen, dan moet een tweede aanroep voor het decoreren van elementen worden geïnitieerd na de verwerking van de event labelProviderChanged.