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.  Veremos os caminhos observando o menu Help do workbench.

Grupos nomeados

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

O workbench define todos os nomes de slot do seu grupo na classe IWorkbenchActionConstants. 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 Ajuda
   Start group - HELP_START - "start"
   End group - HELP_END - "end"
   About action - ABOUT - "About"

O menu de ajuda padrão do workbench consiste em um grupo nomeado chamado "start", seguido por um grupo nomeado chamado "end", seguido pela ação"About". Definir dois grupos fornece aos plug-ins mais controle sobre onde seus itens de contribuição serão posicionados no menu de ajuda.  Quando você define um menu, pode definir quantos slots quiser. 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.

Mas, espere!  Sabemos que há outros itens de menu no menu de ajuda.  Eles são incluídos pelos plug-ins.  Por exemplo, o plug-in help inclui um conjunto de ações que contém o menu "Conteúdo da Ajuda" no workbench.  Eis aqui a marcação plugin.xml do plug-in org.eclipse.help.ui.

<extension point="org.eclipse.ui.actionSets">
	<actionSet
		id="org.eclipse.help.internal.ui.HelpActionSet"
		label="%help"
		visible="true">
			
	<action id="org.eclipse.help.internal.ui.HelpAction"
		menubarPath="help/helpEnd"
		label="%helpcontents"
		class="org.eclipse.help.ui.internal.HelpContentsAction"
		icon="icons/view.gif"
		helpContextId="org.eclipse.help.ui.helpContentsMenu"
		tooltip="%openhelpcontents"/>
	...

A nova ação help será posicionada no menu de ajuda, dentro do grupo helpEnd. Se nenhum outro plug-in contribuiu com o menu de ajuda, isso significa que o item de menu "Conteúdo da Ajuda" aparecerá como o primeiro item no menu, acima do item"Sobre". Se outro plug-in quisesse contribuir com um item que aparecesse sempre acima do item "Conteúdo da Ajuda", ele poderia especificar o grupo helpStart no seu caminho.  

Os caminhos da barra de ferramentas funcionam de forma semelhante. Toda vez que um caminho é especificado, ele deve terminar com o nome de um grupo na barra de ferramentas.

Caminhos completos de menu e ferramenta

Um caminho completo do menu ou da barra de ferramentas é simplesmente "nome do menu/nome do grupo."  Os nomes dos menus no workbench são definidos em IWorkbenchActionConstants. Esta classe é utilizada para mostrar 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."

Externalizando etiquetas da UI

O exemplo acima demonstra uma técnica para externalizar cadeias que aparecem na UI.  As cadeias externalizadas são úteis para tornar a tradução da UI do plug-in para outros idiomas mais simples.  Podemos externalizar as cadeias em nossos arquivos plugin.xml substituindo a cadeia por uma chave (por exemplo, %help, %helpcontents) e criando entradas no arquivo plugin.properties no formato:

   help = "Ajuda"
   helpContents = "Conteúdo da Ajuda"

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 e barras de ferramentas.

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.gif"
		   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 incluir 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.  

Em geral, não é recomendável contribuir para o menu ou a barra de ferramentas de outro plug-in, derivando o nome do caminho de plugin.xml.  É possível que uma versão futura do plug-in possa alterar os nomes dos caminhos.  A prática recomendada é definir uma interface pública (como IWorkbenchActionConstants), a qual especifica exatamente quais menus, grupos de barras de ferramentas e slots são considerados apropriados para serem utilizados por outros plug-ins.

Copyright IBM Corp. e outros 2000,2002.