Chapter 9. Styling Eclipse 4 Applications

One of the biggest changes with the Eclipse 4 model is the separation of content from presentation. This allows the style of an Eclipse application to be configured separately from how the user interface is built and designed. This chapter shows how to style an Eclipse 4 application using styles and themes, similar to the way CSS is used to style HTML.

In this chapter, we shall:

• Style the UI with CSS

• Use the CSS Spy to debug stylesheet rules

• Create custom CSS styles and use them in code

• Use the dark style in a standalone application

• Create multiple themes and switch between them

Styling Eclipse with CSS

Eclipse 4 provides a model of the user interface (represented by classes such as MApplication, MPart, and MWindow) and allows a separate renderer to be able to display the content. This allows for different rendering engines to present the user interface, such as HTML (with RAP) or JavaFX (with e(fx)clipse). To separate content from presentation, the style can be applied in an external stylesheet, based on CSS.

Time for action – styling the UI with CSS

Eclipse 4 user interfaces are styled with CSS. Although this is loosely based on the CSS syntax used by browsers, the stylesheet is interpreted by the Eclipse 4 runtime. CSS stylesheets are composed of selectors and style rules: a selector can be one of a widget name (for example, Button), a model class name (for example, .MPartStack), or an identifier (for example, #PerspectiveSwitcher).

1. The default Eclipse 4 application with sample content (generated by the wizard in Chapter 7, Creating an E4 Application, will have an empty CSS file called css/default.css. Open this file, and add the following rule:

   Shell {
     background-color: blue;
   }

   Tip

   The File | New | Plug-in Project menu can be used to create a new plug-in project, and the Would you like to create a rich client application? combined with the This plug-in will make contributions to the UI will allow the creation of an Eclipse 4 application for testing purposes if required. If this is chosen, ensure...

Time for action – using custom CSS classes

Very often when building a user interface, there will be a need to repeat styles across different components in the application. Instead of using the generic class type, or having to encode multiple styles on a part-by-part basis, CSS classes can be used to define a standard style and applied to individual widgets.

A label will be added to the sample part and associated with a CSS style, and that will be stored in the default CSS file.

1. Open the Hello class and go to the create method that creates the part's UI.

2. At the end of the method, add a new Label, which will be used to demonstrate the styling:

   Label label = new Label(parent, SWT.NONE);
   label.setText("Danger Will Robinson!");

3. Associate the label with a custom CSS class using the setData method on the SWT widget along with the org.eclipse.e4.ui.css.id key and the name of the CSS class:

   label.setData("org.eclipse.e4.ui.css.id", "DireWarningMessage");

4. Finally add the class to the default.css file so...

Using the Eclipse spies

Eclipse has several spies, which can be used to introspect the state of the running workbench. Some are available by default, such as the Plug-in Spy and the Menu Spy, but the ones relating to styling have to be separately installed from a snapshot build site at http://download.eclipse.org/e4/snapshots/org.eclipse.e4.tools/latest/

Time for action – using the CSS Spy

To provide interactive debugging, Eclipse 4 has the CSS Spy, a dialog that can provide information about the user interface widget under the mouse. This can be invoked from the Quick Access search box, by typing css spy, or by pressing the Shift + Alt + F5 keys.

1. Move the cursor to the Quick Access search box by pressing Cmd + 3 (on macOS) or Ctrl + 3 (on other platforms), or by clicking in the search box with the mouse.

2. Enter spy in the quick access bar, and a list of Eclipse 4 spies will be shown, including the CSS Spy:

   

3. Select the CSS Spy from the list, and the spy view will be shown. The user interface is represented as a tree structure, and by selecting individual elements of the user interface, a red highlight box will show where the selected element is located on screen:

   

4. It is also possible to open the spy in its own window by pressing the Alt + Shift + F5 keys:

   

   Tip

   If the CSS spy is not shown in a floating window, reset the perspective with Window | Perspective...

Time for action – integrating the spy into a product

Sometimes it is useful or necessary to be able to debug what an application looks like from the inside. Although the CSS Spy works in the Eclipse instance, it doesn't have any effect on the launched Eclipse 4 application. In order to use the spy in a runtime application, a number of bundles need to be added.

1. Open the .product file and switch to the Contents tab, which lists the plug-ins required by the product.

2. Click on Add... and select both the org.eclipse.e4.tools.css.spy plug-in to the product.

3. Click on the run button at the top of the product to launch with the new bundles.

   Tip

   If the product doesn't launch successfully, manually add the required plug-ins to the launch configuration, or delete the launch configuration and then re-launch the product so that the correct plug-ins are installed.

4. Press Alt + Shift + F5 to open the CSS Spy, and select the danger label in the application:

   

5. The bottom of the CSS Spy shows the current CSS properties...

Styling a custom widget

Widgets that have been created by the user can be styled using CSS with property handlers. As an example, the ClockWidget (created in Chapter 2, Creating Views with SWT) will be added to the E4 application and then upgraded to support custom styling.

Time for action – adding the clock

To add the clock to the Eclipse 4 application, a new part will be added which has a ClockWidget as its only content.

1. To use the ClockWidget in a different plug-in, the package needs to be exported. Open the MANIFEST.MF from the com.packtpub.e4.clock.ui project, and on the Runtime tab, click on Add to add the com.packtpub.e4.clock.ui package to the list of Exported Packages.

2. Create a new class called ClockPart in the com.packtpub.e4.application.parts package.

3. Add a create method with a @PostConstruct annotation that takes a Composite parent argument.

4. In the body of the create method, instantiate a new ClockWidget instance with arguments parent, SWT.NONE, and new RGB(255,0,0). This will require that the com.packtpub.e4.clock.ui package is imported into the com.packtpub.e4.application plug-in. A quick-fix should offer this automatically, but it can be added by opening the MANIFEST.MF, going to the Dependencies tab, and adding the com.packtpub.e4.clock.ui package...

Time for action – using a CSS property

At present the color of the hand is set in the constructor of the ClockWidget, and cannot be changed after creation. It would be better if the style of the widget could be controlled externally using the CSS that is used to style the application. This is handled with an ICSSPropertyHandler subclass from the org.eclipse.e4.ui.css.swt plug-in.

1. Open the plugin.xml file from the com.packtpub.e4.clock.ui plug-in and switch to the Dependencies tab. Add the org.eclipse.e4.ui.css.swt and org.eclipse.e4.ui.css.core plug-ins to the list. To ensure that the bundle will work if these are missing, mark them both as Optional dependencies.

2. Create a new package com.packtpub.e4.ui.internal.css to store the classes necessary for CSS cooperation.

3. Create a new class CSSPropertyClockHandler, which extends AsbtractCSSPropertySWTHandler. The IDE will offer to auto-create the missing methods applyCSSProperty and retrieveCSSProperty, so create these as they will be used next.

4. In...

Time for action – going to the dark side

Eclipse 4 added several new themes for Eclipse, one of which was an updated dark theme. This can be added to an Eclipse 4 application through the use of the org.eclipse.ui.themes plug-in.

1. Edit the .product file and ensure that the org.eclipse.ui.themes is added as a required bundle of the product on the Contents tab. This will ensure that if the product is exported then it contains the required plug-in.

2. Update the launch configuration, by going to the Run | Run... menu and selecting the Eclipse 4 application. On the plug-ins tab, type org.eclipse.ui.themes into the search box, where type filter text is shown. Ensure that the checkbox next to the plug-in is checked.

3. Edit the css/default.css file and add the following to the top:

   @import url("platform:/plugin/org.eclipse.ui.themes/css/e4-dark.css");

4. Run the Eclipse 4 application and the application should be shown in the dark theme:

   

What just happened?

The standard Eclipse themes are delivered inside the...

Time for action – adding themes

Eclipse 4 ships with a theme manager which can be used to swap between themes (in essence, separate CSS files). The theme manager is available for inclusion in Eclipse 4-based applications by adding the org.eclipse.e4.ui.css.swt plug-in as a dependency to the application, and by adding one or more org.eclipse.e4.ui.css.swt.theme extension points.

1. Add the org.eclipse.e4.ui.css.swt.theme plug-in to the Dependencies tab of the plugin.xml file of the com.packtpub.e4.application project.

2. Go to the plugin.xml tab of the plugin.xml file (or edit the file as text) and add the following content to add blue and green themes:

   <extension point="org.eclipse.e4.ui.css.swt.theme">
     <theme label="Blue Theme"
       id="com.packtpub.e4.ui.css.theme.blue"
       basestylesheeturi="css/blue.css"/>
     <theme label="Green Theme"
       id="com.packtpub.e4.ui.css.theme.green"
       basestylesheeturi="css/green.css"/>
   </extension>

3. Create a text file with the name blue.css...

Time for action – switching between themes

The themes can be switched at runtime by interacting with the IThemeEngine, which can be acquired from the Eclipse 4 runtime service through injection. This provides a list of all installed themes, which can be used to populate the list viewer, and to allow the style to be changed.

1. Create a class called ThemePart in the com.packtpub.e4.application.parts package. Add an injected field IThemeEngine, and a create method annotated with @PostConstruct that takes a Composite parameter:

   public class ThemePart {
     @Inject
     private IThemeEngine themeEngine;
     @PostConstruct
     public void create(Composite parent) {
     }
    }

2. In the create method, add a ListViewer that is associated with an ArrayContentProvider:

   ListViewer lv = new ListViewer(parent, SWT.NONE);
   lv.setContentProvider(new ArrayContentProvider());

3. Add a selection listener to the list viewer so that when an item is selected, the element is compared with the list of themes; if one is found, set it through...

Summary

Eclipse 4 can be styled by using a style language very similar to CSS, and the style can be created separately from the underlying UI content. These styles can be integrated into themes and allow the user to dynamically switch between them.

In the next chapter, we'll look at how to create features and update sites, which allows the plug-ins written so far to be served and installed into other Eclipse applications.