Skip Navigation

Creating a Command and a Handler

The procedures in this topic show how to create a command and handler. Before you begin, either create a new plug-in project or use an existing project.

  1. Open your project in Eclipse Package Explorer view.

Adding a New Command Using the org.eclipse.ui.commands Extension Point

  1. Open the Extensions tab.

image038

 

  1. Click Add to display the New Extension dialog.

image024

 

  1. Remove the selection from the Show only extension points from the required plug-ins check box.

  2. In the Extension Point Filter field, type org.eclipse.ui.commands.

You can type either the complete name or * followed by the partial name to display a list of names that contain the characters you enter. Select the name when it appears in the list.

  1. Click Finish.

  1. If the New Plug-in Dependency dialog appears, click Yes.

image005

        Eclipse adds the commands extension point to the Extensions tab.

image044

 

  1. Right-click org.eclipse.ui.commands, and then choose New > command.

image046

 

  1. In Extension Element Details, provide properties to the command element in the following fields.

id

The default id consists of the project name and the extension type. Eclipse uses this name across the application.
Common practice is to enter the fully-qualified project name or project id followed by the type of extension point that you are adding. This identifies the extension point for this command.
The sample uses com.sabre.redapp.example.view.basic.SampleCommand.

name

This is the name of an instance for the extension point that is in the id field. This name appears to end-users on the GUI. It is also displayed on the extensions list.
Common practice is to use the imperative form of a verb for a command name, for example, Save or Add.
Enter the name of your choice.
The sample uses Sample Command.

Adding a New Handler Using the org.eclipse.ui.handlers Handler Extension Point

  1. On the Extensions tab, click Add to display the New Extension dialog.

image050

 

  1. Remove the selection from Show Only Extension Points from the Required Plug-ins. This lets Eclipse provide all extension points.

  1. Add a new extension point. In the Extension Point Filter field, type org.eclipse.ui.handlers. Click Finish.

        Eclipse adds the handlers extension point and a handler command to the Extensions tab.

image052

 

Next, set the properties for the handler in Extension Element Details.

image054

 

  1. The value in the commandId field must be the value for id that you typed when you added org.eclipse.ui.commands. It consists of the package name plus the command type.

        In the commandId field, either type the name of the command, or click Browse to select it from the Select Identifier dialog.

        In the sample, this value is com.sabre.redapp.example.view.basic.SampleCommand .

Adding a Class for the Handler

For an object that is not an editor, you must create a handler. Next, you generate a new class for the handler and then extend org.eclipse.core.commands.AbstractHandler .

If you intend to create an editor, bypass this step.

  1. In Extension Element Details, click the class link. Eclipse displays the New Java Class dialog.

image056

        Eclipse populates most of the fields automatically.

  1. If the Package field is not populated, type the package name.

  1. In the Name field, type a name for your handler. The class name must be in the format xxxHandler, where Handler is the class type. In the sample, this is SampleHandler.

  2. In Superclass, type org.eclipse.core.commands.AbstractHandler. This handler class handles commands.

  3. Select the following check boxes:

    • Constructors from superclass

    • Inherited abstract methods

  1. Click Finish. Eclipse generates a class for the handler and updates MANIFEST.MF automatically.

The Java code for SampleHandler is shown below.

package com.sabre.redapp.example.view.basic;

import org.eclipse.core.commands.AbstractHandler;
import org.eclipse.core.commands.ExecutionEvent;
import org.eclipse.core.commands.ExecutionException;
import org.eclipse.core.commands.IHandler;

public class SampleHandler extends AbstractHandler implements IHandler
{

    @Override
    public Object execute(ExecutionEvent event) throws ExecutionException
    {
        /* Put your code here */
        return null;
    }
}

 

  1. Enter the code for your handler in the execute() method.

        This handler is called every time the command that you defined is triggered.

  1. When you are done, save MANIFEST.MF.

Although you created the command and handler, they are not functional until you bind the command to the proper extension in MANIFEST.MF so that the command can be triggered.