NOW Hiring

Quick links

Eclipse Commands Advanced - Tutorial

Lars Vogel

Version 2.2

18.03.2014

Eclipse Advanced Commands

This article describes use cases for Eclipse commands which go beyond the simple one for adding commands to menus, toolbars, etc.

This article is based on Eclipse Indigo (3.7).


Table of Contents

1.
2. Eclipse Commands
3. Eclipse standard commands
3.1. Overview
3.2. Example
4. Calling commands directly via code
5. Using parameters in commands
6. Defining commands at runtime
7. About this website
8. Links and Literature
8.1. Eclipse Commands Resources
8.2. vogella GmbH training and consulting support

Warning

This tutorial describes the Eclipse 3.x API which is used for Eclipse IDE plug-in development.

For Eclipse RCP you should use the new Eclipse 4 API which is described in the Eclipse RCP tutorial.

2. Eclipse Commands

For an introduction into Eclipse Commands please see Eclipse Commands Tutorial.

3. Eclipse standard commands

3.1. Overview

Eclipse provides lots of standard commands which you can reuse. Just press on the "Browse button" while defining your commandId to see the available standard commands. For example the screenshot shows the usage of the standard about dialog command.

The advantage of using standard commands is that you get the keybinding, icons, etc for free.

Tip

Standard commands sometimes map to actions which are contributed via ActionFactory in the class ApplicationActionBarAdvisor. If the ActionFactory returns an IAction you need to register this action. If not these commands are inactive in your menu. For example the following made the reset perspective and welcome command active.

// Method belongs to class ApplicationActionBarAdvisor
  @Override
  protected void makeActions(IWorkbenchWindow window)
  {
    IWorkbenchAction quickStartAction = ActionFactory.INTRO.create(window);
    register(quickStartAction);
    IWorkbenchAction resetView = ActionFactory.RESET_PERSPECTIVE
        .create(window);
    register(resetView);
  } 

3.2. Example

You can also use standard command and define a new handler for this command, e.g., you can use the standard Eclipse delete command (org.eclipse.ui.edit.delete).

Tip

To find the id of existing commands you can you the Eclipse Plugin Spy.

You can use the extension point "org.eclipse.ui.handlers" to define new handlers for the standard commands.

Tip

Eclipse requires you to have only one active handler at the time therefore you have to use the "activeWhen" restriction on the handler to make it more special then the standard binding. To use for example delete in several views with different handlers use "activeWhen" with the variable "activePartId" and as the value your view id.

Create a new RCP application "de.vogella.rcp.commands.standardcommands" with the template "Hello RCP".

Create a handler for the command "org.eclipse.ui.edit.delete" which display a message box. Add the command "org.eclipse.ui.edit.delete" to the menu.

The result should look like the following.

4. Calling commands directly via code

You can call a command directly. For example if you have a command "add.command" defined you can call it via the following coding.

// From a view you get the site which allow to get the service
IHandlerService handlerService = (IHandlerService) getSite().getService(IHandlerService.class);
try {
  handlerService.executeCommand("add.command", null);
  } catch (Exception ex) {
    throw new RuntimeException("add.command not found");
    // Give message
    }
} 

The code above is called within a view which provides access to the site and to services. You can also get the service via the WorkbenchWindow.

5. Using parameters in commands

You can also define parameters in commands. Create project "de.vogella.rcp.commands.parameterfirst" using the "Hello RCP" template.

Create a command with the id "de.vogella.rcp.commands.parameterfirst.helloName" and a default handler "de.vogella.rcp.commands.parameterfirst.handler.HelloName".

Right-click on your command, select New -> commandParameter

Use the following id for the parameter "de.vogella.rcp.commands.parameterfirst.commandParameter1"

In the handler you have to evaluate the parameter.

package de.vogella.rcp.commands.parameterfirst.handler;

import org.eclipse.core.commands.AbstractHandler;
import org.eclipse.core.commands.ExecutionEvent;
import org.eclipse.core.commands.ExecutionException;
import org.eclipse.jface.dialogs.MessageDialog;
import org.eclipse.ui.handlers.HandlerUtil;

public class HelloName extends AbstractHandler {

  @Override
  public Object execute(ExecutionEvent event) throws ExecutionException {
    String name = event
        .getParameter("de.vogella.rcp.commands.parameterfirst.commandParameter1");
    MessageDialog.openInformation(HandlerUtil.getActiveShell(event),
        "Hello", "Hello " + name);
    return null;
  }
} 

Add this command to the menu. On the command, right-click and select New -> Parameter

As name enter the name of the parameter, pass as value the value you want to use in your handler.

Add the same command again to the menu and pass another parameter.

If you run your application and select the menu entry the value should be used in the message box.

6. Defining commands at runtime

You can create commands at runtime. Create project "de.vogella.rcp.commands.runtimecommands" using the "Hello RCP" template.

Define a menu contribution. Maintain the class "de.vogella.rcp.commands.runtimecommands.DefineCommands" in this menu contribution.

Create the following class.

package de.vogella.rcp.commands.runtimecommands;

import org.eclipse.swt.SWT;
import org.eclipse.ui.menus.CommandContributionItem;
import org.eclipse.ui.menus.CommandContributionItemParameter;
import org.eclipse.ui.menus.ExtensionContributionFactory;
import org.eclipse.ui.menus.IContributionRoot;
import org.eclipse.ui.services.IServiceLocator;

public class DefineCommands extends ExtensionContributionFactory {

  @Override
  public void createContributionItems(IServiceLocator serviceLocator,
      IContributionRoot additions) {
    CommandContributionItemParameter p = new CommandContributionItemParameter(serviceLocator, "",
        "org.eclipse.ui.file.exit",
        SWT.PUSH);
    p.label = "Exit the application";
    p.icon = Activator.getImageDescriptor("icons/alt_window_16.gif");

    CommandContributionItem item = new CommandContributionItem(p);
    item.setVisible(true);
    additions.addContributionItem(item, null);
  }

} 

Run the example, your application should have the Exit command in the menu.

7. About this website

8. Links and Literature

8.1. Eclipse Commands Resources

http://wiki.eclipse.org/Platform_Command_Framework Command Framework wiki

http://wiki.eclipse.org/Command_Core_Expressions Commands Core Expressions

http://blog.eclipse-tips.com/2009/03/commands-part-6-toggle-radio-menu.html Blog series about Eclipse Command from Prakash G.R.

http://hermanlintvelt.blogspot.com/2009/06/eclipse-rcp-commands-part-3-visiblewhen.html Blog series about Eclipse Command from Herman Lintvelt

8.2. vogella GmbH training and consulting support

TRAINING SERVICE & SUPPORT
The vogella company provides comprehensive training and education services from experts in the areas of Eclipse RCP, Android, Git, Java, Gradle and Spring. We offer both public and inhouse training. Whichever course you decide to take, you are guaranteed to experience what many before you refer to as “The best IT class I have ever attended”. The vogella company offers expert consulting services, development support and coaching. Our customers range from Fortune 100 corporations to individual developers.