Eclipse 4 (e4) Tutorial: Part 2 – Application Model and Views

From the Application Model to the Implementation of Views

This tutorial series introduces the core concepts of the Eclipse 4 Application Platform, aka RCP 2.0. One of the key innovations of e4 is the separation between the application model and the implementation of the application’s parts, such as view. In the first part of this tutorial we provided an overview of the application model, as well as the different ways to modify it, using the editor or the API. With the application model, it is possible to define and test the basic design of an application without having implemented single views. In this second part of the tutorial, we explain how to create the missing part, the implementation of views, for which we have thus far created only placeholders in the application model. This tutorial and all other parts of the series are now available as a downloadable PDF.

An application model without views?

At first glance, it might be confusing as to why Eclipse 4 facilitates such a clear separation between the application model and the implementation of UI components. This is especially true, as one part doesn’t really make sense without the other. In Eclipse 3.x and also in other frameworks, implementations of UI components, such as views, have to implement given interfaces. This approach defines exactly which methods a developer has to implement to create a view. However, this approach also restricts the ability to reuse the implementation of UI components.

A well-known example for this problem is the differentiation between views and editors in Eclipse 3.x, which required different interfaces to be implemented. If you want to reuse a view as an editor or vice versa, you had to refactor. Another example would be to reuse a view in a modular dialog. Finally, when RCP applications are transferred to another context, e.g. on a mobile device (see RAP mobile / Tabris), the design of the workbench has to be changed to fit smaller screens. Therefore one of the goals of Eclipse 4 is to implement UI components in a modular and independent way. The UI consists of small, independent parts, which are not bound to any framework classes such as editor or view, and can be reused in any context.

A view without an application model?

To demonstrate the modularity of the application model and the implementation of views, we started in the first part of this tutorial with the creation of an application model without any implementations. Using the e4 tools, you can even visualize the “empty” application model. Before we fill the application model with implementations, we’ll demonstrate the opposite, that is, implementing views using SWT without an existing application model. We’ll develop modular parts of our application before we know the exact design of the workbench to illustrate Eclipse 4′s modular UI development.

In Eclipse 4, views do not have to implement a given interface. Instead, views define the parameters that the workbench needs to provide. In one of the simplest cases, an SWT view just requires a parent composite, on which the view can be placed. The annotation “@Inject” will be used later on by the Eclipse 4 framework to determine if the parameters of the view should be “injected”. We will go into more detail about dependency injection in a future tutorial in this series.

The following code example shows a very easy “Hello World!” view in SWT.

public class ExampleView {
   @Inject
   public ExampleView(Composite parent) {
      Label label = new Label(parent, SWT.NONE);
      label.setText("Hello World!");
   }
}

Using the application model, this view can be shown later on as part of the workbench in an application. To demonstrate the flexible reusability and testability of such a view, we will first use it without any workbench. The following code example shows how to open the “HelloWorld” view just using SWT. It is worth mentioning that this is a plain Java program. To run this, we only need the relevant SWT libraries. Because of this, the view can be reused anywhere, e.g. a dialog, a wizard or even outside of the Eclipse workbench.

public static void main(String[] args) {
   Display display = new Display();
   Shell shell = new Shell(display);
   shell.setLayout(new FillLayout());
   new ExampleView(shell);
   shell.open();
   while( !shell.isDisposed() ) {
      if( ! display.readAndDispatch() ) {
         display.sleep();
      }
   }
}

This screenshot shows the running Hello World application started from a plain Java program.

helloworld Eclipse 4 (e4) Tutorial: Part 2   Application Model and Views

The Reunion

So far we have created and tested an application model and the implementation of a view separately from each other. Now it’s time to bring both parts together. We do this by adding an element (“Part”) in the application model representing the view within the workbench. The part will be linked to the implementation of the view. Using the e4 template application created with the e4 tools (see section on Installation in the Eclipse 4 Tutorial – Part 1), a part can, for example, be created within the existing “PartStack”.

You see in this screenshot that parts are added to the application model as placeholders for views and editors.

add part 260x300 Eclipse 4 (e4) Tutorial: Part 2   Application Model and Views

To link the part to the implementation of the view, the view’s class has to be selected under “Class URI”. When you start the application, Eclipse 4 will create a part within the workbench and the linked view will be initialized. Parameters, which are required by the view, will be taken from the current context and will be injected into the view. As an example, Eclipse 4 will use the content area of the part as a parent composite for the view and therefore place the view within the part.

setclassuri 300x88 Eclipse 4 (e4) Tutorial: Part 2   Application Model and ViewsFigure : Parts are linked to the implementation of views using the Class URI

Another Separation (Adding a Handler)

For our next step, we want to add some behavior to our application. Therefore, we will implement a Handler, which is triggered by a button in the toolbar of the application. Similar to the implementation of UI components, Eclipse 4 allows a clean separation between the framework and the implementation of a handler, which enables reusability and testability. To demonstrate, we’ll follow a similar workflow to the previous sections, implementing and testing the handler independently from the integration into the application model. We’ll then integrate it in a following step.

Also parallel to how UI components work in Eclipse 4, handlers don’t have to implement a given interface. Instead, they define the required parameters. This reduces the number of required parameters to the minimum needed, making it also easier to test the handler. The following code example show the implementation of a very basic handler for opening a “Hello World!” dialog. The handler needs only one parameter, a shell, to open the dialog. Using the annotation “@Execute”, the handler tells the Eclipse 4 framework which method to execute. In addition, the annotation has the same effect as “@Inject”. That means that the required parameters of the method execute(), in this case a shell, will be injected by the framework. As the example handler does not have a state, the execute() method can be static.

public class MyHandler {
 
   @Execute
   public static void execute(Shell shell){
      MessageDialog.openInformation(shell, "", "Hello World!");
   }
 
}

Handlers in Eclipse 4 are very easy to test, reuse and even chain, as they only require the parameters they really use. The following code example shows a simple Java program which tests the implemented handler. These tests could also be written in JUnit.

public static void main(String[] args) {
   Display display = new Display();
   Shell shell = new Shell(display);
   shell.open();
   MyHandler.execute(shell);
   while( !shell.isDisposed() ) {
      if( ! display.readAndDispatch() ) {
         display.sleep();
      }
   }
}

To integrate the handler with a button in a toolbar, we need another element in the application model. The easiest way to integrate the handler is using a “Direct ToolItem” (see Figure ). Analogous to the part, the implementation of the handler can be bound to the element by setting the Class URI. We’ll need to set a label or icon for the tool item to make it visible in the example application.

adddirecttoolitem Eclipse 4 (e4) Tutorial: Part 2   Application Model and ViewsFigure : Creating a Direct ToolItem in the toolbar of the application

Using a “Direct ToolItem” is the fastest way to integrate a handler with an item in the toolbar. However, for maximum reuse we recommend using commands. We do this by simply creating a handler and a command on the root level of the application model. The handler is bound to the implementation as before, but also to the command (see Figure ). Instead of using a “Direct ToolItem”, which is directly bound to the implementation, a “Handled ToolItem” will be bound to the command. This way, commands can be reused within the application, as an example, key bindings can be used to trigger the execution of a handler.

bind handler 300x90 Eclipse 4 (e4) Tutorial: Part 2   Application Model and ViewsFigure : A handler is bound to its implementation as well as to a command.

Conclusion

In Eclipse 4, elements of the UI define which parameters they require. This approach leads to minimal interfaces and implementations that are very easy to test and reuse. This tutorial showed how to create and test views and handlers without having a corresponding element for them in the application model. In the next installment of this tutorial, we describe how to extend and modularize the application model, that is, how to contribute views and handlers from several plug-ins.

This tutorial and all other parts of the series are available as a downloadable PDF or as links below:

 Part 1: Introduction to Eclipse 4

Part 2: Application Model and Views

Part 3: Extending existing models

Part 4: Dependency Injection

Part 5: Soft migration from Eclipse 3.x

Part 6: Behavior Annotations

For more information, contact us:

Jonas Helming and Maximilian Koegel

EclipseSource Munich leads

5 Responses to “Eclipse 4 (e4) Tutorial: Part 2 – Application Model and Views”

  1. [...] with the new platform. Looking forward to your comments and additions. Previous parts (part 1 and part 2) of this tutorial are available now as a downloadable [...]

  2. JavaPins says:

    Eclipse 4 (e4) Tutorial – Part 2…

    Thank you for submitting this cool story – Trackback from JavaPins…

  3. Marco Descher says:

    Hy there,

    thank you for this guide, I have one question however:

    If I have a HandledToolItem of Type “Check” or “Radio” how am I supposed to have a connection of the current state of Check within the contribution and the handler code in this model?

    Thanks, marco

  4. Hi,
    for a check item you could inject the MenuItem into the handler
    @Execute
    execute(MMenuItem item) {
    item.isSelected()
    }

    For Radio: are they even displayed? how does a radio button look like in a toolbar?
    Regards
    Jonas

5 responses so far

Written by . Published in Categories: Planet Eclipse