Command Handler Guide for Eclipse

Introduction to Command Handlers in Eclipse

A command is the declaration of a behavior by id.  Commands are used to declare semantic behavior and the corresponding action implementations can be defined elsewhere by handlers.

There are several advantages of command handlers:

• Defining menu contribution and commands uses same set of extensions points for multiple scenarios.
• UI and handling are not tied, like in Actions framework.
• Multiple handler declarations for the same command with activeWhen and enableWhen conditions defined.

Complete the following steps to contribute a menu and define its action through command-handlers:

1. Define the menu contribution—find the right locationURI
2. Define the command id—required label, icon, tooltip
3. Define the command extension—with/without default handler
4. Define the handler extension—if default handler was not defined

A simple example of menu contributions

Sample Menu Contributions

Use the following table to view sample menu contributions.  Refer to the image that follows the table to view where the menu contributions appear in the RCP application; the corresponding example number is listed in the table.

Note: The required command and handler extension code is given after the table and images. 

<extension

     point="org.eclipse.ui.menus">

  <menuContribution

        allPopups="false"

        locationURI="toolbar:org.eclipse.ui.main.toolbar">

     <toolbar

           id="demo.rcp.search.toolbar"

           label="Search toolbar">

     <command

           commandId="rcp.demo.actions.searchcommand"

           icon="icons/search.png"

           label="Search Files"

           style="push"

           tooltip="Search files">

     </command>

     </toolbar>

  </menuContribution>

<menuContribution

        locationURI="popup:RCP2.DemoView?after=additions">

     <command

           commandId="rcp.demo.actions.runcommand"

           label="Run"

           style="push"

           icon="icons/search.png">

     </command>

  </menuContribution>

<menuContribution

        allPopups="false"

        locationURI="toolbar:RCP2.DemoView?after=additions">

     <command

           commandId="rcp.demo.actions.searchcommand"

           label="Search"

           icon="icons/search.png"

           tooltip="Search files"

           style="push">

     </command>

   </menuContribution>

<menuContribution

        allPopups="false"

        locationURI="menu:org.eclipse.ui.main.menu">

     <menu

           id="demo.rcp.search.menubar"          

           label="Search">       <!-- main menu -->

     <command

           commandId="rcp.demo.actions.searchcommand"    

           icon="icons/search.png"

           label="Search Files"   

           style="push"

           tooltip="Search files">      <!-- Sub menu -->

     </command>

     </menu>

  </menuContribution>



main menu action

<menuContribution

        allPopups="false"

        locationURI="menu:org.eclipse.ui.main.menu">

     <command

           commandId="rcp.demo.actions.MyProductCommand"

           label="Application Info"

           style="push">

     </command>

  </menuContribution>

View Sample Menu Contributions

Examples of menu contributions

Defining Command and Handler Extension Points

In the examples below, the `rcp.demo.actions.searchcommand` command is defined a defaultHandler, whereas the `rcp.demo.actions.runcommand` command defines its handler using the `org.eclipse.ui.handlers` extension. Using the second method, we can define multiple handlers for the same command based on condition and also have more control when the handler has to be active based on the conditions defined.

Note: Additional details can be found at dzone.com and eclipse.org.

  <extension

     point="org.eclipse.ui.commands">

      <command

        defaultHandler="rcp2.handlers.SearchCommandHandler"

        id="rcp.demo.actions.searchcommand"

        name="Search Command Handler">

      </command>

      <command

        id="rcp.demo.actions.runcommand"

        name="Run Command Handler">

      </command>     

  </extension>

  <extension

     point="org.eclipse.ui.handlers">

  <handler

        class="rcp2.handlers.RunCommandHandler"

        commandId="rcp.demo.actions.runcommand">

  </handler>

  </extension>

Handler class

package rcp2.handlers;



import org.eclipse.core.commands.AbstractHandler;

import org.eclipse.core.commands.ExecutionEvent;

import org.eclipse.core.commands.ExecutionException;



public class RunCommandHandler extends AbstractHandler {

   @Override

   public Object execute(ExecutionEvent arg0) throws ExecutionException {

   // Define the required actions here

   return null;

   }

}

Let Us Hear from You!

If you have any comments or questions, we would love to hear from you @MyEclipseIDE on twitter or via the MyEclipse forum.