|
|
| Line 1: |
Line 1: |
| | | [[RAP|RAP wiki home]] | [http://eclipse.org/rap RAP project home] | | | | [[RAP|RAP wiki home]] | [http://eclipse.org/rap RAP project home] | |
| | | | |
| − | This article describes the theming functionality of RWT, the RAP Widget Toolkit.
| + | Please refer to the related articles in the RAP Developer Guide: |
| − | This theming defines the default look and feel of the basic RWT controls like Shell, Button, Text etc.
| + | * [http://help.eclipse.org/help33/index.jsp?topic=/org.eclipse.rap.help/help/html/advanced/theming.html RWT Theming] |
| − | 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.
| + | * [http://help.eclipse.org/help33/index.jsp?topic=/org.eclipse.rap.help/help/html/advanced/theming-custom.html Prepare Custom Widgets for Theming] |
| − | | + | |
| − | == 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 <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.
| + | |
| − | 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" />
| + | |
| − | </extension>
| + | |
| − | </pre>
| + | |
| − | | + | |
| − | === Activate the theme ===
| + | |
| − | | + | |
| − | From M6 on, the theme to use is set by the [[RAP_Branding|branding]].
| + | |
| − | 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:9090/rap?startup=controls&theme=org.eclipse.rap.demo.alttheme</code>).
| + | |
| − | 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.
| + | |
| − | | + | |
| − | === Dimensions === | + | |
| − | | + | |
| − | Dimensions are given as integer numbers with the unit suffix <code>px</code>.
| + | |
| − | As all size calculations in SWT are pixel-based, only the unit "px" is allowed.
| + | |
| − | | + | |
| − | Example: <code>1px</code>
| + | |
| − | | + | |
| − | | + | |
| − | === Box Dimensions ===
| + | |
| − | | + | |
| − | Box dimensions like margins and paddings can be provided in the shorthand syntax known from CSS2.
| + | |
| − | One, two, three, or four dimensions may be specified, separated by spaces.
| + | |
| − | If four dimensions are given, they stand for the values in clock-wise order: top, right, bottom, left.
| + | |
| − | Three values stand for: top, right and left, bottom.
| + | |
| − | Two values stand for: top and bottom, right and left.
| + | |
| − | One values stands for: all four values.
| + | |
| − | | + | |
| − | Examples for valid box dimension definitions are:
| + | |
| − | * <code>5px</code> means: 5px for top, right, bottom, and left edge.
| + | |
| − | * <code>3px 5px</code> means: 3px for top and bottom edge, 5px for left and right.
| + | |
| − | * <code>2px 4px 0px</code> means: 2px for the top edge, 4px for left and right, and 0px for the bottom.
| + | |
| − | * <code>2px 4px 0px 2px</code> 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
| + | |
| − | <code>solid</code>,
| + | |
| − | <code>dotted</code>,
| + | |
| − | <code>dashed</code>,
| + | |
| − | <code>double</code>,
| + | |
| − | <code>inset</code>,
| + | |
| − | <code>outset</code>,
| + | |
| − | <code>groove</code>,
| + | |
| − | <code>ridge</code>, and
| + | |
| − | <code>none</code>.
| + | |
| − | | + | |
| − | 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:
| + | |
| − | * <code>none</code>
| + | |
| − | * <code>1px inset</code>
| + | |
| − | * <code>2px groove</code>
| + | |
| − | * <code>1px solid black</code>
| + | |
| − | * <code>2px 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 10px</code>
| + | |
| − | * <code>Helvetica 10px bold</code>
| + | |
| − | * <code>10px Helvetica bold italic</code>
| + | |
| − | * <code>12px 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 ==
| + | |
| − | | + | |
| − | 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]] |
