Muokkausohjelmien valikot, työkalurivit ja toiminnot

org.eclipse.ui.editorActions

Tämän laajennuspisteen avulla voidaan lisätä toimintoja muilla lisäosilla rekisteröityjen muokkausohjelmien valikoihin ja työkaluriveihin.

Muokkausohjelman peruskokoonpano määräytyy toisen laajennuspisteen perusteella (org.eclipse.ui.editors). Saman muokkausohjelmalajin ilmentymille luodaan yhteinen toimintojoukko, jota ne kaikki käyttävät. Kun tällaista toimintoa kutsutaan, se toteuttaa jonkin toimen käytössä olevassa muokkausohjelmassa. Tämä laajennuspiste toimii samalla tavalla. Kukin luotu toimintolaajennus on kaikkien saman muokkausohjelmalajin ilmentymien yhteiskäytössä. Org.eclipse.ui.IEditorActionDelegate-liittymän toteutusta varten on määritettävä toimintoluokka. Tieto aktiivisesta muokkausohjelmasta välitetään toiminnon suorittavalle objektille IEditorActionDelegate.setActiveEditor-liittymän avulla.

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

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


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

<!ATTLIST editorContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Tämän elementin avulla määritetään muokkausohjelman toiminto- ja/tai valikkojoukko.



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

state         (true | false)

class         CDATA #REQUIRED

enablesFor    CDATA #IMPLIED

actionID      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 muokkausohjelman toimintolaajennuksesta:

   

<extension point=

"org.eclipse.ui.editorActions"

>

<editorContribution id=

"com.xyz.xyzContribution"

targetID=

"com.ibm.XMLEditor"

>

< - valikko id=

"XYZ"

label=

"&amp;XYZ-valikko"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

menubarPath=

"XYZ/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>

</editorContribution>

</extension>

Edellä olevassa esimerkissä määritetty toiminto näkyy valintaobjektina uudessa ylätason valikossa nimeltä XYZ-valikko ja tilanvaihtopainikkeena työkalurivillä. Toiminto on käytettävissä, kun valittuna on vain Java-tiedostoja.

Seuraavassa on toinen esimerkki muokkausohjelman toimintolaajennuksesta:

   

<extension point=

"org.eclipse.ui.editorActions"

>

<editorContribution id=

"com.xyz.xyz2Contribution"

targetID=

"com.ibm.XMLEditor"

>

< - valikko id=

"XYZ2"

label=

"&amp;XYZ2-valikko"

path=

"muokkaa/additions"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ2"

label=

"&amp;Run XYZ2 Tool"

menubarPath=

"edit/XYZ2/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>

</editorContribution>

</extension>

Edellä olevassa esimerkissä määritetty toiminto näkyy valikon vaihtoehtona ylätason Muokkaa-valikon alivalikossa nimeltä XYZ2-valikko. Toiminto otetaan käyttöön, jos valinta ei sisällä Java-tiedostoresursseja.

Class-määritteen arvon oltava sen Java-luokan tarkka nimi, joka toteuttaa org.eclipse.ui.IEditorActionDelegate-liittymän. Tämä luokka ladataan mahdollisimman myöhään, jotta koko lisäosa ladattaisiin vasta sitten, kun sitä todella tarvitaan. Metodia setActiveEditor kutsutaan aina, kun määritetyn lajin muokkausohjelma aktivoidaan. Määritetyn muokkausohjelmalajin ilmentymiä varten luodaan vain yksi toiminto- ja valikkojoukko riippumatta siitä, kuinka monta muokkausohjelmaa työympäristössä on avoinna.

Tämän laajennuspisteen avulla voidaan lisätä toimintoja kohdemuokkausohjelmalla aiemmin luotuihin valikoihin. Lisäksi valikoita ja toimintoja voi lisätä työympäristöikkunaan. Työympäristöikkunan toimintojen ja pääryhmien tunnukset on määritetty org.eclipse.ui.IWorkbenchActionConstants-liittymässä. Niitä tulee käyttää viittauspisteinä uusia toimintoja lisättäessä. 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.

Näihin polkuihin lisätyt toiminnot ja valikot näytetään vain, kun niihin yhdistetty muokkausohjelma on käytössä. Kun kyseinen muokkausohjelma on suljettu, valikot ja toiminnot eivät ole näkyvissä.

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>

Työympäristö sisältää sisäisen oletustekstinmuokkausohjelman. Tähän muokkausohjelmaan voi tehdä lisäyksiä lisäosilla tai muiden lisäosien määrittämillä muokkausohjelmilla.