Ponnahdusvalikot

org.eclipse.ui.popupMenus

Tätä laajennuspistettä käytetään uusien toimintojen lisäyksessä muiden lisäosien omistamiin pikavalikoihin. Toimintoja voidaan lisätä tiettyyn objektilajiin (objectContribution) tai näkymän tai muokkausohjelman osan tiettyyn pikavalikkoon (viewerContribution). Kun käytetään määritettä objectContribution, lisäys näkyy kaikissa näkymän tai muokkausohjelman osan pikavalikoissa, joissa on valittuina määritetyn lajin objekteja. Sen sijaan kun käytetään määritettä viewerContribution, lisäys näkyy vain määritetyssä näkymän tai muokkausohjelman osan pikavalikossa valinnasta riippumatta.

Kun valinta on vaihteleva, lisäys otetaan käyttöön, jos se rekisteröidään mahdollisuuksien mukaan yleiseen valinnan lajiin. Jos suoraa vastinetta ei ole, vastineiksi yritetään hakea yliluokkia ja ylirajapintoja.

Valintaa voidaan rajata edelleen käyttämällä nimisuodatinta. Silloin valinnan kaikkien objektien on vastattava suodatinta, jotta lisäys voidaan ottaa käyttöön.

Objektilisäyksen yksittäisissä toiminnoissa voidaan määrittää määritteen enablesFor avulla, otetaanko se käyttöön yksittäisessä valinnassa, usean objektin valinnassa tai muussa valinnan lajissa.

Jos nämä suodatusmekanismit eivät riitä, toimintolisäyksessä voidaan käyttää filter-mekanismia. Silloin kohdeobjektin määritteet kuvataan nimi-arvo-parien sarjana. Valintaan liitettävät määritteet ovat lajikohtaisia ja itse työympäristön ulkopuolella, joten työympäristö delegoi tämän tason suodatuksen varsinaiseen valintaan.

Toiminnon käyttöönotto ja/tai näkyvyys voidaan määrittää elementtien enablement ja visibility avulla. Nämä kaksi elementtiä sisältävät loogisen lausekkeen, jonka perusteella määritetään käyttöönotto ja/tai näkyvyys.

Komennon muoto on sama elementeissä enablement ja visibility. Kumpikin sisältää vain yhden loogisen lausekkeen alielementin. Elementti on yksinkertaisimmillaan objectClass, objectState, pluginState tai systemProperty. Monimutkaisissa tapauksissa looginen lauseke voidaan yhdistää elementeistä and, or ja not. Sekä elementissä and että elementissä or on oltava kaksi alielementtiä. Elementissä not saa olla vain yksi alielementti.

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

Tämän elementin avulla määritetään toimintojen ja/tai valikkojen ryhmä niihin katseluohjelman pikavalikoihin, joissa ovat valittuina määritetyn lajin objektit.



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

<!ATTLIST viewerContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Tämän elementin avulla määritetään toimintojen ja/tai valikkojen ryhmä näkymän tai muokkausohjelman osan tiettyyn pikavalikkoon.



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

Tämä elementti määrittää toiminnon, jota käyttäjä voi kutsua käyttöliittymässä.



<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Tämän elementin avulla lasketaan kunkin objektin määritteen tila nykyisessä valinnassa. Sitä käytetään vain, jos valinnan kullakin objektilla on määritetty määritteen tila. Valinnan kunkin objektin on toteutettava rajapinta org.eclipse.ui.IActionFilter tai sen on sovelluttava siihen.



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

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Tämän elementin avulla määritetään uusi valikko.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

Tämän elementin avulla uuteen valikkoon luodaan valikon erotin.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

Tämän elementin avulla uuteen valikkoon luodaan nimetty ryhmä. Sillä ei ole graafista esitysmuotoa uudessa valikossa, toisin kuin separator-elementillä.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

Tämän elementin avulla määritetään nykyiseen valintaan perustuva toiminnon käyttöönotto. Järjestelmä ohittaa asetuksen, jos enablement-elementti on määritetty.



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

Tämän elementin avulla määritetään laajennuksen käyttöönotto.



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

Tämän elementin avulla määritetään laajennuksen näkyvyys.



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

Tämä elementti kuvaa kahden alielementtinsä lausekkeiden laskennan tuloksen totuusarvoista AND-toimintoa.



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

Tämä elementti kuvaa kahden alielementtinsä lausekkeiden laskennan tuloksen totuusarvoista OR-toimintoa.



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

Tämä elementti kuvaa alielementtiensä lausekkeiden laskennan tuloksen totuusarvoista NOT-toimintoa.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

Tämän elementin avulla lasketaan kunkin objektin luokka tai rajapinta nykyisessä valinnassa. Jos valinnan kukin objekti toteuttaa määritetyn luokan tai rajapinnan, lauseke lasketaan todeksi.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Tämän elementin avulla lasketaan kunkin objektin määritteen tila nykyisessä valinnassa. Jos valinnan kullakin objektilla on määritetty määritteen tila, lauseke lasketaan todeksi. Tällaisen lausekkeen laskemiseksi valinnan kunkin objektin on toteutettava rajapinta org.eclipse.ui.IActionFilter tai se on sovitettava siihen.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Tämän elementin avulla lasketaan lisäosan tila. Lisäosan tila voi olla jokin seuraavista: installed (vastaa OSGi-käsitettä "tulkittu") tai activated (vastaa OSGi-käsitettä "aktiivinen").



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Tämän elementin avulla lasketaan jonkin järjestelmän ominaisuuden tila. Ominaisuuden arvo noudetaan luokasta java.lang.System.



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

Yleinen juurielementti. Elementtiä voi käyttää laajennuspisteen sisällä määrittämään sen käyttöönottolausekkeen. Käyttöönottolausekkeen aliobjektit yhdistetään AND-operaattorin avulla.



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

Tämä elementti edustaa NOT-operaatiota sen alielementin lausekkeen tuloksen arvioinnissa.



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

Tämä elementti edustaa AND-operaatiota sen kaikkien alielementtien lausekkeiden tuloksen arvioinnissa.



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

Tämä elementti edustaa OR-operaatiota sen kaikkien alielementtilausekkeiden tuloksen arvioinnissa.



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

Tätä elementtiä käytetään toteuttamaan kohteena olevan objektin ilmentymätarkistus. Lauseke palauttaa arvon EvaluationResult.TRUE, jos objektin laji on määritteen arvossa määritetyn lajin alilaji. Muussa tapauksessa palautuu arvo EvaluationResult.FALSE.



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

Tämän elementin avulla arvioidaan kohteena olevan objektin ominaisuustila. Testattavissa olevien ominaisuuksien joukkoa voi laajentaa käyttämällä ominaisuuksien testauksen laajennuspistettä. Testauslauseke palauttaa arvon EvaluationResult.NOT_LOADED, jos varsinaisen testauksen toteuttavaa ominaisuuksien testausta ei ole vielä ladattu.



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

Testaa järjestelmän ominaisuutta kutsumalla metodia System.getProperty ja vertaa tulosta arvoon, joka on määritetty arvomääritteen avulla.



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

Tätä elementtiä käytetään toteuttamaan kohteena olevan objektin yhtäsuuruustarkistus. Lauseke palauttaa arvon EvaluationResult.TRUE, jos objektin arvo on yhtä suuri kuin määritteen arvon antama arvo. Muussa tapauksessa palautuu arvo EvaluationResult.FALSE.



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

Tämän elementin avulla testataan kokoelman elementtien määrä.



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

<!ATTLIST with

variable CDATA #REQUIRED>

Tämä elementti muuttaa tarkasteltavan objektin kaikkien sen aliobjektien osalta annetun muuttujan viittaamaksi objektiksi. Jos muuttujan selvitys ei onnistu, lauseke aiheuttaa poikkeuksen ExpressionException, kun sitä arvioidaan. WITH-lausekkeen aliobjektit yhdistetään AND-operaattorin avulla.



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

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED>

Tämä elementti muuttaa tarkasteltavan objektin kaikkien sen aliobjektien osalta annetun muuttujan viittaamaksi objektiksi. Jos muuttujan selvitys ei onnistu, lauseke aiheuttaa poikkeuksen ExpressionException, kun sitä arvioidaan. WITH-lausekkeen aliobjektit yhdistetään AND-operaattorin avulla.



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

<!ATTLIST adapt

type CDATA #REQUIRED>

Tämän elementin avulla mukautetaan kohteena oleva objekti määritelajin määrittämään lajiin. Lauseke palauttaa arvon "ei ladattu", jos sovitinta tai viitattua lajia ei ole vielä ladattu. Se aiheuttaa poikkeuksen ExpressionException arvioinnin aikana, jos lajin nimeä ei ole lainkaan. Mukautuslausekkeen aliobjektit yhdistetään AND-operaattorin avulla.



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

<!ATTLIST iterate

operator (or|and) >

Tämän elementin avulla iteroidaan muuttuja, joka on lajia java.util.Collection. Jos kohteena oleva objekti ei ole lajia java.util.Collection, ilmenee poikkeus ExpressionException arvioitaessa lauseketta.



Seuraavassa on esimerkki ponnahdusvalikon laajennuspisteestä:

   

<extension point=

"org.eclipse.ui.popupMenus"

>

<objectContribution id=

"com.xyz.C1"

objectClass=

"org.eclipse.core.resources.IFile"

nameFilter=

"*.java"

>

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

Yllä olevassa esimerkissä määritetty objektilisäystoiminto otetaan käyttöön vain yksittäisessä valinnassa (enablesFor-määrite). Lisäksi valinnan kunkin objektin on toteutettava määritetty rajapinta (IFile) ja sen on oltava Java-tiedosto. Tämä toiminto lisätään aiemmin luotuun alivalikkoon. Tämä lisäys tehdään kaikkiin näkymiin, joissa on kyseinen valinta.

Sen sijaan yllä oleva katseluohjelmalisäys näkyy vain tehtävänäkymän pikavalikossa, eikä näkymän valinta vaikuta siihen.

Seuraavassa on esimerkki suodatusmekanismista. Tässä tapauksessa toiminto näkyy vain niissä IMarker-objekteissa, jotka on suoritettu ja joilla on suuri prioriteetti.

   

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

Seuraavassa on toinen esimerkki näkyvyyselementin käytöstä:

   

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

Yllä olevassa esimerkissä määritetty toiminto näkyy valikon vaihtoehtona tehtävänäkymän pikavalikossa, mutta näin on vain silloin, jos "com.xyz"-lisäosa on aktiivinen ja määritetyn järjestelmän ominaisuuden asetus on tosi.

Toimintomääritteen class arvon on oltava sellaisen Java-luokan tarkennettu luokan nimi, joka toteuttaa rajapinnan org.eclipse.ui.IObjectActionDelegate objektilisäyksissä, rajapinnan org.eclipse.ui.IViewActionDelegate näkymiin kuuluviin pikavalikoihin tehtävissä lisäyksissä tai rajapinnan org.eclipse.ui.IEditorActionDelegate muokkausohjelmiin kuuluviin pikavalikoihin tehtävissä lisäyksissä. Kaikissa tapauksissa toteuttava luokka ladataan mahdollisimman myöhään, jotta koko lisäosa ladattaisiin vasta sitten, kun sitä todella tarvitaan.

Huomautus: Takautuvaa yhteensopivuutta varten objektilisäyksissä voidaan toteuttaa rajapinta org.eclipse.ui.IActionDelegate.

Pikavalikon laajennus on mahdollinen osan sisällä vain silloin, kun kohdeosa julkaisee valikon laajennusta varten. Tämä on erittäin suositeltavaa, koska se parantaa tuotteen laajennettavuutta. Tätä varten kunkin osan pitäisi julkaista kaikki pikavalikot, jotka määritetään kutsumalla metodia IWorkbenchPartSite.registerContextMenu. Kun tämä on tehty, työympäristö lisää automaattisesti kaikki olemassa olevat toimintolaajennukset.

Kustakin rekisteröidystä valikosta on annettava valikkotunnus. Osien ristiriidattomuuden vuoksi kaikkien osatoteuttajien pitäisi noudattaa seuraavaa strategiaa.

Lisäksi kaikissa työympäristön kanssa rekisteröidyissä pikavalikoissa olisi oltava vakiolisäyskohta, jonka tunnus on IWorkbenchActionConstants.MB_ADDITIONS. Muut lisäosat käyttävät tätä arvoa lisäyksen viitekohtana. Lisäyskohta voidaan määrittää lisäämällä valikkoon GroupMarker-objekti sopivaan kohtaan.

Työympäristön objekti, joka on valittu pikavalikossa, voi määrittää rajapinnan org.eclipse.ui.IActionFilter. Tämä suodatusstrategia voi suorittaa lajikohtaisen suodatuksen. Työympäristö noutaa suodattimen valintaa varten testaamalla, toteuttaako se rajapinnan IActionFilter. Jos tämä ei onnistu, työympäristö pyytää suodatinta IAdaptable-mekanismin kautta.

Toimintojen ja valikkojen nimiöt voivat sisältää erikoismerkkejä, joihin koodatut valintakirjaimet määritetään käyttämällä et-merkkiä ('&') valitun merkin edessä muunnetussa tekstissä. Koska et-merkkiä ei sallita XML-merkkijonoissa, käytä &amp;-merkkioliota.

Jos valikkoon lisätään vähintään kaksi toimintoa yhdellä laajennuksella, toiminnot näkyvät käänteisjärjestyksessä verrattuna siihen, miten ne luetellaan plugin.xml-tiedostossa. Tämä on kieltämättä hämmentävää. Se havaittiin kuitenkin vasta sitten, kun Eclipse-ympäristön sovellusohjelmaliittymä oli jäädytetty. Muutoksen tekeminen jälkikäteen sotkisi jokaisen lisäosan, joka perustuu aiempaan käytäntöön.

Elementit selection ja enablement ovat toisensa poissulkevia. Elementti enablement voi korvata elementin selection käyttämällä alielementtejä objectClass ja objectState. Seuraavassa on esimerkki:

 

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

>

</selection>

voidaan ilmaista seuraavasti:
 

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<objectState name=

"extension"

value=

"java"

/>

</and>

</enablement>

Työympäristön näkymissä on kiinteitä pikavalikkoja, joihin on jo ladattu useita toimintoja. Näihin valikoihin voidaan liittää lisäosia. Jos katseluohjelma on varannut varastopaikkoja näille lisäyksille ja ne julkaistaan, varastopaikkojen nimiä voidaan käyttää polkuina. Muuten toiminnot ja alivalikot lisätään ponnahdusvalikon loppuun.