Tutorial

The Eclipse platform allows to style an Eclipse application via a Cascading Style Sheet (CSS) file. CSS files are used in the Internet to layout web pages.

With the support of declarative styling in Eclipse you can define the appearance of your Eclipse application in an external file.

In the CSS file you use identifiers, which relate to SWT widgets or predefined pseudo classes.

The following shows an example CSS file.

				
Label {
	font: Verdana 8px;
	color: black;
}

Composite Label {
	color: black;
}


Text {
	font: Verdana 8px;
}

Composite Text {
	background-color: white;
	color: black;
}

SashForm {
	background-color: #c1d5ef;
}


.MTrimBar {
	background-color: #e3efff #c1d5ef;
	color: white;
	font: Verdana 8px;
}

Shell {
    background-color: #e3efff #c1d5ef 60%;
}

			

To define which CSS file your application should use you have two options:

The first approach works fine if you have a fixed styling in your application. You define the property "applicationCSS" on the product in "plugin.xml" pointing to the file. This way your application will be styled at startup.

The second approach is more flexible. You define an extension for the org.eclipse.e4.ui.css.swt.theme extension point which basically defines an id and a pointer to the CSS file. You then define the property "cssTheme" as a property in your product. The theme manager allows to switch styles at runtime and allows to register new themes.

Colors of widgets can be defined in different ways, e.g. the color white can be described via #white, rgb(255,255,2555) or #ffffff.

Styling supports gradients for the background color of UI controls. Linear and radial gradients are supported. To define a gradient use:

				
// linear gradient
background-color: gradient linear color_1 [color_2]* [percentage]*

// For example
background-color: gradient linear white black 
background-color: gradient linear white black blue
background-color: gradient linear white black 50%
background-color: gradient linear white black 50% 20%

// radial gradient
background-color: gradient linear color_1 color_2 [percentage]

// For example
background-color: gradient radial white black
background-color: gradient radial white black 50%

			

If you use the optional percentage in the definition then the color change will be done after the defined percentage.

In your coding you can also specify tags on certain widgets and access them via these tags in your CSS file.

The following example shows how to set this tag for a specific Label.

				
Label label = new Label(parenet, SWT.NONE);
label.setData("org.eclipse.e4.ui.css.id","MyCSSTagForLabel");
			

This element can be addressed in the CSS via:

				
#MyCSSTagForLabel{
	color:#blue;
}
			

The Eclipse e4 tooling provides the CSS spy feature. Once installed, you can open the CSS spy via the SHFT+Alt+F4 shortcut.

Create the folder "css" in your application and create the following file "default.css".

				
Label {
	font: Verdana 8px;
	color: black;
}

Composite Label {
	color: black;
}


Text {
	font: Verdana 8px;
}

Composite Text {
	background-color: white;
	color: black;
}

SashForm {
	background-color: #c1d5ef;
}


.MTrimBar {
	background-color: #e3efff #c1d5ef;
	color: white;
	font: Verdana 8px;
}

Shell {
    background-color: #e3efff #c1d5ef 60%;
}

			

Open the plugin.xml file in your com.example.e4.rcp.todo plug-in. Select the extension tab and add the applicationCSS property to the org.eclipse.core.runtime.products extension point.

The value of this property should point to your CSS file via an URI. The URI follows the platform:/plugin/BundleSymbolicName/path/file convention. For example:

				
platform:/plugin/com.example.e4.rcp.todo/css/default.css
			

Run your application. You should see it styled.

You will now use the theme manager to introduce the possibility to switch the application styling at runtime.

Create the following file "css/red.css".

				
CTabItem, ToolBar, Button, CBanner, CoolBar {
	font-size: 9;
	background-color: red;
}

			

Remove the applicationCSS property and create two extensions for the org.eclipse.e4.ui.css.swt.theme extension point.

Add the "cssTheme" parameter to your product.

Create this handler which will switch the Style to red.

				
import javax.inject.Named;

import org.eclipse.e4.core.di.annotations.Execute;
import org.eclipse.e4.ui.css.swt.theme.IThemeEngine;
import org.eclipse.e4.ui.workbench.IWorkbench;


public class ThemeSwitchHandler {
	@Execute
	public void switchTheme(IThemeEngine engine) {
		engine.setTheme("de.vogella.e4.todo.redtheme", true);
	}
}

			

Add the menu entry to your application model which calls the predefined handler.

If you run the application, you should be able to select the "Themes" and switch your application to a red style similar to the following screenshot.

Source Code of Examples