Eclipse e4 notes. Just some notes about Eclipse 4 for my personal use.

1. Source code

1.1. Workbench XMI file

The base workbench model for the Eclipse IDE is defined in the "org.eclipse.ui.workbench" plug-in in the "LegacyIDE.e4xmi" file. In the org.eclipse.platform plug-in you find the LegacyIDE.e4xmi file which defines the initial window and some model Add-ons.

If Eclipse is started in the compatibility mode, this file is read via the E4Workbench class. This class is part of the org.eclipse.e4.workbench.ui.internal package. E4Workbench will then convert the relevant extension points into elements of the application model.

1.2. Eclipse 4 application - E4Application

The org.eclipse.e4.ui.workbench.swt.E4Application application is defined in the extension point org.eclipse.core.runtime.applications in the org.eclipse.e4.ui.workbench.swt plug-in.

It points to the org.eclipse.e4.ui.internal.workbench.swt.E4Application class which implements the IApplication interface.

The E4Application class, reads the parameter passed to the application, evaluates the model and builds up the context. The loadApplicationModel(IApplicationContext appContext, IEclipseContext eclipseContex) method will load the initial application. The createE4Workbench IApplicationContext applicationContext, Display display) method will process the whole model.

1.3. Model Resource Handler

The org.eclipse.e4.ui.internal.workbench.ResourceHandler class is responsible for loading and saving the model. The loadBaseModel() method will load the Application.e4xmi model.

1.4. Other important classes

Table 1. Important Eclipse 4 classes
Class Description

org.eclipse.e4.workbench.ui.internal.E4Workbench

e4 workbench implementation for the SDK.

org.eclipse.e4.core.services.internal.annotations.AnnotationsSupport

Checks for annotations

org.eclipse.e4.workbench.ui.renderers.swt.WorkbenchRendererFactory

SWT renderer factory, implements IRendererFactory

IPresentationEngine with the default implementation of PartRenderingEngine

Translates the model elements into UI components and reflects all modification in the model in the UI. For example if you change a label in the model this engine will update UI.

2. HDPI support in Eclipse 4.6

Eclipse 4.6 (Neon) support HDPI displays. SWT will scale images and text according to the screen density. This happens automatically.

For testing you can also define the scale factor manually. On GTK you can us the GDK_DPI_SCALE environment variable before launching eclipse, e.g. for 150%:

export GDK_DPI_SCALE=1.5
./eclipse

To only change the SWT scale factor (but not the fonts that get scaled by the OS), you would use the following:

./eclipse -vmargs -Dswt.autoScale=200

By default, Windows only supports scaling factors of 100%, e.g. 1x, 2x,etc. You can instruct the scaling enging to support steps of 25 with the following parameter

./eclipse -vmargs -Dswt.autoScale=quarter

the swt.autoScale property is not meant to be used by end users. It’s just there as a fallback in case the automatic detection somehow went terribly wrong.

On Windows 7, there’s no good way to test this other than using the Display control panel to choose a percentage or set a custom text size (DPI), and then logging out.

3. Providing HDPI images in your plug-in

The Eclipse platform has been extended to support HDPI icons. If you provide only one size of the icons, the platform will scale the icon. You can provide png icons with different sizes by using the @2x convension.

Use png icons instead of gif icons to support real transparency needed for dark themes.

Your 16x16 pixel icon would be the default and your 32x32 pixel icon would be picked on HDPI displays.

For example:

org.eclipse.jdt.astview/icons/e/clear.png
org.eclipse.jdt.astview/icons/e/clear@2x.png

The platform will pick the correct icon automatically.

The Eclipse Platform contains a Maven plug-in which can be used to convert SVG graphics to png.

Clone the Eclipse Platform UI repo to use it. You find the clone URI on the following website:

https://git.eclipse.org/r/#/admin/projects/platform/eclipse.platform.images

Here you find the org.eclipse.images.renderer plug-ins. See its Readme how to convert SVG to png. The generated png can be included into your Eclipse RCP application.

4. HDPI support in Eclipse 4.6

Eclipse 4.6 (Neon) support HDPI displays. SWT will scale images and text according to the screen density. This happens automatically.

For testing you can also define the scale factor manually. On GTK you can us the GDK_DPI_SCALE environment variable before launching eclipse, e.g. for 150%:

export GDK_DPI_SCALE=1.5
./eclipse

To only change the SWT scale factor (but not the fonts that get scaled by the OS), you would use the following:

./eclipse -vmargs -Dswt.autoScale=200

By default, Windows only supports scaling factors of 100%, e.g. 1x, 2x,etc. You can instruct the scaling enging to support steps of 25 with the following parameter

./eclipse -vmargs -Dswt.autoScale=quarter

the swt.autoScale property is not meant to be used by end users. It’s just there as a fallback in case the automatic detection somehow went terribly wrong.

On Windows 7, there’s no good way to test this other than using the Display control panel to choose a percentage or set a custom text size (DPI), and then logging out.

5. Model processing

The ModelAssembler class processes the model fragments and processors in its methods.

6. API guide to the commands framework

See MenuHelper

6.1. The org.eclipse.e4.ui.tests plug-in

The overall test suite for running the plug-ins' tests is org.eclipse.e4.ui.tests.UIAllTests.

package org.eclipse.e4.ui.tests;

/**
 * All E4 UI-related tests
 */
@RunWith(Suite.class)
@Suite.SuiteClasses({
        // Hack: bug 422676, run InjectionEventTest first
        InjectionEventTest.class, (1)
        StartupTestSuite.class,
        UIEventTypesTest.class,
        Bug299755Test.class,
        Bug308220Test.class,
        Bug320857Test.class,
        PartOnTopManagerTest.class,
        PartRenderingEngineTests.class,
        SashRendererTest.class,
        MApplicationCommandAccessTest.class,
        MMenuItemTest.class,
        MPartTest.class,
        MPartSashContainerTest.class,
        MSaveablePartTest.class,
        MToolItemTest.class,
        MWindowTest.class,
        MSashTest.class,
        HandlerTest.class,
        ContextTest.class,
        Bug308317Test.class,
        ModelRobustnessTest.class,
        ResourceHandlerTest.class,
        PartFocusTest.class,
        ModelElementTest.class,
        StackRendererTest.class,
        TabStateHandlerTest.class,
        ThemeDefinitionChangedHandlerTest.class,
        TopoSortTests.class,
        ExtensionsSortTests.class,
        HandlerActivationTest.class,
        ModelAssemblerTests.class,
        ModelAssemblerFragmentOrderingTests.class
        // SWTPartRendererTest.class,
})
public class UIAllTests {
}
1 The InjectionEventTest always has to be run first (https://bugs.eclipse.org/bugs/show_bug.cgi?id=422676)

6.2. ContributionsAnalyzer

The ContributionsAnalyzer class is a class with lots of static method to analyse things like the visibility of MenuItems.

7. Information about the e4 tools

7.1. e4 tools and committer

The e4 tools project provides tools for developing Eclipse 4 based applications. The following follows more or less the same guidelines as the Eclipse platform team.

7.2. Git repository for the e4 tools

The e4 tools are also available via their Git repository.

# Eclipse e4 tooling
git clone git://git.eclipse.org/gitroot/e4/org.eclipse.e4.tools.git

# Some e4 demos, not required, not always working
git clone git://git.eclipse.org/gitroot/e4/org.eclipse.e4.ui.git

7.3. Infos about the e4 tools

Most e4 tools project contain a README.md file which describes their usage and important classes.

7.4. Adding an editor for a custom model elements

The org.eclipse.e4.tools.emf.ui plug-in defines the org.eclipse.e4.tools.emf.ui.editors extension point, which allows registering editors for new model elements.

7.5. Building the e4 tools

You can build the e4 tools locally via Maven Tycho. If you have Maven installed on your machine, the build process is trivial.

Clone the e4 tools project with the following command.

# clone e4 tooling
git clone git://git.eclipse.org/gitroot/e4/org.eclipse.e4.tools.git

Afterwards, you can build the e4 tools via Maven on the command line.

cd org.eclipse.e4.tools
mvn clean verify

After the build finishes successfully, you find a p2 update site in the following folder.

org.eclipse.e4.tools.build/org.eclipse.e4.core.tools.update/target/repository/

8. Tips

8.1. Where do I find the initial application model of the Eclipse SDK

In plug-in "org.eclipse.platform". Here you find the file "LegacyIDE.e4xmi" which defines the initial window and some add-ons. During startup the E4Workbench class from the org.eclipse.e4.workbench.ui.internal package is started.

8.2. Meta-model of the application model

The structure of the application model is defined by a meta-model created with the Eclipse Modeling Framework (EMF). A meta-model describes the structure of a data model, e.g., it defines which properties a part has.

The meta-model of the Eclipse 4 applications is stored in the org.eclipse.e4.ui.model.workbench plug-in inside the model folder. The base model definition can be found in the UIElements.ecore file. The Eclipse 4 model classes have been generated based on this model.

If you want to investigate this model, you should install the EMF tooling.

The Application.e4xmi file, which describes the Eclipse application model, is a persisted version of an EMF model.

8.3. Determine the command ID in a handler

In the handler class you can determine the command ID if the command was triggered via the user interface Determining the ID is not possible, if it was triggered via the command service. The following code snippet shows how to get the command ID.

@Execute
public void execute(MHandledItem item) {
  MCommand command = item.getCommand();
  // Prints out the commmand ID
  System.out.println(command.getElementId());
}

8.4. BindingContext

Eclipse 4 uses predefined BindingContext identifier which are based on org.eclipse.jface.contexts.IContextIds.

These are org.eclipse.ui.contexts.dialog for dialogs, org.eclipse.ui.contexts.window for windows and org.eclipse.ui.contexts.dialogAndWindow for both.

8.5. DI in OSGi stand-alone environments

It is possible to use the DI engine in a standard OSGi environment

public Object start() {
  // get Bundle Information
  Bundle bundle = FrameworkUtil.getBundle(getClass());
  BundleContext bundleContext = bundle.getBundleContext();
  IEclipseContext eclipseCtx =
      EclipseContextFactory.getServiceContext(bundleContext);

  // fill Context with information using set(String,Object)
  // ....

  // create instance of class
  ContextInjectionFactory.make(MyPart.class, eclipseCtx);
}

8.6. Persists user changes

Via a startup parameter you can control if Eclipse should persists model changes. For example, you want to save the last position of the main application window. This is similar to the setSaveAndRestore(true) method call in Eclipse 3.x.

Table 2. Sample Table

Parameter

Description

-persistState false

true

Default is false, if set to false user changes are not recorded.

-clearPersistedState

will delete the recorded delta of the last session.

-deltaRestore true

false

Controls how the deltas are stored. a) Store deltas and them on startup using the Reconciler. This way new contribution will be shown in your application. b) Serialize the complete model (this is similar to 3.x saveAndRestore(true)) and deserialize from XMI.

8.7. Styling the Eclipse 4 IDE

The platform style sheets are stored in the org.eclipse.platform plug-in. This plugin contains a /css folder which contains the style sheets for the individual platforms (os based).

You can use the ThemeManager to style the Eclipse 4 IDE itself. In the Eclipse the theme can be selected via Window  Preferences  General  Appearance.

You can also contribute a new theme via a separate plug-in. Create a plug-in project (no activator required) which has a dependency to the org.eclipse.e4.ui.css.swt.theme plug-in.

Contribute a new theme to the org.eclipse.e4.ui.css.swt.theme extension point. Create a CSS file and point the theme to this file.

Export the plug-in (including the CSS file). Put it into your Eclipse installation folder into the "dropins" folder. You should be able to select your new theme after restarting the Eclipse IDE.

9. Architectural background of the application model

This section contains some background information about the design goals of the Eclipse application model and has been contributed by Eric Moffatt, Eclipse 4 SDK development lead.

9.1. Main areas of the model

Conceptually the model is structured into three areas which are described in the following table.

Table 3. Architectural areas of the model
Area Description

Mix-ins

Abstract interfaces containing the attributes necessary to support their specific roles in some derived concrete types. For example MContext contains only the reference to the context, MContribution contains the instantiated object and MUILabel contains attributes to manage labels and images.

Containment Types

Every concrete container specifies a specific interface as its containment type. It allows the generic to be a specific type and the compiler to generate a compile time error if an attempt is made to add an invalid element to a container. It also means that when creating a domain specific model (or changing the base model) it is relatively easy to loosen the containment rules. For example to allow MParts in the MTrim area, you would only have to add the MTrimElement interface to MPart.

Concrete Classes

Elements that the application model itself contains, defined by a combination of various mix-ins and containment types. These are further sub-divided based into packages in the model definition model.

9.2. Advantages of using mix-ins

Mix-ins allow the Eclipse 4 internal code to manage the mix-ins specifically, regardless of the concrete class they`re a part of. For example the PartRenderingEngine class handles all contexts by checking whether the element being rendered is an MContext. It also allows via the findElements() method of EModelService to locate all elements in the model of a specific type. This is useful for finding all MDirtyable elements for saving.

Mix-ins make domain specific modeling simpler. The Eclipse 4 team anticipate that more sophisticated clients create domain specific models (and the corresponding renderers) so that they could work directly against their own element types.

Having the mix-ins in place makes this much simpler as well as being able to reuse existing code written to manage a particular mix-in.

10. Learn more and get support

This tutorial continues on Eclipse RCP online training or Eclipse IDE extensions with lots of video material, additional exercises and much more content.

Eclipse E4 Wiki

Eclipse RCP

Eclipse EMF

Dependency Injection

If you need more assistance we offer Online Training and Onsite training as well as consulting

See License for license information.