Näkymien valikot, työkalurivit ja toiminnot

org.eclipse.ui.viewActions

Tämän laajennuspisteen avulla lisätään toimintoja muiden lisäosien rekisteröimien näkymien avattavaan valikkoon ja työkaluriviin. Kussakin näkymässä on paikallinen avattava valikko, joka aktivoidaan yleensä napsauttamalla oikeassa ylänurkassa olevaa kolmiopainiketta. Muut lisäosat voivat lisätä tähän valikkoon alivalikoita ja toimintoja. Lisäosat voivat myös lisätä toimintoja näkymän työkaluriviin. Näkymän omistajat saavat ensin täyttää nämä alueet. Siihen liitetään muiden lisäosien valinnaisia lisäyksiä.

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 (viewContribution+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT viewContribution (menu* , action*)>

<!ATTLIST viewContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Tämän elementin avulla määritetään näkymän toimintojen ja/tai valikkojen ryhmä.



<!ELEMENT action (selection* | enablement?)>

<!ATTLIST action

id            CDATA #REQUIRED

label         CDATA #REQUIRED

menubarPath   CDATA #IMPLIED

toolbarPath   CDATA #IMPLIED

icon          CDATA #IMPLIED

disabledIcon  CDATA #IMPLIED

hoverIcon     CDATA #IMPLIED

tooltip       CDATA #IMPLIED

helpContextId CDATA #IMPLIED

style         (push|radio|toggle) "push"

state         (true | false)

class         CDATA #REQUIRED

enablesFor    CDATA #IMPLIED>

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



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



Seuraavassa on esimerkki näkymän toiminnon laajennuksesta:

   

<extension point=

"org.eclipse.ui.viewActions"

>

<viewContribution id=

"com.xyz.xyzViewC1"

targetID=

"org.eclipse.ui.views.navigator.ResourceNavigator"

>

< - valikko id=

"com.xyz.xyzMenu"

label=

"XYZ Menu"

path=

"additions"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

menubarPath=

"com.xyz.xyzMenu/group1"

toolbarPath=

"Normal/additions"

style=

"toggle"

state=

"true"

icon=

"icons/runXYZ.gif"

tooltip=

"Run XYZ Tool"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.RunXYZ"

>

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

/>

</action>

</viewContribution>

</extension>

Yllä olevassa esimerkissä määritetty toiminto otetaan käyttöön vain yksittäisessä valinnassa (enablesFor-määrite). Lisäksi valinnan objektin on oltava Java-tiedostoresurssi.

Seuraavassa on toinen esimerkki näkymän toiminnon laajennuksesta:

   

<extension point=

"org.eclipse.ui.viewActions"

>

<viewContribution id=

"com.xyz.xyzViewC1"

targetID=

"org.eclipse.ui.views.navigator.ResourceNavigator"

>

< - valikko id=

"com.xyz.xyzMenu"

label=

"XYZ Menu"

path=

"additions"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ2"

label=

"&amp;Run XYZ2 Tool"

menubarPath=

"com.xyz.xyzMenu/group1"

style=

"push"

icon=

"icons/runXYZ2.gif"

tooltip=

"Run XYZ2 Tool"

helpContextId=

"com.xyz.run_action_context2"

class=

"com.xyz.actions.RunXYZ2"

>

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<not>

<objectState name=

"extension"

value=

"java"

/>

</not>

</and>

</enablement>

</action>

</viewContribution>

</extension>

Yllä olevassa esimerkissä määritetty toiminto näkyy valikon vaihtoehtona. Toiminto otetaan käyttöön, jos valinta ei sisällä Java-tiedostoresursseja.

Määritteen class arvon on oltava sen Java-luokan tarkennettu nimi, joka toteuttaa rajapinnan org.eclipse.ui.IViewActionDelegate. Tämä luokka ladataan mahdollisimman myöhään, jotta koko lisäosa ladattaisiin vasta sitten, kun sitä todella tarvitaan.

Rajapinta org.eclipse.ui.IViewActionDelegate laajentaa rajapinnan org.eclipse.ui.IActionDelegate ja lisää ylimääräisen metodin, jolloin delegaatti voi alustaa näkymän ilmentymän, johon se tekee lisäyksen.

Tämän laajennuspisteen avulla voidaan lisätä toimintoja kohdenäkymän aiemmin luomiin valikoihin. Jos valikkopolun määrite jätetään pois, uusi valikko tai toiminto lisätään avattavan valikon loppuun.

Toimintolaajennuksen käyttöönottoehdot määritetään alun perin määritteen enablesFor ja joko määritteen selection tai määritteen enablement avulla. Kun toimintodelegaatti on eritelty, se voi kuitenkin ohjata toiminnon käyttöönottotilaa suoraan selectionChanged-metodissaan.

Toimintojen ja valikkojen nimiöt voivat sisältää erikoismerkkejä, joihin on koodattu valintakirjaimia seuraavien sääntöjen mukaisesti:

  1. 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 tai työkaluriville 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>

Kunkin näkymän avattavassa valikossa ja paikallisella työkalurivillä on yleensä joitakin vakio-objekteja. Muiden lisäosien lisäykset liitetään vakiojoukkoon.