Skip to content

Latest commit

 

History

History
421 lines (294 loc) · 19 KB

CSS.md

File metadata and controls

421 lines (294 loc) · 19 KB

Eclipse

Overview

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.

Platform-specific rules

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.

Preferences

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.

Sample

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();

SWT Mapping

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.

Font size

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

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.

Widget: Control

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 }

Widget: Shell

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.

Widget: Button

SWT Method CSS Property Name CSS Example
setAlignment(int) swt-alignment Label { swt-alignment: up; } /* if pushbutton mode */

Widget: Label

SWT Method CSS Property Name CSS Example
setAlignment(int) swt-alignment Label { swt-alignment: center; }

Widget: CTabFolder

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; }

Widget: CTabItem

SWT Method CSS Property Name CSS Example
setShowClose(boolean) swt-show-close CTabItem { swt-show-close: true }

Widget: CTabFolder with e4Renderer

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; }

Pseudo classes which can be used in CSS to style SWT widgets

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

E4/CSS/Add Selector

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);

E4/CSS/Add Styleable Property

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 the Property Handler Class

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 {}

Implement Property Setting

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);
                }
         }

Implement Property Retrieval

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() );
                }
         }

Expose the Property

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());

Using CSS in Eclipse 3.6

The CSS Theme Engine can be used in Eclipse 3.6. See the example "org.eclipse.e4.ui.examples.css.rcp" on GitHub.