Jump to: navigation, search

Difference between revisions of "RAP Theming"

m (RAP Themeing moved to RAP Theming: Theming seems to be the more correct spelling)
Line 1: Line 1:
This article describes the themeing functionality of RWT, the RAP Widget Toolkit.
+
This article describes the theming functionality of RWT, the RAP Widget Toolkit.
This themeing defines the default look and feel of the basic RWT controls like Shell, Button, Text etc.
+
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 themeing of the Eclipse workbench. Instead, it can be compared to the themeing functionality of a desktop system that allows the user to set custom colors for title bars, text background and the like.
+
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.
  
 
== State of Development ==
 
== State of Development ==
  
The RWT themeing mechanism, as introduced with the M4 milestone, is still in an early state of development.
+
The RWT theming mechanism has been introduced with the M4 milestone and extended in M5.
Some details are still likely to change, as our experience with this approach grows.
+
Currently, the RWT theming allows to define custom colors, fonts, borders, dimensions, box dimensions (paddings etc.), and icons.
Your comments and suggestions are welcome.
+
  
Currently, the RWT themeing only allows to define colors.
+
However, is still not much field-tested and some details are still likely to change, as our experience with this approach grows.
Themeing of icons, fonts, borders, margins etc. will follow shortly.
+
Your comments and suggestions are welcome.
  
 
== How to define a custom RWT Theme ==
 
== How to define a custom RWT Theme ==
Line 17: Line 16:
  
 
RWT theme files are simple Java Property files.
 
RWT theme files are simple Java Property files.
A template named <code>theme-template.properties</code> can be found in the <code>src/</code> directory of the RWT plugin (<code>org.eclipse.rap.rwt</code>).
+
A template named <code>theme-template.properties</code> can be found in the <code>src/</code> directory of the RWT plug-in (<code>org.eclipse.rap.rwt</code>).
 
You only have to specify those properties that are relevant for your customization, as undefined properties will stay at their default value.
 
You only have to specify those properties that are relevant for your customization, as undefined properties will stay at their default value.
 
Note that some property names are likely to be changed in the future, other properties will emerge and a few properties will even be dropped.
 
Note that some property names are likely to be changed in the future, other properties will emerge and a few properties will even be dropped.
Line 41: Line 40:
 
=== Activate the theme ===
 
=== Activate the theme ===
  
The extension parameter <code>default</code> specifies whether the theme should be active by default.
+
The extension parameter <code>default</code> (see above) specifies whether the theme should be active by default.
Currently, this is the only way to activate a custom theme.
+
For testing purposes, a custom theme can also be activated by passing the theme id in the URL parameter <code>theme</code> (e.g. <code>http://localhost:8080/rap?w4t_startup=controls&theme=org.eclipse.rap.demo.alttheme</code>).
 
Support for programmatic activation of custom themes is planned for future versions.
 
Support for programmatic activation of custom themes is planned for future versions.
  
Line 61: Line 60:
 
* A hexadecimal color notation in the format <code>#rgb</code> or <code>#rrggbb</code>, that is commonly used for HTML pages.
 
* A hexadecimal color notation in the format <code>#rgb</code> or <code>#rrggbb</code>, that is commonly used for HTML pages.
  
=== Images ===
+
=== Dimensions ===
  
Custom images must be referred to using a '<tt>/</tt>'-separated path name that identifies the location of an image resource within the bundle.
+
Dimensions are given as integer numbers.
 +
As all size calculations in SWT are pixel-based, all numbers represent pixel values.
 +
In contrast to CSS, the unit "px" must not be specified.
  
=== Fonts ===
+
=== Box Dimensions ===
 +
 
 +
Box dimensions like margins and paddings can be provided in the shorthand syntax known from CSS2.
 +
One, two, three, or four integer numbers may be specified, separated by spaces.
 +
If four numbers are given, they stand for the values in clock-wise order: top, right, bottom, left.
 +
Three numbers stand for: top, right and left, bottom.
 +
Two numbers stand for: top and bottom, right and left.
 +
One number stands for: all four values.
 +
 
 +
Examples for valid box dimension definitions are:
 +
*  <code>5</code> means: 5px for top, right, bottom, and left edge.
 +
*  <code>3 5</code> means: 3px for top and bottom edge, 5px for left and right.
 +
*  <code>2 4 0</code> means: 2px for the top edge, 4px for left and right, and 0px for the bottom.
 +
*  <code>2 4 0 2</code> means: 2px top, 4px left, 0px bottom, 2px left.
  
The syntax for font definitions is very similar to the CSS shorthand property ''font''.
 
A font definition contains the font size in pixels, a comma-separated list of font-family names, and the optional keywords <code>bold</code> and <code>italic</code>. The order of the parts does not matter. Examples of valid font definitions are:
 
* <code>Helvetica 10</code>
 
* <code>Helvetica 10 bold</code>
 
* <code>10 Helvetica bold italic</code>
 
* <code>12 Tahoma, "Lucida Sans Unicode", sans-serif italic</code>
 
  
 
=== Borders ===
 
=== Borders ===
Line 88: Line 96:
 
<code>none</code>.
 
<code>none</code>.
  
If one of the complex styles <code>inset</code>, <code>outset</code>, <code>groove</code>, or <code>ridge</code> is given without a color definition, the default system shadow colors (<code>widget.shadow</code>, <code>widget.highlight</code>, etc.) are used to paint the border.
+
If one of the complex styles <code>inset</code>, <code>outset</code>, <code>groove</code>, or <code>ridge</code> is used without a color definition, the default system shadow colors (<code>SWT.COLOR_WIDGET_NORMAL_SHADOW</code>, <code>SWT.COLOR_WIDGET_HIGHLIGHT_SHADOW</code>, etc., see below) are used to paint the border.
  
 
Examples for valid border definitions are:
 
Examples for valid border definitions are:
Line 96: Line 104:
 
*  <code>1 solid black</code>
 
*  <code>1 solid black</code>
 
*  <code>2 solid #fffa00</code>
 
*  <code>2 solid #fffa00</code>
 +
 +
=== Fonts ===
 +
 +
The syntax for font definitions is very similar to the CSS shorthand property ''font''.
 +
A font definition contains the font size in pixels, a comma-separated list of font-family names, and the optional keywords <code>bold</code> and <code>italic</code>. The order of the parts does not matter.
 +
 +
Examples of valid font definitions are:
 +
* <code>Helvetica 10</code>
 +
* <code>Helvetica 10 bold</code>
 +
* <code>10 Helvetica bold italic</code>
 +
* <code>12 Tahoma, "Lucida Sans Unicode", sans-serif italic</code>
 +
 +
=== Images ===
 +
 +
Custom images must be referred to using a '<tt>/</tt>'-separated path name that identifies the location of an image resource within the bundle.
  
 
== SWT System Colors ==
 
== SWT System Colors ==

Revision as of 03:55, 13 July 2007

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.

State of Development

The RWT theming mechanism has been introduced with the M4 milestone and extended in M5. Currently, the RWT theming allows to define custom colors, fonts, borders, dimensions, box dimensions (paddings etc.), and icons.

However, is still not much field-tested and some details are still likely to change, as our experience with this approach grows. Your comments and suggestions are welcome.

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, as undefined properties will stay at their default value. Note that some property names are likely to be changed in the future, other properties will emerge and a few properties will even be dropped. Please refer to the template file shipped with your current version. See below for the syntax of the property values.

Register the new theme with the extension point org.eclipse.rap.swt.themes

In the plugin.xml of your application project, add an extension like this:

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

Activate the theme

The extension parameter default (see above) specifies whether the theme should be active by default. For testing purposes, a custom theme can also be activated by passing the theme id in the URL parameter theme (e.g. http://localhost:8080/rap?w4t_startup=controls&theme=org.eclipse.rap.demo.alttheme). Support for programmatic activation of custom themes is planned for future versions.

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 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.

Dimensions

Dimensions are given as integer numbers. As all size calculations in SWT are pixel-based, all numbers represent pixel values. In contrast to CSS, the unit "px" must not be specified.

Box Dimensions

Box dimensions like margins and paddings can be provided in the shorthand syntax known from CSS2. One, two, three, or four integer numbers may be specified, separated by spaces. If four numbers are given, they stand for the values in clock-wise order: top, right, bottom, left. Three numbers stand for: top, right and left, bottom. Two numbers stand for: top and bottom, right and left. One number stands for: all four values.

Examples for valid box dimension definitions are:

  • 5 means: 5px for top, right, bottom, and left edge.
  • 3 5 means: 3px for top and bottom edge, 5px for left and right.
  • 2 4 0 means: 2px for the top edge, 4px for left and right, and 0px for the bottom.
  • 2 4 0 2 means: 2px top, 4px left, 0px bottom, 2px left.


Borders

A border definition may contain a size in pixels, a style keyword, and a color. All parameters are optional. The valid style keywords are solid, dotted, dashed, double, inset, outset, groove, ridge, and none.

If one of the complex styles inset, outset, groove, or ridge is used without a color definition, the default system shadow colors (SWT.COLOR_WIDGET_NORMAL_SHADOW, SWT.COLOR_WIDGET_HIGHLIGHT_SHADOW, etc., see below) are used to paint the border.

Examples for valid border definitions are:

  • none
  • 1 inset
  • 2 groove
  • 1 solid black
  • 2 solid #fffa00

Fonts

The syntax for font definitions is very similar to the CSS shorthand property font. A font definition contains the font size in pixels, a comma-separated list of font-family names, and the optional keywords bold and italic. The order of the parts does not matter.

Examples of valid font definitions are:

  • Helvetica 10
  • Helvetica 10 bold
  • 10 Helvetica bold italic
  • 12 Tahoma, "Lucida Sans Unicode", sans-serif italic

Images

Custom images must be referred to using a '/'-separated path name that identifies the location of an image resource within the bundle.

SWT System Colors

The SWT system colors, as returned by Display#getSystemColor(), are also themeable. The following list indicates which theme parameters manipulate these colors:

 SWT.COLOR_WIDGET_DARK_SHADOW:  widget.darkshadow
 SWT.COLOR_WIDGET_NORMAL_SHADOW:  widget.shadow
 SWT.COLOR_WIDGET_LIGHT_SHADOW:  widget.lightshadow
 SWT.COLOR_WIDGET_HIGHLIGHT_SHADOW:  widget.highlight
 SWT.COLOR_WIDGET_BACKGROUND:  widget.background
 SWT.COLOR_WIDGET_BORDER:  widget.thinborder
 SWT.COLOR_WIDGET_FOREGROUND:  widget.foreground
 SWT.COLOR_LIST_FOREGROUND:  list.foreground
 SWT.COLOR_LIST_BACKGROUND:  list.background
 SWT.COLOR_LIST_SELECTION:  list.selection.background
 SWT.COLOR_LIST_SELECTION_TEXT:  list.selection.foreground
 SWT.COLOR_INFO_FOREGROUND:  widget.info.foreground
 SWT.COLOR_INFO_BACKGROUND:  widget.info.background
 SWT.COLOR_TITLE_FOREGROUND:  shell.title.foreground
 SWT.COLOR_TITLE_BACKGROUND:  shell.title.background
 SWT.COLOR_TITLE_BACKGROUND_GRADIENT:  shell.title.background.gradient
 SWT.COLOR_TITLE_INACTIVE_FOREGROUND:  shell.title.inactive.foreground
 SWT.COLOR_TITLE_INACTIVE_BACKGROUND:  shell.title.inactive.background
 SWT.COLOR_TITLE_INACTIVE_BACKGROUND_GRADIENT:  shell.title.inactive.background.gradient