Eclipse Papercuts

Eclipse e4 M4 has introduce a new look and feel for the tabs in the workbench. See Eclipse e4 M4 New and Noteworthy. Unfortunately the news and noteworthy document did not give information how to enable this feature.

The e4 mailing list has recently discussed this topic and Remy Suen was kind enough to provide this information. To turn this feature on you have to add the tag “newtablook” to your PartStack.

For example if you create an new e4 application with the e4 wizard you can add this tag via:

<children xsi:type="application:PartSashContainer" xmi:id="_vTa8kiuFEd-PeMLywHTM-g" id="_vTa8kiuFEd-PeMLywHTM-g">
  <children xsi:type="application:PartStack" xmi:id="_vTa8kyuFEd-PeMLywHTM-g" id="_vTa8kyuFEd-PeMLywHTM-g">
     <tags>newtablook</tags>
   <children xsi:type="application:Part" xmi:id="_vTa8lCuFEd-PeMLywHTM-g" id="_vTa8lCuFEd-PeMLywHTM-g" label="Main"/>
</children>

This lead to the following result:

Compared to the “old” look and feel.

For this topic see also Bug 305147 which discusses to move this feature to the CSS styling capabilities.

Eclipse e4 has sometimes the tendency to do thing differently then expected. For example the modeled workbench may not show certain UI elements. In this case it is difficult to find out what is wrong.

This blog post tries to help to look inside the initialization process of an Eclipse e4 application.

In my e4 tutorial I write that you always have to start the application “org.eclipse.e4.ui.workbench.swt.E4Application”.

The implementation class is “org.eclipse.e4.ui.workbench.swt.internal.E4Application” and can be found in the plugin “org.eclipse.e4.ui.workbench” in. This instance of IApplication is created by the framework.

In this class you find the main entry point to your application:

public Object start(IApplicationContext applicationContext)
			throws Exception {

			}

The following line creates the mighty IEclipseContext.

IEclipseContext appContext = createDefaultContext();

In createDefaultContext() you find for example that e4 sets initially an empty Styling engine and you find the registration of the extension registry.

The next line is more interesting, its load the models. Here you can check if the model entries are available as expected.

MApplication appModel = loadApplicationModel(applicationContext,
				appContext);

Just in case you are wondering “M” Elements refer to the UI workbench model modeled with EMF. MApplication is the model element for the application and extends for example MContent which allows to store the IEclipseContext.

After a few lines of compatibility stuff the the model is added to the IEclipseContext and vise versa:

// Set the app's context after adding itself
		appContext.set(MApplication.class.getName(), appModel);
		appModel.setContext(appContext);

The next lines are interesting as they also reveal typical errors (I make). They load the parameters for “applicationXMI”, css stylesheets and the rendering engine. Here you can check if you parameters are read by the engine.

		// Parse out parameters from both the command line and/or the product
		// definition (if any) and put them in the context
		String xmiURI = getArgValue(E4Workbench.XMI_URI_ARG, applicationContext);
		appContext.set(E4Workbench.XMI_URI_ARG, xmiURI);
		String cssURI = getArgValue(E4Workbench.CSS_URI_ARG, applicationContext);
		appContext.set(E4Workbench.CSS_URI_ARG, cssURI);
		String cssResourcesURI = getArgValue(E4Workbench.CSS_RESOURCE_URI_ARG,
				applicationContext);
		appContext.set(E4Workbench.CSS_RESOURCE_URI_ARG, cssResourcesURI);

		// This is a default arg, if missing we use the default rendering engine
		String presentationURI = getArgValue(E4Workbench.PRESENTATION_URI_ARG,
				applicationContext);
		if (presentationURI == null) {
			presentationURI = PartRenderingEngine.engineURI;
			appContext.set(E4Workbench.PRESENTATION_URI_ARG, presentationURI);
		}

The last lines are for actually creating the E4Workbench and running it.

/ Instantiate the Workbench (which is responsible for
// 'running' the UI (if any)...
E4Workbench workbench = new E4Workbench(appModel, appContext);

The class “org.eclipse.e4.workbench.ui.internal.E4Workbench” is worth a look. It defines the fixed values for the possible parameters, e.g. “applicationXMI”.

The init() method is responsible for creating the UI in the method call Workbench.processHierarchy(appElement); where appElement is initially the MApplication. processHierachy() is then recursively called for all model elemements.

I hope this helps in evaluating and debugging the e4 platform. Let me know what you think.

I had several l requests to update Create your first Eclipse e4 application to the latest changes.

I have written an updated version of this description Eclipse e4 tutorial. It should be compliant with the Eclipse e4 Milestone 3.

Like the blog entry this is currently only creating a very simple example. I’m planning to extend this tutorial over time to demonstrate the advantages of dependency injection, css styling, different renderes, etc.

Hope this helps getting started with Eclipse e4.

Let me know what you think about e4 and what e4 functionality should be also be the tutorial.

Update This description has been updated in the following tutorial: Eclipse e4 tutorial.

In the Eclipse e4 webseminar I learned about the e4 UI editor which allow you to change the user interface on the fly.

As you most likely know the Eclipse UI is modelled as an Eclipse EMF model. This model can be changed during directly in Eclipse via the editor or via the EMF API (I have not yet tested this) and the UI will change immeadiately according to the change.

To following my example you need the E4 0.9 download from Eclipse E4 0.9 download.

Start Eclipse e4 tutorial. Select Window -> UI Editor

Open the WorkbenchWindow

You can now modify the model, e.g. you can drag the package explorer on the same level as the Java perspective.

I believe the modeled UI concept is really powerful as it exposes the internal state of the Eclipse based apllication via a well-defined model with a clear API.

Kudos to the Eclipse e4 team!

Update This description has been updated in the following tutorial: Eclipse e4 tutorial.

Eclipse e4 allows to style your applications via css like stylesheets. The following gives a short example how to get started with css stylecheets.

Create a new e4 product “de.vogella.e4.css” similar to the description Your first Eclipse e4 application. Of course you can also copy “de.vogella.e4.first” and edit the package, Application.xmi and the product to fit the new project “de.vogella.e4.css” or just extend “de.vogella.e4.first” with the usage of stylesheets.

I like to have my examples separate therefore I use “de.vogella.e4.css”.

First lets extend our UI from last time a little bit. Change View1.java to the following.

package de.vogella.e4.css.views;

import org.eclipse.e4.core.services.context.IEclipseContext;
import org.eclipse.jface.layout.GridLayoutFactory;
import org.eclipse.swt.SWT;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Button;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Label;
import org.eclipse.swt.widgets.Text;
import org.eclipse.ui.services.IDisposable;

public class View1 implements IDisposable {

	public View1(Composite parent, final IEclipseContext outputContext) {
		GridLayout gridLayout = new GridLayout(2, true);
		Label label = new Label(parent, SWT.NONE);
		label.setText("E4 is new");
		GridData gridData = new GridData(GridData.HORIZONTAL_ALIGN_FILL);
		gridData.horizontalIndent = 20;
		label.setLayoutData(gridData);
		Text text = new Text(parent, SWT.NONE);
		text.setText("and different");

		label = new Label(parent, SWT.NONE);
		label.setText("This is a button");
		new Button(parent, SWT.PUSH).setText("My button");

		GridLayoutFactory.createFrom(gridLayout).generateLayout(parent);
	}

	public void dispose() {

	}
}

Run your application and you get the following:

This is obvious an application which does not yet use css styleing.

Add now the folder css to your application and create the following file myfirststylesheet.css:

Label {
	font: Verdana 20px;
	color:rgb(178,34,34);
	background-color:rgb(255,255,255) rgb(0,0,0) 60%;
}

Button {
	font: Verdana 15px;
	background-color:rgb(255,255,255) rgb(0,0,0);
}

Text {
	font: Verdana 15px;
	background-color:radial rgb(255,255,255) rgb(0,0,0);
}

Add the property “applicationCSS” which points to the css file to your product:

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
   <extension
         point="org.eclipse.e4.workbench.parts">
          <part
            class="de.vogella.e4.first.views.View1"
            label="My first E4 View"
            parentId="org.eclipse.e4.ui.tags.navigation">
      </part>
   </extension>
   <extension
         id="product1"
         point="org.eclipse.core.runtime.products">
      <product
            application="org.eclipse.e4.ui.workbench.swt.application"
            name="vogella">
         <property
               name="appName"
               value="vogella">
         </property>
         <property
               name="applicationXMI"
               value="de.vogella.e4.css/Application.xmi">
         </property>
         <property
               name="applicationCSS"
               value="platform:/plugin/de.vogella.e4.css/css/myfirststylesheet.css">
         </property>
      </product>
   </extension>

</plugin>

Run your Eclipse e4 application and you should receive this amazing and beautiful UI .

Arguably the beauty lies in the eye of the beholder.

I hope this get you started in playing around with the css styling. Check the existing cvs examples (org.eclipse.e4.demo.contacts and org.eclipse.e4.ui.examples.css) to learn more about. You find these in the Eclipse cvs trunk under E4->org.eclipse.e4.ui. The usage of cvs is described Source Code Guide of Eclipse 3.5 (Galileo) – Using cvs

I’m sure you can conjure a nicer UI then I did in my example.

Good luck in your E4 journey!

Update This description has been updated in the following tutorial: Eclipse e4.

Eclipse released on the 29 July 2009 the tech preview version 0.9 of Eclipse e4, which can be downloaded here.

I wasn’t able to find a description how to create an new application based on E4. Starting from the CVS example is possible but I wanted to start from scratch. After several failed attempts to create an E4 application I believe I have found a way to create an E4 application. I assume others will have similar problems so I wanted to share my experience.

To follow this description you need to have knowledge how to develop Eclipse Plugins in Eclipse 3.5 or earlier. Check out this Eclipse Plugin Development Tutorial.

So lets get started with e4.

Download e4. Extract it and start it is similar to older Eclipse versions.

Currently there is no wizard which creates a working scaffold of an E4 application. We will therefore use the exsting plugin templates.

Create a new Plugin project “de.vogella.e4.first”. Do not select “Generate an activator”, nor “This plug-in will make contributions to the UI” nor “Would you like to create a rich client application”. Do not select a template. Press finish.

This will open the Plugin Perspective, switch here to the Package Explorer to see your new project.

Create the package “de.vogella.e4.first”. The result should look like the following.

Select your MANIFEST.MF and add the following dependencies to your plugin.

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: First
Bundle-SymbolicName: de.vogella.e4.first;singleton:=true
Bundle-Version: 1.0.0.qualifier
Bundle-RequiredExecutionEnvironment: JavaSE-1.6
Require-Bundle: org.eclipse.ui,
 org.eclipse.core.runtime,
 org.eclipse.e4.ui.workbench;bundle-version="0.9.0",
 org.eclipse.e4.ui.workbench.renderers.swt;bundle-version="0.9.0",
 org.eclipse.e4.ui.workbench.renderers.swt.contributions;bundle-version="0.9.0",
 org.eclipse.e4.ui.workbench.swt;bundle-version="0.9.0",
 org.eclipse.e4.ui.services;bundle-version="0.9.0",
 org.eclipse.e4.core.services;bundle-version="0.9.0"

You need (some of) these plugins for the usage of E4 features.

Add the following extension points. I noticed that for some of the features you have to modify the plugin.xml directly as the UI does not support them. But you have to create the plugin.xml via the MANIFEST.MF file; as I created it directly as a new file I received a strange system behavior.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
   <extension
         point="org.eclipse.e4.workbench.parts">
          <part
            class="de.vogella.e4.first.views.View1"
            label="My first E4 View"
            parentId="org.eclipse.e4.ui.tags.navigation">
      </part>
   </extension>
   <extension
         id="product"
         point="org.eclipse.core.runtime.products">
      <product
            application="org.eclipse.e4.ui.workbench.swt.application"
            name="vogella">
             <property
               name="appName"
               value="vogella">
         </property>
         <property
               name="applicationXMI"
               value="de.vogella.e4.first/Application.xmi">
         </property>
      </product>

   </extension>

</plugin>

“org.eclipse.e4.workbench.parts” is a new extension point by which you can define your view parts, formally known as views and editors.

The extension point “org.eclipse.core.runtime.products” has a new parameter “applicationXMI”. This is a parameter to the model of your UI. We came to this later. You also do not define your own application; we use “org.eclipse.e4.ui.workbench.swt.application”.

Create a product configuration called “vogella.product”. This is similar to Eclipse 3.5; see here for a description: Eclipse Product Configuration.

Make sure you select “org.eclipse.e4.ui.workbench.swt.application”.

Add as dependency to your product the plugin “org.eclipse.e4.ui.workbench”. Add also the plugin “de.vogella.e4.first”.
Press “add required plugins”.

Create the following two classes:

package de.vogella.e4.first.handlers;

import org.eclipse.e4.workbench.ui.IWorkbench;

public class ExitHandler {
	public void execute(IWorkbench workbench) {
		workbench.close();
	}
}

and

package de.vogella.e4.first.views;

import org.eclipse.e4.core.services.context.IEclipseContext;
import org.eclipse.jface.layout.GridLayoutFactory;
import org.eclipse.swt.SWT;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Label;
import org.eclipse.swt.widgets.Text;
import org.eclipse.ui.services.IDisposable;

public class View1 implements IDisposable {

	public View1(Composite parent, final IEclipseContext outputContext) {
		Label label = new Label(parent, SWT.NONE);
		label.setText("E4 is new");
		GridData gridData = new GridData(GridData.HORIZONTAL_ALIGN_FILL);
		gridData.horizontalIndent = 20;
		label.setLayoutData(gridData);
		Text text = new Text(parent, SWT.NONE);
		text.setText("and different");
		GridLayoutFactory.fillDefaults().generateLayout(parent);
	}

	public void dispose() {

	}
}

You need a model for your application. In the parameter “applicationXMI” we earlier defined that this model will be “de.vogella.e4.first/Application.xmi”. Create the file Application.xmi with the following content.

<?xml version="1.0" encoding="ASCII"?>
<application:MApplication xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:application="http://www.eclipse.org/ui/2008/Application">
  <windows name="Main" x="100" y="100" width="800" height="600">
    <menu>
      <items xsi:type="application:MMenuItem" name="File">
        <menu>
          <items xsi:type="application:MMenuItem" id="" name="Exit" command="//@command.0"/>
        </menu>
      </items>
    </menu>
    <children policy="VerticalComposite">
      <children xsi:type="application:MSashForm" policy="HorizontalSash">
        <children xsi:type="application:MStack">
          <children xsi:type="application:MContributedPart" iconURI="" name="My View" tooltip="My first View" URI="platform:/plugin/de.vogella.e4.first/de.vogella.e4.first.views.View1"/>
        </children>
        <weights>30</weights>
        <weights>70</weights>
      </children>
    </children>
    <handlers id="" URI="platform:/plugin/de.vogella.e4.first/de.vogella.e4.first.handlers.ExitHandler" persistedState="" command="//@command.0"/>
  </windows>
  <command id="application.exit" name="Exit"/>
</application:MApplication>

This is the EMF model which defines your UI. Eclipse should display this model in a EMF editor so that you can investigate it. In this model you find your view and command definition. The content can be viewed via the properities view.

Now start your application from your vogella.product. Starting it directly from the plugin.xml will not work (easily).

If you receive the error “org.eclipse.core.runtime.AssertionFailedException: null argument:-applicationXMI argument missing” check you plugin.xml. E4 created in several cases twice the products entry.

You should be rewarded with this user interface:

With this first application I hope you can started using the E4 advanced features, e.g. CSS styling, etc.

My final thoughts: Eclipse e4 has already amazing capabilities for a tech review release. The new modeled UI removes the need for a lot of boilerplate code.

Try it out!

Given the discussion about E4 and the evolution of Eclipse I’m wondering if it would make sense to flag certain Eclipse extension points as deprecated and add a warning to the PDE tooling if someone uses these extension points. This would help developes to do “the right thing”.

This question came to me while watching The Myth of the Genius Programmer. Björn quoted from this presentation in this post Criticism is not evil . In this video it was explained that tools matter in the sense that they guide new developer in a certain direction.

For example I believe that actions could be marked as deprecated. I see still a lot of questions which relates to actions in the newsgroup and I believe that commands are superior to actions. I know that the description indicates that “org.eclipse.ui.menus” can be used but perhaps more guidance would help?

Any opinions on this?

Update I submitted Bug 285034 for the enhancement in PDE / UI for the warning.