Hurtigmenyer

org.eclipse.ui.popupMenus

Dette utvidelsespunktet blir brukt til å legge til nye handlinger på hurtigmenyer som eies av andre plugin-moduler. Handlinger kan legges til for en bestemt objekttype (objectContribution) eller på en bestemt hurtigmeny i en visnings- eller redigeringsprogramdel (viewerContribution). Når du bruker objectContribution, vil bidraget bli vist på alle hurtigmenyene til visnings- eller redigeringsprogramdeler der den oppgitte typen objekter blir valgt. Hvis du derimot bruker viewerContribution, blir bidraget bare vist på hurtigmenyen til den oppgitte visnings- eller redigeringsprogramdelen, uansett hva som er valgt.

Når valget er heterogent, blir bidraget brukt hvis det er registrert mot en fellestype av valget, hvis mulig. Hvis et direkte samsvar ikke er mulig, blir samsvar med superklasser og supergrensesnitt forsøkt.

Valget kan begrenses videre ved bruk av et navnefilter. Hvis det blir brukt, må alle objektene i valget samsvare med filteret for at bidraget skal kunne brukes.

Enkelthandlinger i et objektbidrag kan bruke attributtet enablesFor for å oppgi om det bare skal gjelde for en enkelt valgtype, flere valgtyper eller alle andre valgtyper.

Hvis disse filtreringsmekanismene er utilstrekkelige, kan et handlingsbidrag bruke filter-mekanismen. I dette tilfellet blir attributtene for målobjektet beskrevet i en rekke navn-verdi-par. Attributtene som gjelder for valget, er typespesifikke og utenfor domenet til selve arbeidsbenken, så arbeidsbenken vil delegere filtrering på dette nivået til det faktiske valget.

Aktiveringen og/eller synligheten til en handling kan defineres ved hjelp av elementene enablement og visibility. Disse to elementene inneholder et boolsk uttrykk som blir evaluert for å bestemme aktiveringen og/eller synligheten.

Syntaksen er den samme for elementene enablement og visibility. Begge inneholder bare ett delelement med et boolsk uttrykk. I sin enkleste form vil dette være et element av typen objectClass, objectState, pluginState eller systemProperty. I mer komplekse tilfeller kan elementene and, or og not kombineres for å danne et boolsk uttrykk. Både and- og or-elementet må inneholde to delelementer. Elementet not kan bare inneholde ett delelement.

<!ELEMENT extension (objectContribution , viewerContribution)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  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 elementet blir brukt til å definere en gruppe med handlinger og/eller menyer for eventuelle visningsprogramhurtigmenyer som objektene av den oppgitte typen er valgt for.



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

<!ATTLIST viewerContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Dette elementet blir brukt til å definere en gruppe med handlinger og/eller menyer for en hurtigmeny for en bestemt visnings- eller redigeringsprogramdel.



<!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 elementet definerer en handling som brukeren kan aktivere i brukergrensesnittet.



<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Dette elementet brukes til å evaluere attributtstatusen til hvert objekt i det gjeldende valget. Det er bare samsvar hvis hvert objekt i valget har den oppgitte attributtilstanden. Hvert objekt i valget må implementere, eller tilpasses til, org.eclipse.ui.IActionFilter.



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

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Dette elementet blir brukt til å definere en ny meny.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

Dette elementet blir brukt til å opprette et menyskilletegn på den nye menyen.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

Dette elementet blir brukt til å opprette en navngitt gruppe på den nye menyen. Det har ingen visuell fremstilling på den nye menyen, i motsetning til separator-elementet.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

Dette elementet blir brukt til å bestemme handlingsaktiveringen basert på det gjeldende valget. Blir ignorert hvis enablement-elementet er oppgitt.



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

Elementet blir brukt til å definere aktiveringen for utvidelsen.



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

Elementet blir brukt til å definere synligheten for utvidelsen.



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

Dette elementet representerer en boolsk AND-operasjon på resultatet av evalueringen av de to delelementuttrykkene.



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

Dette elementet representerer en boolsk OR-operasjon på resultatet av evalueringen av de to delelementuttrykkene.



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

Dette elementet representerer en boolsk NOT-operasjon på resultatet av evalueringen av delelementuttrykkene.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

Dette elementet brukes til å evaluere klassen eller grensesnittet for hvert objekt i det gjeldende valget. Hvis hvert objekt i valget implementerer oppgitt klasse eller grensesnitt, blir uttrykket evaluert som "true".



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Dette elementet brukes til å evaluere attributtstatusen til hvert objekt i det gjeldende valget. Hvis hvert objekt i valget har den oppgitte attributtstatusen, blir uttrykket evaluert som "true". Hvis du skal evaluere denne typen uttrykk, må hvert objekt i valget implementere, eller tilpasses til, org.eclipse.ui.IActionFilter-grensesnittet.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Dette elementet brukes til å evaluere tilstanden til en plugin-modul. Tilstanden til plugin-modulen kan være en av følgende: installed (tilsvarer OSGi-begrepet "behandlet") eller activated (tilsvarer OSGi-begrepet "aktiv").



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Dette elementet brukes til å evaluere tilstanden til en systemegenskap. Egenskapsverdien blir hentet fra java.lang.System.



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

Et generisk rotelement. Elementet kan brukes i et utvidelsespunkt for å definere det tilhørende aktiveringsuttrykket. Underordnede under et aktiveringsuttrykk kombineres med operatoren AND.



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

Dette elementet representerer en NOT-operasjon på resultatet av evalueringen av underelementuttrykket.



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

Dette elementet representerer en AND-operasjon på resultatet av evalueringen av alle dets underelementuttrykk.



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

Dette elementet representerer en OR-operasjon på resultatet av evalueringen av alle tilhørende underelementuttrykk.



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

Dette elementet brukes til å utføre en instanceof-kontroll av objektet i fokus. Uttrykket returnerer EvaluationResult.TRUE hvis objektets type er en subtype under typen som er spesifisert ved attributtverdien. Ellers returneres EvaluationResult.FALSE.



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

Dette elementet brukes til å evaluere egenskapstilstanden til objektet i fokus. Settet med prøvbare egenskaper kan utvides ved hjelp av utvidelsespunktet for egenskapstesting. Testuttrykket returnerer EvaluationResult.NOT_LOADED hvis egenskapstesteren som utfører den faktiske testingen, ennå ikke er lastet inn.



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

Tester en systemegenskap ved å kalle opp metoden System.getProperty, og sammenlikner resultatet med verdien spesifisert gjennom value-attributtet.



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

Dette elementet brukes til å utføre en equals-kontroll av objektet i fokus. Uttrykket returnerer EvaluationResult.TRUE hvis objektet er lik verdien gitt ved attributtverdien. Ellers returneres EvaluationResult.FALSE.



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

Dette elementet brukes til å teste antallet elementer i en samling.



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

<!ATTLIST with

variable CDATA #REQUIRED>

Dette elementet endrer objektet som skal inspiseres, for alle underordnede elementer under objektet som refereres med den gitte variabelen. Hvis variabelen ikke kan behandles, vil uttrykket kaste et ExpressionException ved evaluering. Underordnede under et with-uttrykk kombineres ved hjelp av 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 elementet endrer objektet som skal inspiseres, for alle underordnede elementer under objektet som refereres med den gitte variabelen. Hvis variabelen ikke kan behandles, vil uttrykket kaste et ExpressionException ved evaluering. Underordnede under et with-uttrykk kombineres ved hjelp av operatoren AND.



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

<!ATTLIST adapt

type CDATA #REQUIRED>

Dette elementet brukes til å tilpasse objektet i fokus til typen spesifisert ved attributtypen. Uttrykket returnerer ikke lastet inn hvis adapteren eller typen som det refereres til, ikke er lastet inn. Det kaster et ExpressionException under evaluering hvis typenavnet ikke finnes i det hele tatt. Underordnede under et adapt-uttrykk kombineres ved hjelp av operatoren AND.



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

<!ATTLIST iterate

operator (or|and) >

Dette elementet brukes til å gjenta en variabel som er av typen java.util.Collection. Hvis objektet i fokus ikke er av typen java.util.Collection, kastes et ExpressionException ved evaluering av uttrykket.



Nedenfor finner du et eksempel på et utvidelsespunkt for hurtigmeny.

   

<extension point=

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

>

<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;Show 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 eksempelet over vil den oppgitte objektbidragshandlingen bare aktiveres for et enkelt valg (enablesFor-attributtet). I tillegg må hvert objekt i valget implementere det oppgitte grensesnittet (IFile) og være en Java-fil. Denne handlingen vil legges til i en undermeny som er opprettet tidligere. Dette bidraget vil gjelde i alle visninger som har det nødvendige valget.

Visningsbidraget over, derimot, vil bare bli vist på hurtigmenyen til Oppgaver-visningen, og vil ikke bli påvirket av valget i visningen.

Nedenfor finner du et eksempel på filtermekanismen. I dette tilfellet vil handlingen bare bli vist for IMarkers som er fullstendige og har høy prioritet.

   

<extension point=

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

"High Priority Completed Action Tool"

icon=

"icons/runXYZ.gif"

class=

"com.xyz.actions.MarkerActionDelegate"

>

</action>

</objectContribution>

</extension>

Nedenfor finner du et annet eksempel på bruken av synlighetselementet.

   

<extension point=

"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;Show XYZ"

style=

"push"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

>

</action>

</viewerContribution>

</extension>

I eksempelet over vil den oppgitte handlingen bli vist som et menypunkt på hurtigmenyen i Oppgaver-visningen, men bare hvis plugin-modulen "com.xyz" er aktiv og den oppgitte systemegenskapen er satt til "true".

Verdien av handlingsattributtet class må være et fullt kvalifisert navn på en Java-klasse som implementerer org.eclipse.ui.IObjectActionDelegate for objektbidrag, org.eclipse.ui.IViewActionDelegate for bidrag til hurtigmenyer som tilhører visninger, eller org.eclipse.ui.IEditorActionDelegate for bidrag til hurtigmenyer som hører til redigeringsprogrammer. I alle tilfeller blir implementeringsklassen lastet inn så sent som mulig for å unngå at hele plugin-modulen lastes inn før det er helt nødvendig.

Merk: Ved bakoverkompatibilitet kan org.eclipse.ui.IActionDelegate implementeres for objektbidrag.

Hurtigmenyutvidelser i en del er bare mulig når måldelen publiserer en meny for utvidelser. Det anbefales, fordi det forbedrer utvidbarheten til produktet. Dette krever at hver del publiserer alle hurtigmenyer som er definert, ved å kalle opp IWorkbenchPartSite.registerContextMenu. Når dette er gjort, vil arbeidsbenken automatisk sette inn alle handlingsutvidelser som finnes.

Det må oppgis en meny-ID for hver registrerte meny. For å sikre konsistens på tvers av deler, bør følgende strategi tas i bruk av alle delimplementerere.

Alle hurtigmenyer som er registrert med arbeidsbenken, skal også inneholde et standard innsettingspunkt med IDen IWorkbenchActionConstants.MB_ADDITIONS. Andre plugin-moduler vil bruke denne verdien som et referansepunkt for innsetting. Innsettingspunktet kan defineres ved å legge til en GroupMarker på menyen ved et passende innsettingssted.

Et objekt på arbeidsbenken som er valgt på en hurtigmeny, kan definere en org.eclipse.ui.IActionFilter. Dette er en filtreringsstrategi som kan utføre typespesifikk filtrering. Arbeidsbenken vil hente tilbake filteret for valget ved å teste om det implementerer IActionFilter. Hvis det mislykkes, vil arbeidsbenken be om et filter via IAdaptable-mekanismen.

Handlings- og menyetiketter kan inneholde spesialtegn som koder bokstavvalg som oppgis ved å sette et et-tegn ('&') foran det valgte tegnet i den oversatte teksten. Siden et-tegn ikke er tillatt i XML-strenger, kan du bruke tegnet &amp;.

Hvis en utvidelse legger til to eller flere handlinger på en meny, vil handlingene bli vist i omvendt rekkefølge av den de har i plugin.xml-filen. Dette er nok ikke særlig intuitivt, men det ble oppdaget etter at APIen for Eclipse-plattformen var frosset. Hvis denne virkemåten endres nå, ødelegger det for alle plugin-moduler som er avhengig av den eksisterende virkemåten.

Elementene selection og enablement utelukker hverandre. Elementet enablement kan erstatte elementet selection ved å bruke delelementene objectClass og objectState. For eksempel kan følgende:

 

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

>

</selection>

uttrykkes med:
 

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<objectState name=

"extension"

value=

"java"

/>

</and>

</enablement>

Arbeidsbenk-visningene har innebygde hurtigmenyer der en rekke handlinger allerede er lastet inn. Plugin-moduler kan bidra til disse menyene. Hvis et visningsprogram har reserverte spor for disse bidragene og de offentliggjøres, kan spornavn brukes som baner. Hvis ikke, blir handlinger og delmenyer lagt til på slutten av hurtigmenyen.