Előugró menük

org.eclipse.ui.popupMenus

Ez a kiterjesztési pont szolgál a más bedolgozók tulajdonában lévő helyzetérzékeny menük új tevékenységekkel bővítésére. A tevékenységek hozzáadása történhet egy megadott objektumtípushoz (objectContribution) vagy a nézet vagy szerkesztőrész egy adott helyzetérzékeny menüjéhez (viewerContribution). Az objectContribution használata esetén a hozzáadott elem minden olyan nézet vagy szerkesztőrész helyzetérzékeny menüjében megjelenik, ahol az adott típusú objektumokat lehet kiválasztani. A viewerContribution használata esetén a hozzáadott elem csak a meghatározott nézet vagy szerkesztőrész helyzetérzékeny menüjében jelenik meg, a kiválasztástól függetlenül.

Ha a kiválasztás heterogén, akkor hozzáadott elem akkor kerül alkalmazásra, ha a kijelölés egy általános típusához van bejegyezve, amennyiben lehetséges. Ha közvetlen illesztés nem lehetséges, akkor a rendszer megkísérli a szülőosztályokhoz és szülőfelületekhez illesztést.

A kiválasztás tovább korlátozható névszűrő használatával. Amennyiben alkalmazásra kerül, a kiválasztás összes objektumának illeszkednie kell a szűrőhöz a hozzáadott elem alkalmazásához.

Az objektum-hozzáadás egyes műveletei az enablesFor attribútum segítségével megadhatják, hogy egyszeres, többszörös, vagy milyen más kiválasztási típusnak feleljen meg.

Ha ezek a szűrési mechanizmusok nem lennének elegendők, akkor a tevékenység-hozzáadás használhatja a filter mechanizmust. Ebben az esetben a célobjektum attribútumai név-érték párok sorozataként vannak megadva. A kijelölésnek megfelelő attribútumok típusspecifikusak és túlmutatnak magán a munkaterület tartományán, vagyis a munkaterület delegálni fogja a szűrést ezen a szinten a tényleges kijelölésnek.

Egy tevékenység engedélyezését vagy láthatóságát az enablement és visibility elemekkel lehet megadni. E két elem egy logikai kifejezést tartalmaz, amelyek kiértékelve meghatározzák az engedélyezést és/vagy láthatóságot.

Az enablement és visibility elemek szintaxisa ugyanaz. Mindkettő egyetlen logikai kifejezés részelemet tartalmazhat. A legegyszerűbb esetben ez egy objectClass, objectState, pluginState vagy systemProperty elem. Bonyolultabb esetben az and, or és not elemek kombinálhatók egy logikai kifejezés létrehozása érdekében. Az and és or elemnek egyaránt 2 részelemet kell tartalmaznia. A not elem csak 1 részelemet tartalmazhat.

<!ELEMENT extension (objectContribution , viewerContribution)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT objectContribution (filter* , visibility? , enablement? , menu* , action*)>

<!ATTLIST objectContribution

id          CDATA #REQUIRED

objectClass CDATA #REQUIRED

nameFilter  CDATA #IMPLIED

adaptable   (true | false) "false">

Ezzel az elemmel adható meg tevékenységek és/vagy menük egy csoportja bármelyik megjelenítő helyzetérzékeny menüjébe, amelyben az adott típusú objektumok vannak kiválasztva.



<!ELEMENT viewerContribution (visibility? , menu* , action*)>

<!ATTLIST viewerContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Ezzel az elemmel adható meg tevékenységek és/vagy menük egy csoportja egy nézet vagy szerkesztőrész adott helyzetérzékeny menüjéhez.



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

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

definitionId     CDATA #IMPLIED

menubarPath      CDATA #IMPLIED

icon             CDATA #IMPLIED

helpContextId    CDATA #IMPLIED

style            (push|radio|toggle|pulldown)

state            (true | false)

class            CDATA #REQUIRED

enablesFor       CDATA #IMPLIED

overrideActionId CDATA #IMPLIED

tooltip          CDATA #IMPLIED>

Ez az elem egy tevékenységet ad meg, amelyet a felhasználó meghívhat a felhasználói felületen.



<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Ez az elem használatos az aktuális kijelölésben szereplő egyes objektumok attribútumállapotainak kiértékelésére. Akkor igaz, ha a kijelölés minden egyes objektuma egy adott attribútumállapottal bír. A kijelölés minden egyes objektumának meg kell valósítania (vagy adaptálnia kell) az org.eclipse.ui.IActionFilter felületet.



<!ELEMENT menu (separator+ , groupMarker*)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Ez az elem szolgál egy új menü meghatározására.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

Az elem létrehoz egy menüelválasztót az új menüben.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

Ez az elem az új menüben létrehoz egy megnevezett csoportot. Az új menüben látható módon nem jelenik meg (szemben a separator elemmel).



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

Ez az elem segít annak meghatározásában, milyen tevékenység legyen engedélyezve az aktuális kiválasztás alapján. Figyelmen kívül marad, ha az enablement elem meg van adva.



<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Ez az elem szolgál a kiterjesztés engedélyezésének meghatározására.



<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Ez az elem szolgál a kiterjesztés láthatóságának meghatározására.



<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Az elem egy logikai AND műveletet ábrázol a két részelemként kiértékelt kifejezés eredményén.



<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Az elem egy logikai OR műveletet ábrázol a két részelemként kiértékelt kifejezés eredményén.



<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Az elem egy logikai NOT műveletet ábrázol a részelemként kiértékelt kifejezés eredményén.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

Ez az elem szolgál az aktuális kijelölésben szereplő egyes objektumok osztályainak vagy felületeinek kiértékelésére. A kifejezés értéke akkor igaz, ha a kijelölés minden egyes objektuma megvalósítja az adott osztályt vagy felületet.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Ez az elem használatos az aktuális kijelölésben szereplő egyes objektumok attribútumállapotainak kiértékelésére. A kifejezés értéke akkor igaz, ha a kijelölés minden egyes objektuma egy adott attribútumállapottal bír. Ilyen típusú kifejezés kiértékeléséhez a kijelölés minden objektumának meg kell valósítania, vagy adaptálódnia kell az org.eclipse.ui.IActionFilter felülethez.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Ez az elem szolgál egy bedolgozó állapotának kiértékelésére. A bedolgozó állapota az alábbi lehet: telepített ("feloldott" OSGi állapotnak felel meg) vagy aktivált ("aktív" OSGi állapotnak felel meg).



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Ez az elem szolgál bizonyos rendszertulajdonságok állapotának kiértékelésére. A tulajdonság értéke a java.lang.System helyről kerül lekérésre.



<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Általános gyökérelem. Az elem kiterjesztési pontokon belül használható a hozzá tartozó enablement kifejez meghatározására. Az enablement kifejezések leszármazottai az and operátorral kombinálhatók.



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

Ez az elem egy NOT műveletet képvisel a részelemeként kiértékelt kifejezés eredményén.



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

Ez az elem egy AND műveletet képvisel a részelemeként kiértékelt összes kifejezés eredményén.



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

Ez az elem egy OR műveletet képvisel a részelemeként kiértékelt összes kifejezés eredményén.



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

Ezzel az elemmel végezhető el a fókuszban lévő objektum instanceof ellenőrzése. A kifejezés az EvaluationResult.TRUE értékkel tér vissza, ha az objektum típusa a value attribútumban megadott típus altípusa. Ellenkező esetben EvaluationResult.FALSE kerül visszaadásra.



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

Ezzel az elemmel értékelhető ki a fókuszban lévő objektum tulajdonságának állapota. A tesztelhető tulajdonságok halmaza a tulajdonságtesztelő kiterjesztési ponton terjeszthető ki. A tesztelési kifejezés EvaluationResult.NOT_LOADED értéket ad vissza, ha a tényleges tesztelést végző tulajdonságtesztelő még nincs betöltve.



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

Megvizsgál egy rendszertulajdonságot a System.getProperty metódus meghívásával, és összehasonlítja az eredményt a value attribútumban megadott értékkel.



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

Ezzel az elemmel végezhető el a fókuszban lévő objektum egyenlőségi ellenőrzése. A kifejezés az EvaluationResult.TRUE értékkel tér vissza, ha az objektum egyenlő a value attribútumban megadott értékkel. Ellenkező esetben EvaluationResult.FALSE kerül visszaadásra.



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

Ezzel az elemmel vizsgálható megy egy kollekció elemszáma.



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

<!ATTLIST with

variable CDATA #REQUIRED>

Az elem módosítja a leszármazott elemek tekintetében megvizsgálandó objektumot az adott változó által hivatkozott objektumra. Ha a változó nem oldható fel, akkor a kifejezés a kiértékelés során ExpressionException kivételt ad. A with kifejezések leszármazottai az and operátorral kombinálhatók.



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

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED>

Az elem módosítja a leszármazott elemek tekintetében megvizsgálandó objektumot az adott változó által hivatkozott objektumra. Ha a változó nem oldható fel, akkor a kifejezés a kiértékelés során ExpressionException kivételt ad. A with kifejezések leszármazottai az and operátorral kombinálhatók.



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

<!ATTLIST adapt

type CDATA #REQUIRED>

Ezzel az elemmel adaptálható a fókuszban lévő objektum a type attribútummal megadott típusra. A kifejezés "nincs betöltve" értéket ad vissza, ha a hivatkozott adapter vagy típus még nincs betöltve. ExpressionException kivételt ad a kiértékelés során, ha a típus neve egyáltalán nem létezik. Az adapt kifejezések leszármazottai az and operátorral kombinálhatók.



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

<!ATTLIST iterate

operator (or|and) >

Ezzel az elemmel iterálhatók a java.util.Collection típusú változók. Ha a fókuszban lévő objektum nem java.util.Collection típusú, akkor a kifejezés kiértékelése ExpressionException kivételt ad.



Az alábbiakban bemutatunk egy példát egy előugró menü kiterjesztési pontra:

   

<extension point=

"org.eclipse.ui.popupMenus"

>

<objectContribution id=

"com.xyz.C1"

objectClass=

"org.eclipse.core.resources.IFile"

nameFilter=

"*.java"

>

<menu id=

"com.xyz.xyzMenu"

path=

"additions"

label=

"&amp;XYZ Java Tools"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

style=

"push"

menubarPath=

"com.xyz.xyzMenu/group1"

icon=

"icons/runXYZ.gif"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.XYZToolActionDelegate"

enablesFor=

"1"

/>

</objectContribution>

<viewerContribution id=

"com.xyz.C2"

targetID=

"org.eclipse.ui.views.TaskList"

>

<action id=

"com.xyz.showXYZ"

label=

"&amp;XYZ megjelenítése"

style=

"toggle"

state=

"true"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

/>

</viewerContribution>

</extension>

A fenti példában a megadott objektum-hozzájárulás csak egyetlen kiválszatást enged (enablesFor attribútum). Ezen felül a kiválasztás minden egyes objektumának meg kell valósítania a megadott felületet (IFile) és Java fájlnak kell lennie. Ez a tevékenység kerül hozzáadásra az előbb létrehozott almenübe. A hozzájárulás minden olyan nézetben érvényes lesz, amely a kívánt kiválasztással rendelkezik.

Ezzel szemben a fenti nézet-hozzájárulás csak a Feladatok nézet helyzetérzékeny menüjében jelenik meg és nem befolyásolja a nézet kiválasztása.

Az alábbiakban bemutatunk egy példát a szűrési mechanizmusra. Ebbben az esetben a tevékenység csak az olyan IMarker-ek esetében jelenik meg, amelyek be vannak fejezve és magas prioritásúak.

   

<extension point=

"org.eclipse.ui.popupMenus"

>

<objectContribution id=

"com.xyz.C3"

objectClass=

"org.eclipse.core.resources.IMarker"

>

<filter name=

"done"

value=

"true"

/>

<filter name=

"priority"

value=

"2"

/>

<action id=

"com.xyz.runXYZ"

label=

"Magas prioritású befejezett tevékenységek eszköz"

icon=

"icons/runXYZ.gif"

class=

"com.xyz.actions.MarkerActionDelegate"

>

</action>

</objectContribution>

</extension>

Az alábbiakban bemutatunk még egy példát a visibility elem használatával:

   

<extension point=

"org.eclipse.ui.popupMenus"

>

<viewerContribution id=

"com.xyz.C4"

targetID=

"org.eclipse.ui.views.TaskList"

>

<visibility>

<and>

<pluginState id=

"com.xyz"

value=

"activated"

/>

<systemProperty name=

"ADVANCED_MODE"

value=

"true"

/>

</and>

</visibility>

<action id=

"com.xyz.showXYZ"

label=

"&amp;XYZ megjelenítése"

style=

"push"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

>

</action>

</viewerContribution>

</extension>

A fenti példában a megadott tevékenység egy menüpontként jelenik meg. a Feladatok nézet helyzetérzékeny menüjében, de csak akkor, ha a "com.xyz" bedolgozó aktív és a megadott rendszertulajdonság értéke igaz.

A class tevékenységattribútum értéke az org.eclipse.ui.IObjectActionDelegate-t megvalósító osztály teljes képzésű neve kell, hogy legyen objektum-hozzájárulások esetében, az org.eclipse.ui.IViewActionDelegate-t megvalósító osztály teljes képzésű neve a nézetekhez tartozó helyzetérzékeny menük esetében és az org.eclipse.ui.IEditorActionDelegate-t megvalósító osztály teljes képzésű neve a szerkesztőkhöz tartozó helyzetérzékeny menük esetében. Minden esetben a megvalósító osztály a lehető legkésőbb töltődik be, hogy ne kelljen a teljes bedolgozót betölteni addig, amíg nem feltétlenül szükséges.

Megjegyzés: A visszamenőleges kompatibilitás érdekében az org.eclipse.ui.IActionDelegate is megvalósítható az objektum-hozzájárulásokhoz.

A helyzetérzékeny menük kiterjesztése egy részen belül csak akkor lehetséges, ha a célrész közzéteszi a menüt kiterjesztésre. Ezt erősen javasoljuk, hiszen javítja a termék bővíthetőségét. Ehhez az egyes részeknek közzé kell tenniük a definiált helyzetérzékeny menüket az IWorkbenchPartSite.registerContextMenu meghívásával. Ha ez megtörtént, a munkaterület automatikusan be fog illeszteni minden létező tevékenységkiterjesztést.

Minden egyes bejegyzett menühöz meg kell adni egy menüazonosítót. A részek közötti következetesség érdekében célszerű a következő stratégiát alkalmaznia minden részmegvalósítónak.

A munkaterületen bejegyzett helyzetérzékeny menüknek tartalmazniuk kell egy általános beszúrási pontot is, IWorkbenchActionConstants.MB_ADDITIONS azonosítóval. Más bedolgozók ezt azértékek fogják használni referenciapontként a beszúráshoz. A beszúrási pont megadható egy GroupMarker felvételével a menübe a beszúráshoz alkalmkas ponton.

A munkaterület egy objektuma, amely egy helyzetérzékeny menü kiválasztása, meghatározhat egy org.eclipse.ui.IActionFilter osztályt. Ez a szűrési stratégia képes típusspecifikus szűrésre. A munkaterület lekéri a kiválasztás szűrőjét úgy, hogy ellenőrzi, hogy az megvalósítja-e az IActionFilter-t. Ha nem, akkor a munkaterület kér egy szűrőt az IAdaptable mechanizmuson keresztül.

A tevékenységek és menücímkék tartalmazhatnak hívóbetűket kódoló speciális karaktereket. Ezeket úgy lehet megadni, hogy egy '&' (és-jel) karaktert kell írni a lefordított szöveg megfelelő karaktere elé. Mivel XML karaktersorozatokban az és-jel nem engedélyezett, használja a &amp; kódot.

Ha egy kiterjesztés két vagy több tevékenységgel bővíti a menüt, akkor a tevékenységek a plugin.xml fájlban felsorolthoz képest pont fordítva jelennek meg. Ez a viselkedés kétségkívül szerencsétlen. Ezt azonban az Eclipse API rögzítése után fedeztük fel. Ha most megváltoztatjuk a viselkedést, akkor tönkreteszünk minden olyan bedolgozót, amelyik a meglévő viselkedésen alapul.

A selection és enablement elemek kölcsönösen kizárják egymást. Az enablement helyettesítheti a selection elemet az objectClass és objectState részelemek használatával. Például az alábbi kód:

 

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

>

</selection>

kifejezhető így is:
 

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<objectState name=

"extension"

value=

"java"

/>

</and>

</enablement>

A munkaterület egy sor beépített helyzetérzékeny menüvel érkezik, amelyekben már számos tevékenység található. A bedolgozók hozzátehetnek ezekhez a menükhöz. Ha egy nézetnek vannak fenntartott bővítőhelyei e hozzájárulásokhoz és nyilvánossá vannak téve, akkor a bővítőhelyek elérési utakként használhatók. Egyébként a tevékenységek és az almenük az előugró menü legaljára kerülnek.