Difference between revisions of "RAP Theming"

From Eclipsepedia

Jump to: navigation, search
(State of Development)
Line 9: Line 9:
 
Your comments and suggestions are welcome.
 
Your comments and suggestions are welcome.
  
Currently, the RWT themeing only allows to define colors and icons.
+
Currently, the RWT themeing only allows to define colors.
Themeing of fonts, borders, margins etc. will follow shortly.
+
Themeing of icons, fonts, borders, margins etc. will follow shortly.
  
 
== How to define a custom RWT Theme ==
 
== How to define a custom RWT Theme ==
Line 42: Line 42:
  
 
The extension parameter <code>default</code> specifies whether the theme should be active by default.
 
The extension parameter <code>default</code> specifies whether the theme should be active by default.
Another method of activating a custom theme is by specifying the theme id with URL parameter <code>theme</code>.
+
Currently, this is the only way to activate a custom theme.
 
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 95: Line 95:
 
   SWT.COLOR_TITLE_INACTIVE_BACKGROUND:  shell.title.inactive.background
 
   SWT.COLOR_TITLE_INACTIVE_BACKGROUND:  shell.title.inactive.background
 
   SWT.COLOR_TITLE_INACTIVE_BACKGROUND_GRADIENT:  shell.title.inactive.background.gradient
 
   SWT.COLOR_TITLE_INACTIVE_BACKGROUND_GRADIENT:  shell.title.inactive.background.gradient
 
[[Category:RAP]]
 

Revision as of 11:24, 8 June 2007

This article describes the themeing 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. 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.

Contents

State of Development

The RWT themeing mechanism, as introduced with the M4 milestone, is still in an early state of development. Some details are still likely to change, as our experience with this approach grows. Your comments and suggestions are welcome.

Currently, the RWT themeing only allows to define colors. Themeing of icons, fonts, borders, margins etc. will follow shortly.

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 plugin (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 specifies whether the theme should be active by default. Currently, this is the only way to activate a custom theme. 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.

Images

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

Fonts

Borders

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