Eclipse 4 (e4) Tutorial Part 3 – Extending the Application Model

In 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 model, however, Eclipse applications usually follow a modular design. In this part, we describe how to extend an existing application model with new elements, for example, adding a new entry to a menu. This tutorial and all other parts of the series are now available as a downloadable PDF.

Only one model?

One of the major advantages of Eclipse RCP development is the modular design of applications. The plugin concept, based on OSGi, enables the development of features independently and deployment of same, only if required. A very good example of such a modular application is the Eclipse IDE, where many additional plugin can be installed. Many of these extensions affect the workbench design of an application, that is, they add additional buttons, menu items and views. In e4, the application model is the central and consistent approach to designing the workbench. However, there needs to be a way to extend the application model from new plugins. Eclipse 3.x uses extensions points for this, while Eclipse 4 offers fragments and processors to extend the application model. A fragment is a small application model itself and defines elements which need to be added to the root application model. Fragments can add anything that can be part of the application model, for example handlers, menu items or even windows.
The following diagrams show an example of such an extension. The application model of the plugin „org.eclipse.example.e4“ is extended by a fragment from the plugin „org.eclipse.example.e4.extension“.

fragmentextension 300x162 Eclipse 4 (e4) Tutorial Part 3   Extending the Application Model

The application model can be extended using fragments.

Processors offer a mechanism to programmatically extend an application model. This allows the application to react to the current state of the model. As an example, you can only add a new button if another contribution is installed or if you can remove existing elements. In this tutorial, we describe both ways of extending an application model, fragments and processors. In both cases elements of the application model are linked to their implementations as described in the previous chapters of this tutorial. The implementation is usually part of the plugin doing the contribution, as in the previous example „org.eclipse.example.e4.extension“.

Warm-Up

The first step is to create a main plugin and an application model which can be extended. As in the previous parts of this tutorial we will use the e4 template application, which can be created using a wizard. It is important that elements in the application model which will be extended have a unique id. This id is used to reference elements from the extending fragment. In the template application the application and the toolbar already have an id. As we want to add a new part to the existing part stack, the part stack also has to have an id. Therefore, the field “id” has to be set for the part stack in the application model (Application.e4xmi )

partstack Eclipse 4 (e4) Tutorial Part 3   Extending the Application Model

The existing part stack needs a unique ID

idforpartstack 300x60 Eclipse 4 (e4) Tutorial Part 3   Extending the Application Model

The ID allows referencing of an existing element from an extending fragment

Additionally, we need a second plugin which extends the first one. This second plugin needs the following dependencies:
• org.eclipse.e4.ui.model.workbench
• org.eclipse.e4.core.di
• javax.inject
• the plugin to be extended

Model Fragment

A fragment is nothing more than a small application model. A file containing fragments can be created using the wizard provided by the e4 tools.

new fragment 001 Eclipse 4 (e4) Tutorial Part 3   Extending the Application Model

The extending plugin is set as a container. The model fragment file is opened in an editor which works similarly to the editor used to modify an application model. The first step is to add a fragment. A fragment has to define at which place the main application model is extended. This is done through an Element ID and a feature name. The Element ID defines which element of the main application model is extended, e.g. a tool bar. The feature name defines the EMF reference to which the new element is added. For elements such as toolbars, menus, windows or even the application, the feature is usually defined as a “child”. In the following example, a new element is added as a child of the existing toolbar.

select toolbar 300x62 Eclipse 4 (e4) Tutorial Part 3   Extending the Application Model

The element ID defines which element is extended

select children of toolbar Eclipse 4 (e4) Tutorial Part 3   Extending the Application Model

The feature name defines where the new element is added

Within the new fragment, another new element can now be created. As a simple example, we will add a DirectToolItem as a child of the fragment. To make it visible, a label or icon should be set. To trigger some action on a click on the new tool item, it should be linked to a handler. In the example, it is linked to a handler saying “Hello Eclipse!”.

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

To connect the DirectToolItem to the handler, the “Class URI“ of the DirectToolItem is set to the implementing class. This class is located in the extending plugin.
Of course it is also possible to add more than one element to a fragment. For example, a tool item, a handler and a command can be added and linked to each other.
In any case the new model fragment has to be registered via an extension point.

<extension id=”id” point=”org.eclipse.e4.workbench.model”>

<fragment uri=”fragment.e4xmi”></fragment>

</extension>

Finally, the new plugin adding the model fragment has to be added to the existing product configuration. After restarting the application the tool item should be visible in the same way as a new part would be added to the existing part stack.

new toolbaritem Eclipse 4 (e4) Tutorial Part 3   Extending the Application Model

Model Processor

In addition to being able to use fragments, it is also possible to programmatically extend the application model. In e4 this is accomplished using processors. Processors are especially useful if the extension needs to react to conditions within the existing application model, or if the existing application model is to be modified by an extension. In the example application, we will add a new window that is positioned relatively to the existing window. The new window has the same height as the existing one and is positioned to the left of it. To free space for the new window, the existing window is moved right. To modify the application model, some experience with EMF is useful. A tutorial on EMF can be found under this link [1] The following code shows the implementation of the described processor where the modified application model (MApplication) can be injected.

public class Processor {
 
   @Inject
   MApplication application;
 
   @Execute
   public void execute(){
      MWindow existingWindow = application.getChildren().get(0);
      existingWindow.setX(200);
      MTrimmedWindow newWindow =
      MBasicFactory.INSTANCE.createTrimmedWindow();
      newWindow.setWidth(200);
      newWindow.setHeight(existingWindow.getHeight());
      application.getChildren().add(newWindow);
   }
}

Finally, the same as we did for the model fragment, the processor has to be registered via an extension point. After a restart of the application, the second window should open.

<extension id=”id” point=”org.eclipse.e4.workbench.model”>

<processor beforefragment=”true”

class=”org.eclipse.example.e4.extension.Processor”>

</processor>

</extension>

Conclusion

Model fragments and processors allow the extension of an existing application model. This supports the modular design of an application as new features including UI contributions, can be easily added or removed from an existing application. The definition of model fragments works in the same way as the definitions of the application model itself and does not require additional knowledge. The programmatic extension using processors uses a consistent EMF API and offers full flexibility.
The next chapter of this tutorial will describe dependency injection in Eclipse 4. We will describe how to influence the injected parameters using different annotations, as well as how to trigger the injection manually.

 

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

Comments are closed.

No responses yet

Written by . Published in Categories: Planet Eclipse

Author:
Published:
Jun 26th, 2012
Follow:

Twitter Google+