The new CSS declarative styling support provides developers with the flexibility of styling their user interface based on a set of properties defined within a CSS style sheet. Property values are mapped to changes to SWT widgets, such as fonts and colors. The following CSS selector formats are supported:
- Element name: SWT widget class is used instead of HTML element type
- CSS ID: assignable from Java
- CSS classname: assignable from Java
- Pseudo selector: some SWT widget states are captured in pseudo selectors (e.g.
Button:checked) - widget data: the key elements are available as attributes and the values as data (e.g., a widget where
widget.setData("foo", "bar")will be matched by*[foo='bar']) - widget style bits: the style bits (normally passed through the constructor) are available through the style attribute (e.g.,
Button[style~='SWT.CHECK']
Note that while the support for SWT widgets is the primary focus of the current developers that are working on the CSS code, the core engine is headless and can be used to "style" other things such as for applying arbitrary properties to a model.
An @media rule restricts the rules it contains to one platform, so a theme can carve out an exception without shipping a second style sheet.
Two vendor features name the platform, -eclipse-os and -eclipse-ws, whose values are the ones Platform.getOS() and Platform.getWS() report (linux, win32, macosx and gtk, win32, cocoa).
CTabFolder { background-color: #fafafa; }
@media (-eclipse-os: linux) {
CTabFolder { background-color: #2f2f2f; }
}Three more features cover the operating system version: -eclipse-os-version, -eclipse-min-os-version and -eclipse-max-os-version.
Quote a version with more than one dot, since 10.15.7 is not a single CSS number.
@media (-eclipse-os: macosx) and (-eclipse-min-os-version: "10.15") {
CTabFolder { background-color: #2f2f2f; }
}Comparison happens over the segments the value gives, so its own precision decides the granularity: "10.15" covers all of 10.15.x, and both bounds include the line they name.
Anything that is not a digit separates segments, which drops a Linux -33-generic tail.
A rule can also depend on an installed bundle, which is useful when an optional contribution has to be styled only where it exists.
The bundle is named in the value, since media features are evaluated one by one and cannot refer to each other, and -eclipse-bundle-version, -eclipse-min-bundle-version and -eclipse-max-bundle-version take a symbolic name followed by a version.
@media (-eclipse-bundle: "org.eclipse.ui") { ... }
@media (-eclipse-min-bundle-version: "org.eclipse.ui 3.2") { ... }Unlike the operating system, the installed bundles can change while the workbench runs. A bundle query answers for the moment the rules were indexed, which is when a theme is applied, so a bundle installed afterwards is picked up at the next theme switch.
The usual media query syntax applies: and requires every expression, a comma separated list matches when any query does, not inverts one query, and the media types all and screen match while print and the rest do not.
A guarded rule takes part in the cascade at the position of its @media block.
An unknown feature, value or media type simply does not match, so a query written for a browser contributes no rules instead of breaking the sheet.
Rules can also be restricted per platform from the outside, with the os and ws attributes of the org.eclipse.e4.ui.css.swt.theme extension point, which pick a whole style sheet rather than single rules.
A theme can also set preferences, through an IEclipsePreferences element whose id is the preference node with dots replaced by dashes.
The values a theme sets are removed again when another theme is applied.
IEclipsePreferences#org-eclipse-ui-workbench {
preferences: 'perspectiveSwitcherSide=left';
}perspectiveSwitcherSide places the perspective switcher in the top (default), bottom, left or right trim, and on the left or right it is laid out vertically.
A position the user drags the switcher to is kept until the value changes again.
The sample code below creates a simple Label within a Shell but the Label's foreground colour is styled to a blue colour by the CSS engine.
Display display = new Display();
Shell shell = new Shell();
shell.setLayout(new GridLayout());
Label label = new Label(shell, SWT.LEAD);
label.setText("Hello world!");
label.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, true));
CSSEngine engine = new CSSSWTEngineImpl(display);
engine.parseStyleSheet(new StringReader("Label { color: blue }"));
// applying styles to the child nodes means that the engine
// should recurse downwards, in this example, the engine
// should style the children of the Shell
engine.applyStyles(shell, /* applyStylesToChildNodes */ true);
shell.setSize(400, 300);
shell.open();
while (!shell.isDisposed()) {
if (!display.readAndDispatch()) {
display.sleep();
}
}
display.dispose();CSS style sheets can be used to modify SWT widget properties.
Many SWT property setting methods can be accessed via CSS. These tables show the equivalent mapping from SWT method to CSS property. They also show pseudo selectors which can be used to choose styling based on widget state.
The SWT font height is a point size, so a font-size is resolved to points.
| Value | Meaning | Example |
|---|---|---|
| unitless | points | Label { font-size: 12 } |
pt |
points | Label { font-size: 12pt } |
px |
CSS pixels, converted with 1px = 0.75pt | Label { font-size: 16px } gives 12pt |
em |
relative to the font the widget had before styling | Label { font-size: 1.5em } |
% |
relative to the font the widget had before styling | Label { font-size: 150% } |
larger / smaller |
one step (factor 1.2) up or down from the font the widget had before styling | Label { font-size: larger } |
Relative values are resolved against the font the widget had before styling, so a theme can make a font a bit larger than the rest without overriding the size the user configured.
The font shorthand accepts the same forms, for example Label { font: Verdana larger }, except that a unitless 100 to 900 in steps of 100 is a weight there.
font-weight accepts normal, bold, bolder, lighter and the numbers
100 to 900.
It also accepts the face names designers use, which are not standard CSS:
| Name | Weight |
|---|---|
thin, hairline |
100 |
extra-light, ultra-light |
200 |
light |
300 |
regular |
400 |
medium |
500 |
semi-bold, demi-bold |
600 |
extra-bold, ultra-bold |
800 |
black, heavy |
900 |
The names are case-insensitive and may be written without the hyphen, as in semibold.
They are only understood by font-weight, not in the font shorthand, where they could be part of a family name.
A weight other than 400 or 700 selects the installed face of that weight, for example Semibold for 600.
On GTK Pango picks the closest face of the family, on Windows a family such as "Segoe UI Semibold" is used when it is installed, and on macOS a face of the family with a matching name such as HelveticaNeue-Medium.
Where the family has no face of that weight, the nearest one is taken in the order of CSS font matching: below 400 lighter faces first, above 500 heavier ones first, so 200 can select Light and 800 Black.
If no face is found before regular or bold, a weight of 600 or more selects the bold face and anything below it the regular one.
In the font shorthand a bare 100 to 900 is read as a weight, any other
bare number as a size in points.
| SWT Method | CSS Property Name | CSS Example |
|---|---|---|
| setBackground(Color) | background-color | Button { background-color: #FF0000 } |
| (vertical gradient) | background-color | Button { background-color: #FF0000 #00FF00 100% } |
| (horizontal gradient) | background-color | Button { background-color: #FF0000 #00FF00 100% false } |
| setBackgroundImage(Image) | background-image | Button { background-image: some url } |
| border-color | Button { border-color: #FF0000; } | |
| border-width | Button { border-width: 3 } | |
| border-style | Button { border-style: dotted } | |
| setCursor(Cursor) | cursor | Shell { cursor:crosshair } |
| setFont(Font) | font | Label { font: italic 12 bold "Terminal"; } |
| font-style font-size font-weight font-family | Label { font-style: italic; font-size: 12; font-weight: bold; font-family: "Terminal"; } | |
| setForeground(Color) | color | Button { color: #FF0000 } |
| SWT Method | CSS Property Name | CSS Example |
|---|---|---|
| SVGFileFormat.setCurrentColor(RGB) | swt-svg-current-color | Shell { swt-svg-current-color: #CCCCCC; } (Experimental) |
swt-svg-current-color is experimental and may change or be removed in a future release.
It sets the color that SVG images use for currentColor.
It is a single process-wide default, applied once at startup, so a theme switch takes effect after a restart.
It does not follow the foreground of the widget showing the image, so an icon drawn on a selected or otherwise colored background keeps this color.
Images created before the theme is applied, such as the product window icons, keep SWT's default black.
| SWT Method | CSS Property Name | CSS Example |
|---|---|---|
| setAlignment(int) | swt-alignment | Label { swt-alignment: up; } /* if pushbutton mode */ |
| SWT Method | CSS Property Name | CSS Example |
|---|---|---|
| setAlignment(int) | swt-alignment | Label { swt-alignment: center; } |
| SWT Method | CSS Property Name | CSS Example |
|---|---|---|
| setBorderVisible(boolean) | border-visible | CTabFolder { border-visible: true } |
| setMaximized(boolean) | swt-maximized | CTabFolder { swt-maximized: true } |
| setMinimized(boolean) | swt-minimized | CTabFolder { swt-minimized: true } |
| setMaximizeVisible(boolean) | swt-maximize-visible | CTabFolder { swt-maximize-visible: true } |
| setMinimizeVisible(boolean) | swt-minimize-visible | CTabFolder {swt-minimize-visible: true } |
| setMRUVisible(boolean) | swt-mru-visible | CTabFolder { swt-mru-visible: true } |
| setSimple(boolean) | swt-simple | CTabFolder { swt-simple: true } (Deprecated, curved tabs are no longer supported) |
| setSingle(boolean) | swt-single | CTabFolder { swt-single: true } |
| setUnselectedCloseVisible(boolean) | swt-unselected-close-visible | CTabFolder { swt-unselected-close-visible: true } |
| setUnselectedImageVisible(boolean) | swt-unselected-image-visible | CTabFolder { swt-unselected-image-visible: true } |
| setRenderer(CTabFolderRenderer) | swt-tab-renderer | CTabFolder { swt-tab-renderer: url('bundleclass://org.eclipse.e4.ui.workbench.renderers.swt/org.eclipse.e4.ui.workbench.renderers.swt.CTabRendering'); } |
| setSelectionBackground(Color[],int[]) | swt-selected-tabs-background | CTabFolder { swt-selected-tabs-background: #FF0000 #FFFFFF 100%; } |
| setBackground(Color[],int[]) | swt-unselected-tabs-color | CTabFolder { swt-unselected-tabs-color: #FF0000 #FFFFFF 100%; } |
| setTabHeight(int) | swt-tab-height | CTabFolder { swt-tab-height: 10px; } |
| SWT Method | CSS Property Name | CSS Example |
|---|---|---|
| setShowClose(boolean) | swt-show-close | CTabItem { swt-show-close: true } |
Note: The following examples assume that you have first set the tab-renderer to use CTabRendering (see the tab-renderer CSS property in the CTabFolder table above)
| e4Renderer Method | CSS Property Name | CSS Example |
|---|---|---|
| setOuterKeyline(Color) | swt-outer-keyline-color | CTabFolder { swt-outer-keyline-color: #B6BCCC; } |
| setShadowVisible(boolean) | swt-shadow-visible | CTabFolder { swt-shadow-visible: false; } |
| setShadowColor(Color) | swt-shadow-color | CTabFolder { swt-shadow-color: #F79402; } |
| setSelectedTabFill(Color) | swt-selected-tab-fill | CTabFolder { swt-selected-tab-fill: #F79402; } |
| setTabOutline(Color) | swt-tab-outline | CTabFolder { swt-tab-outline: #F79402; } |
| SWT Widgets | CSS Pseudo Selector | CSS Example |
|---|---|---|
| Control | :focus † | CTabFolder:focus { background-color: #FF0000; } |
| Control | :visible † | Shell:visible { background-color: #FF0000; } |
| Control | :enabled † | Text:enabled { background-color: #FF0000; } |
| Control | :disabled † | Text:disabled { background-color: #FF0000; } |
| Shell | :active | Shell:active { background-color: #FF0000; } |
| Button | :checked | Button:checked { background-color: #FF0000; } |
| CTabFolder | :selected | CTabFolder:selected { background-color: #FF0000; } |
| CTabItem | :selected | CTabItem:selected { font-weight: bold; } |
† As of yet styles are only applied when SWT UI is initially loaded, if widget state is changed afterwards, changes will not take effect
This is a "how-to" that will explain the steps needed to add a CSS Selector in E4.
- Create a class in org.eclipse.e4.ui.css.swt.selectors, and name it "DynamicPseudoClassesSWTxxxxHandler" where "xxxx" is the name of the selector
- Make this new class extend "AbstractDynamicPseudoClassesControlHandler"
public class DynamicPseudoClassesSWTActiveHandler extends AbstractDynamicPseudoClassesControlHandler- Within the class, create a IDynamicPseudoClassesHandler and set it equal to an instance of DynamicPseudoClassesSWTxxxxHandler
public static final IDynamicPseudoClassesHandler INSTANCE = new DynamicPseudoClassesSWTxxxxHandler();- Add the following two methods:
protected void intialize(final Control control, final CSSEngine engine) {}
protected void dispose(Control control, CSSEngine engine) {}- Note: method name is intilize is not initialize
- In the intialize method, add the code needed (most likely listeners to look for change of state). For an example, see org.eclipse.e4.ui.css.swt.selectors.DynamicPseudoClassesSWTActiveHandler
- Make use of the setData() method on the widget (to get information about the widget in another class), as well as applying the styles to the engine. For example, in a listener's method, you can do the following:
try {
control.setData("Some Qualified String", Boolean.TRUE);
engine.applyStyles(control, false, true);
} catch (Exception ex) {
engine.handleExceptions(ex);
}- It is preferable to use a qualified string, and to keep it in org.eclipse.e4.ui.css.swt.CSSSWTConstants
- In the dispose method, get rid of all listeners that were created in the above intialize method
- In org.eclipse.e4.ui.css.swt.dom.SWTElement#isPseudoInstanceOf add the new selector with the use of an "if" statement
if ("xxxx".equals(s)) {}- Within the if statement, return the appropriate boolean value based on the setData() you used in your listener, and add any other conditional statements that may be necessary
if ("xxxx".equals(s)) {
Widget widget = getNativeWidget();
if (widget != null) {
return widget.getData("Some Qualified String") == null;
}
}- Now, we must go in org.eclipse.e4.ui.css.swt.engine.AbstractCSSSWTEngineImpl , and register the name of the selector and the instance of the above class just created:
super.registerDynamicPseudoClassHandler("xxxx", DynamicPseudoClassesSWTxxxxHandler.INSTANCE);This page is a "how-to" that will explain the steps needed to add a styleable CSS property in E4.
An easier approach than what is described here is to simply provide an extension to the org.eclipse.e4.ui.css.core.propertyHandler extension point.
Create a class in org.eclipse.e4.ui.css.swt.properties.custom and name it "CSSPropertyXXXXSWTHandler", where XXXX is the name of the property
- Make this new class extend "AbstractCSSPropertySWTHandler"
public class CSSPropertyXXXXSWTHandler extends AbstractCSSPropertySWTHandler- Add the following two methods:
public void applyCSSProperty(Control control, String property, CSSValue value, String pseudo, CSSEngine engine) throws Exception {}
public String retrieveCSSProperty(Control control, String property, String pseudo, CSSEngine engine) throws Exception {}Within the applyCSSProperty method, write the code needed to apply the wanted styles. For example, for the border-visible property (CTabFolder) we write the following:
public void applyCSSProperty(Control control, String property, CSSValue value, String pseudo, CSSEngine engine) throws Exception {
boolean isBorderVisible = (Boolean)engine.convert(value, Boolean.class, null);
if (control instanceof CTabFolder) {
CTabFolder folder = (CTabFolder) control;
folder.setBorderVisible(isBorderVisible);
}
}Within the retrieveCSSProperty method, write the code needed to retrieve the value of the applied property. Again, for border-visible, we write the following:
public String retrieveCSSProperty(Control control, String property, String pseudo, CSSEngine engine) throws Exception {
if (control instanceof CTabFolder) {
CTabFolder folder = (CTabFolder) control;
return Boolean.toString( folder.getBorderVisible() );
}
}Finally we must wire in the property handler to the CSS Engine. There are two approaches:
- Configure the property using the org.eclipse.e4.ui.css.core.propertyHandler extension point.
- Explicitly configure the CSS engine instance in the initializeCSSPropertyHandlers() method. In this case, we must first register the name of the property and the above class just created. We must also register the CSSPropertyHandler created in the class:
super.registerCSSProperty("xxxx", CSSPropertyXXXXSWTHandler.class);
super.registerCSSPropertyHandler(CSSPropertyXXXXSWTHandler.class, new CSSPropertyXXXXSWTHandler());The CSS Theme Engine can be used in Eclipse 3.6. See the example "org.eclipse.e4.ui.examples.css.rcp" on GitHub.