Nabídky

org.eclipse.ui.menus

3.2

Tento bod rozšíření vývojářům modulů plug-in umožňuje definovat nabídky, oddělovače, logické skupiny a položky nabídek - k zobrazení na libovolných místech aplikace - od stavových řádků až po kontextové nápovědy. Rovněž umožňuje definování skupin takovýchto příspěvků (například akční sady); tyto akční sady mohou zapínat a vypínat koncoví uživatelé. Stručně řečeno, bod rozšíření nabídek obsahuje s výjimkou ikon veškeré grafické prvky pro účely přispívání do libovolných nabídek či vyhrazených oblastí na platformě Eclipse.

Každý prvek v tomto bodu rozšíření obdrží jedinečný identifikátor. Důvodem je, že na tyto prvky mohou odkazovat kamkoli bez nutnosti opětovného zjišťování stavu prvku. Identifikátor může být zapotřebí například pro vyžádání či definování určité akční sady. Tímto způsobem je pro nezávislé dodavatele modulů plug-in zajištěna možnost umísťování takovýchto prvků podle potřeb do nových umístění v rámci rozhraní.

POZNÁMKA: Ve verzi 3.2 je jedinou implementovanou částí tohoto mechanizmu rozšíření část spojená s příspěvky 'obruby'. Pokus o přidání položek, nabídek, panelů nástrojů nebo položek stavového řádku bude fungovat jako NO-OP.

<!ELEMENT extension (item* , menu* , group* , widget*)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT item (parameter* , location* , visibleWhen?)>

<!ATTLIST item

id        CDATA #REQUIRED

commandId CDATA #REQUIRED

menuId    CDATA #IMPLIED>

Určitá položka může být v závislosti na svém umístění položkou nabídky nebo položkou ohraničené oblasti. Text a obraz přidružený k položce se bude vykreslovat na základě příkazu.



<!ELEMENT menu (location* , visibleWhen?)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #IMPLIED>

Nabídka může být připojena k nástrojové položce nebo může být vložena na libovolné místo nabídky pohledu, kontextové nabídky nebo pruhu nabídky nejvyšší úrovně. Vývojář modulu plug-in může bez námahy předpokládat, že pro každý pohled existuje nabídka a panel nástrojů a dále že existuje pruh nabídky nejvyšší úrovně. Kontextové nabídky musejí být v programu před vlastním použitím registrovány (viz Informace rozhraní API).

Nabídka může obsahovat pouze skupiny.



<!ELEMENT group (location*)>

<!ATTLIST group

id                CDATA #REQUIRED

separatorsVisible (true | false) "true">

Logická skupina. Může být viditelná (např. se podle potřeby před a za určitým prvkem zobrazují oddělovače) nebo neviditelná. Při výchozím nastavení jsou logické skupiny viditelné.

Skupina může obsahovat nabídky, položky a jiné skupiny.



<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>

<!ATTLIST widget

id    CDATA #REQUIRED

class CDATA #REQUIRED>

Nabídka nebo prvek obruby, kterým je poskytnut přímý přístup k prvkům widget. Toto lze použít například k vykreslení pole se seznamem. To však bohužel rovněž znamená, že při zobrazení prvku widget v uživatelském rozhraní dojde k načtení modulu plug-in. Tento prvek používejte obezřetně, a vyhněte se tak případným problémům s výkonem. Rovněž může dojít k potížím s podporou makropříkazů, skriptování a většinou příkazových mechanizmů. Při použití jako obruby prvek widget způsobí na čtení modulu plug-in, pokud bude zviditelněn v uživatelském rozhraní.



<!ELEMENT layout EMPTY>

<!ATTLIST layout

fillMajor (true | false)

fillMinor (true | false) >

Tento prvek lze použít k určení různých voleb rozvržení pro prvky přidané do umístění trim (obruba).



<!ELEMENT location (order? , (bar | part | popup))>

<!ATTLIST location

mnemonic   CDATA #IMPLIED

imageStyle CDATA #IMPLIED>

Umístění, ve kterém se může vyskytovat prvek menu, group, item nebo widget. Tento prvek se používá k řízení informací specifických pro umístění.



<!ELEMENT bar EMPTY>

<!ATTLIST bar

type (menu|trim)

path CDATA #IMPLIED>

Konečný prvek v určitém umístění. Může jít o pruh nabídky nebo o ohraničenou oblast. Není-li kvalifikován, indikuje pruh nabídky či ohraničenou oblast nejvyšší úrovně. Je-li kvalifikován pomocí prvku part, indikuje nabídku či ohraničenou oblast této části.



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

Prvek class, který podporuje syntaktickou analýzu rozšíření executable pro prvky widget a dynamic.



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

<!ATTLIST visibleWhen

checkEnabled (true | false) "false">

Řídí viditelnost daného prvku.



<!ELEMENT part (popup | bar)>

<!ATTLIST part

id    CDATA #IMPLIED

class CDATA #IMPLIED>

Určitý prvek v určitém umístění. Kvalifikuje umístění jako odkaz na určitou část pracovní plochy. Může jít o pohled nebo o editor. Kvalifikace může použít buď název třídy dané části (včetně dědičnosti), nebo může odkazovat na identifikátor určitého pohledu nebo editoru.

Použít lze pouze některou z hodnot id a class.



<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Parametr rozhraní executable nebo příkazu - podle toho, na kterém místě v rozšíření se vyskytuje.



<!ELEMENT order EMPTY>

<!ATTLIST order

position   (start|end|before|after)

relativeTo CDATA #IMPLIED>

Určuje polohu nabídky, skupiny, položky nebo prvku widget v rámci určitého umístění.



<!ELEMENT popup EMPTY>

<!ATTLIST popup

id   CDATA #IMPLIED

path CDATA #IMPLIED>

Část umístění. Indikuje, že se nabídka, skupina, položka či prvek widget zobrazuje v místní nabídce.



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

Generický kořenový prvek. Tento prvek je možné použít uvnitř bodu rozšíření pro definování jeho výrazu typu enablement. Podřízené prvky výrazu enablement se kombinují pomocí operátoru and.



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

Tento prvek představuje operaci NOT nad výsledkem vyhodnocení výrazů svých dílčích prvků.



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

Tento prvek představuje operaci AND nad výsledkem vyhodnocení výrazů všech svých dílčích prvků.



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

Tento prvek představuje operaci OR nad výsledkem vyhodnocení výrazů všech svých dílčích prvků.



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

Tento prvek se používá k provádění kontroly typu instanceof nad objektem, na němž je fokus. Tento výraz vrací EvaluationResult.TRUE, pokud je typ daného objektu podtypem typu určeného hodnotou atributu. Jinak je vráceno EvaluationResult.FALSE.



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

Tento prvek se používá k vyhodnocení stavu vlastnosti objektu, na němž je fokus. Množinu testovatelných vlastností je možné rozšířit pomocí bodu rozšíření testeru vlastností. Pokud tester vlastností, který provádí skutečné testování, dosud není načten, vrací testovací výraz EvaluationResult.NOT_LOADED.



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

Testuje vlastnost systému voláním metody System.getProperty a porovnává výsledek s hodnotou stanovenou pomocí atributu value.



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

Tento prvek se používá k provádění kontroly typu equals nad objektem, na němž je fokus. Pokud se objekt rovná hodnotě dodané atributem value, vrací tento výraz EvaluationResult.TRUE. Jinak je vráceno EvaluationResult.FALSE.



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

Tento prvek se používá k testování počtu prvků v kolekci.



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

<!ATTLIST with

variable CDATA #REQUIRED>

Tento prvek mění pro všechny své podřízené prvky objekt, který má být kontrolován, na objekt uvedený v atributu variable. Pokud tuto proměnnou nelze vyřešit, způsobí výraz při jejím vyhodnocování ExpressionException. Podřízené prvky výrazu with se kombinují pomocí operátoru and.



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

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED>

Tento prvek mění pro všechny své podřízené prvky objekt, který má být kontrolován, na objekt uvedený v atributu variable. Pokud tuto proměnnou nelze vyřešit, způsobí výraz při jejím vyhodnocování ExpressionException. Podřízené prvky výrazu with se kombinují pomocí operátoru and.



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

<!ATTLIST adapt

type CDATA #REQUIRED>

Tento prvek se používá k úpravě objektu, na němž je fokus, na typ určený atributem type. Pokud adaptér nebo typ, na který se odkazuje, ještě není načten, vrací tento výraz "not loaded". Pokud daný název typu vůbec neexistuje, způsobí při vyhodnocování výjimku ExpressionException. Podřízené prvky výrazu adapt se kombinují pomocí operátoru and.



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

<!ATTLIST iterate

operator (or|and) >

Tento prvek se používá k opakování nad proměnnou typu java.util.Collection. Pokud objekt, na němž je fokus, není typu java.util.Collection, způsobí při vyhodnocování výrazu výjimku ExpressionException.



Následuje ukázka definice základní nabídky.

<menu id=

"com.mycompany.myplugin.projection"

label=

"%Folding.label"

>

<location mnemonic=

"%Folding.label.mnemonic"

>

<part id=

"AntEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

V tomto příkladu vývojář modulu plug-in přispívá do všech částí, které rozšiřují nebo implementují daný typ. To umožňuje například přidávání určitých příspěvků do všech textových editorů.

<menu id=

"com.mycompany.myplugin.textEditorMenu"

label=

"Text Commands"

>

<location mnemonic=

"X"

>

<part class=

"AbstractTextEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

Máte možnost vzájemně přidružovat nabídky.

<menu id=

"com.mycompany.myplugin.RunWithConfigurationAction"

label=

"Run With Configuration"

helpContextId=

"run_with_configuration_context"

>

<location>

<bar />

</location>

</menu>

V rámci nabídky lze definovat logické skupiny. Tyto logické skupiny mohou být viditelné (např. se podle potřeby před a za určitým prvkem zobrazují oddělovače) nebo neviditelná. Při výchozím nastavení jsou logické skupiny viditelné.

<group id=

"com.mycompany.myplugin.stepGroup"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

<group id=

"com.mycompany.myplugin.stepIntoGroup"

separatorsVisible=

"false"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

Nabídky, skupiny, položky a prvky widget lze vkládat do více umístění.

<item id=

"com.mycompany.myplugin.ToggleStepFilters"

commandId=

"com.mycompany.myplugin.ToggleStepFilters"

>

<location mnemonic=

"%mnemonic"

>

<bar path=

"org.eclipse.ui.run/emptyStepGroup"

/>

</location>

<location>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<bar type=

"trim"

path=

"renderGroup"

/>

</part>

</location>

<location mnemonic=

"%mnemonic"

>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<popup path=

"renderGroup"

/>

</part>

</location>

</item>

Je-li rozevírací prvek zadán bez ID a bez prvku nadřízené části, bude použit pro veškeré kontextové nabídky registrované v pracovní ploše. Toto chování je obdobou chování známých objektových příspěvků. Obdobně rozevírací prvek nejvyšší nabídky s určeným ID ovlivní veškeré kontextové nabídky registrované s daným názvem.

<item id=

"com.mycompany.myplugin.ObjectContribution"

commandId=

"com.mycompany.myplugin.ObjectContribution"

>

<location>

<popup path=

"additions"

/>

</location>

</item>

V určitých případech může být užitečné řízení viditelnosti jednotlivých položek. Zatímco v běžném případě upřednostňujeme zachování stability v rozvržení nabídek a panelů nástrojů, v určitých situacích je zapotřebí skrýt položky, jež v daném momentu nejsou relevantní. Toto platí zejména pro kontextové nabídky, jejichž prostor je omezený. V takovém případě můžete definovat prvek visibleWhen. Tento prvek je téměř identickou obdobou prvků activeWhen a enabledWhen, které jsou definovány v bodu rozšíření popisovačů.

<item id=

"com.mycompany.myplugin.ConvertToWatchExpression"

commandId=

"com.mycompany.myplugin.ConvertToWatchExpression"

>

<location mnemonic=

"%mnemonic"

>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<popup path=

"additions"

/>

</part>

</location>

<visibleWhen>

<with variable=

"selection"

>

<iterate operator=

"and"

>

<not>

<instanceof value=

"IWatchExpression"

/>

</not>

<instanceof value=

"IExpression"

/>

</iterate>

</with>

</visibleWhen>

</item>

Nejobvyklejším případem je zviditelnění určitého prvku při zpřístupnění jeho popisovače. Příslušná obsluha je zajištěna určitou syntaktickou konstrukcí. V prvku visibleWhen existuje atribut checkEnabled.

<item id=

"com.mycompany.myplugin.compareWithPatch"

commandId=

"com.mycompany.myplugin.compareWithPatch"

>

<location mnemonic=

"%mnemonic"

>

<part id=

"MyPart"

>

<popup path=

"additions"

/>

</part>

</location>

<visibleWhen checkEnabled=

"true"

/>

</item>

Jednotlivé položky přidružené k příkazu mohou obsahovat hodnoty parametrů. Pokud parametr poskytnutého identifikátoru není definován, jde o chybu. Pokud položka neobsahuje žádný příkaz, jde rovněž o chybu.

<item id=

"com.mycompany.myplugin.RunHistory"

commandId=

"com.mycompany.myplugin.RunHistory"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

<parameter name=

"index"

value=

"1"

/>

</item>

Rovněž lze zadávat relativní řazení. To se provádí s použitím atributu order v prvku location. Atribut order akceptuje tyto hodnoty: start (vkládá prvek na začátek kontejneru), end (vkládá prvek na konec příslušného kontejneru), after (vkládá prvek za sourozenecký prvek, jehož ID je uvedeno v atributu ref) a before (vkládá prvek před sourozenecký prvek, jehož ID je uvedeno v atributu ref). Relativní řazení lze použít pro libovolný typ prvku nabídky.

<item id=

"com.mycompany.myplugin.MyFirstItem"

commandId=

"com.mycompany.myplugin.MyFirstCommand"

>

<location>

<order position=

"start"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

<item id=

"com.mycompany.myplugin.MySecondItem"

commandId=

"com.mycompany.myplugin.MySecondCommand"

>

<location>

<order position=

"after"

relativeTo=

"com.mycompany.myplugin.MyFirstItem"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

Požadujete-li přímý přístup k prvkům widget (např. kvůli vykreslení pole se seznamem), můžete použít prvek widget. To však bohužel rovněž znamená, že při zobrazení prvku widget v uživatelském rozhraní dojde k načtení modulu plug-in.

<widget id=

"com.mycompany.myplugin.MyComboBoxSimple"

class=

"com.mycompany.myplugin.MyComboBox"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mycompany.myplugin.MyComboBoxParameterized1"

class=

"com.mycompany.myplugin.MyComboBox:a,b,c"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mycompany.myplugin.MyComboBoxParameterized2"

>

<class class=

"com.mycompany.myplugin.MyComboBox"

>

<parameter name=

"list"

value=

"a,b,c"

/>

<parameter name=

"selected"

value=

"c"

/>

<parameter name=

"editable"

value=

"false"

/>

</class>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

Prvky widget rovněž můžete použít jako příspěvek do ohraničené oblasti pracovní plochy. Následující příklad definuje nový prvek widget 'HeapStatus', který má být při výchozím nastavení umístěn bezprostředně za ohraničenou oblast stavového řádku (např. ve spodní části okna pracovní plochy). Další informace o předdefinovaných skupinách získáte v popisu prvku 'bar'.

Povšimněte si, že ohraničenou oblast 'groups' lze přesunout do jiných ohraničených oblastí. Informace o umístění relativeTo bude při určování nového umístění ohraničené oblasti předpokládat, že odkazovaná skupina je ve své výchozí poloze. Obecně se očekává, že přispěvatelé tohoto typu vytvoří vlastní skupinu, do které bude vložen nový prvek widget, což umožní přemísťování prvku obruby (trim) nezávisle na ostatních prvcích obruby. Důležitou výjimkou z tohoto popisu je skupina 'status'.

   

<extension point=

"org.eclipse.ui.menus"

>

<group id=

"TestTrimAPI.heapStatusGroup"

separatorsVisible=

"true"

>

<location>

<bar type=

"trim"

/>

<order position=

"after"

relativeTo=

"status"

/>

</location>

</group>

<widget class=

"HeapStatusWidget"

id=

"TestTrimAPI.HeapStatus"

>

<location>

<bar path=

"heapStatusGroup"

type=

"trim"

/>

</location>

<layout fillMajor=

"false"

fillMinor=

"true"

/>

</widget>

</extension>

Pro registraci kontextové nabídky používejte metodu IWorkbenchPartSite.registerContextMenu.