Time for action – creating commands and handlers

Commands and handlers are common to both Eclipse 3.x and the Eclipse 4 model. In Eclipse 3.x, they are represented as extension points in the plugin.xml file under org.eclipse.ui.commands. In Eclipse 4, they are stored in the E4 fragment file.

A command will be created to represent saying "hello world," and a handler will be created to display the message. These will then be used to add a menu item to execute the operation.

1. Open the fragment for the project, or double-click on the fragment.e4xmi file.

   Tip

   This should open a model editor; if it opens plain XML content, then verify that the E4 tools have been installed correctly.

2. Select the Model Fragment Definition element and click on Add to create a new fragment. Fill in the fields as follows:
   1. Extended Element ID: org.eclipse.e4.legacy.ide.application (this can be found under the Container-Type: Application from the search field)
   2. Feature Name: commands
   
3. Select the newly created Model Fragment if it is not already selected.
4. Choose Command from the dropdown and click on Add. Fill in the fields as follows:
   1. ID: com.packtpub.e4.clock.ui.command.hello
   2. Name: Hello
   3. Description: Says Hello World
   
5. This creates a command that is just an identifier and a name. To specify what it does, it must be connected to a handler, which is done by adding another model fragment. Right-click on the Model Fragments and add a Model Fragment child, using the Extended Element ID org.eclipse.e4.legacy.ide.application, but this time with the Feature Name handlers.
6. Choose Handler from the dropdown and click on Add. Fill in the fields as follows, using the Find... buttons next to the fields to find the elements:
   1. ID: com.packtpub.e4.clock.ui.handler.HelloHandler
   2. Command: Hello – com.packtpub.e4.clock.ui.command.hello
   3. Class URI: bundleclass://com.packtpub.e4.clock.ui/com.packtub.e4.clock.ui.handlers.HleloHandler
   
7. To create a new class, click on Class URI and fill in the fields as follows:
   1. Source folder: com.packtpub.e4.clock.ui/src
   2. Package: com.packtpub.e4.clock.ui.handlers
   3. Name: HelloHandler
   4. Execute Method: execute
   
8. The handler joins the processing of the command. In Eclipse 3.x, this was a class that implemented IHandler (typically AbstractHandler); but in Eclipse 4, this interface is no longer necessary. Implement the class HelloHandler as follows:

   package com.packtpub.e4.clock.ui.handlers;
   import org.eclipse.e4.core.di.annotations.Execute;
   public class HelloHandler {
     public void execute() {
       MessageDialog.openInformation(null, "Hello", "World");
     }
   }

9. The command's ID com.packtpub.e4.clock.ui.command.hello is used to refer to it from menus or other locations. To place the contribution in an existing menu structure, it needs to be added as a menuContribution. Create a new Model Fragment using the Extended Element ID org.eclipse.e4.legacy.ide.application and Feature Name handlers.
10. Select the newly created Model Fragment, choose Menu Contribution from the dropdown, and click on Add. Ensure that the Parent-ID is set to help.
11. Select the newly created Menu Contribution, select Handled Menu Item from the dropdown, and click on Add. Fill in the fields as follows:
    1. ID: com.packtpub.e4.clock.ui.handledmenuitem.Hello
    2. Label: Hello
    3. Command: Hello – com.packtpub.e4.clock.ui.command.hello
    
12. Run the target Eclipse instance, and there will be a Hello menu item under the Help menu. When selected, it will pop up the Hello World message.

    Tip

    If the menu isn't shown, go to the Run | Run Configurations… menu and ensure that the Clear button is selected, to reset the Eclipse instance in order to merge the E4 fragment. Typically this fixes problems where changes to the E4 model aren't seen.

    

What just happened?

Eclipse 3.x introduced the concept of commands and handlers as a means of separating their interface from their implementation. This allows a generic command (such as Copy) to be overridden by specific views. Unlike the traditional command design pattern, which provides implementation as subclasses, the Command in Eclipse uses a retargetable handler to perform the actual execution. In Eclipse 4, the concepts of commands and handlers are used extensively to provide the components of the user interface. The key difference is in their definition; for Eclipse 3.x, this typically occurs in the plugin.xml, whereas in Eclipse 4, it is part of the application model.

In the example, a specific handler was defined for the command, which is valid in all contexts. The handler's class is the implementation; the command ID is the reference.

The menuContributions fragment entry allows menus to be added anywhere in the user interface. The parent defines where the menu item can be created. The syntax for the parent is as follows:

• identifier: This can be a known short name (such as file, window, or help), the global menu (org.eclipse.ui.main.menu), the global toolbar (org.eclipse.ui.main.toolbar), a view identifier (org.eclipse.ui.views.ContentOutline), or an ID explicitly defined in a popup menu's registerContextMenu call
• ?after|before=key: This is a placement instruction to put this after or before other items; typically additions is used as an extensible location for others to contribute to

This allows plug-ins to contribute to other menus, regardless of where they are ultimately located.