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ä.
push | - säännöllinen valikon vaihtoehto tai työkaluvaihtoehto. | |
radio | - valintanapilla valittava valikon vaihtoehto tai työkaluvaihtoehto. Valintanapilla valittavat toiminnot samassa valikko- tai työkaluriviryhmässä toimivat valintajoukkona. Alkuarvo määritetään määritteen state avulla. | |
toggle | - valintaruudulla valittava valikon vaihtoehto tai valintatyökaluvaihtoehto. Alkuarvo määritetään määritteen state avulla. | |
pulldown | - limittyvä valikon vaihtoehto. |
! | - 0 objektia valittu | |
? | - 0 objektia tai 1 objekti valittu | |
+ | - 1 tai useampi objekti valittu | |
multiple, 2+ | - 2 objektia tai useampi objekti valittu | |
n | - täsmällinen määrä objekteja valittu. Esimerkiksi: enablesFor=" 4" ottaa toiminnon käyttöön vain, jos 4 objektia on valittu | |
* | - mikä tahansa määrä objekteja valittu |
Toimintolaajennuksen käyttöönottoehdot määritetään alun perin määritteiden enablesFor, selection ja enablement avulla. Kun toimintodelegaatti on eritelty, se voi kuitenkin ohjata toiminnon käyttöönottotilaa suoraan selectionChanged-metodissaan.
<!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.
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.<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=
"&XYZ Java Tools"
>
<separator name=
"group1"
/>
</menu>
<action id=
"com.xyz.runXYZ"
label=
"&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=
"&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>
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.
Seuraavassa on toinen esimerkki näkyvyyselementin käytöstä:<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>
<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=
"&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.
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ä &-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:
voidaan ilmaista seuraavasti:<selection class=
"org.eclipse.core.resources.IFile"
name=
"*.java"
>
</selection>
<enablement>
<and>
<objectClass name=
"org.eclipse.core.resources.IFile"
/>
<objectState name=
"extension"
value=
"java"
/>
</and>
</enablement>
Copyright (c) 2000, 2005 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html