Configurando e Incluindo Itens de Menu no Eclipse V3.3

Usar o novo mecanismo de menu da V3.3 para acelerar desenvolvimento de plug-in e RCP

Em versões anteriores do Eclipse, incluir comandos em um menu, em um menu pop-up ou em uma barra de ferramentas era complicado. Não mais! O Eclipse V3.3 apresenta um mecanismo que é mais fácil do que nunca. Descubra como usar o ponto de extensão org.eclipse.ui.menus .

Karsten Voigt, IT Architect, IBM

Karsten Voigt é arquiteto e consultor de TI para o IBM Global Business Services na Alemanha. Ele trabalha principalmente para clientes IBM no segmento de mercado automotivo. Sua área de conhecimento é definição de soluções de integração para aplicativos J2EE e Java rich client, incluindo o Lotus Expeditor. Em seu tempo livre, ele projeta, desenvolve e usa aplicativos em Java Swing e Eclipse Rich Client Platform.



19/Fev/2008

Menus, menus pop-up e barras de ferramentas — praticamente todos os plug-ins do Eclipse ou aplicativos Eclipse Rich Client Platform (RCP) precisam deles. O Eclipse V3.3 introduziu um recurso que fornece uma abordagem mais genérica para configurar e incluir itens de menu. Este artigo ilustra como é possível usar o novo mecanismo de menu para acelerar desenvolvimento de plug-in e RCP.

No Eclipse V3.2 e em versões anteriores, era necessário usar diversos pontos de extensão para incluir comandos em um menu, menu pop-up ou barra de ferramentas. Na verdade, havia quatro diferentes pontos de extensão: org.eclipse.ui.actionSets, org.eclipse.ui.viewActions, org.eclipse.ui.editorActions e org.eclipse.ui.popupMenus. Infelizmente, todo tipo de contribuição precisava de seu próprio ponto de extensão e o posicionamento e visibilidade da ação não podiam ser separados.

O Eclipse V3.3 introduz um novo mecanismo: org.eclipse.ui.menus. O ponto de extensão é a nova maneira de posicionar itens de menu.

Este artigo explica os novos conceitos de menu e percorre a criação de um pequeno aplicativo Eclipse RCP para cobrir a maioria dos novos recursos. Você deve ter algumas qualificações básicas para usar Eclipse RCP ou a estrutura de plug-in. A primeira etapa é fazer download de uma distribuição Eclipse que tenha o Plug-in Development Environment (PDE) da Eclipse.org. Recomendo fazer download da versão mais recente do Eclipse Classic. (Consulte Recursos para saber onde localizar o Eclipse e informações básicas adicionais se você for iniciante no Eclipse)

A Estrutura de Comando da Plataforma

Antes de começarmos a implementar um plug-in que usa o novo mecanismo de menu, precisamos entender a estrutura de comando. Um comando é uma descrição declarativa de um componente e é independente dos detalhes de implementação. Um comando pode ser categorizado e uma ligação de teclas pode ser designada. Com essa abordagem, é possível definir uma ligação de teclas genérica e, dependendo do contexto atual, podemos escolher uma implementação específica. A Figura 1 mostra um diagrama de classes de comandos simplificado.

Figura 1. Diagrama de Classes de Comandos
Diagrama de Classes de Comandos

Use o ponto de extensão org.eclipse.ui.commands para definições de comandos. Os comandos também podem ser criados de maneira programática. Para alcançar esse objetivo, podemos usar a interface ICommandService . Diversos manipuladores podem tratar de um comando, mas somente um trata de uma instância do tempo de execução concreta do comando. Para integração à área de trabalho Eclipse, uma imagem, itens de menu e ligações podem ser designados a um comando. Uma boa abordagem é agrupar comandos usando categorias. As categorias facilitam a navegação em aplicativos rich client complexos.


Incluindo uma Contribuição de Menu

Vamos começar usando contribuições de menus. O exemplo começa com a implementação de um pequeno aplicativo RCP que tem uma única entrada de menu. Essa entrada de menu apenas abre um diálogo de mensagem. Esse pequeno exemplo ilustra os principais conceitos para usar comandos, manipuladores e menus.

Crie um novo projeto de plug-in chamado MenuContribution e configure a versão do Eclipse para 3.3. Responda Sim para a pergunta "Gostaria de criar um aplicativo rich client?" Use o modelo Hello RCP. O exemplo é baseado no nome do pacote com.ibm.de.eclipse.menu. Todas as outras configurações podem ser mantidas como o padrão. Agora execute o novo projeto como Aplicativo Eclipse e verá a janela a seguir.

Figura 2. Exemplo Hello RCP
Exemplo Hello RCP

Vamos explicar diferentes contribuições de menu através desse aplicativo. Abra o plugin.xml, alterne para Extensões e inclua a extensão org.eclipse.ui.commands. Como todos os comandos devem estar agrupados em uma categoria, selecione a extensão de comandos e crie uma nova categoria clicando com o botão direito do mouse em Novo > categoria. Preencha os campos da categoria, conforme mostrado na Figura 3.

Figura 3. Detalhes da Categoria de Comandos
Detalhes da Categoria de Comandos

Agora inclua um novo comando na extensão de comandos clicando com o botão direito do mouse em Novo > comando . Configure o ID para com.ibm.de.eclipse.menu.command.testCmd, denomine-o Test Command e configure categoryId para com.ibm.de.eclipse.menu.command.cat1. Para esse comando, precisamos de um manipulador para executar a lógica de negócios associada. Inclua o ponto de extensão org.eclipse.ui.handlers e crie um novo manipulador. O commandId para o manipulador é com.ibm.de.eclipse.menu.command.testCmd. Para criar a classe do manipulador, clique no link da classe, mostrado na Figura 4. A Figura 5 mostra o assistente com os parâmetros necessários.

Sugestão: Se você usar o link da classe em diversas extensões, você cria uma nova classe que contém as interfaces necessárias para o ponto de extensão escolhido.

Figura 4. Novo Link de Classe do Manipulador
Novo Link de Classe do Manipulador
Figura 5. Assistente
Assistente

O manipulador deve implementar o método execute. Inclua as linhas da Lista 1 para mostrar um diálogo de mensagem.

Lista 1. Método execute do Manipulador
public Object execute(ExecutionEvent event) throws ExecutionException {
	IWorkbenchWindow window = 
HandlerUtil.getActiveWorkbenchWindowChecked(event);
	MessageDialog.openInformation(
		window.getShell(), "MenuEclipseArticle Plug-in",
		"Hello, Eclipse world");
	return null;
}

Salve a classe, retorne ao plugin.xml e salve esse arquivo. Agora crie a contribuição do menu para o novo comando e manipulador. Inclua a extensão org.eclipse.ui.menus e crie uma nova menuContribution. A contribuição de menu tem somente uma propriedade denominada locationURI. Essa propriedade define o ponto de inserção onde as inclusões contidas serão incluídas. Use menu:org.eclipse.ui.main.menu como locationURI. Esse URI define um menu, que é colocado no menu Eclipse padrão.

Até agora, definimos somente o ponto de inserção. Para incluir um menu concreto, selecione a contribuição de menu e crie um novo menu. Configure o rótulo como TestMenu e use o ID com.ibm.de.eclipse.menu.test.

A última etapa é a definição do link entre o item de menu e o comando predefinido. Clique em TestMenu e inclua um novo comando. Configure o commandId para com.ibm.de.eclipse.menu.command.testCmd e configure o rótulo para Do something. As extensões para seu plugin.xml devem ter a aparência do que é mostrado na Figura 6. Antes de executar o aplicativo Eclipse, abra a classe ApplicationWorkbenchWindowAdvisor, vá para o método preWindowOpen e inclua a linha configurer.setShowMenuBar(true);. Execute o aplicativo Eclipse e teste nosso novo item de menu.

Figura 6. Visão Geral de Todas as Extensões
Visão Geral de Todas as Extensões

O URI do Local do Menu

No exemplo anterior, definimos um locationURI para o menu que inclui o item de menu diretamente na barra do menu de aplicativos, mas o locationURI também suporta outras contribuições de menu. O padrão a seguir caracteriza pontos de inserção no menu: <scheme>:<menu-id>[?<placement-modifier>].

<scheme> menu
Inclua uma contribuição no menu principal ou no menu para uma visualização. O <menu-id> deve apontar para um ID de visualização existente ou para o menu Eclipse padrão org.eclipse.ui.main.menu. O <placement-modifier> possibilita o posicionamento de contribuições de menu usando o padrão <placement>=<id>. Para posicionamentos, as tags antes ou depois podem ser usadas e o <id> pode ser um nome separador, um ID de menu ou um ID de item existente.
Sugestão: A classe MenuUtil contém alguns valores constantes comuns para URIs de menu.
<scheme> toolbar
Inclua uma contribuição em qualquer barra de ferramentas. Para este <scheme>, o <menu-id> pode apontar para qualquer ID de visualização (para a barra de ferramentas de visualizações), org.eclipse.ui.main.toolbar ou qualquer ID da barra de ferramentas contido na barra de ferramentas principal. Você também pode usar o <placement-modifier>.
<scheme> pop-up
Inclua um menu para IDs de contexto registrados e org.eclipse.ui.popup.any para todos os menus de contexto registrados. O<placement-modifier> também pode ser usado.

Agora, vamos estender nosso exemplo curto e usar diferentes tipos para contribuições de menu.


Incluindo uma Visualização e Contribuições de Visualização

Em seguida, estendemos o pequeno aplicativo para conter uma visualização com uma ação na barra de ferramentas. Alteramos a ação do menu principal existente para abrir a visualização.

Primeiro, inclua o ponto de extensão da visualização (org.eclipse.ui.views) e crie uma nova visualização usando as propriedades mostradas na Figura 7. Em seguida, abra o TestHandler e altere o método de execução para abrir a visualização.

Lista 2. Alterar o Método de Execução para Abrir a Visualização
public Object execute(ExecutionEvent event) throws ExecutionException {
	try {
	HandlerUtil.getActiveWorkbenchWindow(event)
.getActivePage()
.showView("com.ibm.de.eclipse.menu.view.testview");
	} catch (PartInitException e) {
		throw new ExecutionException("Error while opening view", e);
	}
	return null;
}
Figura 7. Criar Detalhes do Elemento de Visualização
Criar Detalhes do Elemento de Visualização

Precisamos, para essa visualização, um novo comando e manipulador para incluir as contribuições propostas. Crie um novo comando e um novo manipulador. Use as propriedades a seguir; o manipulador deve estender org.eclipse.core.commands.AbstractHandler. Use a Lista 1 para implementar o conteúdo do método de execução do manipulador.

Tabela 1. Incluindo um Novo Comando e Manipulador
Comando ou manipuladorDescriçãoPropriedade
Comandoidcom.ibm.de.eclipse.menu.command.viewCmd
nomeComando view
descriçãoUm exemplo do comando view
categoryIdcom.ibm.de.eclipse.menu.command.cat1
ManipuladorcommandIdcom.ibm.de.eclipse.menu.command.viewCmd
classecom.ibm.de.eclipse.menu.handler.ViewHandler

Agora, inclua duas contribuições de menu. Primeiro, inclua uma menuContribution (para a barra de menus e visualização) com o URI menu:com.ibm.de.eclipse.menu.view.testview. O ID da visualização é <menu-id>. Inclua um comando diretamente no menu com o commandId: com.ibm.de.eclipse.menu.command.viewCmd e o rótulo Do something. Como não precisamos de uma estrutura de submenu, não é necessário um menu para a contribuição de menu. Além disso,inclua uma menuContribution para a barra de ferramentas e use o URI toolbar:com.ibm.de.eclipse.menu.view.testview. Para a barra de ferramentas, o comando é referido novamente, mas você precisa escolher um ícone. Use qualquer um dos ícones de plug-in padrão (por exemplo, icons/alt_window_16.gif). Execute o aplicativo, execute o comando do menu principal e dê uma olhada na visualização aberta. A visualização deve conter uma barra de ferramentas e um menu com os comandos propostos.

Figura 8. Visualização de Exemplo com a Barra de Ferramentas e a Contribuição de Menu
Visualização de Exemplo com a Barra de Ferramentas e a Contribuição de Menu

Incluindo uma Contribuição Pop-up Condicional

Por fim, é necessário incluir uma contribuição pop-up condicional no aplicativo de amostra. Primeiro, a visualização é estendida para conter uma lista de elementos. Um menu de contexto será mostrado para esses elementos. Abra a classe TestView e altere o método createPartControl .

Lista 3. Incluir uma Lista e Menu de Contexto em TestView
public void createPartControl(Composite parent) {
	ListViewer lViewer = new ListViewer(new List(parent, SWT.MULTI));
	lViewer.setContentProvider(new ArrayContentProvider());
	lViewer.setInput(new String[] { "1", "2", "3", "4" });
		
	MenuManager menuMgr = new MenuManager();
	menuMgr.add(
new GroupMarker(IWorkbenchActionConstants.MB_ADDITIONS));
	getSite().registerContextMenu(menuMgr, lViewer);
		
	Control control = lViewer.getControl();
	Menu menu = menuMgr.createContextMenu(control);
	control.setMenu(menu);		
}

O padrão ArrayContentProvider cria um ListViewer e mostra apenas uma array de strings. Para essa lista, um MenuManager é criado e todo o conteúdo definido no plugin.xml é incluído usando o novo GroupMarker(IWorkbenchActionConstants.MB_ADDITIONS). O menu de contexto é registrado no site e anexado no controle do ListViewer.

Inclua o pop-up e a instrução condicional no plugin.xml. O menu de contexto deve ser mostrado somente se você selecionar dois elementos na lista. Como essa condição pode ser útil em diversos locais do plug-in,usamos a extensão org.eclipse.core.expressions.definitions para definir uma regra comum. Essa extensão faz parte do plug-in org.eclipse.core.expression que precisa ser incluído, conforme necessário, pelo plug-in. Vá para a seção de dependências do plugin.xml e inclua esse plug-in. Volte à seção de extensão e inclua org.eclipse.core.expressions.definitions. Configure o ID da nova definição criada para twoSelectedCheck. Se nenhuma definição tiver sido criada durante a inclusão da extensão, crie uma. Para essa definição, inclua um elemento with e configure a variável para activeMenuSelection. O elemento with especifica o nome da variável usado para a verificação. Se a variável não puder ser resolvida, uma ExpressionException será emitida enquanto a regra é avaliada.

Diversas variáveis de padrão são definidas no Eclipse. Para obter uma lista completa das variáveis disponíveis, revise a definição de Command Core Expressions na Wikipedia (consulte Recursos). Usamos activeMenuSelection no exemplo. Essa variável é a seleção disponível enquanto um menu de contexto está em exibição. Agora, inclua uma contagem no elemento e configure o valor para 2. É definida a regra que conta os elementos ativos selecionados e retorna true se dois elementos forem selecionados. O plugin.xml para a definição deve ter a aparência da Lista 4.

Lista 4. Extensão de Definição no plugin.xml
<extension point="org.eclipse.core.expressions.definitions">
<definition id="twoSelectedCheck">
         <with variable="activeMenuSelection">
            <count value="2"></count>
         </with>
      </definition>
</extension>

Após criar a definição, incluímos uma nova contribuição de menu. Vá para o ponto de extensão org.eclipse.ui.menus e inclua um menu com o pop-up locationURI : org.eclipse.ui.popup.any. Também inclua um comando com commandIdcom.ibm.de.eclipse.menu.command.viewCmd para esse menu. Até agora, sempre vimos o menu de contexto. Para alternar esse comportamento, inclua o elemento visibleWhen no comando. Em seguida, inclua um elemento de referência com definitionId twoSelectedCheck no elemento visibleWhen . Por fim, teste o aplicativo. TestView agora contém uma lista de elementos. Se dois elementos forem selecionados, poderemos ver um menu de contexto.

Usar o elemento visibleWhen no arquivo de configuração de um plug-in é uma ótima maneira de restringir a visibilidade das contribuições de menu no design ou tempo de execução. Demonstramos esse poder no exemplo onde estendemos seu uso com outra definição de regra. TestView obtém um campo de texto adicional e o comando da barra de ferramentas está disponível somente se o campo de texto tiver o foco. Primeiro, estenda TestView com o código encontrado na Lista 5. Usamos IFocusService para registrar o campo de texto de forma que o aplicativo possa tratar de mudanças de foco para o campo de texto.

Lista 5. TestView com Campo de Texto Registrado em IFocusService
public void createPartControl(Composite parent) {
	parent.setLayout(new FillLayout(SWT.VERTICAL));
		
	Text text = new Text(parent, SWT.BORDER);
		
	IFocusService focusService = 
(IFocusService) PlatformUI.getWorkbench()
.getService(IFocusService.class);
	focusService.addFocusTracker(text, "textControlId");
		
	ListViewer lViewer = new ListViewer(new List(parent, SWT.MULTI));
	...
}

A próxima etapa é a criação de uma nova definição. Vá para org.eclipse.core.expressions.definitions e inclua uma definição denominada focusDefinition com um elemento with usando a variável activeFocusControlId. Essa variável contém o ID do controle que tem o foco e foi registrado usando IFocusService. Inclua um elemento equals com o valor textControlId. Essa regra retorna true se o componente ativo em foco tiver o ID textControlId. A Lista 6 mostra a definição no plugin.xml. Inclua essa definição em um menu da barra de ferramentas usando visibleWhen com um elemento de referência mostrado na Lista 7. Execute e teste o exemplo.

Lista 6. Definição de Regra de Controle de Foco
<definition id="focusDefinition"> <with variable="activeFocusControlId">
     		<equals value="textControlId"></equals>
      </with> </definition>
Lista 7. Contribuição de Menu da Barra de Ferramentas com visibleWhen
<menuContribution locationURI="toolbar:com.ibm.de.eclipse.menu.view.testview">
      <command
      	commandId="com.ibm.de.eclipse.menu.command.viewCmd"
            icon="icons/alt_window_16.gif" label="Do something"
            tooltip="Do something">
            <visibleWhen>
            	<reference definitionId="focusDefinition"></reference>
            </visibleWhen>
      </command> </menuContribution>

Conclusão

A nova org.eclipse.ui.menus fornece uma maneira útil de definir mudanças e inclusões de menu de maneira inteligente e consistente. O único truque é aprender como usar o locationURI. Além da definição de menu normal, é possível definir regras para possibilitar a visibilidade condicional de entradas de meu. Mas o que fazer com os aplicativos e plug-in existentes? A resposta é fácil: migre seus aplicativos para usarem o novo mecanismo. Por que migrar? Alguns recursos do Eclipse dos quais você depende podem não estar disponíveis em releases futuros. Consulte Recursos para obter informações adicionais referentes a mudanças planejadas nas contribuições de menu.


Download

DescriçãoNomeTamanho
Sample Perl scriptsos-eclipse-3.3menuContribution.zip65KB

Recursos

Aprender

Obter produtos e tecnologias

Discutir

Comentários

developerWorks: Conecte-se

Los campos obligatorios están marcados con un asterisco (*).


Precisa de um ID IBM?
Esqueceu seu ID IBM?


Esqueceu sua senha?
Alterar sua senha

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


A primeira vez que você entrar no developerWorks, um perfil é criado para você. Informações no seu perfil (seu nome, país / região, e nome da empresa) é apresentado ao público e vai acompanhar qualquer conteúdo que você postar, a menos que você opte por esconder o nome da empresa. Você pode atualizar sua conta IBM a qualquer momento.

Todas as informações enviadas são seguras.

Elija su nombre para mostrar



Ao se conectar ao developerWorks pela primeira vez, é criado um perfil para você e é necessário selecionar um nome de exibição. O nome de exibição acompanhará o conteúdo que você postar no developerWorks.

Escolha um nome de exibição de 3 - 31 caracteres. Seu nome de exibição deve ser exclusivo na comunidade do developerWorks e não deve ser o seu endereço de email por motivo de privacidade.

Los campos obligatorios están marcados con un asterisco (*).

(Escolha um nome de exibição de 3 - 31 caracteres.)

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


Todas as informações enviadas são seguras.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=80
Zone=Software livre
ArticleID=382618
ArticleTitle=Configurando e Incluindo Itens de Menu no Eclipse V3.3
publish-date=02192008