Pop op-menuer

org.eclipse.ui.popupMenus

Dette udvidelsespunkt bruges til at tilføje nye funktioner til kontekstmenuer, der ejes af andre plugins. Funktionsbidrag kan foretages til en bestemt objekttype (objectContribution) eller til en bestemt kontekstmenu for en oversigts- eller editordel (viewerContribution). Når du bruger objectContribution, bliver bidraget vist i alle kontekstmenuer til oversigts- eller editordele, hvor objekter af den angivne type er valgt. I modsætning hertil vil bidraget kun blive vist i den valgte kontekstmenu til en oversigts- eller editordel, hvis du bruger viewerContribution, uanset valget.

Når valget er heterogent, bliver bidraget anvendt, hvis det registreres for en generel type af valget, og det er muligt at anvende det. Hvis der ikke findes en direkte match, forsøges sammenligninger med superklasser og supergrænseflader.

Valget kan blive yderligere begrænset gennem brugen af et navnefilter. Hvis det anvendes, skal alle objekter i valget matche filteret, før bidraget bliver anvendt.

Individuelle funktioner i et objektbidrag kan bruge attributten enablesFor til at angive, om det skal gælde for en enkelt valgtype, flere valgtyper eller en anden valgtype.

Hvis disse filtreringsmekanismer ikke er tilstrækkelige, kan et funktionsbidrag bruge mekanismen filter. I dette tilfælde beskrives attributterne for målobjektet i en række navne-/værdi-par. De attributter, der gælder for valget, er typespecifikke og ligger uden for selve arbejdsbænkens domæne, så arbejdsbænken delegerer filtrering på dette niveau til det faktiske valg.

En funktions aktivering og/eller synlighed kan defineres ved hjælp af elementerne enablement og visibility. Disse to elementer indeholder et boolesk udtryk, der evalueres for at bestemme aktiveringen og/eller synligheden.

Syntaksen er den samme for elementerne enablement og visibility. De indeholder begge kun et underelement til et boolesk udtryk. I de mest enkle tilfælde vil det være et af følgende elementer: objectClass, objectState, pluginState eller systemProperty. I mere komplekse tilfælde kan elementerne and, or og not kombineres, så de danner et boolesk udtryk. Både elementet and og or skal indeholde to underelementer. Elementet not må kun indeholde et underelement.

<!ELEMENT extension (objectContribution , viewerContribution)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

navn  CDATA #IMPLIED>


<!ELEMENT objectContribution (filter* , visibility? , enablement? , menu* , action*)>

<!ATTLIST objectContribution

id          CDATA #REQUIRED

objectClass CDATA #REQUIRED

nameFilter  CDATA #IMPLIED

adaptable   (true | false) "false">

Dette element bruges til at definere en gruppe funktioner og/eller menuer til kontekstmenuer i en fremviser, hvor der er valgt objekter af den angivne type.



<!ELEMENT viewerContribution (visibility? , menu* , action*)>

<!ATTLIST viewerContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Dette element bruges til at definere en gruppe funktioner og/eller -menuer til en bestemt kontekstmenu for en oversigts- eller editordel.



<!ELEMENT action (selection* , enablement?)>

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

definitionId     CDATA #IMPLIED

menubarPath      CDATA #IMPLIED

icon             CDATA #IMPLIED

helpContextId    CDATA #IMPLIED

style            (push|radio|toggle|pulldown)

state            (true | false)

class            CDATA #REQUIRED

enablesFor       CDATA #IMPLIED

overrideActionId CDATA #IMPLIED

tooltip          CDATA #IMPLIED>

Dette element definerer en funktion, som brugeren kan starte i brugergrænsefladen.



<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Dette element bruges til at evaluere attributtilstanden for hvert objekt i det aktuelle valg. Kun en match, hvis alle objekter i valget har den angivne attributtilstand. Alle objekter i valget skal implementere eller tilpasses til org.eclipse.ui.IActionFilter.



<!ELEMENT menu (separator+ , groupMarker*)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Dette element bruges til at definere en ny menu.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

Dette element bruges til at oprette en menuseparator på den nye menu.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

Dette element bruges til at oprette en navngiven gruppe på den nye menu. Den har ingen visuel repræsentation på den nye menu i modsætning til elementet separator.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

klasse CDATA #REQUIRED

navn  CDATA #IMPLIED>

Dette element bruges til at hjælpe med at bestemme funktionsaktiveringen på basis af det aktuelle valg. Ignoreres, hvis elementet enablement er angivet.



<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Dette element bruges til at definere aktiveringen af udvidelsen.



<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Dette element bruges til at definere synligheden for udvidelsen.



<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Dette element repræsenterer en boolesk AND-funktion på resultatet af evalueringen af dets to underelementudtryk.



<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Dette element repræsenterer en boolesk OR-funktion på resultatet af evalueringen af dets to underelementudtryk.



<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Dette element repræsenterer en boolesk NOT-funktion på resultatet af evalueringen af dets to underelementudtryk.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

Dette element bruges til at evaluere klassen eller grænsefladen for hvert objekt i det aktuelle valg. Hvis hvert objekt i valget implementerer den angivne klasse eller grænseflade, evalueres udtrykket som true.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Dette element bruges til at evaluere attributtilstanden for hvert objekt i det aktuelle valg. Hvis hvert objekt i valget har den angivne attributtilstand, evalueres udtrykket som true. For at evaluere denne type udtryk skal hvert objekt i valget implementere eller tilpasse dig grænsefladen org.eclipse.ui.IActionFilter.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Dette element bruges til at evaluere tilstanden for plugin. Tilstanden for plugin kan være en af følgende: installed (svarer til OSGi-konceptet "resolved") eller activated (svarer til OSGi-konceptet "active").



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Dette element bruges til at evaluere tilstanden for visse systemegenskaber. Egenskabsværdien hentes fra java.lang.System.



<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Et generisk rodelement. Elementet kan anvendes i et udvidelsespunkt for at angive dets aktiveringsudtryk. Underordnede til et aktiveringsudtryk kombineres vha. en operator.



<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>

Dette element repræsenterer en NOT-funktion på resultatet af evalueringen af dets underelementudtryk.



<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Dette element repræsenterer en AND-funktion på resultatet af evalueringen af dets underelementudtryk.



<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Dette element repræsenterer en OR-funktion på resultatet af evalueringen af alle dets underelementudtryk.



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

Dette element anvendes til at udføre et instanceof-check af objektet i fokus. Udtrykket returnerer EvaluationResult.TRUE, hvis objektets type er en undertype der er angivet af attributværdien. Eller returneres EvaluationResult.FALSE.



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

Dette element anvendes til evaluere egenskabstilstanden for objektet i fokus. Sættet af egenskaber, der kan testes, kan udvides vha. udvidelsespunktet egenskabstester. Testudtrykket returnerer EvaluationResult.NOT_LOADED, hvis egenskabstester, der udfører den aktuelle test, ikke er indlæst endnu.



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

Tester en systemegenskab ved at kalde metoden System.getProperty og sammenligner resultatet med den værdi, der er angivet via værdiattributten.



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

Dette element anvendes til at udføre en sammenligningskontrol af objektet i fokus. Udtrykket returnerer EvaluationResult.TRUE, hvis objektet er lig med værdiudbyderen for attributværdien. Eller returneres EvaluationResult.FALSE.



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

Dette element anvendes til at teste antallet af elementer i en samling.



<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST with

variable CDATA #REQUIRED>

Dette element ændrer det objekt, der skal undersøges for alle underordnede elementer, til et objekt, der henvises til fra en given variabel. Hvis variablen ikke kan opløses, vil udtrykket sende en ExpressionException, når den evalueres. En underordnet med et with-udtryk kombineres ved at bruge operatoren and.



<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED>

Dette element ændrer det objekt, der skal undersøges for alle underordnede elementer, til et objekt, der henvises til fra en given variabel. Hvis variablen ikke kan opløses, vil udtrykket sende en ExpressionException, når den evalueres. En underordnet med et with-udtryk kombineres ved at bruge operatoren and.



<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST adapt

type CDATA #REQUIRED>

Dette element anvendes til at tilpasse objekter i fokus til den type, der er angivet af attributtypen. Udtrykket returnerer ikke indlæst, hvis adapteren eller den type, der henvises til, ikke er indlæst endnu. Det sender enExpressionException under evalueringen, hvis typenavnet slet ikke findes. Underordnede til et tilpasset udtryk kombineres vha. operatoren AND.



<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST iterate

operator (or|and) >

Dette element anvendes til gentagelser for en variabel, der har typen java.util.Collection. Hvis objektet i fokus ikke er af typen java.util.Collection, sendes der en ExpressionException, når udtrykket evalueres.



Her er et eksempel på et udvidelsespunkt til en pop op-menu:

   

<udvidelsespunkt=

"org.eclipse.ui.popupMenus"

>

<objectContribution id=

"com.xyz.C1"

objectClass=

"org.eclipse.core.resources.IFile"

nameFilter=

"*.java"

>

< menu id=

"com.xyz.xyzMenu"

path=

"additions"

label=

"&amp;XYZ Java-værktøjer"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

style=

"push"

menubarPath=

"com.xyz.xyzMenu/group1"

icon=

"icons/runXYZ.gif"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.XYZToolActionDelegate"

enablesFor=

"1"

/>

</objectContribution>

<viewerContribution id=

"com.xyz.C2"

targetID=

"org.eclipse.ui.views.TaskList"

>

<action id=

"com.xyz.showXYZ"

label=

"&amp;Vis XYZ"

style=

"toggle"

state=

"true"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

/>

</viewerContribution>

</extension>

I eksemplet ovenfor bliver det angivne objektbidrag kun aktiveret for et enkelt valg (attributten enablesFor). Desuden skal alle objekter i valget implementere den angivne grænseflade (IFile), og de skal være Java-filer. Denne funktion tilføjes til en tidligere oprettet undermenu. Bidraget vil være effektivt i alle oversigter, som indeholder det påkrævede valg.

I modsætning hertil vil fremviserbidraget kun blive vist i kontekstmenuen for oversigten Opgaver, og det vil ikke være påvirket af valget i oversigten.

Her er et eksempel på filtermekanismen. I dette tilfælde bliver funktionen kun vist for IMarkers, som er udført og har høj prioritet.

   

<udvidelsespunkt=

"org.eclipse.ui.popupMenus"

>

<objectContribution id=

"com.xyz.C3"

objectClass=

"org.eclipse.core.resources.IMarker"

>

<filter name=

"done"

value=

"true"

/>

<filter name=

"priority"

value=

"2"

/>

<action id=

"com.xyz.runXYZ"

label=

"Udførte funktioner med høj prioritet"

icon=

"icons/runXYZ.gif"

class=

"com.xyz.actions.MarkerActionDelegate"

>

</action>

</objectContribution>

</extension>

Her er et andet eksempel på brugen af elementet visibility:

   

<udvidelsespunkt=

"org.eclipse.ui.popupMenus"

>

<viewerContribution id=

"com.xyz.C4"

targetID=

"org.eclipse.ui.views.TaskList"

>

<visibility>

<and>

<pluginState id=

"com.xyz"

value=

"activated"

/>

<systemProperty name=

"ADVANCED_MODE"

value=

"true"

/>

</and>

</visibility>

<action id=

"com.xyz.showXYZ"

label=

"&amp;Vis XYZ"

style=

"push"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

>

</action>

</viewerContribution>

</extension>

I ovenstående eksempel bliver den angivne funktion vist som et menupunkt på kontekstmenuen til oversigten Opgaver, men kun hvis plugin'en "com.xyz" er aktiv, og den angivne systemegenskab er angivet til true.

Værdien af funktionsattributten class skal være et fuldstændigt klassenavn på en Java-klasse, der implementerer org.eclipse.ui.IObjectActionDelegate, hvis der er tale om objektbidrag, org.eclipse.ui.IViewActionDelegate ved bidrag til kontekstmenuer, som hører til oversigter, eller org.eclipse.ui.IEditorActionDelegate ved bidrag til kontekstmenuer, som hører til editorer. I alle tilfælde indlæses den implementerende klasse så sent som muligt for at undgå indlæsning af hele plugin'en, inden der er reelt behov for den.

Bemærk: Af hensyn til bagudkompatibiliteten kan org.eclipse.ui.IActionDelegate implementeres til objektbidrag.

Kontekstmenuudvidelse inden for en del er kun muligt, når måldelen publicerer en menu til udvidelse. Det anbefales kraftigt, da det forbedrer produktets udvidelsesmuligheder. Af den grund bør alle dele publicere de kontekstmenuer, som er defineret, ved at kalde IWorkbenchPartSite.registerContextMenu. Når det er gjort, vil arbejdsbænken automatisk indsætte de eksisterende funktionsudvidelser.

En menu-id skal leveres for hver registreret menu. Af hensyn til konsekvensen på tværs af delene bør alle delimplementorer anvende følgende strategi:

En kontekstmenu, som er registreret på arbejdsbænken, skal indeholde et standardindsætningspunkt med id'en IWorkbenchActionConstants.MB_ADDITIONS. Andre plugins vil bruge denne værdi som referencepunkt ved indsættelse. Indsætningspunktet kan være defineret ved at tilføje en GroupMarker til menuen på et sted, der er egnet til indsættelse.

Et objekt på arbejdsbænken, som er valget i en kontekstmenu, kan definere en org.eclipse.ui.IActionFilter. Dette er en filtreringsstrategi, som kan udføre typespecifik filtrering. Arbejdsbænken henter filteret til valget ved at teste, om det implementerer IActionFilter. I benægtende fald vil arbejdsbænken bede om et filter via mekanismen IAdaptable.

Funktions- og menuetiketter kan indeholde specialtegn, der koder valgbogstaver, som angives ved at placere og-tegnet ('&') foran det valgte tegn i den oversatte tekst. Da og-tegn ikke er tilladt i XML-strenge, skal du bruge tegnentiteten &amp;.

Hvis to eller flere funktioner tilføres til en menu via en enkelt udvidelse, bliver funktionerne vist i omvendt rækkefølge af den, de har i filen plugin.xml. Denne funktionsmåde er ikke-intuitiv. Men den er blevet opdaget, efter at Eclipse Platform API'et er blevet fastfrosset. Hvis funktionsmåden ændres nu, vil det forstyrre de plugin, der anvender den eksisterende funktionsmåde.

Elementerne selection og enablement udelukker gensidigt hinanden. Elementet enablement kan erstatte elementet selection ved brug af underelementerne objectClass og objectState. For eksempel kan følgende:

 

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

>

</selection>

udtrykkes ved hjælp af:
 

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<objectState name=

"extension"

value=

"java"

/>

</and>

</enablement>

Oversigterne på arbejdsbænken har indbyggede kontekstmenuer, der allerede indeholder en række forskellige funktioner. Plugins kan bidrage til disse menuer. Hvis en fremviser har reserveret skuffer til disse bidrag, og de gøres offentlige, kan skuffenavne bruges som stier. Ellers bliver funktioner og undermenuer tilføjet sidst på pop op-menuen.