Toimintojoukot

org.eclipse.ui.actionSets

Tämän laajennuspisteen avulla voidaan lisätä valikoita, valikkovaihtoehtoja ja työkalurivin painikkeita työympäristöikkunan yhteisiin alueisiin. Tällaisia lisäyksiä kutsutaan yhteisellä nimellä toimintojoukko, ja ne tulevat näkyviin työympäristöikkunaan, kun käyttäjä mukauttaa perspektiiviä.

Käytössä on toteutusrajoitus, joka vaikuttaa tällä hetkellä toimintojoukkoihin. On tärkeää määrittää koko valikkorakenne, johon toimintojoukossa viitataan. Jos esimerkiksi jokin muu toimintojoukko määrittää valikon nimeltä "esimerkki", ei ole mahdollista luottaa siihen, että "esimerkki" on olemassa. Valikko "esimerkki" on määritettävä uudelleen jokaiseen sitä käyttävään toimintojoukkoon.

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

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


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

<!ATTLIST actionSet

id          CDATA #REQUIRED

label       CDATA #REQUIRED

visible     (true | false)

description CDATA #IMPLIED>

Tämän elementin avulla määritetään toiminnoista ja/tai valikoista koostuva ryhmä.



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

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

accelerator      CDATA #IMPLIED

definitionId     CDATA #IMPLIED

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|pulldown) "push"

state            (true | false)

pulldown         (true | false)

class            CDATA #IMPLIED

retarget         (true | false)

allowLabelUpdate (true | false)

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 toimintojoukosta (huomaa, miten alielementtejä ja määritteitä on käytetty):

    

<extension point =

"org.eclipse.ui.actionSets"

>

<actionSet id=

"com.xyz.actionSet"

label=

"Omat toiminnot"

>

< - valikko id=

"com.xyz.xyzMenu"

label=

"XYZ Menu"

path=

"additions"

>

<separator name=

"group1"

/>

<separator name=

"option1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

style=

"toggle"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/group1"

icon=

"icons/runXYZ.gif"

tooltip=

"Run XYZ Tool"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.RunXYZ"

enablesFor=

"1"

>

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

/>

</action>

<action id=

"com.xyz.runABC"

label=

"&amp;Aja XYZ-työkalu"

style=

"push"

menubarPath=

"com.xyz.xyzMenu/group1"

toolbarPath=

"Normal/XYZ"

icon=

"icons/runABC.gif"

tooltip=

"Aja XYZ-työkalu"

helpContextId=

"com.xyz.run_abc_action_context"

retarget=

"true"

allowLabelUpdate=

"true"

>

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<not>

<objectState name=

"extension"

value=

"java"

/>

</not>

</and>

</enablement>

</action>

<action id=

"com.xyz.runDEF"

label=

"&amp;Aja DEF-työkalu"

style=

"radio"

state=

"true"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runDEF.gif"

tooltip=

"Aja DEF-työkalu"

class=

"com.xyz.actions.RunDEF"

helpContextId=

"com.xyz.run_def_action_context"

>

</action>

<action id=

"com.xyz.runGHI"

label=

"&amp;Aja GHI-työkalu"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runGHI.gif"

tooltip=

"Aja GHI-työkalu"

class=

"com.xyz.actions.RunGHI"

helpContextId=

"com.xyz.run_ghi_action_context"

>

</action>

<action id=

"com.xyz.runJKL"

label=

"&amp;Aja JKL-työkalu"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runJKL.gif"

tooltip=

"Aja JKL-työkalu"

class=

"com.xyz.actions.RunJKL"

helpContextId=

"com.xyz.run_jkl_action_context"

>

</action>

</actionSet>

</extension>

Edellisessä esimerkissä määritetty Omat toiminnot -toimintojoukko ei ole oletusarvon mukaan näkyvissä perspektiiveissä, koska koodissa ei ole visible-määritettä.

XYZ-toiminto näytetään valikon valittavana vaihtoehtona, joka ei ole valittuna oletustilassa. Sitä voi käyttää vain, kun valittuna on yksi Java-tiedosto.

ABC-toiminto näytetään sekä valikossa että työkalurivillä. Sitä voi käyttää vain, kun valinta ei sisällä yhtään Java-tiedostoa. Huomaa myös, että koska tämä on uudelleenohjattu (retarget) toiminto, sille ei ole määritetty class-määritettä.

DEF-, GHI- ja JKL-toiminnot näytetään valikossa valintanappeina. Niitä voi käyttää aina siitä riippumatta, mitä objekteja on valittu.

Class-määritteen arvon on oltava sen luokan tarkka nimi, joka toteuttaa org.eclipse.ui.IWorkbenchWindowActionDelegate- tai org.eclipse.ui.IWorkbenchWindowPulldownDelegate-liittymän. Jälkimmäistä liittymää on käytettävä, kun style-määritteen arvo on pulldown. Tämä luokka on toiminnon toteutuksesta vastaava käsittelytoiminto. Jos retarget-määritteen arvo on true, tämä määrite ohitetaan, joten sille ei tarvitse tällöin antaa arvoa. Tämä luokka ladataan mahdollisimman myöhään, jotta koko lisäosa ladattaisiin vasta sitten, kun sitä todella tarvitaan.

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.

Työympäristö ei luo valikoita lisäosan puolesta. Valikoiden, joihin valikkopolkumäärityksissä viitataan, on oltava olemassa.

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>

Tämän laajennuspisteen avulla lisäosia voidaan käyttää uusien ylätason valikoiden lisäämiseen. Lisäksi lisäosilla voidaan määrittää nimettyjä ryhmiä, joihin voidaan lisätä toimintoja muilla lisäosilla.

Ylätason valikot luodaan seuraavien path-määritteen arvojen avulla:

Jos path-määritteelle ei ole annettu arvoa, uusi valikko lisätään lisäysvalikkoryhmään.

Työympäristöikkunan oletusryhmät on määritetty IWorkbenchActionConstants-liittymään. Näitä vakioarvoja voi käyttää koodissa dynaamisina lisäyksinä. Arvot voi myös kopioida XML-tiedostoon haluttaessa luoda tiivis integrointi aiemmin luotujen työympäristön valikoiden ja työkalurivin kanssa.

Osa työympäristöikkunan valikkojen ja työkalurivin vaihtoehdoista on määritetty algoritmien avulla. Tällaisissa tapauksissa ikkunan laajennukset on tehtävä erillisellä mekanismilla. Kun esimerkiksi ympäristöön lisätään uusi työympäristönäkymä, Perspektiivi-valikkoon tulee näkyviin uusi vaihtoehto. Myös ohjattujen tuonti-, vienti- ja luontitoimintojen laajennukset lisätään ikkunaan automaattisesti.