RWT Theming

This article describes the theming functionality of RWT, the RAP Widget Toolkit. This theming defines the default look and feel of the basic RWT controls like Shell, Button, Text etc. It must not be mixed up with the theming of the Eclipse workbench. Instead, it can be compared to the theming functionality of a desktop system that allows the user to set custom colors for title bars, text background and the like.

Introduction

Capabilities of the RWT Theming

In general, the RWT theming allows to define

• custom colors,
• custom fonts,
• custom borders,
• custom dimensions and box dimensions (paddings etc.),
• custom images and icons

A theme setting always affects all instances of a control equally. It is not possible to define different presentation schemes for the same widget, such as blue buttons, large buttons and oval buttons. If this is what you need, you probably need a custom widget.

As an example, the difference between the default look and feel and a custom theme could look like this:

How to Define a Custom RWT Theme

Create a Custom Theme File

RWT theme files are simple Java Property files. A template named theme-template.properties can be found in the src/ directory of the RWT plug-in (org.eclipse.rap.rwt). You only have to specify those properties that are relevant for your customization, undefined properties stay at their default value. See below for the syntax of the property values.

The following is an example for a simple theme file:

# My Aquablue Theme
#

# Frame border for group boxes
# default: 1 solid #aca899
group.frame.border: 2 dotted #56a0ea

# Font for title bar of Shells
# default: bold 11 "Segoe UI", Corbel, Calibri, Tahoma, "Lucida Sans Unicode", sans-serif
shell.title.font: bold 15 "Trebuchet MS", Arial, Helvetica, sans-serif

# Height of the title bar of Shells
# default: 18
shell.title.height: 25

...
  

Register the New Theme

In order to make your theme available, you have to register it with the extension point org.eclipse.rap.swt.themes. In the plugin.xml of your application project, add an extension like this:

   <extension
         point="org.eclipse.rap.swt.themes">
      <theme
            id="my.application.aquablue"
            name="Aqua Blue Test Theme"
            file="aqua-blue.properties" />
   </extension>
  

Activate the Theme

To make your application use the custom theme you have to register a branding as shown in the example below. For details, refer to the article on RAP branding).

   <extension
         point="org.eclipse.rap.ui.branding">
      <branding
            id="my.application.aquabranding"
            servletName="aqua"
            defaultEntrypointId="my.application.entrypoint1"
            themeId="my.application.aquablue">
      </branding>
   </extension>
  

For testing purposes, a custom theme can also be activated by passing the theme id in the URL parameter theme (e.g. http://localhost:9090/rap?startup=controls&theme=my.application.aquablue). There is no support for programmatic activation of custom themes yet.

Syntax for Property Values

Property values specified in a theme file must conform to the following syntactical rules:

Colors

Colors can be specified in one of these ways:

• A color keyword. Only the 16 basic [http://www.w3.org/TR/REC-html40/types.html#h-6.5 HTML 4.0 colors] (aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, and yellow) are supported. The keywords are case-insensitive.
• A comma separated list of three decimal integer numbers in the range 0 .. 255 that denote the red, green, and blue portion of the color, respectively.
• A hexadecimal color notation in the format #rgb or #rrggbb, that is commonly used for HTML pages.

Examples for valid color definitions:

• white
• 0, 128, 128
• #fffaf0