Valikot

org.eclipse.ui.menus

3.2

Tämä laajennuspisteen avulla lisäosan kehittäjä voi määrittää valikkoja, erottimia, loogisia ryhmiä ja valikkovaihtoehtoja mihin tahansa sovelluksessa tilariveistä pikavalikoihin. Sen avulla voi myös määrittää tällaisten lisäysten joukkoja (eli toimintojoukkoja). Käyttäjä voi ottaa toimintojoukon käyttöön tai poistaa ne käytöstä. Lyhyesti sanottuna valikkojen laajennuspiste sisältää kuvakkeita lukuun ottamatta kaikki esityselementit, joita tarvitaan mihin tahansa Eclipsen valikkoon tai reunusalueeseen.

Laajennuspisteen kullekin elementille annetaan yksilöllinen tunnus. Näin elementteihin voi viitata muualla tarvitsematta kirjoittaa elementtiä uudelleen. Tunnus voi esimerkiksi olla tarpeen toimintojoukon tilauksessa tai määrityksessä. Lisäksi tällä tavoin muiden valmistajien lisäosien kehittäjät voivat sijoittaa elementit uusiin sijainteihin liittymässä tarpeen mukaan.

HUOMAUTUS: Versiossa 3.2 ainoa tämän laajennusmekanismin toteutettu osa on "trim"-lisäyksiin liitetty osa. Objekti-, valikko-, työkalu- tai tilarivimerkintöjen lisäys toimii tyhjäkäskynä.

<!ELEMENT extension (item* , menu* , group* , widget*)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT item (parameter* , location* , visibleWhen?)>

<!ATTLIST item

id        CDATA #REQUIRED

commandId CDATA #REQUIRED

menuId    CDATA #IMPLIED>

Kohde voi olla valikkovaihtoehto tai reunuksen kohde sen mukaan, mihin se on sijoitettu. Kohteeseen liittyvä teksti ja kuva piirretään komennosta.



<!ELEMENT menu (location* , visibleWhen?)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #IMPLIED>

Valikko voi näkyä liitettynä työkaluriviin tai johonkin kohtaan näkymävalikossa, pikavalikossa tai ylätason valikkopalkissa. Lisäosan kehittäjä voi olettaa, että kussakin näkymässä on valikko ja työkalurivi sekä ylätason valikkopalkki. Pikavalikot on rekisteröitävä ohjelmallisesti, ennen kuin niitä voi käyttää (katso API-tiedot).

Valikko voi sisältää vain ryhmiä.



<!ELEMENT group (location*)>

<!ATTLIST group

id                CDATA #REQUIRED

separatorsVisible (true | false) "true">

Looginen ryhmä. Se voi olla näkyvä (esimerkiksi ennen tai jälkeen oleva erotin tarpeen mukaan) tai näkymätön. Oletusarvon mukaan loogiset ryhmät ovat näkyviä.

Ryhmä voi sisältää valikkoja, kohteita ja toisia ryhmiä.



<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>

<!ATTLIST widget

id    CDATA #REQUIRED

class CDATA #REQUIRED>

Valikko- tai trim-elementti, joka voi käyttää widget-objekteja suoraan. Tämän avulla voi esimerkiksi hahmontaa yhdistelmäruudun. Valitettavasti tämä tarkoittaa, että jos widget-elementti tulee näkyväksi käyttöliittymässä, se johtaa lisäosan lataamiseen. Käytä tätä elementtiä varoen, koska se voi aiheuttaa ongelmia suoritustehossa. Tämä aiheuttaa ongelmia myös makrotuen, komentosarjojen ja vastaavien komentoihin perustuvien toimintojen käytössä. Trim-elementtinä käytettävä widget-objekti aiheuttaa lisäosalatauksen vain, kun se näkyy käyttöliittymässä.



<!ELEMENT layout EMPTY>

<!ATTLIST layout

fillMajor (true | false)

fillMinor (true | false) >

Tämän elementin avulla voit määrittää erilaisia asetteluvaihtoehtoja elementeille, jotka on lisätty trim-sijainteihin.



<!ELEMENT location (order? , (bar | part | popup))>

<!ATTLIST location

mnemonic   CDATA #IMPLIED

imageStyle CDATA #IMPLIED>

Sijainti, jossa voi olla menu, group, item tai widget. Tämän elementin avulla hallitaan sijaintikohtaisia tietoja.



<!ELEMENT bar EMPTY>

<!ATTLIST bar

type (menu|trim)

path CDATA #IMPLIED>

Sijainnissa oleva lehtielementti. Se voi olla valikkopalkki tai reunusalue. Jos se on tarkentamaton, se tarkoittaa ylätason valikkopalkkia tai reunusta. Jos se on tarkennettu part-elementin avulla, se tarkoittaa kyseisen osan valikkoa tai reunusta.



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

Luokkaelementti, joka tukee ajettavaa laajennuksen jäsennyssyntaksia widget- ja dynamic-elementeissä.



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

<!ATTLIST visibleWhen

checkEnabled (true | false) "false">

Hallitsee elementin näkyvyyttä.



<!ELEMENT part (popup | bar)>

<!ATTLIST part

id    CDATA #IMPLIED

class CDATA #IMPLIED>

Sijainnissa oleva elementti. Tämä tarkentaa sijainnin viittaamaan tiettyyn työympäristön osaan. Se voi olla joko näkymä tai muokkausohjelma. Tarkennuksessa voidaan käyttää joko osan luokan nimeä (perintä mukaan luettuna), tai se voi viitata näkymän tai muokkausohjelman tunnukseen.

Vain joko id tai class voidaan määrittää.



<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Parametri toteutettavaan laajennukseen tai komento. Tämä määräytyy sen mukaan, missä se näkyy laajennuksessa.



<!ELEMENT order EMPTY>

<!ATTLIST order

position   (start|end|before|after)

relativeTo CDATA #IMPLIED>

Hallitsee valikon, ryhmän, kohteen tai widget-objektin sijaintia tietyssä sijainnissa.



<!ELEMENT popup EMPTY>

<!ATTLIST popup

id   CDATA #IMPLIED

path CDATA #IMPLIED>

Sijainnin osa. Se osoittaa, että valikon, ryhmän, kohteen tai widget-objektin tulee näkyä ponnahdusvalikossa.



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



Valikon perusmääritys näyttää seuraavanlaiselta.

< - valikko id=

"com.mycompany.myplugin.projection"

label=

"%Folding.label"

>

<location mnemonic=

"%Folding.label.mnemonic"

>

<part id=

"AntEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

Tässä esimerkissä lisäosan kehittäjä toimittaa kaikkiin osiin, jotka toimivat aliluokkina tai toteuttavat annetun lajin. Näin voi esimerkiksi lisätä joitakin lisäyksiä kaikkiin tekstin muokkausohjelmiin.

< - valikko id=

"com.mycompany.myplugin.textEditorMenu"

label=

"Text Commands"

>

<location mnemonic=

"X"

>

<part class=

"AbstractTextEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

Ohjeen voi yhdistää valikkoon.

< - valikko id=

"com.mycompany.myplugin.RunWithConfigurationAction"

label=

"Run With Configuration"

helpContextId=

"run_with_configuration_context"

>

<location>

<bar />

</location>

</menu>

Valikossa voi määrittää loogisia ryhmiä. Loogiset ryhmät voivat olla näkyviä (esimerkiksi ennen tai jälkeen oleva erotin tarpeen mukaan) tai näkymättömiä. Oletusarvon mukaan loogiset ryhmät ovat näkyviä.

<group id=

"com.mycompany.myplugin.stepGroup"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

<group id=

"com.mycompany.myplugin.stepIntoGroup"

separatorsVisible=

"false"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

Valikkoja, ryhmiä, kohteita ja widget-objekteja voi sijoittaa useisiin sijainteihin.

<item id=

"com.mycompany.myplugin.ToggleStepFilters"

commandId=

"com.mycompany.myplugin.ToggleStepFilters"

>

<location mnemonic=

"%mnemonic"

>

<bar path=

"org.eclipse.ui.run/emptyStepGroup"

/>

</location>

<location>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<bar type=

"trim"

path=

"renderGroup"

/>

</part>

</location>

<location mnemonic=

"%mnemonic"

>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<popup path=

"renderGroup"

/>

</part>

</location>

</item>

Jos ponnahduselementti on määritetty ilman tunnusta ja pääobjektin osaelementtiä, se on käytössä kaikissa pikavalikoissa, jotka työympäristöön on rekisteröity. Tämä toimii samoin kuin vanhat objektin lisäykset. Samaten ylätason ponnahduselementti, jolla on tunnus, vaikuttaa kaikkiin pikavalikoihin, jotka on rekisteröity kyseisellä nimellä.

<item id=

"com.mycompany.myplugin.ObjectContribution"

commandId=

"com.mycompany.myplugin.ObjectContribution"

>

<location>

<popup path=

"additions"

/>

</location>

</item>

Joskus voi olla tarpeen hallita kohteen näkyvyyttä. Yleensä on suositeltavaa säilyttää valikkojen ja työkalurivien asettelu, mutta välillä kannattaa piilottaa kohteet, jotka eivät ole oleellisia. Tämä koskee varsinkin pikavalikkoja, joissa tilaa on vähän. Tässä tapauksessa määritetään visibleWhen-elementti. Tämä elementti on melkein samanlainen kuin activeWhen- ja enabledWhen-elementit, jotka on määritetty käsittelytoimintojen laajennuspisteessä.

<item id=

"com.mycompany.myplugin.ConvertToWatchExpression"

commandId=

"com.mycompany.myplugin.ConvertToWatchExpression"

>

<location mnemonic=

"%mnemonic"

>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<popup path=

"additions"

/>

</part>

</location>

<visibleWhen>

<with variable=

"selection"

>

<iterate operator=

"and"

>

<not>

<instanceof value=

"IWatchExpression"

/>

</not>

<instanceof value=

"IExpression"

/>

</iterate>

</with>

</visibleWhen>

</item>

Yleisin tilanne on, että jotain tuodaan näkyviin, kun sen käsittelytoiminto on käytössä. Tämä toteutetaan syntaktisin keinoin. Elementtiin visibleWhen kuuluu määrite checkEnabled.

<item id=

"com.mycompany.myplugin.compareWithPatch"

commandId=

"com.mycompany.myplugin.compareWithPatch"

>

<location mnemonic=

"%mnemonic"

>

<part id=

"MyPart"

>

<popup path=

"additions"

/>

</part>

</location>

<visibleWhen checkEnabled=

"true"

/>

</item>

Mikä tahansa komentoon liittyvä kohde voi sisältää parametriarvoja. Jos tietyn tunnuksen parametria ei ole määritetty, kyseessä on virhe. Jos kohteella ei ole komentoa, myös se on virhe.

<item id=

"com.mycompany.myplugin.RunHistory"

commandId=

"com.mycompany.myplugin.RunHistory"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

<parameter name=

"index"

value=

"1"

/>

</item>

Voit määrittää myös suhteellisen järjestyksen. Tämä toteutetaan järjestysmääritteen avulla sijaintielementissä. Järjestysmäärite hyväksyy seuraavat arvot: start (sijoittaa elementin säilön alkuun), end (sijoittaa elementin sen säilön loppuun), after (sijoittaa elementin sen rinnakkaiselementin jälkeen, jonka tunnus vastaa ref-arvoa) ja before (sijoittaa elementin sen rinnakkaiselementin edelle, jonka tunnus vastaa ref-arvoa). Suhteellista järjestystä voi käyttää kaikenlaisiin valikkoelementteihin.

<item id=

"com.mycompany.myplugin.MyFirstItem"

commandId=

"com.mycompany.myplugin.MyFirstCommand"

>

<location>

<order position=

"start"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

<item id=

"com.mycompany.myplugin.MySecondItem"

commandId=

"com.mycompany.myplugin.MySecondCommand"

>

<location>

<order position=

"after"

relativeTo=

"com.mycompany.myplugin.MyFirstItem"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

Jos widget-objekteja on tarpeen käyttää suoraan (esimerkiksi yhdistelmäruudun hahmonnukseen), voit käyttää widget-elementtiä. Valitettavasti tämä tarkoittaa, että jos widget-elementti tulee näkyväksi käyttöliittymässä, se johtaa lisäosan lataamiseen.

<widget id=

"com.mycompany.myplugin.MyComboBoxSimple"

class=

"com.mycompany.myplugin.MyComboBox"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mycompany.myplugin.MyComboBoxParameterized1"

class=

"com.mycompany.myplugin.MyComboBox:a,b,c"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mycompany.myplugin.MyComboBoxParameterized2"

>

<class class=

"com.mycompany.myplugin.MyComboBox"

>

<parameter name=

"list"

value=

"a,b,c"

/>

<parameter name=

"selected"

value=

"c"

/>

<parameter name=

"editable"

value=

"false"

/>

</class>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

Widget-objektien avulla voit myös tehdä lisäyksiä työympäristön reunukseen. Seuraavassa esimerkissä määritetään uusi HeapStatus-widget-objekti, joka sijoitetaan oletusarvon mukaan heti tilarivin reunuksen jälkeen (eli työympäristöikkunan alaosaan). Lisätietoja ennalta määritetyistä joukoista on bar-elementin kuvauksessa.

Huomaa, että reunuksen "joukot" voi sijoittaa uudelleen muille reunusalueille. Sijaintitietojen relativeTo-arvossa oletetaan, että viitattu ryhmä on oletussijainnissaan, kun uuden reunuksen sijaintia selvitetään. Yleensä oletetaan, että tällaiset toimittajat luovat oman ryhmän uutta widget-objektia varten, jolloin reunuselementti voidaan siirtää muista reunuselementeistä riippumattomasti. Merkittävä poikkeus on status-joukko.

   

<extension point=

"org.eclipse.ui.menus"

>

<group id=

"TestTrimAPI.heapStatusGroup"

separatorsVisible=

"true"

>

<location>

<bar type=

"trim"

/>

<order position=

"after"

relativeTo=

"status"

/>

</location>

</group>

<widget class=

"HeapStatusWidget"

id=

"TestTrimAPI.HeapStatus"

>

<location>

<bar path=

"heapStatusGroup"

type=

"trim"

/>

</location>

<layout fillMajor=

"false"

fillMinor=

"true"

/>

</widget>

</extension>

Voit rekisteröidä kontekstivalikon IWorkbenchPartSite.registerContextMenu-metodien avulla.