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 legegyserűbb esetben ez egy objectClass, objectState, pluginState vagy systemProperty elem. Bonyolultabb esetben az and, or és not elemek is felhasználhatók egy összetettebb logikai kifejezés létrehozására. Az and és or elemek két részelemet kell, hogy tartalmazzanak. A not elem csak egy 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 a felhasználói felületről a felhasználó által meghívható tevékenységet adja meg.



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

Ez az elem szolgál az új menü egy elválasztójának létrehozására.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

Ez az elem szolgál az új menü egy megnevezett csoportjának létrehozására. 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 használatos 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. Az ilyen típusú kifejezések kiértékeléséhez a kijelölés minden egyes objektumának meg kell valósítania (vagy alkalmazkodnia kell) az org.eclipse.ui.IActionFilter felületet.



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



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; XYZ eszköz futtatása"

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.