A command in Eclipse is a declarative description of a component and is independent from the implementation details.

A command can be categorized, assigned to the user interface and a key binding can be defined for the command. The behavior of a command is defined via a handler.

To define a command you create an extension to the org.eclipse.ui.command extension point.

The org.eclipse.ui.menu extension point is used to define where the command is visible in the application, e.g., you could define that the command is visible in the application menu or in a view menu.

The menuContribution contribution has an ID value which allow to identify the contribution.

menuContribution has an locationURI attribute which allows to define where in the user interface a command is displayed. This different attribute values are summarized in the following table.

Frequently you want to position a new command behind or before another command. For example the Save All menu entry should be positioned after the Save menu entry.

You can define the relative position of a command in this locationURI by using the pattern ?before=ID or ?after=ID.

The ID can be an existing separator name, menu ID, or item ID. The command will then be placed before or after the element with the corresponding ID.

For example if you want to add a command to an existing menu with the fileMenu ID behind the menu entry with the oneEntry ID use the menu:fileMenu?after=oneEntry locationURI .

The org.eclipse.ui.handlers extension point connects the command to a certain class which is called once the command is executed.

The behavior of a command is defined via handlers. The handler is the class which is executed once the command is called and must implement the IHandler interface from the org.eclipse.core.commands package.

In most cases you extend the org.eclipse.core.commands.AbstractHandler class which provides a default implementation for the IHandler interface.

The execute() method is called if the handler is executed.

In the execute() method you get access to frequently used values and services via the HandlerUtil class.

Handler can be defined with conditions (activeWhen) under which define the conditions under which the handlers are valid for a command. You can define several handlers for a command but only handler can be valid for a command at a certain point. Otherwise the Eclipse runtime will not enabled the command.

We will create a command which will exit the application. Create a new RCP project "de.vogella.rcp.commands.first" using the "Hello RCP" template. Click on the plugin.xml and select the Extensions tab. Press the Add... button.

Search for the extension "org.eclipse.ui.commands". Select it and press finish.

Create a new command by right-click on your extension point and by selecting New -> command.

Set the ID to "de.vogella.rcp.commands.first.commands.Exit" and the name to "Exit". Enter the class "de.vogella.rcp.commands.first.commands.ExitHandler" as defaultHandler.

Press the hyperlink "defaultHandler" to create the class which should extend "org.eclipse.core.commands.AbstractHandler".

package de.vogella.rcp.commands.first.commands;

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

public class ExitHandler extends AbstractHandler {

  @Override
  public Object execute(ExecutionEvent event) throws ExecutionException {
    HandlerUtil.getActiveWorkbenchWindow(event).close();
    return null;
  }

} 

The command which we defined should be used in a menu. Add a extension to the org.eclipse.ui.menus extension point. Right-click on the extension point and select New → menuContribution.

Create a new menu contribution with the "menu:org.eclipse.ui.main.menu" locationURI. Make sure this URL is correct spelled, otherwise your menu will not be shown.

Right-click your menucontribution and select New → Menu. Add a menu with the "File" label and the "fileMenu" ID.

Select your menu, right-click on it, select New-> Command. Maintain your commandID. Set the label to "Exit" and the tooltip to "Exits the application".

This should result in a plugin.xml file which looks like the following.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>

   <extension
         id="application"
         point="org.eclipse.core.runtime.applications">
      <application>
         <run
               class="de.vogella.rcp.commands.first.Application">
         </run>
      </application>
   </extension>
   <extension
         point="org.eclipse.ui.perspectives">
      <perspective
            name="RCP Perspective"
            class="de.vogella.rcp.commands.first.Perspective"
            id="de.vogella.rcp.commands.first.perspective">
      </perspective>
   </extension>
   <extension
         point="org.eclipse.ui.commands">
      <command
            defaultHandler="de.vogella.rcp.commands.first.commands.ExitHandler"
            id="de.vogella.rcp.commands.first.commands.Exit"
            name="Exit">
      </command>
   </extension>
   <extension
         point="org.eclipse.ui.menus">
      <menuContribution
            locationURI="menu:org.eclipse.ui.main.menu">
         <menu
               id="fileMenu"
               label="File">
            <command
                  commandId="de.vogella.rcp.commands.first.commands.Exit"
                  label="Exit"
                  style="push"
                  tooltip="Exit the application">
            </command>
         </menu>
      </menuContribution>
   </extension>

</plugin> 

Run the example. You should see menu with the file and if you select the "Exit" entry you application should exit.

You can add commands to the application toolbar and to a view toolbar.

Create a new project "de.vogella.rcp.intro.commands.toolbar". Use the "RCP application with a view" as a template. Create a command "de.vogella.rcp.intro.commands.toolbar.Hello" with the default handler "de.vogella.rcp.intro.commands.toolbar.handler.Hello". This handler will open a JFace Dialog.

package de.vogella.rcp.intro.commands.toolbar.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 Hello extends AbstractHandler {

  @Override
  public Object execute(ExecutionEvent event) throws ExecutionException {
    MessageDialog.openInformation(HandlerUtil.getActiveWorkbenchWindow(event).getShell(), "Info", "Info for you");
    return null;
  }

} 

Add a menucontribution to the "org.eclipse.ui.menus extension" point. Set the location URI to "toolbar:org.eclipse.ui.main.toolbar". Add a toolbar to your menu contribution.

Add the command "de.vogella.rcp.intro.commands.toolbar.Hello" to the toolbar. Assign a label and an icon to it.

Activate the application toolbar via ApplicationWorkbenchWindowAdvisor.java and set the configurer.setShowCoolBar(true); (

package de.vogella.rcp.intro.commands.toolbar;

import org.eclipse.swt.graphics.Point;
import org.eclipse.ui.application.ActionBarAdvisor;
import org.eclipse.ui.application.IActionBarConfigurer;
import org.eclipse.ui.application.IWorkbenchWindowConfigurer;
import org.eclipse.ui.application.WorkbenchWindowAdvisor;

public class ApplicationWorkbenchWindowAdvisor extends WorkbenchWindowAdvisor {

  public ApplicationWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer configurer) {
    super(configurer);
  }

  public ActionBarAdvisor createActionBarAdvisor(IActionBarConfigurer configurer) {
    return new ApplicationActionBarAdvisor(configurer);
  }

  public void preWindowOpen() {
    IWorkbenchWindowConfigurer configurer = getWindowConfigurer();
    configurer.setInitialSize(new Point(400, 300));
    configurer.setShowStatusLine(false);
    configurer.setShowCoolBar(true);
    configurer.setTitle("RCP Application");
  }
} 

The result should look like the following. If you select the element in the toolbar an information dialog should open.

You can also add a command directly to a view toolbar. For this we will extend the previous example. Change the class "Perspective" to the following (a stand-alone view does not have a own toolbar).

package de.vogella.rcp.intro.commands.toolbar;

import org.eclipse.ui.IPageLayout;
import org.eclipse.ui.IPerspectiveFactory;

public class Perspective implements IPerspectiveFactory {

  public void createInitialLayout(IPageLayout layout) {
    String editorArea = layout.getEditorArea();
    layout.setEditorAreaVisible(false);
    layout.setFixed(true);

    layout.addView(View.ID, IPageLayout.LEFT, 1.0f, editorArea);
  }

} 

Create a new menu contribution to the extension point "org.eclipse.ui.menus" with the locationURI: "toolbar:de.vogella.rcp.intro.commands.toolbar.view". ""toolbar:"" tells the system to add it to the toolbar while the second argument is the id of your view.

Create then a new command for this menucontribution and set the command id to "de.vogella.rcp.intro.commands.toolbar.Hello". Assign the label "Say Hello" to it.

Run the application to see your new view contribution.

The following adds a dropdown list to the application coolbar.

This creation is a bit strange. You create a helper drop-down command to which later the other (real) commands will be assigned to.

Therefore create a command with the id "referenceToMenuId". Maintain also the default handler. For example you could reuse "de.vogella.rcp.intro.commands.toolbar.handler.Hello".

Add a new menucontribution to the "org.eclipse.ui.menus" extension point. Set the location URI to "toolbar:org.eclipse.ui.main.toolbar". Add a toolbar to this extension and a new command to this new toolbar. As the id use "referenceToMenuId" give it a label and an icon and change the style to "pulldown".

Create a new menucontribution and set the locationURI to: "menu:referenceToMenuId"

Add your exiting command "de.vogella.rcp.intro.commands.toolbar.Hello" two times to this menu. Use different labels.

Run your application, it should now have a drop-down list in the application toolbar.

Please consider a contribution if this article helped you. It will help to maintain our content and our Open Source activities.

Writing and updating these tutorials is a lot of work. If this free community service was helpful, you can support the cause by giving a tip as well as reporting typos and factual errors.

If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.

This tutorial is Open Content under the CC BY-NC-SA 3.0 DE license. Source code in this tutorial is distributed under the Eclipse Public License. See the vogella License page for details on the terms of reuse.

Source Code of Examples

Eclipse Commands Advanced

Key bindings for Commands

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

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