Caminhos do menu e da barra de ferramentas

Vimos muitas contribuições de ação que especificam o caminho para a localização da ação delas. Vamos nos aprofundar no significado desses caminhos.  

Caminhos de Menu

Veremos os caminhos de menu primeiramente observando o menu Ajuda do workbench.

Grupos nomeados no workbench

As localizações para inserção de novos menus e itens de menu são definidas utilizando grupos nomeados. Um grupo nomeado é como um slot ou marcador que permite inserir itens de menu em determinados pontos de uma barra de menus ou menu de opções.

O workbench define todos os nomes de slot do grupo nas classes IWorkbenchActionConstants e IIDEActionConstants. (Duas classes diferentes são utilizadas desde que os itens de menu relacionados ao recurso estejam fatorados fora do workbench genérico). Para cada menu do workbench, grupos nomeados são colocados no menu em localizações nas quais espera-se que os plug-ins irão inserir novas ações.

A descrição a seguir do menu de ajuda é uma adaptação da definição de classe IWorkbenchActionConstants.

   Ações padrão do menu de Ajuda
   Start group - HELP_START - "start"
   End group - HELP_END - "end"

O menu de ajuda do workbench padrão define um grupo nomeado chamado "start," seguido por um grupo nomeado chamado "end,". Definir dois grupos dá aos plug-ins um pouco mais de controle sobre os locais em que os itens que foram contribuídos serão posicionados dentro do menu de ajuda.  Quando você define um menu, pode definir quantos slots desejar. A inclusão de mais slots fornece aos outros plug-ins maior controle sobre onde as contribuições deles aparecem com relação às contribuições existentes.

Os plug-ins que incluem um item de menu no menu de ajuda podem utilizar esses nomes de grupo para decidir para onde os itens de menu irão. Por exemplo, o plug-in da folha de dicas inclui um conjunto de ação contendo o menu "Folhas de Dicas..." no workbench.  Aqui está a marcação de org.eclipse.ui.cheatsheets plugin.xml do plugin.

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

A nova ação da ajuda será colocada no menu ajuda, dentro do grupo helpStart.

Caminhos completos de menu

Um caminho de menu completo é simplesmente "nome do menu/nome do grupo."  A maioria dos nomes de menu para o workbench são definidos em IWorkbenchActionConstants. (Os nomes de menu relacionados ao recurso são definidos e,IIDEActionConstants.) Se procurarmos o nome do menu ajuda nesta classe, descobriremos que o nome completo do caminho para nossa ação de ajuda é "help/helpEnd."

Alguns menus têm submenus aninhados. É lá que surgem os caminhos mais longos. Se o menu de ajuda definiu um submenu chamado "submenu", com um grupo nomeado chamado"submenuStart", o caminho completo do menu para uma ação no novo menu será "help/submenu/submenuStart."

Externando etiquetas da UI

O exemplo acima demonstra uma técnica para externalizar cadeias que aparecem na UI.  As cadeias externalizadas são úteis para simplificar a conversão da UI do plug-in para outras linguagens.  Podemos externalizar as cadeias em nossos arquivos plugin.xml , substituindo a cadeia por uma chave (%CHEAT_SHEETS_MENU) e criando entradas no arquivoplugin.properties do formulário:

	CHEAT_SHEETS_MENU = Folhas de Dicas...

O arquivo plugin.properties pode ser traduzido para outros idiomas e o plugin.xml não precisará ser modificado.

Incluindo novos menus e grupos

Em muitos exemplos que vimos até o momento, as ações que eram contribuições dos plug-ins de exemplo foram incluídas nos grupos nomeados existentes dentro de menus.

Os pontos de extensão actionSets, viewActions, editorActions e popupMenus permitem também definir novos menus e grupos dentro da contribuição. Isso significa que você pode definir novos submenus ou novos menus de opções e contribuir com suas ações para esses novos menus. Nesse caso, o caminho para a nova ação conterá o nome do menu recentemente definido.

Vimos essa técnica quando a ferramenta Leia-me definiu um novo menu para seu conjunto ações.  Vamos ver a marcação novamente, agora que observamos os caminhos do menu mais detalhadamente.

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

Incluímos um novo menu chamado  "org_eclipse_ui_examples_readmetool" cujo rótulo é definido pela chave "%ActionSet.name" no arquivo de propriedades. Nesse menu, definimos três grupos nomeados:  "slot1," "slot2" e "slot3."  Incluímos esse novo menu no caminho "window/additions."

Se voltarmos para IWorkbenchActionConstants, veremos esta definição do menu da janela no javadoc:

    * <h3>Ações padrão do menu Janela</h3>
    * <ul>
    * <li>Grupo de ação extra do tipo Janela (<code>WINDOW_EXT</code>)</li>

Se olharmos mais de perto a definição de classe, veremos estas definições relacionadas:

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

A partir desta informação, podemos juntar os pedaços do caminho incluindo alguma coisa no menu "Window" do workbench.  O próprio menu é chamado de "window" e ele define um slot chamado "additions."  Utilizamos o caminho "window/additions" para adicionar nosso novo menu.

Na declaração do conjunto de ações, incluímos uma ação no menu que acabamos de definir, utilizando o caminho "window/org_eclipse_ui_examples_readmetool/slot1".

Outros plug-ins poderiam incluir nosso menu, utilizando o mesmo caminho (ou talvez um dos outros slots) para incluir um de seus próprios menus.  

No exemplo da ferramenta Leia-me, utilizamos o atributo separator para identificar os nomes de grupos.  Isso fará com que uma linha separadora apareça entre esses grupos quando eles contiverem itens.  Em vez disso, poderíamos utilizar o atributo groupMarker se desejarmos definir um grupo nomeado sem mostrar separadores no menu para distinguir os grupos.

Caminhos da Barra de Ferramentas

Os caminhos da barra de ferramentas funcionam de maneira semelhante aos caminhos de menu.  

Barras de ferramentas nomeadas no workbench

A barra de ferramentas do workbench é composta de barras de ferramentas que recebem contribuição de diferentes plug-ins, incluindo o próprio workbench.  Em qualquer barra de ferramentas específica, há grupos nomeados ou slots que podem ser utilizados para inserir novos itens de barra de ferramentas.    

A descrição a seguir das barras de ferramentas do workbench é adaptada da definição de classe IWorkbenchActionConstants.

// IDs da barra de ferramentas do workbench
public static final String TOOLBAR_FILE = "org.eclipse.ui.workbench.file"
public static final String TOOLBAR_NAVIGATE = "org.eclipse.ui.workbench.navigate"; 

// IDs de grupos da barra de ferramentas do workbench. Para adicionar um item no início do grupo,
// utilize o ID GROUP. Para adicionar um item no final de um grupo, utilize o ID EXT.
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"; 

No caso mais simples, um plug-in pode contribuir com um item de barra de ferramentas em sua própria barra de ferramentas.  Por exemplo, as ações da ferramenta Leia-me contribuídas no menu também recebem um caminho da barra de ferramentas:

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

Como não há qualquer referência aos caminhos ou grupos da barra de ferramentas do workbench, as ações do Leia-me aparecem em seu próprio grupo na barra de ferramentas.  Em vez disso, a especificação do seguinte caminho poderia posicionar o item na barra de ferramentas do arquivo no grupo salvar:

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

Os caminhos definidos em IWorkbenchActionConstants podem ser referenciados nos caminhos da barra de ferramentas de outros plug-ins.

Adicionando a conjuntos de ações de outro plug-in

Suponha que desejamos que os itens da barra de ferramentas de um plug-in sejam melhor integrados com ações de um plug-in diferente.  Vejamos como o plug-in de ferramentas externo (org.eclipse.ui.externaltools) integra suas ações com a barra de ferramentas do depurador.  O depurador (org.eclipse.debug.ui) define suas ações da barra de ferramentas da seguinte forma:

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

Exatamente como na ferramenta Leia-me, o plug-in do depurador define seu próprio caminho da barra de ferramentas, o que significa que os itens da barra de ferramentas estarão dentro de sua própria barra de ferramentas no workbench.  O que faz o plug-in de ferramentas externo?

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

Observe a utilização do ID do conjunto de ações do depurador no caminho da barra de ferramentas.  A utilização de um ID de conjunto de ações no caminho denota que o item da barra de ferramentas deve ser colocado na barra de ferramentas utilizada pelo conjunto de ações referenciado.  Em um grupo da barra de ferramentas, os itens são ordenados por ID de conjunto de ações; dessa forma, para nosso exemplo, a ação das ferramentas externa aparecerá depois das ações do depurador. 

Ao adicionar uma barra de menus de um conjunto de ações, novos grupos também podem ser definidos.  Se o plug-in de ferramentas externo definir seu toolbarpath como "org.eclipse.debug.ui.launchActionSet/external" um novo grupo seria criado para a ação na barra de ferramentas.  Como nos menus, os grupos de barra de ferramentas são delineados por separadores. 

Utilizando Caminhos de Outro Plug-in

Em geral, não é recomendável contribuir para o menu ou barra de ferramentas de outro plug-in fazendo a derivação do nome do caminho de plugin.xml, a menos que ele tenha sido especificamente marcado como disponível para clientes.  É possível que uma versão futura do plug-in possa alterar os nomes dos caminhos.  Duas maneiras comuns de marcar os IDs e caminhos do conjunto de ações de seu plug-in como apropriados são: