Eclipse 4 (e4) Tutorial Part 1 – The e4 Application Model

The countdown is on for Eclipse 4. For the current Kepler release, the core tooling components are again built based on the Eclipse SDK 4.3. This series will introduce the new concepts in the Eclipse 4 Application Platform, aka RCP 2.0. It is likely that most projects will use the compatibility layer initially, however, it is worthwhile to look at the new concepts and try them out. This tutorial and all other parts of the series are now available as a downloadable PDF.

I will start with the foundation of every Eclipse 4 application, the application model. In this first part, I would like to introduce the different options for modifying this model.

Application Model vs. Views

In Eclipse 4, the application model defines the workbench, including views, menu contributions and key bindings. The model doesn’t require that you first implement the single components. For example, you can work with the model without implementing a view.

The cornerstones of the application model are windows and parts. Contrary to the eclipse 3.x platform, e4 has combined views and editors into the concept of Parts, which represent views inside a window. If you add a part in the model, you can later connect it to your implementation of the selected view. To show the resulting separation between the general workbench design and the implementation of single parts, I will not show any SWT code in this section. Instead we’ll focus on the model and how to connect the model to code.

picture6 Eclipse 4 (e4) Tutorial Part 1   The e4 Application ModelThe Parts of an application model are connected later to their implementations

Installation

You can get the latest version of Eclipse 4 here:  http://www.eclipse.org/eclipse4/. The IDE itself is based on Eclipse 4 and also contains several useful tools to create RCP and RCP 2 applications. Additionally, we recommend installing the e4 Tools, which, thanks to Tom Schindl, provide a very useful template for creating applications as well as an editor to modify the application model. At writing, these tools are still in incubator status and can be installed from an update site, Please pick the latest version from here:  http://download.eclipse.org/e4/downloads/

installe4tools Eclipse 4 (e4) Tutorial Part 1   The e4 Application Model

The first step

After installing Eclipse 4 the easiest way to get started is to use the e4 template to create a new e4 application. To create a project, choose the „e4 Application Project“ entry within the „new Project“ wizard. For this application you don’t have to change anything except the name of the application. The template creates a product definition and you can start the application simply by starting this product. To start it, open the *.product file and click on run or debug in the upper right corner of the editor. As you can see below, the generated template application already contains a window, two menus, a toolbar and a perspective stack.

picture1 003 Eclipse 4 (e4) Tutorial Part 1   The e4 Application ModelClick here to start the product.

The Editor

To modify the application model you’ll need an editor which you can start by opening the Application.e4xmi located in the root level of the project. On the left side you see a tree showing the complete contents of the model. By double-clicking an element in the tree, a detailed view will be opened on the right side allowing you to modify the properties of that element.

The top-level elements of an application are usually one or more windows that you can find in the application model under “windows”. The template project already contains a TrimmedWindow. By double-clicking this element you can, for instance, modify the size of this window. Check the result by restarting the application.

With a right click in the tree, new elements can be added and existing ones can be removed. As an example you can remove the existing PerspectiveStack and just add a single Part instead. After a restart of the application you will notice that the main area of the application does not have a border anymore. However, the new part isn’t visible and it would be nice to have some control over the result. I’ll describe how to do that in the next section.

 picture2 Eclipse 4 (e4) Tutorial Part 1   The e4 Application ModelOpen the application model to modify the workbench

Live Editing

Eclipse allows you to define the workbench using the application model even without providing implementations. However, this is sometimes hard to work with because empty Parts are often hard to identify. To resolve this Tom Schindl introduced the idea of a live editor. It allows you to access the application model of a running application, modify it and highlight selected components. To enable the live editor you need to start two plug-ins along with your application. You can check them in the run configuration and additionally click on “Add required” to include the required dependencies. A run configuration should have been created for you when you first started the product.

picture3 Eclipse 4 (e4) Tutorial Part 1   The e4 Application Model

In the running application you can start the live editor via ALT+SHIFT+F9. This editor works exactly like the editor in your IDE, however, it directly accesses the application model of the running application. If you, for instance, open the TrimmedWindow in the editor and change its size or position, the changes are directly applied in the running application.

picture4 Eclipse 4 (e4) Tutorial Part 1   The e4 Application Model

The live editor is not only capable of modifying elements, you can even add new ones. As an example, if you add a new window to the application model (right-click on the tree-node windows), a new window will be opened in the application. To maintain an overview of which components are visible in the application, these components can be colored. By right-clicking an element in the live editor, e.g. the TrimBar and selecting “Show Control”, the control will be colored in red in the running application.

 

picture5 Eclipse 4 (e4) Tutorial Part 1   The e4 Application ModelElements of the application models can be colored in the running application.

Using this feature, one can easily visualize changes within the application model. This is especially useful for elements which are not directly visible in the UI. As an example, if you add a new Part in a Window, it will not be visible without coloring as it does not have any content yet.

If you use the live editor to change the application model the changes will only be reflected in the running application. To transfer them into the deployable application, you can copy the modified version of the model using the tab „XMI“ and copy it into the model available in your IDE.

Programmatical Access to the Model

One of the major advantages of the application model is the ability to modify it via API. As the application model is represented in EMF, the API is very familiar to anyone who has used EMF before. Using this API you can create or modify parts of the application programmatically, for example, reacting to a user action. To test this in the template application you can use one of the existing handlers, such as the class OpenHandler.  As you can see in this handler, there is a method execute() marked with the annotation @execute, which will be executed if the connected ToolItem is pressed by the user.

Dependency injection, which we’ll go into more detail on later, allows the programmer to easily define which parameters are needed within this method. In the following code example the method requires the application window as parameter so it will be injected by the framework. In the first line a new part is created and in the second line this part is added to the window. You can check the result by using the live editor described above. First you’ll need to start the application and the live editor. Then click the open button in the toolbar of the example application. In the live editor you can confirm that the new part has been added correctly and even color it in the application.

@Execute
public void execute(MWindow mWindow) {
    MPart newPart = MBasicFactory.INSTANCE.createPart();
    mWindow.getChildren().add(newPart);
}

In the second code example, a new window is created. To add this new window into the application, the application is required as a parameter. Using the API, the window is sized, a new part is added into the window and the window is added to the application. By adding the window to the application, it is opened in the running application. Restart the application and press the button again to check the result.

@Execute
public void execute(MApplication application) {
    MWindow mWindow = MBasicFactory.INSTANCE.createTrimmedWindow();
    mWindow.setHeight(200);
    mWindow.setWidth(400);
    mWindow.getChildren().add(MBasicFactory.INSTANCE.createPart());
    application.getChildren().add(mWindow);
}

Scripting

Another nice feature of the live editor is the ability to apply scripting and access parts of the model API during runtime. As this code will be dynamically interpreted, JavaScript is used. Scripts can be executed on any part of the application model. To do so, start the application and the live editor (ALT+SHIFT+F9). Right click any element, e.g. a window, and select “Execute script”. In the open window, you can enter JavaScript, which will be wrapped to the Java API. The following code example will set the label of a window – during runtime.

mainObject.setLabel("Hello Eclipse")

This second example will make an element invisible. You can try executing this example on the ToolBar, which you can find in the model tree under TrimmedWindow => TrimBar => WindowTrim => ToolBar

mainObject.setVisible(false)

Conclusion

The e4 application models allows you to define the general design of an application in a consistent way, without implementing single parts in advance. We described different methods to modify the application model, including how to modify the model during runtime using the live editor or the API. At this point we have only created placeholders in the application. The next part of this series describes how to connect the application model with the implementation of UI components, that is, how to create the connection between a part and the implementation of a view filling this part.

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

Author: Jonas Helming

14 Responses to “Eclipse 4 (e4) Tutorial Part 1 – The e4 Application Model”

  1. John Arthorne says:

    Great blog post! I hope you don’t mind I have added a link to it on the Eclipse 4 tutorials page:

    http://wiki.eclipse.org/Eclipse4/Tutorials#EclipseSource_Eclipse_4_Tutorial

    Feel free to correct any information or add more details about your planned series on that page. It will be linked from the main “Eclipse 4″ landing page for the Juno release.

  2. Mark says:

    Is it just me or is the Juno update site broken? I cannot install e4 Tools because it depends on EMF. And I get “No repository found at http://download.eclipse.org/releases/juno.” for the Juno update site.

  3. Peter Kirschner says:

    The mail sent after registration does not contain any link.

  4. Jonas Helming says:

    thanks for linking I will keep that updated.

  5. Jonas Helming says:

    EMF should be already within the Eclipse 4 installation. You might miss emf databinding?

  6. Jonas Helming says:

    you should be able to login on the page which is linked, with the account and get the PDF. Please tell me if you have any problems doing that!

  7. Peter Kirschner says:

    Login is not feasible. Tried on different browsers .(IE, Chrome, Firefox)

    An error occurred during login. Most likely you didn’t enter the username or password correctly.
    Be certain that you enter them precisely as they are, including upper/lower case.
    Another possibility is that cookies might be disabled in your webbrowser.

    And yes, cookies are enabled ;-)

  8. Mark says:

    Jonas, yes, something in EMF is missing. I downloaded both the m6 and m7 with the same result.

    Wellllll. I just checked this morning and I can connect to the repo. So, either something was temporarily wrong with it or something along the way (intranet, firewall, etc).

  9. [...] 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 [...]

  10. [...] applications 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 [...]

  11. JavaPins says:

    Eclipse 4 (e4) Tutorial Part 1 – The e4 Application Model…

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

  12. [...] the previous parts of this tutorial series we described how to create an application model and link those elements to implementations. Until now we have only worked with one application [...]

  13. [...] much easier way to develop plugins, and RCP Applications.  There are great resources available to help you get started. Also, the e4 incubator has a number of exciting technologies, including a live model editor that [...]

  14. [...] 4 is the new platform for application development in Eclipse. We already succeeded to run e4 applications on RAP two years ago, but then we got [...]

14 responses so far

Written by . Published in Categories: EclipseSource News, Planet Eclipse