NOW Hiring

Quick links

Eclipse RCP (Rich Client Platform) - Tutorial

Lars Vogel

Version 7.1


Building Eclipse based applications

This tutorial gives an overview about the Eclipse application platform using the Eclipse 4 (e4) programming model.

This tutorial describes the creation of Eclipse based applications, e.g., Eclipse RCP applications. It describes the modeled application concept and the new programming model which is based on annotations and dependency injection.

Table of Contents

1. What is an Eclipse RCP application?
2. The Architecture of Eclipse
2.1. Architecture of Eclipse based applications
2.2. Core components of the Eclipse platform
2.3. Eclipse API and internal API
2.4. Important configuration files for Eclipse plug-ins
3. Download the Eclipse Software Development Kit (SDK)
4. Install the e4 tools
4.1. Install the e4 tools
4.2. Install the e4 spies from
5. Exercise: Wizard to create an RCP application
5.1. Target
5.2. Create project
5.3. Launch your Eclipse application via the product file
5.4. Validating
6. The usage of run configurations
6.1. What are run configurations?
6.2. Reviewing run configurations
6.3. Run arguments
7. Launch configuration and Eclipse products
8. Common launch problems
8.1. Checklist for common launch problems
8.2. Finding missing plug-in dependencies during a product launch
9. Eclipse 4 application model
9.1. What is the application model?
9.2. Connecting model elements to classes and resources
9.3. Runtime application model
10. User interface model elements
10.1. Window
10.2. Parts
10.3. Available part containers
10.4. Perspective
11. Overview of available model objects
12. Features and Products
13. Exercise: Create an Eclipse plug-in
13.1. Target
13.2. Creating a plug-in project
13.3. Validate the result
14. Exercise: From plug-in to Eclipse 4 application
14.1. Target
14.2. Create a project to host the product configuration file
14.3. Create a product configuration file
14.4. Configure the start levels
14.5. Create a feature project
14.6. Enter the feature as content into the product
14.7. Remove the version dependency from the features in the product
14.8. Create an application model
14.9. Add a window to the application model
14.10. Start the application
15. Exercise: Configure the deletion of persisted model data
15.1. Delete the persisted user changes at startup
15.2. Why is this setting necessary?
16. Exercise: Modeling a User Interface
16.1. Desired user interface
16.2. Open the Application.e4xmi file
16.3. Add a perspective
16.4. Add part sash and part stack containers
16.5. Create the parts
16.6. Validate the user interface
17. Enter the dependencies
17.1. Add the plug-in dependencies
17.2. Validating
18. Exercise: Connect Java classes with the parts
18.1. Create a new package and some Java classes
18.2. Connect the Java classes with your parts
18.3. Validating
19. Exercise: Using the SWT browser widget
19.1. Implementation
19.2. Solution
20. Introduction to dependency injection
21. Dependency injection and annotations
21.1. Define class dependencies in Eclipse
21.2. Annotations to define class dependencies in Eclipse
21.3. On which objects does Eclipse perform dependency injection?
21.4. Dynamic dependency injection based on key / value changes
22. The Eclipse context
22.1. What is the Eclipse context?
22.2. Relationship definition in the Eclipse context
22.3. Which model elements have a local context?
22.4. Life cycle of the Eclipse context
23. Objects available for dependency injection
23.1. How are objects selected for dependency injection
23.2. How to access the model objects?
23.3. Default entries in the Eclipse context
23.4. Qualifiers for accessing the active part or shell
23.5. Tracking a child context with @Active
24. Using annotations to define behavior
24.1. API definition
24.2. API definition via inheritance
24.3. API definition via annotations
24.4. Behavior annotations imply method dependency injection
24.5. Use the @PostConstruct method to build the user interface
24.6. Why is the @PostConstruct method not called?
25. Exercise: Using @PostConstruct
25.1. Implement an @PostConstruct method
25.2. Validating
26. Menu and toolbar application objects
26.1. Adding menu and toolbar entries
26.2. The usage of commands and handlers
26.3. Behavior annotations and dependency injection for handler classes
26.4. Determining the relevant handler for a command
26.5. Evaluation of @CanExecute
26.6. Mnemonics
26.7. Naming schema for command and handler IDs
27. Exercise: Adding menus
27.1. Target of this exercise
27.2. Create command model elements
27.3. Creating the handler classes
27.4. Creating handler model elements
27.5. Adding a menu
27.6. Implement a handler class for exit
27.7. Validating
27.8. Possible issue: Exit menu entry on a MacOS
28. Exercise: Adding a toolbar
28.1. Target of this exercise
28.2. Adding a toolbar
28.3. Validating
29. View, popup and dynamic menus
29.1. View menus
29.2. Popup menu (context menu)
29.3. Dynamic menu and toolbar entries
30. Toolbars, ToolControls and drop-down tool items
30.1. Adding toolbars to parts
30.2. ToolControls
30.3. Drop-down tool items
31. More on commands and handlers
31.1. Passing parameters to commands
31.2. Usage of core expressions
31.3. Evaluate your own values in core expressions
32. Key bindings
32.1. Using key bindings in your application
32.2. JFace default values for binding contexts
32.3. Define Shortcuts
32.4. Activate bindings
32.5. Key bindings for a part
33. Enable to start your product with right mouse click
34. Learn more about Eclipse 4 RCP development
35. About this website
36. Links and Literature
36.1. Eclipse RCP resources
Get the book! Eclipse RCP book

1. What is an Eclipse RCP application?

An Eclipse RCP application is a stand-alone application based on Eclipse platform technologies. This book uses the terms Eclipse based applications, Eclipse application, Eclipse 4 application and Eclipse RCP application interchangeably for referring to such applications.

2. The Architecture of Eclipse

2.1. Architecture of Eclipse based applications

An Eclipse application consists of individual software components. The Eclipse IDE can be viewed as a special Eclipse application with the focus on supporting software development.

The core components of the Eclipse IDE are depicted in the following graphic. The intention of the graphic is to demonstrate the general concept, the displayed relationships are not 100% accurate.

Important Eclipse IDE components

The most important Eclipse components of this graphic are described in the next section. On top of these base components, the Eclipse IDE adds additional components which are important for an IDE application, for example, the Java development tools (JDT) or version control support (EGit).

An Eclipse RCP application typically uses the same base components of the Eclipse platform and adds additional application specific components as depicted in the following graphic.

Typical components of an Eclipse RCP application

2.2. Core components of the Eclipse platform

OSGi is a specification to describe a modular approach to develop component-based Java applications. The programming model of OSGi allows you to define dynamic software components, i.e., OSGi services. Equinox is one implementation of the OSGi specification and is used by the Eclipse platform as its runtime. This Equinox runtime provides the necessary API's and framework to run a modular Eclipse application.

SWT is the standard user interface component library used by Eclipse. JFace provides some convenient APIs on top of SWT. The workbench provides the framework for the application. It is responsible for displaying all other user interface components.

EMF is the Eclipse Modeling Framework which provides functionality to model a data model and to use this data model at runtime.

2.3. Eclipse API and internal API

An OSGi runtime allows the developer to mark Java packages as public, provisional or internal APIs. The internal API is private, therefore not visible. The provisional API are to test non-finalized APIs, therefore are visible but non-stable. The public API, or simply API, are the visible and stable API, that can be reused by other components.

API definition in Eclipse

The Eclipse platform project marks packages either as public API or as provisional API, to make all Java classes accessible to Eclipse developers. If the Eclipse platform project releases an API, the platform project plans to keep this API stable for as long as possible.

If API is internal but accessible, i.e., marked as provisional, the platform team can change this API in the future. If you use such API, you must be prepared that you might have to make some adjustments to your application in a future Eclipse release.

If you use unreleased API, you see a Discouraged access: The not API (restriction on required project ...) warning in the Java editor.


You can turn off these warnings for your workspace via WindowPreferencesJavaCompilerErrors/Warnings and by setting the Discouraged reference (access rules) flag to Ignore.

Turning of the Eclipse warnings

Alternatively you can turn off these warnings on a per project basis, via right-click on the project PropertiesJava Compiler and afterwards use the same path as for accessing the global settings. You might have to activate the Enable project specific settings checkbox at the top of the Error/Warnings preference page.

2.4. Important configuration files for Eclipse plug-ins

An Eclipse plug-in has the following main configuration files. These files are defining the API, and the dependencies of the plug-in.

  • MANIFEST.MF - contains the OSGi configuration information.

  • plugin.xml - optional configuration file, contains information about Eclipse specific extension mechanisms.

An Eclipse plug-in defines its meta data, like its unique identifier, its exported API and its dependencies via the MANIFEST.MF file.

The plugin.xml file provides the possibility to create and contribute to Eclipse specific API. You can add extension points and extensions in this file. Extension-points define interfaces for other plug-ins to contribute functionality. Extensions contribute functionality to these interfaces. Functionality can be code and non-code based. For example a plug-in might contain help content.

3. Download the Eclipse Software Development Kit (SDK)

The following description is based on the latest Eclipse 4.6 release. Download the latest version of the Eclipse SDK build from the following URL:

This website should look similar to the following screenshot. Click on the link of the latest released version (the release version with the highest number) to get to the download section. Download Page

The download is a compressed archive of multiple files. This format depends on you platform, Windows the zip format, while Linux and Mac OS uses the tar.gz format.

4. Install the e4 tools

4.1. Install the e4 tools

The e4 tools provide the tools to develop Eclipse 4 RCP applications. These tools provide wizards to create Eclipse application artifacts and an application model editor. They can be installed into the Eclipse SDK via the Eclipse default update site.

Install the Eclipse 4 tooling

Install the tools and restart your Eclipse IDE after the installation.

4.2. Install the e4 spies from

You can use the following URL to install the latest tools:

Other versions of the tools can can be found on the e4tools site. If you click on a Build Name link, you also find the URL for the update site. The following screenshots demonstrate this for a particular build of the e4 tools. Note, that this website might change over time.

Official update site for e4 tools part 1

Official update site for e4 tools part 2

5. Exercise: Wizard to create an RCP application

5.1. Target

The following exercise demonstrates how to create an Eclipse RCP application based on a template. It also shows how to start the application via the Eclipse IDE. You learn all the details of what happened here in later chapters.

5.2. Create project

Select FileNewOther...Plug-in DevelopmentPlug-in Project from the menu of your Eclipse IDE.

Create a project called com.example.e4.rcp.wizard. Use the settings similar to the following screenshots, most of them are the default settings.

On the last wizard page, select the Create sample content (parts, menu etc.) flag. Via this flag you configure that the generated application has example content, e.g., a view and some menu and toolbar entries.


The wizard adds also the clearPersistedState flag to the product configuration file. This ensures that changes during development in your application model are always visible. See Section 15.1, “Delete the persisted user changes at startup” for more information.

5.3. Launch your Eclipse application via the product file

Open the generated product file by double-clicking on the file.

Starting the Eclipse 4 application

Switch to the Overview tab in the editor and launch your Eclipse application by pressing the Launch an Eclipse application hyperlink. This selection is highlighted in the following screenshot.

Starting the Eclipse 4 application

5.4. Validating

As a result your Eclipse application should start. The application should look similar to the following screenshot.

6. The usage of run configurations

6.1. What are run configurations?

A run configuration defines the environment which will be used to execute a generic launch. For example, it defines arguments to the Java virtual machine (VM), plug-in (classpath) dependencies, etc.

If you start an Eclipse application the corresponding run configuration is automatically created or updated.


If you are starting an Eclipse runtime IDE for testing, and clear the workspace location the next run will prompt you to choose a workspace.

6.2. Reviewing run configurations

To review and edit your run configurations select RunRun Configurations... from the Eclipse menu.

On the Main tab in the field Location, you specify where the Eclipse IDE creates the files necessary to start your Eclipse based application.

Shows the run configuration, highlighting the location setting

6.3. Run arguments

The run configuration allows you to add additional start arguments for your application on the Arguments tab. By default Eclipse includes already several parameters, e.g. parameters for -os, -ws and -arch to specify the architecture on which the application is running.

-consoleLog in the run configuration


To pass system properties to your Eclipse application, you can add launch parameters using the -D switch. As example, if you add the argument -Dmy.product.loglevel=INFO, you can get the "INFO" value with System.getProperties("my.product.loglevel").

The following table lists several useful launch arguments.

Table 1. Launch parameters

Parameter Description
consoleLog Error messages of the running Eclipse application are written to standard-out (System.out) which can be viewed in the Eclipse IDE Console view that started the RCP application.

Specifies the locale used for your application. The locale defines the language specific settings, i.e., which translation is used and the number, date and currency formatting.

For example -nl en starts your application using the English language. This is useful for testing translations.

console Provides access to an OSGi console where you can check the status of your application.
noExit Keeps the OSGi console open even if the application crashes. This allows to analyze the application dependencies even if the application crashes during startup.
clearPersistedState Deletes cached runtime changes of the Eclipse 4 application model.

7. Launch configuration and Eclipse products

The launch configuration stores the settings from the product configuration file. The launch configuration is created or updated every time you start your application via the product.

You can use the created run configuration directly for starting the application again. In this case changes in the product configuration file are not considered.


Using an existing run configuration is a common source of frustration and time consuming error analysis. To ensure that you use the latest configuration from your product, start your application via the product file.

8. Common launch problems

8.1. Checklist for common launch problems

Errors in the run configurations of Eclipse RCP application are frequently the source of problems. This chapter describes common problems related to the start of RCP applications. It can be used as a reference in case you face issues during the startup of your application. The following table lists potential problems and solutions.

Table 2. Run configuration problems

Problem Investigate
"Could not resolve module" message during start up.

Check that all required plug-ins are included in your product configuration. Make sure that your product defines dependencies to all required plug-ins or features. See Section 8.2, “Finding missing plug-in dependencies during a product launch ”

Bundles may also require a certain version of the Java virtual machine, e.g., a bundle may require Java 1.6 and will therefore not load in a Java 1.5 VM. Check the MANIFEST.MF file on the Overview tab in the Execution Environments section which Java version is required.

""java.lang.RuntimeException: No application id has been found." message during start up.

See "Could not resolve module" message during start up error. In most cases also triggered by a missing plug-in dependency.

Strange behavior but no error message. Check if your run configuration includes the -consoleLog parameter. This option allows you to see errors from Eclipse based applications in the Console view of the Eclipse IDE.
Runtime configuration is frequently missing required plug-ins Make sure that your product or your feature(s) includes all required dependencies.
A change in the product Dependencies tab is not reflected in the run configuration (e.g., a new plug-in is added but is not included in the run configuration) A product updates an existing run configuration if you start the product directly from the product definition file. If you select the run configuration directly, it will not be updated.
Application model changes are not reflected in the Eclipse 4 application.

Eclipse 4 persists user changes in the application in a delta file which is restored at startup. During development this might lead to situations where model changes are not correctly applied to the runtime model, e.g., you define a new menu entry and this entry is not displayed in your application.

Either set the Clear flag on the Main tab in your run configuration or add the clearPersistedState parameter for your product configuration file or run configuration.

Services, e.g., key bindings or the selection service, are not working in an Eclipse 4 application. In Eclipse releases before 4.3 every part needed to implement a @Focus method which places the focus on an SWT control. This error does not occur anymore with Eclipse 4.3 or a higher release.
Menu entries are disabled in the Eclipse application.

Ensure that the HandlerProcessingAddon class in the package org.eclipse.e4.ui.internal.workbench.addons is registered as model add-on. The bundle symbolic name is org.eclipse.e4.ui.workbench.

Application "org.eclipse.ant.core.antRunner" could not be found in the registry or Application could not be found in the registry. Ensure that you have pressed the New... button in the product configuration file and selected the E4Application as application to start. You can check the current setting in your plugin.xml file on the Extensions tab and in the details of the org.eclipse.core.runtime.products extension.

8.2. Finding missing plug-in dependencies during a product launch

The most common problem is that some required plug-ins are missing in your product. If you are using a feature based product configuration, you need to ensure that all plug-ins which are referred to in the MANIFEST.MF file are also included in your features. This error is reported in the Console view, typically it is one of the first error messages and you need to scroll up to see it.

The following listing shows how this message typically looks like (formating changed to make the text fit better).

   Could not resolve module: [9]
      Unresolved requirement: 

After identifying the missing plug-ins ensure that you add them to your product (if the product is plug-in based) or to your features (if the product is feature based).


Eclipse can check for missing dependencies automatically before you run the Launch configuration. On the Plug-ins Tab press the Validate Plug-ins button or select the Validate plug-ins automatically prior to launching option. This will check if you have all the required plug-ins in your run configuration.

Validating the runtime configuration

Avoid fixing problems with dependencies in the run configuration because the run configuration is created and updated based on the product configuration file. So always ensure that the product file is correctly configured instead of changing the derived information. The product configuration is used for the export of your product, hence an error in the product dependencies results in an exported application which cannot be started.

9. Eclipse 4 application model

9.1. What is the application model?

The Eclipse platform uses an abstract description, called the application model, to describe the structure of an application. This application model contains the visual elements as well as some non-visual elements of the application.

The visual parts are, for example, windows, parts (views and editors), menus, toolbars, etc. Examples for non-visual components are handlers, commands and key bindings.

Each model element has attributes which describe its current state, e.g. the size and the position of a window. The application model also expresses the relationship of the model elements via a hierarchy.

The individual user interface widgets, which are displayed in a part, are not defined via the application model, i.e., the content of the part is still defined by your source code. If the application model was a house, it would describe the available rooms (parts) and their arrangement (perspectives, part stacks, part sash containers), but not the furniture of the rooms. This is illustrated by the following image.

Limits of the modeled workbench

The base of the application model is typically defined as a static file. By default, it is called Application.e4xmi and located in the main directory of the plug-in which defines the product extension. This file is read at application startup and is used to construct the initial application model. Changes made by the user are persisted and re-applied at startup.

The application model is extensible, e.g., other plug-ins can contribute to it via model processors and model fragments.

9.2. Connecting model elements to classes and resources

Model elements can point to a class or to a static resource via a Uniform Resource Identifier (URI). For this purpose Eclipse defines two URI patterns. Eclipse instantiates the referred objects or resources in most cases lazily. For example, the classes for a part are instantiated when the part gets visible.

The following table describes the support URI patterns. The example assumes that the bundle is called test to have a short name.

Table 3. URI pattern

Pattern Description

bundleclass:// BSN/package.classname



Identifier for a Java class.

It consists of the following parts: bundleclass:// is a fixed prefix, BSN stands for Bundle-SymbolicName and is defined in a configuration file called MANIFEST.MF file. The Bundle-SymbolicName is followed by a '/' and the fully qualified classname.

platform:/plugin/ BSN/path/filename.extension



Used to identify resources.

Identifier for a resource in a plug-in. platform:/plugin/ is a fixed prefix, followed by the BSN stands for Bundle-SymbolicName as defined in the MANIFEST.MF file, followed by the path to the file and the filename.

For example a part, have a Class URI attribute which points to a Java class via the bundleclass:// URI. This class provides the behavior of the part. The corresponding object is created by the Eclipse framework. Using the house/rooms metaphor from earlier, the class is responsible for defining the furnishings, the layout of the room and how the interactive objects behave.

An example for a static resource reference is the the Icon URI attribute of a part. This attribute can point to an icon that is used for the part.

9.3. Runtime application model

At runtime of the application the created set of model objects is called the runtime application model. This runtime application model is dynamic, i.e., you can change the model objects and its attributes and these changes are reflected in your application. The Eclipse platform has change listeners registered on the model objects and updates the user interface whenever you change relevant attributes.

10. User interface model elements

The following model elements represents the basic elements which you use to create the user interface of your application.

10.1. Window

Eclipse applications consist of one or more windows. Typically, an application has only one window, but you are not limited to that, e.g., if you want to support multiple connected monitors.

Eclipse application showing 2 windows

10.2. Parts

Parts are user interface components which allow you to navigate and modify data. A part can have a drop-down menu, context menus and a toolbar. The Parts can be stacked or positioned next to each other depending on the container into which they are dropped.

Eclipse application with a few parts

Parts are typically classified as views and editors.

A view is typically used to work on a set of data, which might be a hierarchical structure. If data is changed via the view, this change is typically directly applied to the underlying data structure. A view sometimes allows the user to open an editor for the selected set of data. For example, the Package Explorer view allows you to browse the files of Eclipse projects. If you for example rename a file via the Package Explorer view, the file name is directly changed on the file system.

Editors are typically used to modify a single data element, e.g., the content of a file or a data object. To apply the changes made in an editor to the data structure, the user has to explicitly save the editor content.

For example, the Java editor is used to modify Java source files. Changes to the source file are applied once the user selects the Save button. A dirty editor tab is marked with an asterisk left to the name of the modified file.

Editor marked as dirty

10.3. Available part containers

Parts can be directly assigned to a window or a perspective. They can also be grouped and arranged via additional model elements, i.e., via part stack (Part Stack) or via part sash container (Part Sash Container) elements.

A part stack contains a stack of parts showing the content of one part while displaying only the headers of the other parts. One part is active and the user can switch to another part by selecting the corresponding tab.

A part sash container displays all its children at the same time either horizontally or vertically aligned.

The following screenshot shows a simple Eclipse application layout using two part sash container and three part stacks.

An example arrangement of Parts in an Eclipse application

On the top of this layout there is a horizontal part sash container which contains another part sash container and one part stacks. The part sash container on the next level contains two part stacks. The hierarchy is depicted in the following graphic.

The hierarchy of Parts using PartStacks and PartSashcontainers.

You can use the Container Data attribute on a child of a part sash container to assign a layout weight. This layout weight is interpreted as the relative space the corresponding child element should get assigned in the part sash container. The setting is depicted in the following screenshot.

Container data for layouting

If you set the Container Data for one element, you must define it for all the other elements, too. Otherwise the missing values are interpreted as very high and these elements take up all available space.


The initial total of all the container data values is maintained when elements in the sash are moved. In order to allow fine grained/smooth dragging this total must be similar to the screen resolution. A too low value (i.e., 50 / 50) causes the part to be moved multiple pixels per sash unit, which the user will realize as a jerky movement. Therefore, use a sufficient high value, e.g., 10000.

10.4. Perspective

A perspective is an optional container for a set of parts. Perspectives can be used to store different arrangements of parts. For example, the Eclipse IDE uses them to layout the views appropriate to the task (development, debugging, review, ...) the developer wants to perform.

You can place perspectives in a perspective stack of the application model. Switching perspectives can be done via the part service provided by the Eclipse platform.

11. Overview of available model objects

During startup the Eclipse framework parses the available information about the application model (Application.e4xmi, persisted user changes and model contributions) and stores this information in Java objects. These objects are called model objects and at runtime they represent the attributes from the model elements.

The following table lists the types of the important model objects.

Table 4. Eclipse model elements

Model element Description
MApplication Describes the application object. All other model elements are contained in this object.
MAddon A self-contained component typically without user interface. It can register for events in the application life cycle and handle these events.
MWindow Represents a window in your application.
MTrimmedWindow Similar to MWindow but it allows containing toolbars for the windows (via the TrimBars model elements).
MPerspective Represents a different layout of parts to be shown inside the window. Should be contained in a MPerspectiveStack.
MPart Represents the model element part, e.g., a view or an editor.
MDirtyable Property of MPart which can be injected. If set to true, this property informs the Eclipse platform that this Part contains unsaved data (is dirty). In a handler you can query this property to provide a save possibility.
MPartDescriptor MPartDescriptor is a template for new parts. A new part based on this part descriptor can be created and shown via the Eclipse framework.
Snippets Snippets can be used to pre-configure model parts which you want to create via your program. You can use the Eclipse framework to clone such a snippet and use the result object to attach it to the application model at runtime.

12. Features and Products

The following description uses feature projects and products, please see Feature projects and Eclipse Products and Deployment for a description of these topics.

13. Exercise: Create an Eclipse plug-in

13.1. Target

In the following exercise you create a standard Eclipse plug-in. This plug-in is later converted into an Eclipse RCP application.


The following description calls this plug-in the application plug-in as this plug-in will contain the main application logic.

13.2. Creating a plug-in project

In Eclipse select FileNewOther... Plug-in DevelopmentPlug-in Project.

Selection the Eclipse Plug-in Wizard

Give your plug-in the name com.example.e4.rcp.todo and press the Next button.

First page of the Eclipse Plug-in Wizard specifying the project name.

On the next wizard page make the following settings. Select No at the Would you like to create a rich client application? option and uncheck This plug-in will make contributions to the UI. Uncheck the Generate an activator, a Java class that controls the plug-in's life cycle option.

Second page of the Eclipse Plug-in Wizard specifying the plug-in ID, version, Name, Activator and the RCP type.

Press the Finish button. If you click the Next button instead of Finish, the wizard shows you a template selection page which you can bypass without a selection.

13.3. Validate the result

Open the project and ensure that no Java classes were created in the source folder.

In the manifest editor switch to the Dependencies tab and ensure that there are no entries.

14. Exercise: From plug-in to Eclipse 4 application

14.1. Target

In this chapter you convert the generated plug-in into an Eclipse RCP application.

14.2. Create a project to host the product configuration file

Create a new project called com.example.e4.rcp.todo.product via FileNewOthers...GeneralProject.

14.3. Create a product configuration file

Right-click on this project and select NewProduct Configuration.

Create a product configuration file called todo.product inside the com.example.e4.rcp.todo.product folder.

Press the Finish button. The file is created and opened in an editor.

Press the New... button on the Overview tab of the product editor.

Press the new button in the product editor

Enter to-do as the Product Name, your plug-in as the Defining Plug-in, product as the Product ID and select org.eclipse.e4.ui.workbench.swt.E4Application in the Application combo box.

Entering the product details

14.4. Configure the start levels

Switch to the Configuration tab in the product editor and press the Add Recommended... button. These settings are for example used by the Maven/Tycho build system,hence it is good practice to configure them.

Setting the default start level

14.5. Create a feature project

Create a new feature project called com.example.e4.rcp.todo.feature via FileNewOther...Plug-in DevelopmentFeature Project.

You can press the Finish button on the first wizard page.

Feature project

Afterwards select the Plug-ins tab in the editor of the feature.xml file. Press the Add... button and include the com.example.e4.rcp.todo plug-in into this feature.

Feature project


Ensure you have added the plug-in on the Included Plug-ins tab to include it into your feature. Using the Dependencies tab is wrong for this exercise.

14.6. Enter the feature as content into the product

Open your todo.product product file and change your product configuration file to use features.

For this select the features option on the Overview tab of the product editor.

Switching to feature on the product configuration file

Select the Contents tab and add the following features via the Add... button.

  • com.example.e4.rcp.todo.feature

  • org.eclipse.e4.rcp

  • org.eclipse.emf.ecore

  • org.eclipse.emf.common

Adding the required features to your product


If you cannot add one of the listed features to your product, ensure that you have changed your product to be based on features.

14.7. Remove the version dependency from the features in the product

To avoid problems with different versions of the org.eclipse.e4.rcp feature, delete the version number from your product. You can do this via the Properties... button on the Contents tab of the product configuration editor.

Remove version number

Remove version number

If other features have a version dependency, also remove these. The result should look similar to the following screenshot.

Remove version number via the Properties button

14.8. Create an application model

Select FileNewOther...Eclipse 4 ModelNew Application Model to open a wizard to create an application model file.

Enter your com.example.e4.rcp.todo application plug-in as the container and use the file name suggested by the wizard.

Press the Finish button. This triggers the creation of the Application.e4xmi file inside the com.example.e4.rcp.todo plug-in and opens it.

14.9. Add a window to the application model

Add one window to your application model so you have a visual component.

Right-click on the Windows and Dialogs node, and select Trimmed Window as depicted in the following screenshot.

Adding a trimmed window

Enter an ID, the position and size of the window and a label as shown in the screenshot below.

Enter the data for the TrimmedWindow in the model editor


If you start and close your application the last state of the application is persisted by the framework and restored the next time you start this application. This is undesired during development, as the latest state from the application model file should be used. In Section 15.1, “Delete the persisted user changes at startup” you configure your product to remove all the persisted changes from the last run.

14.10. Start the application

Open the product file and select the Overview tab. Press the Launch an Eclipse application hyperlink in the Testing section.

Starting the product

Validate that your application starts. You should see an empty window, which can be moved, resized, minimized, maximized and closed.

15. Exercise: Configure the deletion of persisted model data

15.1. Delete the persisted user changes at startup

To ensure that always the latest version of your application model is used, add the -clearPersistedState parameter to your product configuration file.

The following screenshot shows this setting in the product configuration file.

Delete persisted Eclipse application model


Ensure that you used the - sign and that the parameter is typed correctly. Is must be:


15.2. Why is this setting necessary?

At startup of an Eclipse application the Eclipse platform restores the state in which you left the application before the last shutdown. During development this might lead to situations where changes are not correctly applied and displayed, e.g., you define a new menu entry and this entry is not displayed in your application.

Alternatively to the approach described above, you can also set the Clear flag on the Main tab in your Run configuration. This would also delete other persisted data, like for example preference values.

16. Exercise: Modeling a User Interface

16.1. Desired user interface

In the following exercises you create the basis of the application user interface. At the end of this exercise your user interface should look similar to the following screenshot.

Screenshot of the application

16.2. Open the Application.e4xmi file

Open the Application.e4xmi file in the Eclipse 4 model editor via a double-click or right-click on it and select Open WithEclipse 4 model editor.

16.3. Add a perspective

Add a perspective stack with one perspective to your application model so that you can later easily add more of them.

Navigate to your window inside the Application.e4xmi file. Select the Controls node. Add a Perspective Stack via the context menu on the Controls entry as indicated in the following screenshot.

Adding a PerspectiveStack to the Eclipse RCP application


Alternatively to the context menu you can also use the Add... button on the detail page to add child elements to the selected element.

After creating the perspective stack add a Perspective to it, either via the context menu or the Add... button.

Adding a Perspective

Enter the To-do value in the Label field and the com.example.e4.rcp.todo.perspective value in the ID field.

Adding a Perspective to the Eclipse 4 application

16.4. Add part sash and part stack containers

Select Controls below the newly created perspective and add a part sash container element.

Add PartSashContainer

Change its Orientation attribute to Horizontal and enter into the ID field the com.example.e4.rcp.todo.partsashcontainer.main value.

Change the orientation attribute

Add a part stack as the first child to your part sash container element.

Re-select the parent part sash container and add another part sash container element. Now add two part stacks to the second part sash container.

After these changes your application model should look similar to the following screenshot.

Application model structure

16.5. Create the parts

Add a part model element to each part stack. As ID for the parts use the prefix com.example.e4.rcp.todo.part and the suffix from the following table. Also put the label from the table into the appropriate field of the part editor.

Table 5. Label and ID from the Parts

ID Suffix Label
.todooverview Overview
.tododetails Details
.playground Playground

The final structure of your application model should be similar to the following screenshot. The screenshot also shows the detailed data of the overview part inside the detail pane of the application model editor.

Part data

16.6. Validate the user interface

Start your product and validate that the user interface looks as planned. Reassign your model elements if required. The model editor supports drag-and drop for reassignment.

Also note that you can already see the structure, even though you have not created any Java classes so far.

17. Enter the dependencies

17.1. Add the plug-in dependencies

In the upcoming exercises you will use the functionality from other Eclipse plug-ins. This requires that you define a dependency to these plug-ins in your application.

Remember that application plug-in is the short form for the com.example.e4.rcp.todo plug-in.

Open the META-INF/MANIFEST.MF file in your application plug-in and select the Dependencies tab. Use the Add... button in the Required Plug-ins section to add the following plug-ins as dependency.

  • org.eclipse.core.runtime

  • org.eclipse.swt

  • org.eclipse.e4.core.di

  • org.eclipse.e4.ui.workbench

  • org.eclipse.e4.ui.di

  • org.eclipse.e4.core.di.extensions

17.2. Validating

The result should be similar to the following screenshot.

Plug-in Dependencies

18. Exercise: Connect Java classes with the parts

18.1. Create a new package and some Java classes

Create the package in the application plug-in.

Create three Java classes called TodoOverviewPart, TodoDetailsPart and PlaygroundPart in this package.


You can create the classes by clicking on the Class URI hyperlink in the detail pane of the model editor for the part. This also connects the created class to the model object. If you do this, you can skip Section 18.2, “Connect the Java classes with your parts” of this exercise.

The following code shows the TodoDetailsPart class. All classes should not extend another class, nor do they implement any interface.


public class TodoDetailsPart {


18.2. Connect the Java classes with your parts

Open the Application.e4xmi file and connect the class with the corresponding part model element. You can do this via the Class URI property of the part model element.

The following table gives an overview of which elements should be connected.

Table 6. Mapping Java classes with part model element

Class Part ID suffix
TodoOverviewPart *.todooverview
TodoDetailsPart *.tododetails
PlaygroundPart *.playground

The Eclipse 4 model editor allows you to search for an existing class via the Find... button. The initial list of Contribution Classes is empty, start typing in the Class Name field to see the results.

Finding a model class in the Application model

The following screenshot shows the result for the overview part.

Finding a model class in the Application model

18.3. Validating

Run your application. It should start, but you should see no difference in the user interface.

To validate that the model objects are created by the Eclipse runtime create a no-argument constructor for one of the classes and add a System.out.println() statement. Afterwards verify that the constructor is called, once you start the application.

19. Exercise: Using the SWT browser widget

19.1. Implementation

In this exercise you will display Google Maps in an SWT Browser widget.


This exercise does not always work on a Linux system because on certain Linux versions the Browser widget does not work. See the Eclipse SWT FAQ answered at How do I use the WebKit renderer on Linux-GTK for details.

Change the PlaygroundPart class so the part looks like the following screenshot.

SWT Browser Widget example with Google Maps


This example might not work, in case Google changes its API.

If you enter a text in the text field and press the button, the map should center based on the input in the text field. This input should be interpreted as city.

19.2. Solution

Your PlaygroundPart class should look similar to the following code.



import javax.annotation.PostConstruct;

import org.eclipse.e4.ui.di.Focus;
import org.eclipse.swt.SWT;
import org.eclipse.swt.browser.Browser;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Button;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Text;

public class PlaygroundPart {
  private Text text;
  private Browser browser;

  public void createControls(Composite parent) {
    parent.setLayout(new GridLayout(2, false));

    text = new Text(parent, SWT.BORDER);
    text.setMessage("Enter City");
    text.setLayoutData(new GridData(SWT.FILL, SWT.CENTER, true, false, 1, 1));

    Button button = new Button(parent, SWT.PUSH);
    button.addSelectionListener(new SelectionAdapter() {
      public void widgetSelected(SelectionEvent e) {
        String city = text.getText();
        if (city.isEmpty()) {
        try {
          // not supported at the moment by Google
          // browser.setUrl(""
          // + URLEncoder.encode(city, "UTF-8")
          // + "&output=embed");
              + URLEncoder.encode(city, "UTF-8")
              + "/&output=embed");

        } catch (UnsupportedEncodingException e1) {

    browser = new Browser(parent, SWT.NONE);
    browser.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true, 2, 1));


  public void onFocus() {

20. Introduction to dependency injection

See Dependency injection in Java for an introduction into the concept of dependency injection,

21. Dependency injection and annotations

21.1. Define class dependencies in Eclipse

The programming model in Eclipse supports constructor, method and field injection according to the Java Specification Request 330 (JSR330). Eclipse also defines additional annotations for the purpose of dependency injection. The most important annotations are covered in Section 21.2, “Annotations to define class dependencies in Eclipse”, other more special annotations are covered in there corresponding chapters.

The Eclipse dependency framework ensures that the key and the type of the injected object is correct. For example, if you specify that you want to have an object of type Todo for the "xyz" key, as shown in the following field declaration, the framework will only inject an object if it finds one with an assignable type.

@Inject @Named("xyz") Todo todo; 

21.2. Annotations to define class dependencies in Eclipse

The following table gives an overview of dependency injection related annotations based on JSR330 and the Eclipse specific ones.

Table 7. Basic annotations for dependency injection

Annotation Description
@javax.inject.Inject Defined by JSR330, can be added to a field, a constructor or a method. The Eclipse framework tries to inject the corresponding objects into the fields or the parameters of the instance.
@javax.inject.Named Defined by JSR330, defines the key for the value which should be injected. By default, the fully qualified class name is used as the key. Several keys for default values are defined as constants in the IServiceConstants interface.

Eclipse specific annotation, marks an injected value to be optional. If no valid object can be determined for the given key (and type), the framework does not throw an exception.

The specific behavior depends on where the @Optional is placed. The following description is based on the key. If the key cannot be resolved the following happens:

  • for parameters: a null value will be injected;

  • for methods: the method calls will be skipped

  • for fields: the values will not be injected.

Note that null is an acceptable value to be set in the context, and it is different from a key being removed from the context. For example, if the following is called context.set(SOMEKEY, null), anybody listening for SOMEKEY will be injected with null.

@GroupUpdates Eclipse specific annotation, indicates that updates for this @Inject should be batched. If you change such objects in the Eclipse context , the update is triggered by the processWaiting() method of the IEclipseContext object. This annotation is intended to be used by the platform for performance optimization and should rarely be necessary in RCP applications.


The Eclipse platform supports additional annotations for special purposes, e.g., for receiving events (sent by the event service) or working with preferences. For a summary of all standard annotations defined in the Eclipse platform see ???.

21.3. On which objects does Eclipse perform dependency injection?

The Eclipse runtime creates objects for the Java classes referred by the application model. During this instantiation the Eclipse runtime scans the class definition for annotations. Based on these annotations the Eclipse framework performs the injection.

Eclipse does not automatically perform dependency injection on objects which are created in your code with the new operator.

21.4. Dynamic dependency injection based on key / value changes

The Eclipse framework tracks which object expressed a dependency to which key and type. If the value to which a key points changes, the Eclipse framework re-injects the new value in the object which expressed a dependency to the corresponding type. This means applications can be freed from having to install (and remove) listeners.

For example, you can define via @Inject that you want to get the current selection injected. If the selection changes, the Eclipse framework will inject the new value.

The re-injection only works on methods and fields which are marked with @Inject. It will not work on parameters injected into constructors and methods which are marked with @PostConstruct, as these methods are only executed once. This will be explained later in Section 22.4, “Life cycle of the Eclipse context”.


This does not mean that Eclipse tracks the fields of the value to which the key points. For example if the mykey1 key points to a Todo object as value, and the key points to a new object, this triggers the re-injection of the value to all objects which have a relevant class dependency. But if a field inside the existing Todo object changes, it does not trigger a re-injection.

22. The Eclipse context

22.1. What is the Eclipse context?

During startup of an Eclipse application the Eclipse runtime creates an object based on the IEclipseContext interface. This object is called the context or the Eclipse context.

The context is similar to a Map data structure, in which objects can be placed under a certain key. The key is a String and in several cases the fully qualified class name is used as key. The value (to which the key points) can be injected into other objects.

22.2. Relationship definition in the Eclipse context

As described earlier the Eclipse context is similar to a Map data structure. But unlike a map, the Eclipse context is hierarchical and can also dynamically compute values for requested keys.

For certain model objects (see Section 22.3, “Which model elements have a local context?”) a local context is created. Such a context is associated with an application model object.

The different context objects are connected to form a hierarchical tree structure based on the structure of your application model. The highest level in this hierarchy is the application context.

A sample context hierarchy is depicted in the following picture.

Context hierarchy

Objects can be placed at different levels in the context hierarchy. This allows that the same key points to different objects in the hierarchy.

For example, a part can express a dependency to a Composite object via a field declaration similar to: @Inject Composite parent; Since parts have different local contexts they can receive different objects of the type Composite.

22.3. Which model elements have a local context?

Currently the following model elements implement the MContext interface and therefore have their own context:

  • MApplication

  • MWindow

  • MPerspective

  • MPart

  • MPopupMenu

22.4. Life cycle of the Eclipse context

The Eclipse framework creates the context hierarchy based on the application model during the start process. By default, it places certain objects under predefined keys into the context, e.g., services to control the Eclipse framework functionality.

The model objects and the created objects based on the class URI attributes are created by the Eclipse platform. For each model element with a custom context the Eclipse framework determines which objects should be available in the local context of the model object. If required, it also creates the required Java objects referred by the Class URI property of the model elements. This is for example the case if a part is visible to the user.


The renderer framework is responsible for creating the local context of the UI related model elements. This framework allows you to define classes which are responsible for setting up the UI implementation of the model objects. A class responsible for a model element is called the renderer for this model element.

For example, the ContributedPartRenderer class is the default renderer for part model objects. This renderer creates a Composite for every part and puts this Composite into the local context of the part.

After the initial creation of the Eclipse context hierarchy, the framework or the application code can change the key-value pairs stored in the context. In this case objects which were created with the related Eclipse functionality (for example by the Eclipse dependency injection framework) are updated with the new values.

Objects in the context are persisted in memory (transient), i.e., once the application is stopped the context gets destroyed.

23. Objects available for dependency injection

23.1. How are objects selected for dependency injection

As described in Section 21.1, “Define class dependencies in Eclipse” an object which is created by Eclipse can use annotations to describe its class dependencies.

During dependency injection for an object created by Eclipse, the Eclipse framework searches for a fitting object based on the specified key. The search starts in the local context associated with the application model object. If this key is not available, Eclipse continues to search in the parent context. This process continues until the main context has been reached.

Context hierarchy with OSGi

As you learn in later chapters the Eclipse context is not the only possible source of objects which can get injected. Other examples which are covered later are OSGi services, preferences, events and custom objects. The search happens (mostly) transparently for the caller of the injection.

23.2. How to access the model objects?

For the class references in the application model (see ???), the Eclipse framework creates the corresponding objects when needed. Such an object has access to its corresponding model object (see Section 11, “Overview of available model objects”) via dependency injection.

For example, in the implementation of a part you can access the model information of a part via: @Inject MPart part;

23.3. Default entries in the Eclipse context

The Eclipse framework creates several objects in the context. These are:

  • model objects - contain the data of the application model

  • services - software components which are defined by the Eclipse platform or via the OSGi service registry

  • several other objects which have explicitly been added to the context

The context can be modified by the application code and the framework. As the Eclipse framework automatically tracks the dependencies of the objects it creates, it can update them as described in Section 21.4, “Dynamic dependency injection based on key / value changes”.

23.4. Qualifiers for accessing the active part or shell

The Eclipse platform places the part which is currently selected and the active shell into the IEclipseContext of the application object. The related keys are defined in the IServiceConstants interface.

For example, the following method would allow you to track the current active part in another part.

// tracks the active part
public void receiveActivePart(@Named(IServiceConstants.ACTIVE_PART) MPart activePart) {
  if (activePart != null) {
    System.out.println("Active part changed "
        + activePart.getLabel());

To track the active shell use the IServiceConstants.ACTIVE_SHELL key.

// tracks the active shell
public void receiveActiveShell(@Named(IServiceConstants.ACTIVE_SHELL) Shell shell) {
  if (shell != null) {
    System.out.println("Active shell (Window) changed");


Eclipse uses handlers to define actions which can be triggered via menu or toolbar entries. For a handler implementation class it is not necessary to use these qualifiers, as a handler is executed in the active context of the application.

23.5. Tracking a child context with @Active

The @Active annotation allows you to track values in a child context. The Eclipse framework keeps track of the current active branch in the hierarchy of the IEclipseContext. For example, if the user selects a part, the path in the IEclipseContext hierarchy from the root to the IEclipseContext of the part is the current active branch.

With the @Active annotation you can track values in the current active branch of a child element. Whenever the active branch changes and the value of the referred key changes this value is re-injected into the object which uses the @Active annotation.

The usage of this annotation is demonstrated by the following code snippet.

public class MyOwnClass {
  void setChildValue(@Optional @Named("key_of_child_value") @Active String value) {
    this.childValue = value;


The @Active annotation is currently not used within the Eclipse framework itself and the author of this book has not yet managed to find a good use case for this annotation.

24. Using annotations to define behavior

24.1. API definition

If you use a framework in your application, you need to have a convention for how your application interacts with the framework. For example, if a Java object is responsible for handling a toolbar button click, the framework needs to know which method of this object needs to be called.

For this purpose every framework defines an Application Programming Interface (API). This API defines how you can interact with the framework from your code. The API also defines the interaction of application objects created or controlled by the framework. Typically, a framework uses inheritance or annotations for this purpose.

24.2. API definition via inheritance

The "traditional" way of defining an API is via inheritance. This approach requires that your classes extend or implement framework classes and interfaces. The Eclipse 3.x platform API used this approach.

The framework defines, for example, an abstract class which defines methods to be implemented. In the example of the toolbar button the method might be called execute() and the framework knows that this method must be called once the button is clicked.

API definition via inheritance is a simple way to define an API, but it also couples the classes tightly to the framework. For example, testing the class without the framework is difficult. It also makes extending or updating the framework difficult as such an update may affect clients. This is why the Eclipse 4.x does not use this approach anymore.

24.3. API definition via annotations

The Eclipse 4.x platform API is based on annotations, e.g., annotations are used to identify which methods should be called at a certain point in time. These annotations are called behavior annotations.

The following table lists the available behavior annotations for parts.

Table 8. Eclipse life cycle annotations for parts

Annotation Description
@PostConstruct Is called after the class is constructed and the field and method injection has been performed.
@PreDestroy Is called before the class is destroyed. Can be used to clean up resources.
@Focus Is called whenever the part gets the focus.
@Persist Is called if a save request on the part is triggered by the Eclipse framework.
@PersistState Is called before the model object is disposed, so that the part is able to save its instance state. This method is called before the @PreDestroy method.

The @PostConstruct, @PreDestroy annotations are included in the javax.annotation package. @Persist, @PersistState and @Focus are part of the org.eclipse.e4.ui.di package.

Eclipse defines additional behavior annotations for commands and for the application life cycle which are covered in the respective chapters.

24.4. Behavior annotations imply method dependency injection

Behavior annotations imply that the framework needs to provide the specified parameters to the method, i.e., the framework also performs method dependency injection. If you also add the @Inject annotation, the method is called twice, first during the dependency injection phase and later for the behavior annotation. This is typically undesired and therefore an error.

24.5. Use the @PostConstruct method to build the user interface

It is recommended to construct the user interface of a part in a method annotated with the @PostConstruct annotation. It would also be possible to create the user interface in the constructor, but this is not recommended as field and method injection have not been done at this point.

Creating the user interface in an @PostConstruct method requires that @Inject methods are aware that the user interface might not have been created yet.

24.6. Why is the @PostConstruct method not called?

Both Java 7 and the Eclipse platform expose the @PostConstruct annotation. In your Eclipse application you need to tell the framework that the annotation from the Eclipse platform should be used.


Eclipse 4.6 (Neon) fixed that. In Eclipse Neon you do not need a versionized import for the javax.annotation package anymore.

In case your @PostConstruct method is not called, ensure that you have defined a dependency to org.eclipse.core.runtime in the MANIFEST.MF file. See for details on this issue.


org.eclipse.core.runtime exports javax.annotation in the correct version. If you have a dependency to org.eclipse.core.runtime in your MANIFEST.MF file, no additional package dependency is needed. If, for some reasons, you want to avoid a dependency to org.eclipse.core.runtime, you could define a package dependency to the javax.annotation package and set the version to 1.0.0.

25. Exercise: Using @PostConstruct

25.1. Implement an @PostConstruct method

Add the following method to your TodoOverviewPart, TodoDetailsPart and PlaygroundPart classes. In case you created constructors for these classes you can remove them.

import javax.annotation.PostConstruct;
import org.eclipse.swt.widgets.Composite;

// more code

public void createControls(Composite parent) {
  + " @PostConstruct method called.");

25.2. Validating

Run your application and validate that the @PostConstruct method is called. If this does not work, see Section 24.6, “Why is the @PostConstruct method not called?” for a solution.

26. Menu and toolbar application objects

26.1. Adding menu and toolbar entries

You can add menus and toolbars to your RCP application via the application model. These entries can be positioned at various places. You can, for example, add a menu to a window or a part. These elements define, directly or indirectly, a link to a class. An instance of this class is created by the framework and responsible for the behavior if the menu or toolbar entry is selected. Such a class is called handler class.

26.2. The usage of commands and handlers

The Eclipse application model allows you to specify commands and handlers.

The usage of the commands and handlers model element is optional. You can use the Direct MenuItem or a Direct ToolItem model elements. These entries define a reference to a class (handler class). An instance of this handler class is created by the framework and its annotated methods are called by the framework if necessary. Menus and toolbars support separators.

A command is a declarative description of an abstract action which can be performed, for example, save, edit or copy. A command is independent from its implementation details. The Eclipse framework does not provide standard commands, i.e., you have to create all required commands in your application model.

The behavior of a command is defined via a handler. A handler model element points to a class (handler class) via the contributionURI property of the handler. This attribute is displayed as Class URI in the model editor.

Commands are used by the Handled MenuItem and Handled ToolItem model elements.

Prefer the usage of commands over the usage of direct (menu or tool) items. Using commands together with handlers allows you to define different handlers for different scopes (applications or part) and you can define key bindings for the handler's associated commands.

26.3. Behavior annotations and dependency injection for handler classes

In a handler class exactly one method must be annotated with the @Execute annotation. In additional, you can also annotate one method with the @CanExecute annotation. If you annotate more than one method with the same annotation, the framework calls only one of them. The Eclipse runtime uses dependency injection to provide the parameters of the method. The purpose of these annotations are described in the following table.

Table 9. Behavior annotations for handler classes

Annotation Description

Marks the method which is responsible for the action of the handler class. The framework executes this method once the related user interface element, e.g., the menu entry, is selected.


Marks a method to be visited by the Eclipse framework to check if the handler class can be executed. If a handler class returns false in this method, Eclipse disables the corresponding user interface element. For example, the save button is active if the handler class returns true in the @CanExecute method.

The default for this method is true, which means, if the handler class can always be executed, it does not need to implement a @CanExecute method.

The following example demonstrates the implementation of a handler class.

package com.example.e4.rcp.todo.handlers;

// import statements cut out
// ..

public class ExitHandler {
  public void execute(IWorkbench workbench) {

  // just to demonstrates the usage of
  // the annotation
  public boolean canExecute() {
    return true;


A handler instance does not have its own Eclipse context (IEclipseContext). It is executed with the Eclipse context of the active model element which has a Eclipse context. In most common cases this is the context of the active part.

All required parameters should be injected into the method annotated with @Execute, as you want the handler class to retrieve its runtime information during execution.


To ensure that you get the expected values from the active context ALWAYS get the required values injected as parameters into your methods annotated with @Execute or @CanExecute.

26.4. Determining the relevant handler for a command

If a command is selected, the runtime determines the relevant handler for the command. The application model allows you to create a handler for the application, a window and a part.

Each command can have only one valid handler for a given scope. The Eclipse framework selects the handler most specific to the model element.

For example, if you have two handlers for the "Copy" command, one for the window and another one for the part then the runtime selects the handlers closest to model element which is currently selected by the user.

26.5. Evaluation of @CanExecute

A method annotated with @CanExecute is called by the framework, if a change in the Eclipse context happens. For example, if you select a new part. If the method returns false, the framework disables any menu and tool items that point to that command.

You can request the re-evaluation of the @CanExecute methods by sending out an event via the event broker.

// evaluate all @CanExecute methods

// evaluate a context via a selector 
Selector s = (a selector that an MApplicationElement or an ID);

//See for details 

26.6. Mnemonics

The application model allows you to define mnemonics. A mnemonic appears as an underlined letter in the menu when the user presses and holds the ALT key and allows the user to quickly access menu entries by keyboard.

You specify mnemonics by prefixing the letter intended to be the mnemonic with an ampersand (&) in the label definition. For example, the label &Save with the S underlined (S) when the Alt key is pressed.

26.7. Naming schema for command and handler IDs

A good convention is to start IDs with the top level package name of your project and to use only lower case letters.

The IDs of commands and handlers should reflect their relationship. For example, if you implement a command with the ID, you should use as the ID for the handler. If you have more than one handler for one command, add another suffix to it, describing its purpose, e.g.

In case you implement commonly used functions, e.g., save, copy, you should use the existing platform IDs, as some Eclipse contributions expect these IDs to better integrate with the OS (e.g., on Mac OS, preferences are normally placed under the first menu). A more complete list of command IDs is available in org.eclipse.ui.IWorkbenchCommandConstants.

Table 10. Default IDs for commonly used commands

Command ID
Save All org.eclipse.ui.file.saveAll
Undo org.eclipse.ui.edit.undo
Redo org.eclipse.ui.edit.redo
Cut org.eclipse.ui.edit.cut
Copy org.eclipse.ui.edit.copy
Paste org.eclipse.ui.edit.paste
Delete org.eclipse.ui.edit.delete
Import org.eclipse.ui.file.import
Export org.eclipse.ui.file.export
Select All org.eclipse.ui.edit.selectAll
Preferences org.eclipse.ui.window.preferences
Exit org.eclipse.ui.file.exit

27. Exercise: Adding menus

27.1. Target of this exercise

In this exercise you create commands and handlers for your application. Afterwards you will create menu entries using these commands.

27.2. Create command model elements

Open the Application.e4xmi file of your com.example.e4.rcp.todo plug-in and select the Commands entry. This selection is highlighted in the following screenshot.

Adding commands to your application

Via the Add... button you can create new commands. The name and the ID are the important fields. Create the following commands.

Table 11. Commands

ID Name
org.eclipse.ui.file.saveAll Save
org.eclipse.ui.file.exit Exit New Todo
com.example.e4.rcp.todo.command.remove Remove Todo
com.example.e4.rcp.todo.command.test For testing

27.3. Creating the handler classes

Create the com.example.e4.rcp.todo.handlers package for your handler classes.

All handler classes implement an execute() method annotated with @Execute.

package com.example.e4.rcp.todo.handlers;

import org.eclipse.e4.core.di.annotations.Execute;

public class SaveAllHandler {
  public void execute() {
    System.out.println((this.getClass().getSimpleName() + " called"));

Using this template for all classes, implement the following classes.

  • SaveAllHandler

  • ExitHandler

  • NewTodoHandler

  • RemoveTodoHandler

  • TestHandler

27.4. Creating handler model elements

Select the application-scoped Handlers entry in your application model and create the handlers from the following table for your commands. For the definition of handlers the ID, command and class are the relevant information.

Use the com.example.e4.rcp.todo.handler prefix for all IDs of the handlers.

Table 12. Handlers

Handler ID Command Class
.saveall Save SaveAllHandler
.exit Exit ExitHandler
.new New Todo NewTodoHandler
.remove Remove Todo RemoveTodoHandler
.test For testing TestHandler

The application model editor shows both the name and the ID of the command. The class URI follows the bundleclass:// schema, the table only defines the class name to make the table more readable. For example, for the save handler this looks like the following:


Defining a handler in Eclipse 4

27.5. Adding a menu

In your Application.e4xmi file select your TrimmedWindow entry in the model and flag the Main Menu attribute.

Assign the ID to your main menu.


Ensure that this ID of the main menu is correct. You use it later to contribute another menu entry via another plug-in.

Add two menus, one with the name "File" and the other one with the name "Edit" in the Label attribute.

Also set the ID for the File menu. Use as ID for the Edit menu.

Creating a menu

Add a Handled MenuItem model element to the File menu. This item should point to the Save command via the Command attribute.

Adding a menu item to the menu

Add a Separator after the Save menu item and after that add an entry for the Exit command.

Add all other commands to the Edit menu.

27.6. Implement a handler class for exit

To test if your handler is working, change your ExitHandler class, so that it closes your application, once selected.

package com.example.e4.rcp.todo.handlers;

import org.eclipse.e4.core.di.annotations.Execute;
import org.eclipse.e4.ui.workbench.IWorkbench;

public class ExitHandler {
  public void execute(IWorkbench workbench) {

27.7. Validating

Validate that your save handler is called if you select Save from the menu.

Also check that you can exit the application via the Exit menu entry.

27.8. Possible issue: Exit menu entry on a MacOS

If you use the "org.eclipse.ui.file.exit" ID for your exit command, the Eclipse framework tries to map the exit command to its default menu location on the MacOS. If you don't see your exit menu, in its defined position, check this location.

28. Exercise: Adding a toolbar

28.1. Target of this exercise

In this exercise you add a toolbar to your application.

28.2. Adding a toolbar

Select the TrimBars node under your TrimmedWindow entry and press the Add... button. The Side attribute should be set to Top, so that all toolbars assigned to that trimbar appear on the top of the application.

Adding a toolbar

Add a ToolBar model element to your TrimBar. Add a Handled ToolItem to this toolbar which points to the org.eclipse.ui.file.saveAll command.

Set the label for this entry to Save.

Adding a menu item to the menu

28.3. Validating

Validate that your save handler is called if you select Save from the menu or the toolbar.

29. View, popup and dynamic menus

29.1. View menus

You can define one menu in a part as a view menu. Please note that the application model allows to define more than one menu but the default Eclipse implementation supports only one menu for a part. To add a view menu entry, select the Menus entry under the part and append a ViewMenu model entry to it.

Adding a View menu

29.2. Popup menu (context menu)

You can also define a popup menu for SWT controls via the application model. To achieve this create a Popup Menu for the part which contains the SWT control.

Defining a popupmenu in the application model

The popup menu contains entries, as, for example, a HandledMenuItem.

ID for the popupmenu

After this the pop menu can be assigned to an SWT control with the EMenuService service which can be accessed via dependency injection. This class provides the registerContextMenu(control, id) method for this purpose. The id parameter of the registerContextMenu method must be the ID attribute of your Popup Menu model element.

The following pseudo code shows an example for the registration. It uses a JFace viewer, as the popup menu needs to be registered on the SWT control, the example code demonstrates how to access this control.


import javax.annotation.PostConstruct;

import org.eclipse.swt.SWT;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Text;

public class TodoOverviewPart {

  public void createControls(Composite parent, EMenuService menuService) {
    // more code...
    TableViewer viewer = new TableViewer(parent, SWT.FULLSELECTION | SWT.MULTI);
    // more code
    // register context menu on the table

If you want to implement this example, your plug-in must have dependencies defined for the org.eclipse.e4.ui.workbench.swt, the and the org.eclipse.e4.ui.model.workbench plug-ins in its MANIFEST.MF file.

29.3. Dynamic menu and toolbar entries

You can also create menu and toolbar entries at runtime with the DynamicMenuContribution model element.

This model element points to a class in which you annotate a method with the @AboutToShow annotation. The annotated method is called if the user selects the user interface element. The @AboutToHide annotation can be used to annotate a method which is called before the menu is hidden.

In these methods you can dynamically create menu entries.

30. Toolbars, ToolControls and drop-down tool items

30.1. Adding toolbars to parts

Toolbars in the application model are defined within the Trimbars model element. A trimbar can be defined for TrimmedWindow model elements. Via its Side attribute you define if the trimbar should be placed on the top, left, right or bottom corner of the resulting window.

To add a toolbar to a view, set the Toolbar flag on the model element for the part and create the entries in the application model.

Such an example setup is displayed in the following screenshot.

Adding a toolbar to a part

30.2. ToolControls

ToolControl model element points to a Java class which can create controls that are displayed in the toolbar.

For example, the following code creates a Text field in the toolbar which looks like a search field.

package com.example.e4.rcp.todo;

import javax.annotation.PostConstruct;

import org.eclipse.jface.layout.GridDataFactory;
import org.eclipse.swt.SWT;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Text;

public class SearchToolItem {
  public void createControls(Composite parent) {
    final Composite comp = new Composite(parent, SWT.NONE);
    comp.setLayout(new GridLayout());
    Text text = new Text(comp, SWT.SEARCH | SWT.ICON_SEARCH | SWT.CANCEL
        | SWT.BORDER);
    GridDataFactory.fillDefaults().hint(130, SWT.DEFAULT).applyTo(text);


You can add such a ToolControl, for example, to your windows trimbar as depicted in the following screenshot.

Adding a ToolItems to the Window Trim

The following screenshot shows this ToolControl used in an example RCP application.

Resulting application with a search Toolitem

30.3. Drop-down tool items

Set the Menu attribute on an toolitem to be able to define a menu similar to the Run As... button in the Eclipse IDE. This button is depicted in the following screenshot.

Drop-down menu for a toolitem

31. More on commands and handlers

31.1. Passing parameters to commands

You can also pass parameters to commands. For this select a command and press the Add button in the Parameters section.

The ID is the identifier which you can use to get the parameter value injected via the @Named annotation.

Add a parameter to a command

In your HandledMenuItem or HandledToolItem add a parameter and put the ID from the command parameter definition into the Name field. The entry from the Value field is passed to the handler of the command.

Passing a parameter from a menu entry to a command


The ID of the parameter is the important one. This ID must be injected via the @Named annotation and used as Name (second field) during the definition of the menu or toolbar. This is highlighted in the following picture.

Relationship between parameters in command and menu

To get the parameter injected into your handler class you specify the ID of the parameter via the @Named annotation. This is demonstrated in the following code example.

package com.example.e4.rcp.todo.handlers;

import java.util.List;

import javax.inject.Named;

import org.eclipse.e4.core.di.annotations.Execute;
import org.eclipse.e4.ui.model.application.MApplication;
import org.eclipse.e4.ui.model.application.ui.advanced.MPerspective;
import org.eclipse.e4.ui.model.application.ui.basic.MWindow;
import org.eclipse.e4.ui.workbench.modeling.EModelService;
import org.eclipse.e4.ui.workbench.modeling.EPartService;

// switcher perspectives based on a command parameter 
public class PerspectiveSwitchHandler {
  public void switchPerspective(MWindow window, 
      EPartService partService,
      EModelService modelService,
      @Named("perspective_parameter") String perspectiveId) {
    // use parameter to find perspectives
    List<MPerspective> perspectives = modelService.findElements(window,
        perspectiveId, MPerspective.class, null);

    // switch to perspective with the ID if found
    if (!perspectives.isEmpty()) {


Alternatively to injecting each parameter, you can also inject the ParameterizedCommand command and access the parameters via API.

package com.example.e4.rcp.todo.handlers;

import javax.inject.Named;

import org.eclipse.e4.core.di.annotations.Execute;

public class TestHandlerWithCommandInjected {
  private String parametername = "com.example.e4.rcp.todo" + 
  public void execute(ParameterizedCommand command) {
    Object queryId = command.getParameterMap().get(parametername);
    // more...


31.2. Usage of core expressions

The visibility of menus, toolbars and their entries can be restricted via core expressions. You add the corresponding attribute in the application model to the ID defined by the org.eclipse.core.expressions.definitions extension point in the plugin.xml file.

To add this extension point to your application, open the plugin.xml file and select the Dependencies tab in the editor. Add the org.eclipse.core.expressions plug-in in the Required Plug-ins section.

Afterwards select the Extensions tab, press the Add button and add the org.eclipse.core.expressions.definitions extension. You define an ID under which the core expression can be referred to in the application model.

Via right-click on the extension you can start building your expression.

The following example can be used to restrict the visibility of a menu entry based on the type of the current selection. You will later learn how to set the current selection. Please note that the variable for the selection is currently called org.eclipse.ui.selection. In Eclipse 3.x this variable is called selection.

      <with variable="org.eclipse.ui.selection">
    <iterate ifEmpty="false" operator="or">
      <instanceof value="com.example.e4.rcp.todo.model.Todo">

You can assign this core expression to your menu entry in the application model. It can be used to restrict the visibility of model elements.

Enabling the core expression for a menu entry

Assigning it to the menu entry

This approach is similar to the definition of core expressions in Eclipse 3.x.

The values available for Eclipse 3.x are contained in the ISources interface and documented in the Eclipse core expressions wiki . Eclipse 4 does not always support the same variables, but the wiki documentation might still be helpful.

31.3. Evaluate your own values in core expressions

You can also place values in the IEclipseContext of your application and use these for your visible-when evaluation.

The following code demonstrates an example handler class which places a value for the myactivePartId key in the context (you will learn more about modifying the IEclipseContext later).

public void execute(IEclipseContext context) {
  // put an example value in the context

The following shows an example core expression which evaluates to true if an myactivePartId key with the value is found in the context.


This core expression can get assigned to a menu entry and control the visibility.

Assigning the visible-when core expression to the menu entry

32. Key bindings

32.1. Using key bindings in your application

It is also possible to define key bindings (shortcuts) for your Eclipse application. This requires two steps, first you need to enter values for the Binding Context node of your application model.

Afterwards you need to enter the key bindings for the relevant binding context in the BindingTable node of your application model. A binding table is always assigned to a specific binding context. A binding context can have several binding tables assigned to it.

Binding contexts are defined hierarchically, so that key bindings in a child override the matching key binding in the parent.


Even though they sound similar a binding context is used for keybindings while the Eclipse context (IEclipseContext) is used as source for dependency injection.

32.2. JFace default values for binding contexts

The binding context is identified via its ID. They can get assigned to a window or a part in the application model. This defines which keyboard shortcuts are valid for the window and which are valid for the part.

Eclipse JFace uses predefined IDs to identify binding contexts. These IDs are based on the org.eclipse.jface.contexts.IContextIds class. JFace distinguishes between shortcuts for dialogs, windows or both.

The following table gives an overview of the supported IDs and their validity.

Table 13. Default BindingContext values

Context ID Description
org.eclipse.ui.contexts.dialogAndWindow Key bindings valid for dialogs and windows
org.eclipse.ui.contexts.dialog Key bindings valid for dialogs
org.eclipse.ui.contexts.window Key bindings valid for windows

As an example, Ctrl+C (Copy) would be defined in dialogAndWindows as it is valid everywhere, but F5 (Refresh) might only be defined for a Window and not for a Dialog.

32.3. Define Shortcuts

The BindingTable node in the application model allows you to create key bindings based on a binding context. For this you create a new BindingTable model element and define a reference to the binding context via its ID.

In your key binding entry you specify the key sequence and the command associated with this shortcut.

How to add the BindingContext Entries

The control keys are different for each platform, e.g., on the Mac vs. a Linux system. You can use Ctrl, but this would be hardcoded. It is better to use the M1 - M4 meta keys.

Table 14. Key mapping

Control Key Mapping for Windows and Linux Mapping for Mac
M1 Ctrl Command
M2 Shift Shift
M3 Alt Alt
M4 Undefined Ctrl

These values are defined in the SWTKeyLookup class.

32.4. Activate bindings

If there are several valid key bindings defined, the ContextSet class is responsible for activating one of them by default. ContextSet uses the binding context hierarchy to determine the lookup order. A binding context is more specific depending on how many ancestors are between it and a root binding context (the number of levels it has). The most specific binding context is considered first, the root one is considered last.

You can also use the EContextService service which allows you to explicitly activate and deactivate a binding context via the activateContext() and deactivateContext() methods.

32.5. Key bindings for a part

You can assign a specific binding context to be active while a part is active.

BindingContent defined specific for a part

Key bindings assigned to a part are valid in addition to the key bindings provided by the currently active binding context, i.e. your global key bindings are still active in addition with the key bindings of the part.

33. Enable to start your product with right mouse click

You can also add the pde nature to your project in which you placed the product configuration file, if you want to be able to start your product via a right-click on the product and by selecting Run-asEclipse Application.


The Package Explorer view may have a filter set for .*resources. You can modify this filter via the view menu as depicted in the following screenshot.

Remove filter

For this purpose remove the filter in the Package Explorer view for files starting with . (dot) and modify the .project file to the following.

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

34. Learn more about Eclipse 4 RCP development

I hope you enjoyed this tutorial. You find this tutorial and much more information also in the Eclipse 4 RCP book from this author.

35. About this website

36. Links and Literature

36.1. Eclipse RCP resources

36.1.1. Eclipse Bug Tracker and Eclipse forum

Eclipse Forum for asking questions and providing feedback.

Eclipse Bug Tracker for reporting errors or feature requests.