Cesty nabídek a panelu nástrojů

Viděli jsme mnoho příspěvků akcí, určujících cestu pro umístění jejich akcí. Podívejme se podrobněji, co tyto cesty znamenají.  

Cesty nabídek

Na cesty nabídek se podívejme nejprve pohledem na nabídku Nápověda pracovní plochy.

Pojmenované skupiny v pracovní ploše

Umístění pro vložení nových nabídek a položek nabídek jsou definována pomocí pojmenovaných skupin. Pojmenovanou skupinu si můžete představit jako pozici nebo zástupný symbol, který vám umožňuje vložit položky nabídky do určitých bodů v panelu nabídek, nebo v rozbalovací nabídce.

Pracovní plocha definuje všechny své názvy pozic skupiny ve třídách IWorkbenchActionConstants a IIDEActionConstants. (Jsou použity dvě různé třídy, protože položky nabídky související se zdroji jsou stanoveny z obecné pracovní plochy). Pro každou nabídku pracovní plochy jsou pojmenované skupiny umístěny v nabídce v místě, kam je očekáváno, že moduly plug-in vloží nové akce.

Následující popis nabídky nápovědy je přizpůsoben z definice třídy IWorkbenchActionConstants.

   Standardní akce nabídky Nápověda
   Spustit skupinu - HELP_START - "start"
   Ukončit skupinu - HELP_END - "end"

Standardní nabídka nápovědy pracovní plochy definuje pojmenovanou skupinu nazvanou "start," následovanou pojmenovanou skupinou nazvanou "end,". Definování dvou skupin dává modulům plug-in poněkud víc kontroly nad tím, kam jejich vložené položky budou umístěny v nabídce nápovědy.  Když definujete nabídku, můžete definovat libovolný počet pozic. Přidání více pozic poskytuje ostatním modulům plug-in více kontroly nad tím, kde se jejich příspěvky objeví relativně k existujícím příspěvkům.

Moduly plug-in, které přidávají položku nabídky do nabídky nápovědy mohou použít tyto názvy skupin k rozhodnutí, kam půjdou jejich položky nabídky. Například modul plug-in cheatsheet přidává akční sadu obsahující nabídku "Cheat Sheets..." do pracovní plochy.  Zde je markup org.eclipse.ui.cheatsheets plugin.xml modulu plug-in.

   <extension
	point="org.eclipse.ui.actionSets">
	<actionSet
		label="%CHEAT_SHEETS"
		visible="true"
		id="org.eclipse.ui.cheatsheets.actionSet">
		<action
			label="%CHEAT_SHEETS_MENU"
			class="org.eclipse.ui.internal.cheatsheets.actions.CheatSheetHelpMenuAction"
			menubarPath="help/helpStart"
			id="org.eclipse.ui.cheatsheets.actions.CheatSheetHelpMenuAction">
		</action>
	</actionSet>
</extension>

Do nabídky nápovědy bude umístěna nová akce nápovědy, dovnitř skupiny helpStart.

Plně kvalifikované cesty nabídky

Úplná cesta nabídky je jednoduše "menu name/group name."  Většina názvů nabídky pro pracovní plochu je definována v IWorkbenchActionConstants. (Názvy nabídky související se zdroji jsou definovány v IIDEActionConstants.) Když hledáme název nabídky nápovědy v této třídě, zjistíme, že plně kvalifikovaný název cesty pro naše akce nápovědy je "help/helpEnd."

Některé nabídky mají vnořené podnabídky. Je tomu tak v případech, kdy do hry vstupují delší cesty. Pokud by nabídka nápovědy měla definovanou podnabídku nazvanou "submenu" s pojmenovanou skupinou nazvanou "submenuStart," pak by plně kvalifikovaná cesta nabídky pro akci v nové podnabídce byla "help/submenu/submenuStart."

Externalizace štítků uživatelského rozhraní

Výše uvedený příklad ukazuje techniku pro externalizaci řetězců objevujících se v UI.  Externalizované řetězce jsou použity ke zjednodušení převodu modulů plug-in uživatelského rozhraní do jiných jazyků.f  Řetězce můžeme externalizovat v našich souborech plugin.xm , nahrazením řetězce klíčem (%CHEAT_SHEETS_MENU) a vytvořením vstupů v souboru plugin.properties formuláře.

	CHEAT_SHEETS_MENU = Cheat Sheets...

Soubor plugin.properties může být převeden do různých jazyků a plugin.xml nebude muset být změněn.

Přidání nových nabídek a skupin

V mnoha příkladech, které jsme až dosud viděli, byly akce vložené vzorovými moduly plug-in přidány do existujících pojmenovaných skupin dovnitř nabídek.

Body rozšíření actionSets, viewActions, editorActions, a popupMenus vám také umožňují definovat nové nabídky a skupiny ve vašem příspěvku. To znamená, že můžete definovat nové podnabídky nebo nové rozbalovací nabídky a vložit do těchto nových nabídek své akce. V takovém případě bude cesta pro vaši novou akci obsahovat název vaší nově definované nabídky.

Tuto techniku jsme viděli, když nástroj pro soubory Readme definoval novou nabídku pro svou akci.  Podívejme se nyní na markup, kterým jsme se zabývali v cestách nabídky, ještě jednou podrobněji.

   <extension point = "org.eclipse.ui.actionSets">
   <actionSet id="org_eclipse_ui_examples_readmetool_actionSet"
	   label="%ActionSet.name"
	   visible="true">
	   <menu id="org_eclipse_ui_examples_readmetool"
		   label="%ActionSet.menu"
		   path="window/additions"> 
		   <separator name="slot1"/>
		   <separator name="slot2"/>
		   <separator name="slot3"/>
	   </menu>
	   <action id="org_eclipse_ui_examples_readmetool_readmeAction"
		   menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
		   toolbarPath="readme"
		   label="%ReadmeAction.label"
		   tooltip="%ReadmeAction.tooltip"
		   helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context"
		   icon="icons/ctool16/openbrwsr.png"
		   class="org.eclipse.ui.examples.readmetool.WindowActionDelegate"
		   enablesFor="1">
		   <selection class="org.eclipse.core.resources.IFile"
				name="*.readme">
		   </selection>
	   </action>
	   ...

Přidali jsme novou nabídku nazvanou  "org_eclipse_ui_examples_readmetool" jejíž popis je definován klíčem "%ActionSet.name" v souboru vlastností. Ve stejné nabídce definujeme tři pojmenované skupiny   "slot1," "slot2," a "slot3."  Přidáme tuto novou nabídku do cesty "window/additions."

Jestliže jdeme zpět to IWorkbenchActionConstants, uvidíme tuto definici v nabídce okna v javadoc:

    * <h3>Akce nabídky standardního okna</h3>
    * <ul>
    * <li>Skupina akcí podobná nadbytečným oknům (Extra Window)(<code>WINDOW_EXT</code>)</li>

Podíváme-li se dále na definici třídy, uvidíme tyto související definice:

   public static final String MENU_PREFIX = "";
   ...
   public static final String M_WINDOW = MENU_PREFIX+"window";
   ...
   public static final String MB_ADDITIONS = "additions";  // Skupina.
   ...
   public static final String WINDOW_EXT = MB_ADDITIONS;   // Skupina.

Z této informace můžeme složit dohromady cestu pro přidání něčeho do pracovní plochy "Window" menu.  Nabídka samotná se nazývá "window" a definuje jednu pozici nazvanou "additions."  Použijeme cestu "window/additions" pro přidání nové položky.

V deklaraci akční sady přidáme akci do naší nově definované nabídky, pomocí cesty "window/org_eclipse_ui_examples_readmetool/slot1."

Další moduly plug-in by mohly přidávat do naší nabídky pomocí stejné cesty (nebo možná jedné z jiných pozic) pro přidání jedné ze svých vlastních nabídek.  

V příkladu s nástrojem pro soubory Readme používáme atribut separator k identifikaci názvů skupin.  To způsobí, že se oddělovač řádků objeví mezi těmito skupinami, když obsahují položky.  Mohli bychom místo toho použít atribut groupMarker, jestliže chceme definovat pojmenovanou skupinu bez zobrazení jakéhokoliv oddělovače v nabídce, pro rozlišení mezi skupinami.

Cesty panelu nástrojů

Cesty panelu nástrojů fungují podobně jako cesty nabídek.  

Pojmenované panely nástrojů v pracovní ploše

Panel nástrojů pracovní plochy se skládá z panelů nástrojů vložených různými moduly plug-in, včetně pracovní plochy samotné.  V každém konkrétním panelu nástrojů jsou pojmenované skupiny nebo pozice, které mohou být použity pro vložení nových položek panelu nástrojů.    

Následující popis panelů nástrojů pracovní plochy je přizpůsoben z definice třídy IWorkbenchActionConstants.

// ID panelu nástrojů pracovní plochy
public static final String TOOLBAR_FILE = "org.eclipse.ui.workbench.file"
public static final String TOOLBAR_NAVIGATE = "org.eclipse.ui.workbench.navigate"; 

// ID skupiny panelu nástrojů pracovní plochy. Chcete-li přidat položku na začátek skupiny,
// použijte GROUP id. Chcete-li přidat položku na konec skupiny, použijte EXT id.
public static final String PIN_GROUP = "pin.group"; 
public static final String HISTORY_GROUP = "history.group"; 
public static final String NEW_GROUP = "new.group"; 
public static final String SAVE_GROUP = "save.group"; 
public static final String BUILD_GROUP = "build.group"; 

V nejjednodušším případě může modul plug-in přispět položkou panelu nástrojů ve svém vlastním panelu nástrojů.  Například, akcím nástrojů pro soubory Readme, přispěným do nabídky, je také poskytnuta cesta panelu nástrojů:

<action id="org_eclipse_ui_examples_readmetool_readmeAction"  
   menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
   toolbarPath="readme"
...

Protože neexistuje žádný odkaz na cesty nebo skupiny panelu nástrojů pracovní plochy, akce readme se objeví ve své vlastní skupině na panelu nástrojů.  Určení následující cesty by místo toho umístilo položku do panelu nástrojů souboru ve skupině uložení:

...
<action id="org_eclipse_ui_examples_readmetool_readmeAction"  
   menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
   toolbarPath="org.eclipse.ui.workbench.file/save.group"
...

Na cesty definované v IWorkbenchActionConstants může být odkazováno v cestách panelu nástrojů jiných modulů plug-in.

Přidání do akčních sad jiných modulů plug-in

Předpokládejme, že modul plug-in chce své položky panelu nástrojů lépe integrovat s akcemi z jiných modulů plug-in   Podívejme se, jak modul plug-in externích nástrojů (org.eclipse.ui.externaltools) integruje své akce s panelem nástrojů ladicího programu.  Ladicí program (org.eclipse.debug.ui) definuje své akce panelu nástrojů následovně:

   <extension
      point="org.eclipse.ui.actionSets">
   <actionSet
         label="%LaunchActionSet.label"
         visible="false"
         id="org.eclipse.debug.ui.launchActionSet">
   ...
   <action
         toolbarPath="debug"
         id="org.eclipse.debug.internal.ui.actions.RunDropDownAction"
         hoverIcon="icons/full/ctool16/run_exc.png"
         class="org.eclipse.debug.internal.ui.actions.RunToolbarAction"
         disabledIcon="icons/full/dtool16/run_exc.png"
         icon="icons/full/etool16/run_exc.png"
         helpContextId="run_action_context"
         label="%RunDropDownAction.label"
         pulldown="true">
   </action>
   ...

Stejně jako nástroj pro soubory Readme, modul plug-in ladicího programu definuje svou vlastní cestu panelu nástrojů, což znamená, že jeho položky panelu nástrojů budou uvnitř svého vlastního panelu nástrojů na pracovní ploše.  Co modul plug-in externích nástrojů dělá?

<extension point="org.eclipse.ui.actionSets">
	<actionSet
		id="org.eclipse.ui.externaltools.ExternalToolsSet"
		label="%ActionSet.externalTools"
		visible="true">
		...
		<action
			id="org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar"
			definitionId= "org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar"
			label="%Action.externalTools"
			toolbarPath="org.eclipse.debug.ui.launchActionSet/debug"
			disabledIcon="icons/full/dtool16/external_tools.png"
			icon="icons/full/etool16/external_tools.png"
			hoverIcon="icons/full/ctool16/external_tools.png"
			tooltip="%Action.externalToolsTip"
			pulldown="true"
			class="org.eclipse.ui.externaltools.internal.menu.ExternalToolMenuDelegate">
		</action>
	</actionSet>
</extension>

Všimněte si použití ID akční sady ladicího programu v cestě panelu nástrojů.  Použití ID akční sady v cestě znamená, že položka panelu nástrojů by měla být umístěna do panelu nástrojů použitého odkazovanou akční sadou.  Uvnitř skupiny panelu nástrojů jsou položky seřazeny pomocí ID akční sady, takže pro náš příklad se akce externích nástrojů objeví za akcemi ladicích programů. 

Když přidáváme do panelu nástrojů akční sady, mohou být také definovány nové skupiny.  Pokud moduly plug-in externích nástrojů definovaly své toolbarpath jako "org.eclipse.debug.ui.launchActionSet/external", byla by vytvořena nová skupina pro akci na panelu nástrojů.  Tak jako u nabídek jsou skupiny panelu nástrojů naznačeny separátory. 

Použití cest z jiných modulů plug-in

Obecně není správným postupem přispět do nabídky nebo panelu nástrojů jiného modulu plug-in odvozením názvu cesty z plugin.xml, pokud nebyla výslovně označena jako k dispozici klientům.  Je možné, že by budoucí verze modulu plug-in mohla změnit názvy cesty.  Dva obecné způsoby označení id akční sady a cest vašich modulů plug-in jako běžně dostupných jsou následující: