Vi vet att insticksprogram kan definiera specialiserade filtillägg och bidra med redigerare som tillhandahåller specialiserade redigeringsfunktioner för dessa filtyper. Under redigering (eller byggande) av en resurs, kan ett insticksprogram behöva märka resurser för att meddela problem eller annan information till användaren. Resursmarkörmekanismen används för hantering av denna typ av information.
En markör är som en gul postit-lapp fastsatt på en resurs. På markören kan du notera information om ett problem (t.ex. plats, hur allvarligt det är) eller en aktivitet som ska utföras. Eller så kan du helt enkelt notera en plats för en markör som ett bokmärke.
Användare kan snabbt hoppa till den markerade platsen i en resurs. Arbetsmiljöns användargränssnitt stöder presentation av bokmärken, brytpunkter, aktiviteter och problem vid sidan av redigeraren. Dessa markörer kan även visas som objekt i vyer, t.ex. aktivitets- eller bokmärkesvyn.
Plattformsresursernas API definierar metoder för att skapa markörer, ange markörvärden och utöka plattformen med nya markörtyper. Medan plattformen hanterar markörer, är det insticksprogrammen som styr deras skapande, borttagning och attributvärden.
Markörer är avsedda att vara små, lättviktiga objekt. Det kan finnas hundratals, till och med tusentals markörer i ett enda projekt. Ett exempel: Java-kompilatorn använder en markör till att flagga varje problem den träffar på i källkoden.
Plattformen kastar bort markörer anslutna till resurser som tas bort, men insticksprogrammen ansvarar för att ta bort deras gamla markörer när de inte längre gäller för en resurs som fortfarande existerar.
Manipulering av en markör liknar manipulering av en resurs. Markörer är handtagsobjekt. Du kan erhålla ett markörhandtag från en resurs, men du vet inte att det verkligen finns förrän du använder protokollet exists() eller på annat sätt försöker ändra det. När du har fastställt att det finns en markör kan du ställa frågor till namngivna attribut som kan ha tilldelats den.
Markörer ägs och hanteras av plattformen, som tar hand om att göra dem beständiga och att meddela lyssnare när markörer läggs till, tas bort eller ändras. Insticksprogram ansvarar för att skapa nödvändiga markörer, ändra deras attribut och ta bort dem när de inte längre behövs.
Markörer skapas inte direkt med en konstruktör. De skapas med fabriksmetoden (IResource.createMarker()) på den associerade resursen.
IMarker marker = file.createMarker(IMarker.TASK);
Om du vill skapa en markör med global omfattning (ej associerad till någon specifik resurs), kan du använda arbetsyteroten (IWorkspace.getRoot()) som resurs.
Koden för borttagning av en markör är rättfram.
try { marker.delete(); } catch (CoreException e) { // Something went wrong }
När en markör tas bort blir dess markörobjekt (handtag) "föråldrat." Insticksprogram bör använda protokollet IMarker.exists() och kontrollera att ett markörobjekt fortfarande är giltigt.
Du kan ta bort markörer i grupp genom att be en resurs ta bort dess markörer. Den här metoden är användbar när du tar bort många markörer samtidigt eller om enskilda markörhänvisningar eller idn inte är tillgängliga.
int depth = IResource.DEPTH_INFINITE; try { resource.deleteMarkers(IMarker.PROBLEM, true, depth); } catch (CoreException e) { // something went wrong }
När du tar bort en grupp markörer anger du en markörtyp att ta bort, t.ex. IMarker.PROBLEM eller null om du vill ta bort alla markörer. Det andra argumentet anger huruvida du vill ta bort deltypsmarkörer. (Vi ska strax ta en titt på deltyper när vi definierar nya markörtyper.) Argumentet depth styr borttagningens djup.
Du kan också ta bort markörer med IWorkspace.deleteMarkers(IMarker []).
Om du har en markör kan du fråga efter dess associerade resurs, dess id (unikt i förhållande till den resursen) och dess typ. Du kan också få tillgång till ytterligare information via generiska attribut.
Varje typ av markör har en specifik uppsättning attribut som definieras av skaparen av markörtypen med namngivningskonventioner. Gränssnittet IMarker definierar en uppsättning konstanter som innehåller standardattributnamnen (och vissa av de förväntande värdena) för plattformens markörtyper. Följande metod ändrar attribut med hjälp av plattformskonstanter.
IMarker marker = file.createMarker(IMarker.TASK); if (marker.exists()) { try { marker.setAttribute(IMarker.MESSAGE, "A sample marker message"); marker.setAttribute(IMarker.PRIORITY, IMarker.PRIORITY_HIGH); } catch (CoreException e) { // You need to handle the case where the marker no longer exists } }
Attribut underhålls generiskt som namn/värde-par, där namnen är strängar och ett värde bara kan vara av en av de värdetyper som hanteras (booleskt, heltal, sträng). Begränsningen för värdetyper gör det möjligt för plattformen att snabbt och enkelt hålla fast vid markörerna.
Det går att ställa frågor till resurser om deras markörer och till markörer om deras underordnade objekt. Ett exempel: om du ställer frågor till arbetsyteroten med oändligt djup, tas alla markörer på arbetsytan med i beaktande.
IMarker[] problems = null; int depth = IResource.DEPTH_INFINITE; try { problems = resource.findMarkers(IMarker.PROBLEM, true, depth); } catch (CoreException e) { // something went wrong }
Det resultat som returneras av findMarkers beror på de argument som skickats. I kodstycket ovan letar vi efter alla markörer av typen PROBLEM som visas på resursen och alla dess direkt och indirekta underliggande objekt.
Om du skickar null som markörtyp, får du alla markörtyper som är associerade till resursen. Det andra argumentet anger huruvida vi till titta på resursens underordnade objekt. Argumentet depth styr sökningens djup när du tittar på resursens underordnade objekt. Djupet kan vara DEPTH_ZERO (bara den givna resursen), DEPTH_ONE (resursen och alla dess direkta underordnade objekt) eller DEPTH_INFINITE (resursen och alla dess direkta och indirekta underordnade objekt).
Plattformens standardmarkörer (aktivitet, problem och bokmärke) är beständiga. Det betyder att deras läge sparas mellan arbetsmiljöns avstängningar och uppstarter. Däremot kan markörer av en beständig typ selektivt göras transienta om du anger att det reserverade attributet transient ska vara sant.
Nya markörtyper som deklareras av insticksprogram är inte beständiga såvida de inte deklarerats som sådana.
Insticksprogram kan deklarera sina egna markörtyper med utökningspunktenorg.eclipse.core.resources.markers. Standardmarkörtyperna för problem, aktiviteter och bokmärken deklareras av plattformen i koden till resursernas insticksprogram.
<extension id="problemmarker" point="org.eclipse.core.resources.markers" name="%problemName"> <super type="org.eclipse.core.resources.marker"/> <persistent value="true"/> <attribute name="severity"/> <attribute name="message"/> <attribute name="location"/> </extension> <extension id="taskmarker" point="org.eclipse.core.resources.markers" name="%taskName"> <super type="org.eclipse.core.resources.marker"/> <persistent value="true"/> <attribute name="priority"/> <attribute name="message"/> <attribute name="done"/> <attribute name="userEditable"/> </extension> <extension id="bookmark" point="org.eclipse.core.resources.markers" name="%bookmarkName"> <super type="org.eclipse.core.resources.marker"/> <persistent value="true"/> <attribute name="message"/> <attribute name="location"/> </extension>
Nya markörtyper härstammar från befintliga med multipel härstamning. Nya markörtyper ärver alla attributen från deras supertyper och lägger till ev. nya attribut definierade som del av deklarationen. De ärver och transitivt attribut från supertyperna för deras supertyper. Följande kod definierar en ny typ av markör i det hypotetiska insticksprogrammet com.example.markers.
<extension id="mymarker" point="org.eclipse.core.resources.markers" /> <extension id="myproblem" point="org.eclipse.core.resources.markers"> <super type="org.eclipse.core.resources.problemmarker"/> <super type="com.example.markers.mymarker"/> <attribute name="myAttribute" /> <persistent value="true" /> </extension>
Lägg märke till typen org.eclipse.core.resources.problemmarker som egentligen är en av de fördefinierade typerna (alias IMarker.PROBLEM).
Det enda tecknet på att en markörsupertyp inte är ärvd är dess beständighetsflagga. Standardvärdet för beständighet är falskt, så alla markörtyper som ska vara beständiga måste därför ange <persistent value="true"/>.
När du har deklarerat den nya markörtypen i ditt insticksprogram kan du skapa förekomster av markörtypen com.example.markers.myproblem och fritt ange eller hämta attributet myAttribute.
Genom att deklarera nya attribut kan du associera data med markörer som du planerar att använda någon annanstans (i dina vyer eller redigerare). Markörer av en viss typ behöver inte ha värden för alla deklarerade attribut. Attributdeklarationerna är mer till för att lösa problem med namngivningskonventioner (så att alla använder "message" till att tala om en markörs beskrivning) istället för begränsningsinnehåll.
public IMarker createMyMarker(IResource resource) { try { IMarker marker = resource.createMarker("com.example.markers.myproblem"); marker.setAttribute("myAttribute", "MYVALUE"); return marker; } catch (CoreException e) { // You need to handle the cases where attribute value is rejected } }
Du kan ställa frågor till dina egna markörtyper på samma sätt som du ställer frågor till plattformens markörtyper. Metoden nedan hittar alla mymarkers associerade till den givna målresursen och alla dess underliggande objekt. Lägg märke till att den även hittar alla myproblems sedan sant skickas för argumentet includeSubtypes.
public IMarker[] findMyMarkers(IResource target) { String type = "com.example.markers.mymarker"; IMarker[] markers = target.findMarkers(type, true, IResource.DEPTH_INFINITE); }