Support free tutorials:











vogella training Training Books



Eclipse 4 CSS Styling- Tutorial

Based on Eclipse 4.2 and Eclipse 4.3

Lars Vogel

Version 6.2

10.07.2013

Revision History
Revision 0.1 14.02.2009 Lars
Vogel
created
Revision 0.2 - 6.2 16.02.2009 - 10.07.2013 Lars
Vogel
bug fixes and enhancements

Eclipse 4 and CSS Styling

This tutorial gives an introduction into the CSS styling capabilities of Eclipse 4.


Table of Contents

1. Eclipse and declarative styling
1.1. Styling Eclipse applications
1.2. Limitations
2. Fixed styling in Eclipse
3. Dynamic styling using themes
4. Styling Possibilities
4.1. CSS attributes and selectors
4.2. Styling based on identifiers and classes
4.3. Colors and gradients
4.4. CSS support for custom widgets
5. CSS Tools
5.1. CSS Spy
5.2. CSS Scratchpad
6. Exercise: Styling with CSS files
6.1. Target
6.2. Create CSS file
6.3. Define applicationCSS property
6.4. Validate
6.5. Adjust build.properties
7. Exercise: Dynamic style switching with themes
7.1. Target
7.2. Add dependencies
7.3. Create CSS file
7.4. Remove the applicationCSS property
7.5. Create theme extensions
7.6. Validate
7.7. Implement a new menu entry
7.8. Validate theme switching
7.9. Adjust build.properties
8. Learn more about Eclipse 4 RCP development
9. Support this website
9.1. Thank you
9.2. Questions and Discussion
10. Links and Literature
10.1. Source Code
10.2. CSS styling resources
10.3. vogella Resources

Get the book Eclipse RCP book

1. Eclipse and declarative styling

1.1. Styling Eclipse applications

The visual appearance of your Eclipse application can be styled via external files similar to the CSS 2.1 standard.

CSS selectors used in Eclipse are identifiers, which relate to widgets or other elements, for example predefined pseudo classes. Non-standard properties are prefixed with either swt- or eclipse-.

The following example shows a CSS file which defines a styling for an Eclipse application.

Label {
  font: Verdana 8px;
  color: black;
}
Composite Label {
  color: black;
}
Text {
  font: Verdana 8px;
}
/* Identifies only those SWT Text elements
appearing within a Composite */
Composite Text {
  background-color: white;
  color: black;
}
SashForm {
  background-color: #c1d5ef;
}
/* background uses a gradient */
.MTrimBar {
  background-color: #e3efff #c1d5ef;
  color: white;
  font: Verdana 8px;
}

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

The Eclipse platform support static as well as dynamic styling of an application. In the case of static styling the styling cannot be exchanged at runtime, while in the case of dynamic styling it is possible to switch the styling at runtime.

1.2. Limitations

SWT as the default user interface toolkit of Eclipse has certain limitations with regards of styling components, which are based on the limitations of the underlying operating system. For example it is not possible to style menus and table headers because this is not supported by the SWT implementation. Also some platforms do not allow the styling of certain widgets, e.g. the Button or the ScrollBar widget.

2. Fixed styling in Eclipse

You can specify a fixed styling of your application via a property in your extension for the org.eclipse.core.runtime.products extension point. Like all extensions this extension is contributed via the plugin.xml file.

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

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

The screenshot shows an example for the plugin.xml file which the applicationCSS property defined.

applicationCSS entered on the product extension

The corresponding file is shown below. It leaves out possible other properties you have set, e.g. for a life cycle handler.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>

 <extension
   id="product"
   point="org.eclipse.core.runtime.products">
  <product
     application="org.eclipse.e4.ui.workbench.swt.E4Application"
      name="to-do">
   <property
       name="appName"
       value="to-do">
   </property>
   <property
     name="applicationCSS"
     value="platform:/plugin/com.example.e4.rcp.todo/css/default.css">
   </property>
  </product>
 </extension>

</plugin> 

3. Dynamic styling using themes

You can define multiples themes via an extension in the plugin.xml file. The Eclipse platform provides the theme service with an instance of the IThemeEngine interface. Via this instance you can change the active theme at runtime.

To create new themes you define extensions for the org.eclipse.e4.ui.css.swt.theme extension point. Such a extension defines an ID for the style and a pointer to the CSS file.

You must also define the default theme via the cssTheme property in your org.eclipse.core.runtime.products extension. This can also be used to define a fixed styling.

Warning

If cssTheme is not set, the IThemeEngine service is not registered as service by the Eclipse platform.

The switching of themes is demonstrated in the following handler code.

package com.example.e4.rcp.todo.handlers;

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

public class ThemeSwitchHandler {
  private static final String DEFAULT_THEME = "com.example.e4.rcp.todo.default";
  private static final String RAINBOW_THEME = "com.example.e4.rcp.todo.rainbow";
  
  // Remember the state
  static boolean defaulttheme= true;
  @Execute
  public void switchTheme(IThemeEngine engine) {
    // second argument defines that change is 
    //persisted and restored on restart
    if (!engine.getActiveTheme().getId().equals(DEFAULT_THEME)){
      engine.setTheme(DEFAULT_THEME, true);
    } else {
      engine.setTheme(RAINBOW_THEME, true);
    }
  }
} 

4. Styling Possibilities

4.1. CSS attributes and selectors

The CSS attributes for SWT widgets which can be styled are listed under the following link:

http://wiki.eclipse.org/E4/CSS/SWT_Mapping 

Eclipse application model elements, e.g. MPartStack or MPart can also be styled. The CSS selectors are based on the Java classes for the model elements. Some examples are given in the following table.

Table 1. Model elements and CSS selectors

Model Element CSS Selector
MPart .MPart
MPartStack .MPartStack
MPartSashContainer .MPartSashContainer


For example you could hide the minimize and maximize button of a MPartStack via the following CSS rule.

.MPartStack {
  swt-maximize-visible: false;
  swt-minimize-visible: false;
} 

Eclipse supports also CSS pseudo classes. The following tables lists several of these pseudo classes.

Table 2. CSS pseudo classes in Eclipse

CSS pseudo classes Description
Button:checked Selects checked buttons
:active For example shell:active selects the active shell\
:selected Allows to style a selected element, e.g. a part in a PartStack.


4.2. Styling based on identifiers and classes

You can specify tags on widgets in your source code and use these tags for styling. You can specify an identifier or a class. A identifier is supposed to be unique while a class can be assigned to several elements.

The following example demonstrates how to set the identifier and the class on SWT widgets.

// IStylingEngine is injected
@Inject IStylingEngine engine;

// more code....

Label label = new Label(parent, SWT.NONE);
Text text = new Text(parent, SWT.BORDER);

// set the ID, must be unique in the same window
engine.setID(label, "MyCSSTagForLabel"); 

// set the class, can be used several times
engine.setClassname(text, "error"); 

These elements can be addressed in the CSS file via:

#MyCSSTagForLabel{
  color:#blue;
}

.error { 
  border: 1px red; 
} 

4.3. Colors and gradients

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

Styling supports gradients for the background color of user interface widgets. Linear and radial gradients are supported. The definition of gradients is demonstrated in the following listing.

// 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 radial 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. The following picture shows the result of different settings.

Different Gradient settings

Note

Please note that the current gradient specification is not compliant with the CSS specification and that it might change in the future.

4.4. CSS support for custom widgets

It is also possible to implement CSS support for custom widgets. See the following URL: Eclipse 4 CSS Wiki for more information.

5. CSS Tools

5.1. CSS Spy

The CSS spy tool helps to see the possible styling options for selected elements. CSS spy is part of the e4 tooling project and can be installed from its update site. See the Eclipse 4 installation description for details.

You can open the CSS spy via the Shift+Alt+F5 shortcut.

CSS spy allows you to see the available properties and the current style settings.

The CSS Spy in action

5.2. CSS Scratchpad

The CSS Scratchpad allows to change CSS rules interactively. is also part of the e4 tooling project.

You open it via the Ctrl+Shift+Alt+F6 shortcut.

If you click the Apply button, the entered CSS is applied at runtime to your application.

6. Exercise: Styling with CSS files

6.1. Target

In this exercise you style your application with a CSS file.

6.2. Create CSS file

Create a folder called css in your com.example.e4.rcp.todo plug-in and create the following default.css file.

Label {
  font: Verdana 8px;
  color: black;
}
Composite Label {
  color: black;
}
Text {
  font: Verdana 8px;
}
/* Identifies only those SWT Text elements
appearing within a Composite */
Composite Text {
  background-color: white;
  color: black;
}
SashForm {
  background-color: #c1d5ef;
}
/* background uses a gradient */
.MTrimBar {
  background-color: #e3efff #c1d5ef;
  color: white;
  font: Verdana 8px;
}

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

6.3. Define applicationCSS property

Open the plugin.xml file in your com.example.e4.rcp.todo plug-in. Select the Extensions tab.

Selecting the extension

Right-click on your product entry and select Newproperty.

Adding a property

Use applicationCSS as name for the property. The value of this property should use the following identifier.

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

Setting the CSS property

6.4. Validate

Start your application. The application should be styled according to your CSS file.

Change the CSS style sheet and restart your application to see the effect.

6.5. Adjust build.properties

Add the created CSS file to your build.properties file in the com.example.e4.rcp.todo plug-in to make it available in an exported application.

7. Exercise: Dynamic style switching with themes

7.1. Target

The following exercises assumes that you already implemented CSS support for your application based on the last exercise. In this exercise you use the IThemeEngine to introduce the ability to switch the application styling at runtime.

7.2. Add dependencies

Add the org.eclipse.e4.ui.css.swt.theme plug-in as dependency to your application plug-in.

7.3. Create CSS file

Create the following css/rainbow.css file.

Shell {
  background-color: red orange yellow green orange 30% 60% 75% 95%
}

.MPartStack {
  font-size: 22px;
  color:orange;
}  

.MPart:selected {
   visible:gone;
   background-color:black;
}

.MPartStack {
border-visible:false;
} 

7.4. Remove the applicationCSS property

Remove the applicationCSS property from your product extension. For this select the property and press the Remove button as depicted in the following screenshot.

Remove applicationCSS

7.5. Create theme extensions

Select the Extensions tab in the editor for the plugin.xml file and create two extensions for the org.eclipse.e4.ui.css.swt.theme extension point.

You create an extension in the Extensions tab by pressing the Add... button.

Add button in extension points

Select the org.eclipse.e4.ui.css.swt.theme extension point and press the Finish button.

Selecting

Right-click on the org.eclipse.e4.ui.css.swt.theme extension to create a new theme. The following screenshots show the extensions which you should create.

The relevant part in the plugin.xml file should look like the following.

<extension
         point="org.eclipse.e4.ui.css.swt.theme">
      <theme
            basestylesheeturi="css/default.css"
            id="com.example.e4.rcp.todo.default"
            label="Default Theme">
      </theme>
      <theme
            basestylesheeturi="css/rainbow.css"
            id="com.example.e4.rcp.todo.rainbow"
            label="Rainbow">
      </theme>
</extension> 

Add the cssTheme property to your product. It should point to the com.example.e4.rcp.todo.default theme you created.

Warning

Ensure that the cssTheme property is correctly set. Without this initial setting the IThemeEngine does not work.

7.6. Validate

Start your application and ensure that the application is styled according to the cssTheme property setting.

7.7. Implement a new menu entry

Create a new Java class, which allows you to switch between the themes.

package com.example.e4.rcp.todo.handlers;

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

public class ThemeSwitchHandler {
  private static final String DEFAULT_THEME = "com.example.e4.rcp.todo.default";
  private static final String RAINBOW_THEME = "com.example.e4.rcp.todo.rainbow";
  
  // Remember the state
  static boolean defaulttheme= true;
  @Execute
  public void switchTheme(IThemeEngine engine) {
    // second argument defines that change is 
    //persisted and restored on restart
    if (!engine.getActiveTheme().getId().equals(DEFAULT_THEME)){
      engine.setTheme(DEFAULT_THEME, true);
    } else {
      engine.setTheme(RAINBOW_THEME, true);
    }
  }
} 

Define a new command and a handler in your application model for switching the style. Assign the above class to the handler.

Add a menu entry to your application model which uses your handler for switching the style.

7.8. Validate theme switching

Start the application and select your new menu entry. Afterwards the styling of your application should use the rainbow theme.

Note

Changes in styling may require a restart of your application if your new style does not override all properties of the old style.

7.9. Adjust build.properties

Ensure that all CSS files are selected in your build.properties file in the com.example.e4.rcp.todo plug-in to make them available in an exported application.

8. Learn more about Eclipse 4 RCP development

I hope you enjoyed this tutorial. You find this tutorial and much more information also in the Eclipse 4 RCP book from this author.

9. Support this website

This tutorial is Open Content under the CC BY-NC-SA 3.0 DE license. Source code in this tutorial is distributed under the Eclipse Public License. See the vogella License page for details on the terms of reuse.

Writing and updating these tutorials is a lot of work. If this free community service was helpful, you can support the cause by giving a tip as well as reporting typos and factual errors.

9.1. Thank you

Please consider a contribution if this article helped you.

Flattr this

9.2. Questions and Discussion

If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.

10. Links and Literature

10.1. Source Code

Source Code of Examples

10.2. CSS styling resources

Eclipse Wiki for CSS attributes

10.3. vogella Resources

vogella Training Android and Eclipse Training from the vogella team

Android Tutorial Introduction to Android Programming

GWT Tutorial Program in Java, compile to JavaScript and HTML

Eclipse RCP Tutorial Create native applications in Java

JUnit Tutorial Test your application

Git Tutorial Put all your files in a distributed version control system