Contribuições de menu do workbench

Vimos vários pontos de extensão diferentes que contribuem com vários menus e várias barras de ferramentas no workbench. Como saber qual utilizar? A tabela a seguir resume as várias contribuições de menu e a utilização delas.

Nome do ponto de extensão

Localização das Ações

Detalhes

viewActions

As ações aparecem na barra de ferramentas local e no menu de opções local de uma exibição específica.

Contribua com uma classe de ação que implemente IViewActionDelegate. Especifique o ID da contribuição e o ID da exibição de destino que deve mostrar a ação. A etiqueta e a imagem ditam a aparência da ação na UI. O caminho especifica a localização relativa aos itens de menu e de barra de ferramentas da exibição.

editorActions

As ações são associadas a um editor e aparecem no menu e/ou na barra de ferramentas do workbench.

Contribua com um classe de ação que implemente IEditorActionDelegate. Especifique o ID da contribuição e o ID do editor de destino que faz com que a ação seja mostrada. A etiqueta e a imagem especificam a aparência da ação na UI. Caminhos separados do menu e da barra de ferramentas especificam a existência e a localização da contribuição no menu e na barra de ferramentas do workbench.

popupMenu

As ações aparecem no menu pop-up de um editor ou de uma exibição. As ações associadas a um tipo de objeto aparecem em todos os pop-ups das exibições e dos editores que mostram o tipo de objeto. As ações associadas a um menu pop-up específico aparecem somente nesse menu pop-up.

As contribuições de objeto especificam o tipo de objeto para o qual a ação deve aparecer em um menu pop-up. A ação será mostrada em todos os pop-ups da exibição e do editor que contiverem o tipo de objeto.  Forneça uma classe de ação que implemente IObjectActionDelegate
As contribuições do visualizador especificam o ID do menu pop-up de destino no qual o item de menu deve aparecer.  Forneça uma classe de ação que implemente IEditorActionDelegate ou IViewActionDelegate

actionSets

As ações aparecem nos menus e na barra de ferramentas principais do workbench. As ações são agrupadas em conjuntos de ações. Todas as ações em um conjunto serão mostradas nos menus e nas barras de ferramentas do workbench, de acordo com o conjunto de ações selecionado pelo usuário e a perspectiva atual mostrada no workbench.

Contribua com uma classe de ação que implemente IWorkbenchWindowActionDelegate ou IWorkbenchWindowPulldownDelegate. Especifique o name e o id do conjunto de ações. Enumere todas as ações definidas para aquele conjunto de ações. Para cada ação, caminhos separados de menu e barra de ferramentas especificam a existência e a localização da contribuição no menu e na barra de ferramentas do workbench.

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 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". Por que dois grupos? Para fornecer algum controle para os plug-ins de até onde eles aparecem no menu de ajuda. Quando você define um menu, pode definir quantos slots gostaria. 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.internal.ui.ShowHelp"/>
    </actionSet>
</extension>

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 de menu ou barra de ferramentas é simplesmente uma lista de pares de nome de menu e grupo nomeado. Os nomes de menu do workbench são definidos também em IWorkbenchActionConstants. É por isso que sabíamos que o nome do caminho completo para a nossa ação help era"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 também uma técnica para externar cadeias que aparecem na UI.  Isso é útil para traduzir a UI do plug-in para outros idiomas.  Podemos externar as cadeias em nossos arquivos plugin.xml , substituindo a cadeia por uma chave (por exemplo, %help, %helpcontents) e criando entradas no arquivo plugin.properties do formulário:

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

Dessa maneira, 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="ReadMe Actions"
        visible="true">
        <menu id="org_eclipse_ui_examples_readmetool"
            label="Readme &amp;File Editor"
            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="&amp;Open Readme Browser@Ctrl+R"
            tooltip="Open Readme Browser"
            helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context"
            icon="icons/basic/ctool16/openbrwsr.gif"
            class="org.eclipse.ui.examples.readmetool.WindowActionDelegate"
            enablesFor="1">
            <selection class="org.eclipse.core.resources.IFile"
                name="*.readme">
            </selection>
        </action>
    </actionSet>
</extension>

Incluímos um novo menu chamado  "org_eclipse_ui_examples_readmetool". Sua etiqueta é a cadeia "Readme &File Editor". 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>Standard Window menu actions</h3>
* <ul>
* <li>Extra Window-like action group (<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.