This tutorial introduces you to the programming model of Eclipse RCP applications.

1. Introduction to Eclipse based applications

1.1. History of the Eclipse framework

The Eclipse IDE version 2.0 started as a modular and extensible IDE application. The Eclipse 3.0 version from 2004 allowed building stand-alone applications based on same framework.

At this point, the term Eclipse RCP (Eclipse Rich Client Platform) was coined. It means that the Eclipse framework is used to create feature-rich stand-alone desktop applications.

The release of Eclipse in version 4.x simplified and unified the Eclipse programming model. It is based on state-of-the-art technologies, like dependency injection and declarative styling via CSS files.

The Eclipse IDE can be viewed as a special Eclipse application with the focus on supporting software development. For example, the Java development tools (JDT) provide the functionality to develop Java applications.

1.2. High-level architecture

An Eclipse application consists of individual software components, called plug-ins. They can use and extend existing components. The most important configuration file for plug-ins is the MANIFEST.MF file. It defines the meta data of the plug-in, like its unique identifier, its exported API and its dependencies.

For example, a new plug-in can create new menu entries or toolbar entries.

Important Eclipse IDE components

An Eclipse RCP application typically uses the same base components as the Eclipse IDE. On top of these, they add application specific components as depicted in the following graphic.

Typical components of an Eclipse RCP application

Eclipse applications use the Equinox runtime. This runtime is implemented based on the OSGi specification. This specification describes a modular approach to develop component-based Java applications. It also defines dynamic software components, i.e., OSGi services.

As user interface toolkit, most Eclipse RCP applications use SWT(Standard Widget Toolkit) and additional extensions of SWT.

2. Installation

2.1. Download the Eclipse SDK

Download the latest release of the Eclipse SDK (Software development kit) build from the SDK download page. Click on the link of the latest released version (the release version with the highest number). The download section should look similar to the following screenshot. Download Page

The download is a compressed archive of multiple files. This format depends on you platform:

  • Windows uses the zip format

  • Linux uses the tar.gz format.

  • Mac uses the dmg (Disk Image) format

2.2. Install the e4 tools

The e4 tools provide tools to develop Eclipse plug-ins and applications. If there are not part your Eclipse distribution, you can install them via your release update site. Use menu:[Help|Install New Software…​] and select the update site of your release. If you are using the latest release, you use the following stable update site.

Install the Eclipse 4 tooling

Install the tools and restart the Eclipse IDE afterwards.

2.3. Install the e4 spies

The e4 spies are helpful to analysis Eclipse plug-ins and applications. To install them, open the Eclipse update manager via Open Help  Install new software…​. You can use the following URL to install the latest tools:

The official website for the e4 tools be found on the e4tools site.

3. Exercise: Create an RCP application with the wizard

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.

3.1. Create project

Create a project called com.example.e4.rcp via the File  New  Other…​  Plug-in Development  Plug-in Project from the menu of your Eclipse IDE.


Use the settings similar to the following screenshots, most of them are the default settings.


Press Next.


Press Next.


Press Next.

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 the clearPersistedState startup option to the product configuration file. This ensures that the latest state of your application model is used once the application is started.

3.2. Launch your 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

3.3. Validate

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


If you pressed Press Finish after selecting the template, the generated RCP application will only show an empty window. Delete the plug-in and redo the creation and ensure you use the last wizard page from Exercise: Create an RCP application with the wizard.

4. The Eclipse application model

4.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, e.g., 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. For RCP application this file is, by default, called Application.e4xmi and located in the main directory of the plug-in which defines the product extension. The Eclipse IDE ships with its own base application file. 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.

4.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 1. URI pattern for class and static file references
Pattern Description




Identifier for a Java class. It consists of the following parts: bundleclass:// is a fixed prefix. Bundle-SymbolicName is defined in MANIFEST.MF file. The Bundle-SymbolicName is followed by a '/' and the fully qualified classname.




Used to identify resources. Identifier for a resource in a plug-in. platform:/plugin/ is a fixed prefix, followed by the Bundle-SymbolicName, 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.

5. User interface model elements

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

5.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

5.2. Parts

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

Eclipse application with a few parts

Parts can be 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

5.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.

TIP: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.

5.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.

5.5. 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). It stores this information in Java objects during runtime. 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 2. Eclipse model elements
Model element Description


Describes the application object. All other model elements are contained in this object.


A self-contained component typically without user interface. It can register for events in the application life cycle and handle these events.


Represents a window in your application.


Similar to MWindow but it allows containing toolbars for the windows (via the TrimBars model elements).


Represents a different layout of parts to be shown inside the window. Should be contained in a MPerspectiveStack.


Represents the model element part, e.g., a view or an editor.


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 is a template for new parts. A new part based on this part descriptor can be created and shown via the Eclipse framework.


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.

6. Contributing to the application model

6.1. Modularity support for the application model

Eclipse applications are based on the modularity of plug-ins. Every plug-ins can contribute to the application model.

Typical, the initial structure of the application model is described in file called Application.e4xmi. Model contributions can be static or dynamic:

  • Static contributions are contributed via text files. These extensions are called fragments or model fragments.

  • Dynamically contributions are contributed via Java classes. These extensions are called processors or model processors.

These model contributions are registered via the org.eclipse.e4.workbench.model extension point. This extension point is defined in the org.eclipse.e4.ui.workbench plug-in.

The model contributions are read during startup and are used to build the runtime application model.

6.2. Constructing the 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.

6.2.1. User Changes

Changes during runtime, are written back to the model. For example, if the user positions a part into another stack via drag and drop.

If the Eclipse application is closed, theses changes are recorded and saved in the workbench.xmi file. This file is located in the .metadata/.plugins/org.eclipse.e4.workbench folder.

User changes can be deleted at start of your application via the clearPersistedState parameter as a launch parameter. In most cases this is undesired behavior for an exported application and only used during development.

6.2.2. Runtime application model

At runtime the application model of an Eclipse application consists of different components:

  • Application model - By default defined via the Application.e4xmi file

  • Model contributions - Based on fragments and processors

  • User changes - Changes the user did to the user interface during his last usage

These different components of the runtime application model need to be combined.

The Eclipse platform creates the runtime application model based on the initial application model(Application.e4xmi) and applies the model contributions to it. User deltas are applied afterwards. If these deltas do not apply anymore, e.g., because the base model has changed, they will be skipped.

The deltas are applied to the model based on the IDs of the user interface component.

The automatic persistence of the application model is misleading during development. The developer adds a new part and this part is not visible after startup of the application because Eclipse assumes that the user closed it in an earlier session. Use the clearPersistedState parameter to avoid the processing of user changes at startup.

Comparison with Eclipse 3.x

The programming model of Eclipse 3.x primarily uses extension points to define contributions to the application. These extensions define new parts, new menus, etc. This approach is no longer used in modern Eclipse RCP applications. All contributions are made via fragments or processors. If your are using the compatibility layer, Eclipse stills supports plug-in based contributions.

7. Model fragments

A model fragment is a file which typically ends with the .e4xmi extension. It statically specifies model elements and the location in the application model to which it should be contributed.

For example, a fragment can contribute a new menu containing several new menu entries.

The e4 tools project provides a wizard and an editor for model fragments.

The application model editor also allows you to extract a subtree into a new or existing fragment. Select a model element, right click on it and select Extract into a fragment from the context menu.

7.1. How to define model fragments extension elements

In fragments you contribute to an existing model element. You also have to specify the Featurename to which you want to contribute. A Featurename is a direct link to the structure of the application model.

The following table lists some Featurename values and their purposes.

Table 3. Contribution, Featurename and Element id
You want to contribute to a Featurename Element Id

Command to the application


ID of your application

Handler to the application


ID of your application

New MenuItem / HandledMenuItem to existing menu


ID of the menu

New menu to the main menu of the window


ID of your main menu

New Part to existing PartStack


ID of your PartStack

7.2. Defining the model element which gets extended

If you want to contribute to an element of the application model you can:

  • specify the ID of the element to which you are contributing

  • use an XPath expression to describe the model element which should get extended

The following table gives several examples how you can use XPath expressions to define the model element you want to extend.

Table 4. Sample XPaths for the Application Model
XPath Element in Application Model


The slash (/) always addresses the root element of an XML file, which always is the MApplication element.


Contribute to the main menu.


Contribute to all children of the main menu, e.g. to every menu in it.


Contribute to the first child of the main menu. In most applications this would be the menu:File menu.

xpath://mainMenu/[@[local-name()='type' and .='menu:Menu']]

Contribute to the first Menu of the main menu. This xpath is more detailed than the one above since it also requires that the main menu child is of type menu:Menu. In most application this would be the menu:File menu.


Contribute to the bottom trimbar.


Contribute to the top trimbar. When the MTrimBar is on top the side attribute is omitted, therefore not(@side) is used.

xpath://children[@*[local-name()='type' and .='basic:Part']]

Contribute to a MPart.

xpath://children[@*[local-name()='type' and .='basic:Part']][./tags = 'Editor']

Contribute to a MPart which is tagged with the Editor tag.

A nice tool for evaluating XPaths is the Eclipse XPath evaluation plug-in.

Eclipse XPath plugin in the marketplace

7.3. Position of new model elements

Fragments define the desired position of new model elements via the Position in List attribute. The following values are allowed:

Table 5. Position in list
Value Description


Positions the element on the beginning of the list.


Places the new model elements at position theIndex. Example: index:0


Places the new model elements before the model element with the ID theOtherElementsId.


Places the new model elements after the model element with the ID theotherelementsid.

Fragments of independent plug-ins are processed in the order of the dependencies in the MANIFEST.MF file. Therefore, first or index might not always result in the desired outcome.

8. Model processors

A processor allows contributing to the model via program code. This enables the dynamic creation of model elements during the start of the application.

9. More to learn about Features and Products

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

10. Exercise: Creating an Eclipse RCP application

In this exercise you create a standard Eclipse plug-in. Afterwards, you convert the generated plug-in into an Eclipse RCP application. This plug-in is used as basis for your user interface components.

10.1. Cleanup

If you created other projects earlier, it is recommended that you close them or remove them from the workspace to avoid side effects. To close a project, right click on it and select Close from the content menu. To remove a project from the workspace, right click on it and select Delete from the content menu. In the resulting dialog DO NOT set the "Delete project content on disk" flag, this way you can later import the project again, if needed.

If you are using a target definition file, the corresponding project must of course stay (open) in the workspace.

10.2. Creating a plug-in project

Create the com.vogella.tasks.ui plug-in project via the File  New  Other…​  Plug-in Development  Plug-in Project menu entry.

Selection the Eclipse Plug-in Wizard

On the first wizard page enter com.vogella.tasks.ui as project name and press the Next button.

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

On the next wizard page ensure the following settings are made:

  • Select No at the Would you like to create a rich client application? option

  • Uncheck the This plug-in will make contributions to the UI option

  • 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

Press the Finish button.

If you click the Next button instead of Finish, the wizard shows you a template selection page. So not make a selection and finish the wizard.

10.3. Review the generated code

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

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

10.4. Create a feature project

Create a new feature project called com.vogella.tasks.feature via File  New  Other…​  Plug-in Development  Feature Project.

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

Feature project

Afterwards select the Included Plug-ins tab in the editor of the feature.xml file. Press the Add…​ button and include the com.vogella.tasks.ui 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.

10.5. Create a project to host the product configuration file

Create a new project called com.vogella.tasks.product via the File  New  Other…​  General  Project menu entry.


Press Finish.

10.6. Create a product configuration file

Right-click on the com.vogella.tasks.product project and select File  New  Other…​  Plug-in Development  Product Configuration.

training product10

Create a product configuration file called todo.product inside the com.vogella.tasks.product folder.

training product20

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

Ensure that a ID, version and Name is set. Version should be set to 0.0.1 (or any other three numbers separated by dots) as this is required for the command line build.

Entering the product version

10.7. 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

10.8. 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.vogella.tasks.feature

  • org.eclipse.e4.rcp

  • org.eclipse.emf.ecore

  • org.eclipse.emf.common

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

The result should look similar to the following screenshot.

Adding the required features to your product
Remove the version dependency from the features in the product

Older versions of the Eclipse IDE added the current version of the feature. As the version of an included feature may change over time, you should avoid using the feature version number in your product. If you version is set, you can remove it via the Properties…​ button on the Contents tab of the product configuration editor.

Remove version number
Remove version number

10.9. Create an application model

Create an application model file in your com.vogella.tasks.ui plug-in via the File  New  Other…​  Eclipse 4  Model  New Application Model menu entry.

training product48

Enter your com.vogella.tasks.ui application plug-in as the container and use the file name suggested by the wizard.

training product50

Press the Finish button to create the application model file and to open it in an editor.

10.10. Add a window to the application model

Add one window to your application model.

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

Adding a trimmed window

Enter an ID with the taskmanager suffix, 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

10.11. Ensure to delete the persisted user interface state at startup

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. 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: -clearPersistedState

10.12. Start the application and validate the result

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.

10.13. Modeling a user interface

In the this part of the exercise, you create the basis of the application user interface.

10.14. Desired user interface

At the end of this exercise, your user interface should look similar to the following screenshot.

Screenshot of the application

10.14.1. Open the application model

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

10.14.2. Add part sash and part stack containers

Select Controls below the window and add a part sash container element.

Add PartSashContainer

Change its Orientation attribute to Horizontal and enter into the ID field the com.vogella.tasks.ui.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 a part sash container element. Add two part stacks to this new element.

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

Application model structure

10.14.3. Create the parts

Add one part to each stack. Use the ID’s and labels from the following table.

Enter the name first, the ID should be adjusted based on the name, if the label was empty.

Table 6. Label and ID for the parts
ID Suffix Label







The final structure of your application model should be similar to the following screenshot. In the screenshot the overview part is selected in the tree hence you see its data.

Part data

10.14.4. Validate the user interface

Start your product and validate that the user interface looks as planned. See Desired user interface for the desired result.

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.

10.15. Define the API which can be used

To use classes from other plug-ins in a plug-in, you need to add dependencies to them in the MANIFEST.MF file of the plug-in. In this exercise you prepare the usage of classes from other plug-in.

Open the META-INF/MANIFEST.MF file in your com.vogella.tasks.ui plug-in and select the Dependencies tab. Use the Add…​ button in the Required Plug-ins section to add the following plug-ins as dependencies:

  • 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

Use the Add…​ button in the Imported Packages section to add the following plug-ins as dependencies:

  • javax.annotation

  • javax.inject

The result should be similar to the following screenshot (version may differ).

Plug-in Dependencies
Show Solution

The following is a potential solution. The minimum versions of the plug-ins dependencies have been removed while the minimal versions of the imported packages are still included. The minimum version of the imported packages ensures that all plug-ins use the same version in a Java 8 environment.

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Ui
Bundle-SymbolicName: com.vogella.tasks.ui;singleton:=true
Bundle-Version: 1.0.0.qualifier
Import-Package: javax.annotation;version="1.2.0",
Require-Bundle: org.eclipse.core.runtime,

10.16. Create Java classes and connect with the parts

10.16.1. Create a new package and some Java classes

Create the package in the application plug-in.

Create the following three Java classes in this package:

  • TodoOverviewPart

  • TodoDetailsPart

  • PlaygroundPart

Theses classes should not extend another class, nor should they implement any interface.

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 Connect the Java classes with your parts.

The following code shows the TodoDetailsPart class.


public class TodoDetailsPart {
    public TodoDetailsPart() {
        System.out.println(this.getClass().getSimpleName() + " constructed");

10.16.2. Connect the Java classes with your parts

In your application model 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 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.

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

Table 7. Mapping Java classes with part model element
Class Part ID suffix







The following screenshot shows the result for the overview part.

Finding a model class in the Application model

10.16.3. Validate

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

To validate that the model objects are created at runtime check the Console view of Eclipse for the output of the System.out.println() statements.

11. Exercise: Using the SWT browser widget

11.1. Implementation

In this exercise you use several SWT widgets to allow to search and display cities on Google maps.

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.

11.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() {

12. Exercise: Contributing a part descriptor via model fragments

In this exercise you create a model fragment to contribute a part descriptor. You will build this part descriptor in a way that it can also contributed to the Eclipse IDE.

12.1. Create a new plug-in

Create a simple plug-in project called The following description abbreviates the plug-in name to the plug-in.

12.2. Add the dependencies

In the MANIFEST.MF file, add the following plug-ins as dependencies to your plug-in.

  • org.eclipse.core.runtime

  • org.eclipse.swt

  • org.eclipse.jface

  • org.eclipse.e4.core.di

  • org.eclipse.e4.ui.workbench

  • org.eclipse.e4.ui.di

12.3. Create a part class

Create the following class.


import javax.annotation.PostConstruct;

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

public class AdditionalInformationPart {
    public void postConstruct(Composite parent) {
        new Text(parent, SWT.BORDER | SWT.MULTI);

12.4. Create a model fragment

Use the fragment wizard to create a new model fragment via the File  New  Other…​  Eclipse 4  Model  New Model Fragment menu entry.

Creating fragments with the wizard

Select the plug-in as the container and use fragment.e4xmi as the name for the file.

Creating fragments with the wizard

Press the Finish button.

12.5. Validate that the fragment is registered as extension

The fragment creation wizard also adds the org.eclipse.e4.workbench.model extension to your contribute plug-in. To review this open the plugin.xml file.

If the plugin.xml file is missing, open your MANIFEST.MF file. Select the Overview tab and click on the Extensions link. This shows the Extensions tab in the editor and once you add an extension in this tab the plugin.xml file is generated.

Open the Extensions tab and set the field apply to always. Your entry then should look similar to this screenshot:

Adding the fragment to the extensions

If the entry in the plugin.xml is missing you can create it by clicking on the Add…​ button. Afterwards add a new extension for the org.eclipse.e4.workbench.model extension point. Once this has been created, use the a right mouse click to add a fragment to the extension.

The resulting plugin.xml file should look similar to the following code.

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

12.6. Adding model elements

Open the fragment.e4xmi file in its editor. Select the Model Fragments node and press the Add…​ button.

Use xpath:/ as extended element id and descriptors as Feature name.

Adding a part descriptor 1

Now trigger the right mouse menu and choose Add Child  PartDescriptor. Select the Part Descriptor and press the Find button on the Class URI field. Choose the AdditionalInformationPart class we’ve created earlier.

Adding a part descriptor 2

Due to Bug 538787 the find button in Eclipse 2018-09 does not work. You have to manually enter the following: bundleclass://

Now switch to the Supplementary tab and add the following tags:

  • View

  • categoryTag:vogella

Adding a part descriptor 2

The View tag ensures that the Eclipse IDE accepts this part descriptor as valid view, if you use this plug-in in the Eclipse IDE. For pure e4 RCP applications this flag is not needed.

Do not forget to press the Add button, after you entered the text.

12.7. Update product

Add the new plug-ins to your feature and start via the product file. Ensure that your part descriptor is present, for example, via the model spy.

12.8. Validate

Add the Eclipse model spy to your runtime application and ensure that you see the part descriptor. Optional create a new handler which opens a new part based on this part descriptor.

This plug-in can be used to extend the Eclipse IDE or a RCP application. In the Eclipse IDE you can open the additional part via Window  Show View  Other…​ dialog.

12.9. Introduction to dependency injection

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

13. Dependency injection and Eclipse

13.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 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;

13.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 8. Basic annotations for dependency injection
Annotation Description


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.


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.


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.

13.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.

13.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 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.

13.5. OSGi services and Eclipse dependency injection

OSGi services are available for dependency injection in Eclipse applications. If you define your custom OSGi services, you can inject them into your model objects. This removes the need to create singleton or factory implementations in your application to access data.

If a requested key is not found in the Eclipse context hierarchy, the Eclipse framework dynamically queries for a fitting OSGi service in the OSGi registry.

Context hierarchy with OSGi

For example, if you have an OSGi service declared for the ITodoService interface you can inject it via the following code snippet into a field of an Eclipse part.

@Inject ITodoService service;

14. The Eclipse context

14.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. But unlike a map, the Eclipse context is hierarchical and can also dynamically compute values for requested keys.

For certain model objects (see 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.

14.2. 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

14.3. 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.

14.4. How are objects selected for dependency injection

As described in On which objects does Eclipse perform dependency injection? 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.

14.5. How to access the model objects?

For the class references in the application model, the Eclipse framework creates the corresponding objects when needed. Such an object has access to its corresponding model object via dependency injection.

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

14.6. 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 Dynamic dependency injection based on key / value changes.

14.7. 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.

14.8. 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 followingcode 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 tutorial has not yet managed to find a good use case for this annotation.

15. Using annotations to define behavior

15.1. API definition in a framework

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.

15.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.

15.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 9. Eclipse life cycle annotations for parts
Annotation Description


Is called after the class is constructed and the field and method injection has been performed.


Is called before the class is destroyed. Can be used to clean up resources.


Is called whenever the part gets the focus.


Is called if a save request on the part is triggered by the Eclipse framework.


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.

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.

15.4. 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.

Why is the @PostConstruct method not called?

The following description is only valid for Eclipse versions before the Eclipse 4.6 (Eclipse Neon) release. As of Eclipse 4.6 the framework uses the Java version of @PostConstruct and the problem described here, cannot happen anymore.

Before Eclipse 4.6, both Java 7 and the Eclipse platform exposed the @PostConstruct annotation. In your Eclipse application you need to tell the framework that the annotation from the Eclipse platform should be used. org.eclipse.core.runtime exports javax.annotation in the correct version. 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. See Eclipse 4 RCP FAQ for details on this issue.

16. Exercise: Using @PostConstruct

16.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.");

16.2. Validate

Run your application and validate that the @PostConstruct method is called.

If you receive an error message similar to the following: Unable to process "TodoOverviewPart#createControls()": no actual value was found for the argument "Composite"., ensure you imported the SWT Composite and not the SWT.

import org.eclipse.swt.widgets.Composite;

// MORE code

17.1. Adding menu and toolbar entries

You can add menus and toolbars to your Eclipse 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. Each element define, directly or indirectly, one or several links to a class which is responsible for the execution. These classes are responsible for the behavior once the menu or toolbar entry is selected. Such a class is called handler class.

17.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, e.g., 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.

17.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 10. 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.vogella.tasks.ui.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.

17.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.

17.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, UIEvents.ALL_ELEMENT_ID);

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

//See for details

17.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, if you use the the label &Save, the S will be underlined if the Alt key is pressed.

17.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 in your RCP application, 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 11. Default IDs for commonly used commands
Command ID


Save All


















Select All







18. View, popup and dynamic menus

18.1. View menus

You can define one menu in a part as a view menu. 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

The application model allows to define more than one menu. But the default Eclipse implementation supports only one menu for a part.

You can also define a popup menu for SWT controls via the application model. See the exercise for detailed steps, how to do this.

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.

19. Toolbars, ToolControls and drop-down tool items

19.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

19.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.vogella.tasks.ui;

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

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

20. More on commands and handlers

20.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.vogella.tasks.ui.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.vogella.tasks.ui.handlers;

import javax.inject.Named;

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

public class TestHandlerWithCommandInjected {
    private String parametername = "com.vogella.tasks.ui" +
    public void execute(ParameterizedCommand command) {
      Object queryId = command.getParameterMap().get(parametername);
      // more...


20.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.

20.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

21. Key bindings

21.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.

21.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 12. Default BindingContext values
Context ID Description


Key bindings valid for dialogs and windows


Key bindings valid for dialogs


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.

21.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 13. Key mapping
Control Key Mapping for Windows and Linux Mapping for Mac













These values are defined in the SWTKeyLookup class.

21.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.

21.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.

22. Exercise: Adding menus

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

22.1. Create command model elements

Open the Application.e4xmi file of your com.vogella.tasks.ui 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 14. Commands
ID Name









For testing

22.2. Creating the handler classes

Create the com.vogella.tasks.ui.handlers package for your handler classes.

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

package com.vogella.tasks.ui.handlers;

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

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

Create now the the following classes by copying the above class.

  • SaveAllHandler

  • ExitHandler

  • NewTodoHandler

  • RemoveTodoHandler

  • TestHandler

22.3. 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.vogella.tasks.ui.handler prefix for all IDs of the handlers.

Table 15. Handlers
Handler ID Command Class








New Todo



Remove Todo



For testing


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 handler with the com.vogella.tasks.ui.handler.saveall id uses the following entry to point to his handler class.

Defining a handler in Eclipse 4

22.4. 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.

22.5. 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.vogella.tasks.ui.handlers;

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

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

22.6. Validate

Validate that your save handlers are called if you select them in the menu.

22.7. 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 maps the menu entry to its default menu location on the MacOS. If you don’t see your exit menu, in its defined position, check this location.

23. Exercise: Add a context menu to a table

In this exercise you implement a context menu for a table in your TodoOverviewPart. You connect the menu entry with the delete command.

23.1. Adding dependencies

Add the following plug-ins as dependencies to the MANIFEST.MF file of your application plug-in.

  • org.eclipse.e4.ui.workbench.swt

  • org.eclipse.e4.ui.model.workbench

23.2. Implementation

Create a Popup Menu in the application model 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.FULL_SELECTION | SWT.MULTI);

        // more code

        // register context menu on the table

If you want to implement this example, your plug-in must have the following dependencies defined in its MANIFEST.MF file:

  • org.eclipse.e4.ui.workbench.swt


  • org.eclipse.e4.ui.model.workbench

Change the RemoveTodoHandler so that it writes, "Soon, I will really delete your todo".

You will change the RemoveTodoHandler to delete the selected todo once you have learned about the selection service.

24. Exercise: Adding a toolbar

In this exercise you add a toolbar to your application.

24.1. 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

24.2. Validate

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

25. Exercise: Define key bindings

25.1. Create binding context entries

Select the Binding Contexts entry in your application model. Define a new entry with the org.eclipse.ui.contexts.dialogAndWindow ID. As name use "Windows and Dialogs".

How to add the Binding Context Entries

Afterwards add the following sub-entries:

Table 16. Binding context entries
ID Name





The resulting entry is depicted in the following screenshot.

How to add the Binding Context Entries
The name attribute of a binding context entry is not allowed to be empty.

25.2. Create key bindings for a BindingContext

Create a key binding for your Save command to the M1+S shortcut. Afterwards create a keybinding for your Exit command to the M1+X shortcut.

The required entries are depicted in the following screenshots.

How to add the Binding Context Entries
How to add the Binding Context Entries

Run your program and test it.

26. Exercise: Contributing menus via model fragments

In this exercise you create a model fragment to contribute a menu entry, a command and a handler to your application model.

26.1. Create a new plug-in

Create a simple plug-in project called com.vogella.tasks.ui.contribute. The following description abbreviates the plug-in name to the contribute plug-in.

26.2. Add the dependencies

In the MANIFEST.MF file, add the following plug-ins as dependencies to your contribute plug-in.

  • org.eclipse.core.runtime

  • org.eclipse.swt

  • org.eclipse.jface

  • org.eclipse.e4.core.di

  • org.eclipse.e4.ui.workbench

  • org.eclipse.e4.ui.di

26.3. Create a handler class

Create the com.vogella.tasks.ui.contribute.handlers package and the following class.

package com.vogella.tasks.ui.contribute.handlers;

import org.eclipse.e4.core.di.annotations.Execute;
import org.eclipse.jface.dialogs.MessageDialog;
import org.eclipse.swt.widgets.Shell;

public class OpenMapHandler {

    public void execute(Shell shell) {
        MessageDialog.openInformation(shell, "Test", "Just testing");

26.4. Create a model fragment

Use the fragment wizard to create a new model fragment via the File  New  Other…​  Eclipse 4  Model  New Model Fragment menu entry.

Creating fragments with the wizard

Select the contribute plug-in as the container and use fragment.e4xmi as the name for the file.

Creating fragments with the wizard

Press the Finish button.

26.5. Validate that the fragment is registered as extension

The fragment creation wizard also adds the org.eclipse.e4.workbench.model extension to your contribute plug-in. To review this open the plugin.xml file.

If the plugin.xml file is missing, open your MANIFEST.MF file. Select the Overview tab and click on the Extensions link. This shows the Extensions tab in the editor and once you add an extension in this tab the plugin.xml file is generated.

On the Extensions tab validate that you have an entry similar to the following screenshot. Ensure apply is set to always.

Adding the fragment to the extensions

If the entry in the plugin.xml is missing you can create it by clicking on the Add…​ button. Afterwards add a new extension for the org.eclipse.e4.workbench.model extension point. Once this has been created, use the a right mouse click to add a fragment to the extension.

The resulting plugin.xml file should look similar to the following code.

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



26.6. Adding model elements

Open the fragment.e4xmi file in its editor. Select the Model Fragments node, right-click on it and add one fragment.

Adding a model fragment

Use xpath:/ as the Extended Element ID to extend any application.

You need to define to which feature you will be adding to. For Featurename, specify the value commands. Make sure you have the Model Fragment selected and use the Add…​ button to add a Command to your model fragment.

Adding a model fragment

Define an entry similar to the following.

Adding a command to the model fragment

Create a new model fragment for the handler. The Extended Element ID is again xpath:/, the Featurename is handlers.

Add a Handler to this model fragment, pointing to your OpenMapHandler class.

Adding a handler to the model fragment

Use com.vogella.tasks.ui.contribute.handler.openmap as ID for the handler. Point to the Open Map command and the OpenMapHandler class.

Adding a handler to the model fragment

Add another Model Fragment and contribute to menuContributions.

Adding a menu contribution

Add a menuContribution and use as parent ID. This assumes that the application you are extending uses this ID, it is the standard ID of the Eclipse IDE.

Adding a menu contribution

If your Eclipse application uses a difference ID you need to use the id of your main menu.

Now add an menu and a handled menu item to your model with the following attributes:

  • ID:

  • Label: Map

Adding a menu contribution

Add a HandledMenuItem which points to your new command. The created entry should be similar to the following screenshot.

Adding a menu item to the menu

26.7. Update the product configuration (via the feature)

Add the contribute plug-in to your feature.

26.8. Validate

Start your application via your product.

Ensure that you added this new plug-in to your feature and saved the changes. Remember to start via the product to update the launch configuration.

You should see the new Map entry in the application menu. If you select this entry a message dialog opens.

If the menu entry is not displayed, ensure that your IDs are correctly entered. Also ensure that you either use the clearPersistedState flag or clear the workspace data in your Launch configuration.

27. Exercise: Implementing a model processor

In this exercise you replace an existing menu entry with another menu entry.

27.1. Enter the dependencies

Continue to use the com.vogella.tasks.ui.contribute plug-in for this exercise.

In the MANIFEST.MF, add the following plug-ins as dependencies to your contribute plug-in.


  • org.eclipse.e4.core.contexts

  • org.eclipse.e4.ui.model.workbench

27.2. Create the Java classes

Create the following dialog and handler classes.

package com.vogella.tasks.ui.contribute.dialogs;

import javax.inject.Inject;
import javax.inject.Named;

import org.eclipse.jface.dialogs.Dialog;
import org.eclipse.swt.SWT;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;
import org.eclipse.swt.widgets.Label;
import org.eclipse.swt.widgets.Shell;

public class ExitDialog extends Dialog {
    public ExitDialog(@Named(IServiceConstants.
            ACTIVE_SHELL) Shell shell) {

    protected Control createDialogArea(Composite parent) {
        Label label = new Label(parent, SWT.NONE);
        label.setText("Closing this application may result in data loss. "
                + "Are you sure you want that?");
        return parent;

package com.vogella.tasks.ui.contribute.handlers;

import org.eclipse.e4.core.contexts.ContextInjectionFactory;
import org.eclipse.e4.core.contexts.IEclipseContext;
import org.eclipse.e4.core.di.annotations.Execute;
import org.eclipse.e4.ui.workbench.IWorkbench;
import org.eclipse.jface.window.Window;

import com.vogella.tasks.ui.contribute.dialogs.ExitDialog;

public class ExitHandlerWithCheck {
    public void execute(IEclipseContext context, IWorkbench workbench) {
        ExitDialog dialog = ContextInjectionFactory.
                make(ExitDialog.class, context);
        if ( == Window.OK) {

Create the model processor class. This class removes all menu entries which have "exit" in their ID from the menu with the ID. It also adds a new entry.

package com.vogella.tasks.ui.contribute.processors;

import java.util.ArrayList;
import java.util.List;

import javax.inject.Inject;
import javax.inject.Named;

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

import com.vogella.tasks.ui.contribute.handlers.ExitHandlerWithCheck;

public class MenuProcessor {

    // the menu is injected based on the parameter
    // defined in the extension point
    private MMenu menu;

    public void execute(EModelService modelService) {
        // remove the old exit menu entry
        if (!menu.getChildren().isEmpty()) {
            List<MMenuElement> list = new ArrayList<>();
            for (MMenuElement element : menu.getChildren()) {
                // use ID instead of label as label is later translated
                if (element.getElementId() != null) {
                    if (element.getElementId().contains("exit")) {

        // now add a new menu entry
        MDirectMenuItem menuItem = modelService.createModelElement(MDirectMenuItem.class);
        menuItem.setLabel("Another Exit");
                + "com.vogella.tasks.ui.contribute/"
                + ExitHandlerWithCheck.class.getName());

Ensure that your menu entry in the Application.e4xmi file labeled with Exit, contains exit in its ID.

27.3. Register processor via extension

In your contribute plug-in register your processor via the org.eclipse.e4.workbench.model extension.


Right-click on the processor and select New  element. The value from the ID parameter is the ID of the model element which is injected into your processor class. Use as id* parameter.


This assumes that you used as ID for your File menu in the main application model. The ID of the element defined in the extension point must match the @Named value in the processor. If such an element is not found it is not injected into the processor.

27.4. Validate

Start your application. In the model fragment exercises, the contribute plug-in was already added to your product.

Ensure that the existing Exit menu entry is removed and your new menu entry with the Another Exit label is added to the file menu.

28. 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-as  Eclipse 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.


29. Learn more about Eclipse RCP development

I hope you enjoyed this tutorial. You find an extended online training at the Eclipse RCP online training website.

30. Eclipse RCP resources

31. vogella training and consulting support

Copyright © 2012-2019 vogella GmbH. Free use of the software examples is granted under the terms of the Eclipse Public License 2.0. This tutorial is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany license.