on May 10th, 2012Eclipse 4 final sprint – Part 1 – The e4 Application Model
The countdown is on for Eclipse 4. For the upcoming Juno release, the core tooling components will build on the Eclipse SDK 4.2. 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. The first part of the tutorial is available now 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.
The 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 this update site: http://download.eclipse.org/e4/downloads/drops/R-0.12M6-201203151300/repository
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.
Click 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.
Open 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.
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.
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.
Elements 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.
For more information, contact us:
Maximilian Koegel and Jonas Helming
EclipseSource Munich leads
Email: e4@eclipsesource.com
This tutorial and all other parts of the series are available as a downloadable PDF.
Author: Jonas Helming
But I can hardly remember any technical problem that caused me as much of a headache as these few names did. I hope that after so many discussions, this new API will prove to be simple to understand and to use.
