Já vimos muitos contributos de acções que especificam o caminho para a localização da sua acção. Vejamos em mais pormenor o que significam estes caminhos.
Veremos primeiro os caminhos de menus no menu de Ajuda da área de trabalho.
As localizações para inserir novos menus e artigos de menu são definidas com grupos denominados. Poderá considerar um grupo denominado como uma ranhura ou um marcador de lugar que permite inserir artigos de menu em certos pontos de uma barra de menus ou um menu pendente.
A área de trabalho define todos os seus nomes de ranhuras de grupo nas classes IWorkbenchActionConstants e IIDEActionConstants. (São utilizadas duas classes diferentes dado que os artigos de menu relacionados com recursos são calculados fora da área de trabalho genérica.) Para cada menu de área de trabalho, são colocados grupos denominados no menu em localizações onde se espere que os plug-ins insiram novas acções. .
A descrição seguinte do menu de ajuda é adaptada da definição da classe IWorkbenchActionConstants.
Acções de menu da Ajuda Padrão Grupo de início - HELP_START - "start" Grupo de fim - HELP_END - "end"
O menu de ajuda da área de trabalho padrão define um grupo denominado chamado "start," seguido de outro grupo denominado chamado "end". Ao definir dois grupos dá-se aos plug-ins mais controlo sobre o posicionamento dos artigos contributos no menu da ajuda. Ao definir um menu, poderá definir as ranhuras que entender. Se adicionar mais ranhuras dará aos outros plug-ins mais controlo sobre a posição dos seus contributos relativamente aos contributos existentes.
Os plug-ins que adicionam um artigo de menu ao menu de ajuda podem utilizar estes nomes de grupos para decidir onde fica o seu artigo de menu. Por exemplo, o plug-in da folha de apontamentos adiciona um conjunto de acções que contém o menu "Folhas de apontamentos..." à área de trabalho. De seguida é apresentada a marcação do ficheiro plugin.xml do plug-in org.eclipse.ui.cheatsheets.
<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 acção de ajuda será colocada no menu de ajuda, dentro do grupo helpStart.
Um caminho de menu completo é simplesmente "nome de menu/nome de grupo". A maioria dos nomes de menus para a área de trabalho é definida em IWorkbenchActionConstants. (Os nomes de menus relacionados com recursos são definidos em IIDEActionConstants.) Se procurarmos o nome do menu de ajuda neste classe, veremos que o nome do caminho totalmente qualificado da nossa acção de ajuda é "help/helpEnd."
Há menus com submenus imbricados, e aqui entra a noção de caminhos mais longos. Se o menu de ajuda tiver definido um submenu chamado "submenu" com um grupo denominado chamado "submenuStart," o caminho de menus totalmente qualificado de uma acção no novo submenu seria "help/submenu/submenuStart."
O exemplo supra demonstra uma técnica para externalizar cadeias de caracteres que a aparecem na UI. As cadeias externalizadas são utilizadas para facilitar a tradução da UI do plug-in noutros idiomas. Podemos externalizar as cadeias nos nossos ficheiros plugin.xml substituindo a cadeia por uma chave (%CHEAT_SHEETS_MENU) e criando entradas no ficheiro plugin.properties no formato:
CHEAT_SHEETS_MENU = Folhas de apontamentos...
O ficheiro plugin.properties pode ser traduzido em diferentes idiomas e o ficheiro plugin.xml não precisa de ser modificado.
Em muitos dos exemplos que vimos até agora, as acções contribuídas pelos mesmos plug-ins foram adicionadas a grupos denominados existentes dentro de menus.
Os pontos de extensão actionSets, viewActions, editorActions, e popupMenus também permitem definir novos menus e grupos dentro do nosso contributo. Significa isto que se pode definir novos submenus ou novos menus pendentes e contribuir com acções para estes menus. Neste caso, o caminho para a nova acção irá conter o nome do menu recentemente definido.
Vimos esta técnica quando a ferramenta readme definiu um novo menu para o seu conjunto de acções. Vejamos a marcação mais uma vez, agora que já vimos os caminhos de menu em mais detalhe.
<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="janela/adições"> <separator name="ranhura1"/> <separator name="ranhura2"/> <separator name="ranhura3"/> </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> ...
Adicionámos um novo menu chamado "org_eclipse_ui_examples_readmetool" cuja etiqueta é definida pela chave "%ActionSet.name" no ficheiro de propriedades. Neste menu, definimos três grupos denominados: "ranhura1," "ranhura2," e "ranhura3." Adicionamos este menu ao caminho "janela/adições."
Se voltarmos a IWorkbenchActionConstants, veremos esta definição do menu janela no javadoc:
* <h3>Acções de menu Janela padrão</h3> * <ul> * <li>Grupo de acções do tipo Janela extraordinárias<code>WINDOW_EXT</code>)</li>
Se observarmos a definição da 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"; // Group. ... public static final String WINDOW_EXT = MB_ADDITIONS; // Group.
A partir destas informações, podemos juntas as peças do caminho para adicionar algo ao menu "Janela" da área de trabalho. O próprio menu chama-se "janela" e define uma ranhura chamada "adições." Utilizamos o caminho "janela/adições" para adicionar o nosso novo menu.
Na declaração do conjunto de acções, adicionamos uma acção ao nosso menu acabado de definir, com o caminho "janela/org_eclipse_ui_examples_readmetool/ranhura1."
Os outros plug-ins poderiam adicionar ao nosso menu através do mesmo caminho (ou talvez uma das outras ranhuras) para adicionar um dos seus próprios menus.
No exemplo da ferramenta readme, utilizamos o atributo separator para identificar os nomes de grupos. Isto fará com que apareça uma linha divisória entre estes grupos quando contiverem artigos. Poderíamos utilizar o atributo groupMarker se quiséssemos definir um grupo denominado sem mostrar linhas divisórias no menu para distingior grupos.
Os caminhos de barras de ferramentas funcionam de modo semelhante aos caminhos de menus.
A barra de ferramentas da área de trabalho compõe-se de barras de ferramentas que foram contributo de diferentes plug-ins, incluindo da própria área de trabalho. Dentro de qualquer barra de ferramentas, há grupos denominados ou ranhuras que se podem utilizar para inserir novos artigos de barra de ferramentas.
A descrição seguinte das barras de ferramentas da área de trabalho é adaptada da definição da classe IWorkbenchActionConstants.
// ids de barras de ferramentas da área de trabalho 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 de barras de ferramentas da área de trabalho. Para adicionar um artigo ao princípio do grupo, // utilize o id GROUP. Para adicionar um artigo ao final do 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 artigo de barra de ferramentas na sua própria barra de ferramentas. Por exemplo, as acções da ferramenta readme que foram contributos para o menu também recebem um caminho de barra de ferramentas:
<action id="org_eclipse_ui_examples_readmetool_readmeAction" menubarPath="window/org_eclipse_ui_examples_readmetool/slot1" toolbarPath="readme" ...
Dado que não há referência aos caminhos ou grupos da barra de ferramentas da área de trabalho,as acções readme aparecem no seu próprio grupo na barra de ferramentas. Se especificássemos o seguinte caminho colocaríamos o artigo na barra de ferramentas do menu ficheiro, no grupo de acções de salvaguarda:
... <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 poderão ser referenciados nos caminhos de barra de ferramentas de outros plug-ins.
Suponhamos que um plug-in quer os seus artigos de barra de ferramentas melhor integrados com acções de um plug-in diferente. Vejamos como o plug-in de ferramentas externas (org.eclipse.ui.externaltools) integra as suas acções na barra de ferramentas do depurador. O depurador (org.eclipse.debug.ui) define as suas acções de barra de ferramentas deste modo:
<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> ...
Tal como a ferramenta readme, o plug-in depurador define o seu próprio caminho de barra de ferramentas, ou seja, os seus artigos de barra de ferramentas ficam dentro de uma barra de ferramentas própria na área de trabalho. O que faz o plug-in de ferramentas externas?
<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>
Repare no uso do ID do conjunto de acções do depurador no caminho da barra de ferramentas. Ao utilizar um ID de conjunto de acções no caminho mostramos que o artigo de barra de ferramentas deve ser colocado na barra de ferramentas utilizada pelo conjunto de acções referenciado. Dentro de um grupo de barras de ferramentas, os artigos são ordenados por ID de conjunto de acções, de modo que para o nosso exemplo, a acção de ferramentas externas irá aparecer depois das acções do depurador.
Quando se adiciona à barra de ferramentas de um conjunto de acções, também se podem definir novos grupos. Se o plug-in de ferramentas externas tivesse definido o seu caminho_barras_ferramentas como "org.eclipse.debug.ui.launchActionSet/external", seria criado novo grupo para a acção na barra de ferramentas. Tal como com os menus, os grupos de barras de ferramentas são delineados por linhas divisórias.
Regra geral, não é boa ideia contribuir para o menu ou a barra de ferramentas de outro plug-in mediante derivação do nome do caminho oriundo do ficheiro plugin.xml, a menos que tenha sido marcado especificamente como disponível para clientes. É possível que uma futura versão do plug-in possa alterar os nomes dos caminhos. São duas as maneiras comuns de marcar os IDs de conjuntos de acções do plug-in como presas fáceis: