Rozevírací nabídky

org.eclipse.ui.popupMenus

Tento bod rozšíření se používá k přidávání nových akcí do kontextových nabídek vlastněných jinými moduly plug-in. Příspěvky akce mohou být poskytnuty proti určitému typu objektu (objectContribution) nebo proti určité kontextové nabídce části pohledu nebo editoru (viewerContribution). Při použití objectContribution se příspěvek zobrazí ve všech kontextových nabídkách části pohledu nebo editoru, kde jsou vybrány objekty určeného typu. Naopak při použití viewerContribution se příspěvek zobrazí pouze v určené kontextové nabídce části pohledu nebo editoru, bez ohledu na výběr.

Pokud je výběr různorodý, příspěvek bude použit, pokud je registrován proti běžnému typu výběru, jestliže je to možné. Pokud není možné přímé srovnání, bude proveden pokus o srovnání se supertřídami a superrozhraními.

Výběr lze dále omezit použitím filtru názvů. Pokud je filtr použit, všechny objekty ve výběru musí filtru vyhovovat, aby bylo možno příspěvek použít.

Jednotlivé akce v příspěvku objektu mohou použít atribut enablesFor k určení, zda se má použít pouze u jednoduchého, vícenásobného nebo jiného typu výběru.

Pokud jsou tyto filtrovací mechanizmy nevyhovující, příspěvek akce může použít mechanizmus filter. V tomto případě jsou atributy cílového objektu popsány v posloupnosti párů název-hodnota. Atributy, které se aplikují na výběr, odpovídají typu a jsou mimo rozsah samotné domény pracovní plochy (Workbench), proto bude pracovní plocha delegovat filtrování na této úrovni do aktuálního výběru.

Zpřístupnění nebo viditelnost zvolené akce lze nastavit pomocí příslušného prvku enablement nebo visibility. Tyto dva prvky obsahují logický výraz, který je vyhodnocen pro stanovení zpřístupnění (enablement) anebo viditelnosti (visibility).

Syntaxe je stejná jak pro prvek enablement, tak i pro prvek visibility. Oba obsahují pouze jeden dílčí prvek logického výrazu. V nejjednodušším případě to bude prvek objectClass, objectState, pluginState nebo systemProperty. V komplexnějších případech mohou být kombinovány prvky and, or a not pro vytvoření logického výrazu. Prvky and a or musí obsahovat 2 dílčí prvky. Prvek not musí obsahovat pouze 1 dílčí prvek.

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

Tento prvek se používá k definování skupiny akcí nebo nabídek pro kterékoli kontextové nabídky prohlížeče, pro které jsou objekty určeného typu vybrány.



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

<!ATTLIST viewerContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Tento prvek se používá k definování skupiny akcí nebo nabídek pro konkrétní kontextovou nabídku části pohledu nebo editoru.



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

Tento prvek definuje akci, kterou může uživatel vyvolat v uživatelském rozhraní.



<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Tento prvek se používá pro vyhodnocení stavu atributu každého objektu v aktuálním výběru. Stav odpovídá pouze tehdy, pokud má každý objekt ve výběru určený stav atributu. Každý objekt ve výběru musí implementovat nebo se přizpůsobit rozhraní org.eclipse.ui.IActionFilter.



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

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Tento prvek se používá pro definování nové nabídky.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name CDATA #REQUIRED>

Tento prvek se používá pro vytváření oddělovače nabídky v nové nabídce.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name CDATA #REQUIRED>

Tento prvek se používá pro vytváření pojmenované skupiny v nové nabídce. Na rozdíl od prvku separator nemá žádné vizuální znázornění v nové nabídce.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

Tento prvek se používá pro usnadnění zjištění, zda je akce zpřístupněna na základě aktuálního výběru. Prvek je ignorován, pokud je zadán prvek enablement.



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

Tento prvek se používá k definování zpřístupnění pro rozšíření.



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

Tento prvek se používá k definování viditelnosti pro rozšíření.



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

Tento prvek představuje logickou operaci AND na výsledku vyhodnocení dvou výrazů jeho dílčích prvků.



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

Tento prvek představuje logickou operaci OR na výsledku vyhodnocení dvou výrazů jeho dílčích prvků.



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

Tento prvek představuje logickou operaci NOT na výsledku vyhodnocení výrazů jeho dílčích prvků.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name CDATA #REQUIRED>

Tento prvek se používá pro vyhodnocení třídy nebo rozhraní každého objektu v aktuálním výběru. Pokud každý objekt ve výběru implementuje zadanou třídu nebo rozhraní, je výraz vyhodnocen jako true.



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Tento prvek se používá pro vyhodnocení stavu atributu každého objektu v aktuálním výběru. Pokud má každý objekt ve výběru zadaný stav atributu, je výraz vyhodnocen jako pravdivý (true). Aby bylo možné vyhodnotit tento typ výrazu, musí se každý objekt ve výběru implementovat nebo přizpůsobit rozhraní org.eclipse.ui.IActionFilter.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Tento prvek se používá pro vyhodnocení stavu modulu plug-in. Stav modulu plug-in může být jeden z následujících: instalován (ekvivalentní stavu "vyřešený" v rámci konceptu OSGi) nebo aktivován (ekvivalentní stavu "aktivní" v rámci konceptu OSGi).



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Tento prvek se používá pro vyhodnocení stavu některé vlastnosti systému. Hodnota vlastnosti je získána z java.lang.System.



Následuje příklad bodu rozšíření rozevírací nabídky:

   

<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;Show XYZ"

style=

"toggle"

state=

"true"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

/>

</viewerContribution>

</extension>

Ve výše uvedeném příkladě bude určená akce příspěvku objektu povolena pouze pro jeden výběr (atribut enablesFor). Kromě toho musí každý objekt ve výběru implementovat určené rozhraní (IFile) a musí být soubor Java. Tato akce bude přidána do předtím vytvořené podnabídky. Tento příspěvek bude účinný ve kterémkoli pohledu, který má požadovaný výběr.

Naproti tomu výše uvedený příspěvek prohlížeče se zobrazí pouze v kontextové nabídce pohledu úlohy a nebude ovlivněn výběrem v pohledu.

Následuje příklad filtrovacího mechanizmu. V tomto případě se akce zobrazí pouze pro IMarkers, které jsou dokončeny a mají vysokou prioritu.

   

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

"High Priority Completed Action Tool"

icon=

"icons/runXYZ.gif"

class=

"com.xyz.actions.MarkerActionDelegate"

>

</action>

</objectContribution>

</extension>

Následuje jiný příklad použití prvku visibility:

   

<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;Show XYZ"

style=

"push"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

>

</action>

</viewerContribution>

</extension>

Ve výše uvedeném příkladu se uvedená akce zobrazí jako položka nabídky v kontextové nabídce pohledu úlohy, avšak pouze pokud je aktivní modul plug-in "com.xyz" a uvedená vlastnost systému je nastavena na hodnotu true.

Hodnota atributu akce class musí být úplný název třídy Java, která implementuje org.eclipse.ui.IObjectActionDelegate v případě příspěvků objektů, org.eclipse.ui.IViewActionDelegate pro příspěvky do kontextových nabídek, které náležejí pohledům, nebo org.eclipse.ui.IEditorActionDelegate pro příspěvky do kontextových nabídek, které náležejí editorům. Ve všech případech je implementující třída načtena co možná nejpozději, aby se zabránilo načtení celého modulu plug-in, dokud není skutečně potřebný.

Poznámka: Za účelem zpětné kompatibility lze implementovat org.eclipse.ui.IActionDelegate pro příspěvky objektů.

Rozšíření kontextové nabídky v rámci části je možné pouze, pokud cílová část publikuje nabídku pro rozšíření. Tento postup se důrazně doporučuje, protože zlepšuje rozšiřitelnost produktu. Aby mohl být tento postup proveden, musí každá část publikovat všechny kontextové nabídky definované voláním IWorkbenchPartSite.registerContextMenu. Jakmile je tento postup proveden, pracovní plocha automaticky vloží všechna rozšíření akcí, která existují.

Pro každou registrovanou nabídku musí být poskytnuto id. Pro zachování konzistence mezi částmi musí všechny implementátory částí přijmout následující strategii.

Jakákoli kontextová nabídka, která je registrována v pracovní ploše, by měla také obsahovat standardní bod vložení s id IWorkbenchActionConstants.MB_ADDITIONS. Jiné moduly plug-in tuto hodnotu použijí jako referenční bod pro vložení. Bod vložení může být definován přidáním GroupMarker do nabídky v odpovídajícím umístění pro vložení.

Objekt v pracovní ploše, který je výběrem v kontextové nabídce, může definovat org.eclipse.ui.IActionFilter. Jedná se o strategii filtrování, která může provádět filtrování podle typu. Pracovní plocha načte filtr pro výběr otestováním, zda implementuje IActionFilter. Pokud dojde k selhání, pracovní plocha požádá o filtr pomocí mechanizmu IAdaptable.

Štítky akcí a nabídek mohou obsahovat speciální znaky, které kódují mnemotechnické informace, specifikované pomocí znaku ampersand ('&') před vybraným znakem v přeloženém textu. Jelikož znak ampersand není v řetězcích XML povolen, použijte znakovou entitu &amp;.

Pokud jedno rozšíření přispívá do nabídky dvěma nebo více akcemi, budou tyto akce zobrazeny v opačném pořadí, než v jakém jsou uvedeny v souboru plugin.xml. Toto chování je takto navrženo. Nicméně bylo objeveno až po zafixování rozhraní API platformy Eclipse. Změna tohoto chování by tuto chvíli narušila všechny moduly plug-in, které jsou závislé na současném chování.

Prvky selection a enablement se navzájem vylučují. Prvek enablement může nahradit prvek selection pomocí dílčích prvků objectClass a objectState. Například následující:

 

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

>

</selection>

lze vyjádřit pomocí:
 

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<objectState name=

"extension"

value=

"java"

/>

</and>

</enablement>

Pohledy pracovní plochy mají vestavěné kontextové nabídky, které již mají načteny řadu akcí. Moduly plug-in mohou do těchto nabídek přispívat. Pokud má prohlížeč pro tyto příspěvky rezervované sloty a tyto sloty jsou veřejné, názvy slotů lze použít jako cesty. V opačném případě budou na konec rozevírací nabídky přidány akce a podnabídky.