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 de menu primeiramente observando o menu Ajuda do 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 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 de 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 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.
Mas espere! Sabemos que existem itens de menu no menu de Ajuda. Eles são adicionados por plug-ins. Por exemplo, o plug-in de ajuda adiciona um conjunto de ações que contém o menu "Conteúdo da Ajuda" do workbench. Segue a marcação retirada de 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.
Um caminho completo do menu é 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."
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 (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.
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.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 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.
Os caminhos da barra de ferramentas funcionam de maneira semelhante aos caminhos de menu.
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.
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.gif" class="org.eclipse.debug.internal.ui.actions.RunToolbarAction" disabledIcon="icons/full/dtool16/run_exc.gif" icon="icons/full/etool16/run_exc.gif" 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.gif" icon="icons/full/etool16/external_tools.gif" hoverIcon="icons/full/ctool16/external_tools.gif" 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.
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: