E4/DeclarativeUI/RAPThemingCSS

Name of Technology: RAP (RWT) Theming

Purpose: CSS flavor used for theming RWT widgets in RAP (Rich Ajax Platform)

Contact: Ralf Sternberg, Innoopract GmbH

Committers: RAP Committers

Current License: EPL

RAP Overview

RAP is a platform that lets you run RCP applications on a web server and access them with a browser. RAP uses an implementation of a (growing) subset of SWT for the web environment, called RWT, that renders widgets in a browser.

The RWT theming allows to define the default look of these widgets (comparable to the theming capabilities of a desktop environment).

A few month ago we decided to switch from theme definitions in simple property files to the more flexible and popular CSS format.

We would love to see a convergence between the RWT theming and the CSS support in e4.

CSS Flavor

Element Names

Element names are plain widget names without any namespace prefixes for the sake of readability. There are no name collisions in SWT, custom RWT widgets can declare a different name/prefix (every themeable widget provides an xml file that declares its widget name and its themeable properties). Example:

List, Table {
  background-color: white:
}

Style Flags

We represent every style flag as a single attribute:

Label[BORDER], CLabel[BORDER] {
  border: 1px solid #ff0000;
}

An alternative had been to have a list of style flags in a single "style" attribute, but this would result in more complicated CSS declarations such as:

Label[style~="BORDER"], CLabel[style~="BORDER"] {
  ...
}

Some style flags are used to select a certain widget subtype (e.g. SEPARATOR, RADIO). We decided to use attributes for all style flags for consistency instead of inventing new names like PushButton or Separator. CSS attributes can also be combined like this:

Button[PUSH][BORDER] {
  ...
}

Dynamic Widget States

We use pseudo-classes for dynamic states like hover, selected, focused, etc.

Button[PUSH]:hover {
  background-color: white
}

CSS Class Syntax

CSS class syntax for "widget variants". This is a way to style certain widget instances separately, comparable to classes in HTML. Example:

Button.shopping-cart {
  padding: 10 px;
  background-image: url( "images/shopping-cart-bg.png" );
}

button.setData( WidgetUtil.CUSTOM_VARIANT, "shopping-cart" );

We think that the .class notation is a natural fit even though the spec reserves this construct for HTML.

IDs

In addition, we could also support widget ids, but this would restrict the style definition to one single widget instance. We didn't see any advantage in this so far, but we don't see any problems either.

Button#mybutton {
  ...
}

Properties

Reuse existing CSS property names wherever possible (such as font, border, color, background-color, background-image, etc.) We only invented a few new properties where no suitable CSS property existed, for example "background-gradient-color".

Differences between RWT theming to e4 CSS

Although both e4 CSS and RWT theme file CSS define styles for SWT widgets, there are some differences:

• RWT theming defines the *default* look of widgets, i.e. the styles that apply when no custom color, font, etc. has been set. These values are also restored when calling setColor( null ), setFont( null ) etc. In SWT, the default style is defined by the windowing system. As an effect, setColor( null ) would always re-install the system default no matter what is defined in the CSS, right?

• RAP can potentially provide more flexible styling than a widget toolkit on the desktop as it is not bound to the operating system's restrictions. For example, developers will be able to define hover colors, radius of rounded corners, or register their own images for check boxes.

• RWT theming is limited to widgets, it cannot (yet) be used to style workbench parts.

Links

• RAP Project: http://www.eclipse.org/rap
• RAP help on theming: http://help.eclipse.org/ganymede/index.jsp?topic=/org.eclipse.rap.help/help/html/advanced/theming.html