Difference between revisions of "RAP Theming"

From Eclipsepedia

Jump to: navigation, search
(Fonts)
(8 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This article describes the themeing functionality of RWT, the RAP Widget Toolkit.
+
| [[RAP|RAP wiki home]] | [http://eclipse.org/rap RAP project home] |
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.
+
  
== State of Development ==
+
Please refer to the related articles in the RAP Developer Guide:
 
+
* [http://help.eclipse.org/ganymede/index.jsp?topic=/org.eclipse.rap.help/help/html/advanced/theming.html RWT Theming]
The RWT themeing mechanism, as introduced with the M4 milestone, is still in an early state of development.
+
* [http://help.eclipse.org/ganymede/index.jsp?topic=/org.eclipse.rap.help/help/html/advanced/theming-custom.html Prepare Custom Widgets for Theming]
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 <code>theme-template.properties</code> can be found in the <code>src/</code> directory of the RWT plugin (<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.
+
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 <code>org.eclipse.rap.swt.themes</code> ===
+
 
+
In the <code>plugin.xml</code> of your application project, add an extension like this:
+
 
+
<pre>
+
  <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>
+
</pre>
+
 
+
=== Activate the theme ===
+
 
+
The extension parameter <code>default</code> 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 [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 <code>0 .. 255</code> that denote the red, green, and blue portion of the color, respectively.
+
 
+
* A hexadecimal color notation in the format <code>#rgb</code> or <code>#rrggbb</code>, that is commonly used for HTML pages.
+
 
+
=== 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.
+
 
+
=== 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>
+
 
+
=== Borders ===
+
 
+
 
+
== SWT System Colors ==
+
 
+
The SWT system colors, as returned by <code>Display#getSystemColor()</code>, 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
+
  
 
[[Category:RAP]]
 
[[Category:RAP]]

Revision as of 09:20, 1 September 2008

| RAP wiki home | RAP project home |

Please refer to the related articles in the RAP Developer Guide: