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.
org.eclipse.ui
, tunnus voi olla org.eclipse.ui.item1
.<!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ä.
org.eclipse.ui
, tunnus voi olla org.eclipse.ui.menu1
.<!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ä.
org.eclipse.ui
, tunnus voi olla org.eclipse.ui.group1
.<!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ä.
org.eclipse.ui
, tunnus voi olla org.eclipse.ui.widget1
.IWorkbenchWidget
. Työasema voi valita käyttöön oletustoteutuksen AbstractWorkbenchTrimWidget
. Kyseinen toteutus käsittelee "init"-metodin ja lataa tuloksen välimuistiin getWorkbenchWindow
-metodin kautta käyttöä varten.<!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.
false
.false
.<!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.
menu
tai trim
. Jos lisäys tapahtuu valikkoon, kohteen pääobjektiksi tulee jokin widget-rakenne. Yleensä tämä tarkoittaa, että widget-elementtien käyttö ei kannata eikä kohteen komennon kuvake ole tarpeen. Oletusarvo on menu
.
Jos teet lisäyksiä trim
-elementtiin, palkki ei
yleensä edellytä erityistä komentoa tai kuvaketta; sen pitäisi
täyttyä widget-objektilla, joka näyttää trim-elementin sisällön.
Reunuksen sisällä työympäristö määrittää yleiset ryhmät, jotka vastaavat eri sijainteja ikkunan ympärillä:
vertical1
.'/'
.<!ATTLIST class
class CDATA #REQUIRED>
Luokkaelementti, joka tukee ajettavaa laajennuksen jäsennyssyntaksia widget
- ja dynamic
-elementeissä.
IExecutableExtension
.<!ELEMENT visibleWhen (not | or | and | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
<!ATTLIST visibleWhen
checkEnabled (true | false) "false">
Hallitsee elementin näkyvyyttä.
true
, alielementtejä ei ole. Tämä vain tarkistaa komennon käyttöönottotilan ja muuntaa vastaavan elementin näkyväksi, jos komento on käytössä.<!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.
Tämä mää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.
Jos ristiriitoja ilmenee, Eclipse valitsee jonkin järjestyksen. Ainoa varmuus on, että ristiriidan ilmetessä järjestys säilyy samana niin kauan kuin seuraavat seikat pätevät:
position
on before
tai after
.<!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>
IWorkbenchPartSite.registerContextMenu
-metodien avulla.
Copyright (c) 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