Difference between revisions of "Eclipse4/RCP/CSS"

From Eclipsepedia

< Eclipse4‎ | RCP
Jump to: navigation, search
m (Resources)
(Setting the Widget Class and Id)
(One intermediate revision by one user not shown)
Line 1: Line 1:
 
One area of improvement with the E4AP was to rethink how to approach themeing or styling an application — to change its look and feel.  E4AP supports radical changes through the use of CSS, or <em>cascading style sheets</em>, the same technology used in HTML.
 
One area of improvement with the E4AP was to rethink how to approach themeing or styling an application — to change its look and feel.  E4AP supports radical changes through the use of CSS, or <em>cascading style sheets</em>, the same technology used in HTML.
  
A general discussion of CSS is beyond the scope of this document.  But as the E4AP's CSS support is largely based on HTML- and SVG-based CSS, many of the CSS tutorials and guides are mostly applicable to the E4AP [http://en.wikipedia.org/wiki/Css#Further_reading].  In brief, CSS supports separating how content is shown from how the content is presented (e.g., colors, fonts).  CSS applies <em>rules</em> to affect the appearance of some subset of <em>elements</em> within a <em>document</em>.  These elements are selected using <em>selectors</em> that identify elements based on element properties or their relationship to other elements within the document's <em>container hierarchy</em>.
+
In brief, CSS supports separating how content is shown from how the content is presented (e.g., colors, fonts).  CSS applies <em>rules</em> to affect the appearance of some subset of <em>elements</em> within a <em>document</em>.  These elements are selected using <em>selectors</em> that identify elements based on element properties or their relationship to other elements within the document's <em>container hierarchy</em>. A general discussion of CSS is beyond the scope of this document, but as the CSS support is largely based on the [http://www.w3.org/TR/CSS21/ same CSS standard as HTML and SVG CSS], many of the CSS tutorials and guides are mostly applicable to the E4AP [http://en.wikipedia.org/wiki/Css#Further_reading]. 
  
 
Applying CSS to styling widgets, windows, and dialogs, may seem a bit strange at first.  But a UI forms a hierarchy just like an HTML document.  For example, an SWT window or dialog has a <tt>Shell</tt> as a root container, which contains a number of <tt>Composite</tt> or <tt>Group</tt> elements, each containing other widgets such as a <tt>CTabFolder</tt>, <tt>Text</tt>, <tt>Tree</tt>, or <tt>Table</tt>.
 
Applying CSS to styling widgets, windows, and dialogs, may seem a bit strange at first.  But a UI forms a hierarchy just like an HTML document.  For example, an SWT window or dialog has a <tt>Shell</tt> as a root container, which contains a number of <tt>Composite</tt> or <tt>Group</tt> elements, each containing other widgets such as a <tt>CTabFolder</tt>, <tt>Text</tt>, <tt>Tree</tt>, or <tt>Table</tt>.
Line 7: Line 7:
 
== CSS Mapping ==
 
== CSS Mapping ==
  
The E4AP exposes [[Eclipse4/RCP/Modeled_UI/Model_Elements|modelled elements]] and their constituent widgets to the CSS support.  The SWT support exposes a widget and its children.
+
CSS selectors support identifying elements by their <em>type</em>, <em>class</em>, or <em>id</em>, in the form "<em>type</em>#<em>id</em>.<em>class</em>".  In the CSS-SWT mapping:
 +
* The <em>type</em> corresponds to the simple class name of the widget (e.g., <tt>Button</tt>, <tt>Composite</tt>).
 +
* The CSS specification defines that the id must be unique within the document (i.e., within the window).  A widget's <em>id</em> may be set by calling <tt>WidgetElement.setId(widget, "unique-id")</tt>. 
 +
* An element may have a number of classes.  The set of classes may be specified using <tt>WidgetElement.setCSSClass(widget, "space delimited set of classes")</tt>.  CSS-SWT also exposes SWT's widget's data values through the class attribute.
  
CSS selectors support identifying elements by their <em>type</em>, <em>class</em>, or <em>id</em>, in the form "<em>type</em>#<em>id</em>.<em>class</em>"In the E4AP/SWT mapping:
+
The E4AP further annotates the widgets used for rendering the [[Eclipse4/RCP/Modeled_UI/Model_Elements|modelled elements]]Specifically:
* The <em>type</em> corresponds to the Java class of the widget (e.g., <tt>Button</tt>, <tt>Composite</tt>).
+
* A Modeled UI element's interface type (e.g., <tt>MPart</tt>, <tt>MTrimmedWindow</tt>) and its tags are exposed as CSS classes.   
* Elements may have a number of classes.  The E4AP exposes the Modeled UI element's interface type (e.g., <tt>MPart</tt>, <tt>MTrimmedWindow</tt>) and its tags through the class attributeThe SWT's widget's data values are also available through the class attribute.
+
 
* The <em>id</em> corresponds to the modelled element's <tt>elementId</tt>, with periods replaced with dashes.
 
* The <em>id</em> corresponds to the modelled element's <tt>elementId</tt>, with periods replaced with dashes.
  
== Using Selectors ==
+
=== Using Selectors ===
  
* Selecting on style bits: SWT widget style bits are exposed through the "style" attribute allowing queries like <tt>Button[style~='SWT.CHECK']</tt>.
+
Some nifty ways that selectors can be used:
* classes
+
* Selecting on style bits: SWT widget style bits are exposed through the "style" attribute allowing queries like <tt>Button[style~='SWT.CHECK']</tt>
 +
* Selecting by modelled element type. For example, to style partstacks shown within the editor area, to differentiate editors from views: <tt>#org-eclipse-ui-editorss .MPartStack</tt>
 +
* Some JFace-created elements, such as instances of <tt>org.eclipse.jface.dialogs.Dialog</tt> and <tt>org.eclipse.jface.windows.Window</tt> install the JFace object as the top-level widget's data object.  The class hierarchy of this object can be queried using the "swt-data-class" attribute.  So the following selector will identify all Shells that are from a JFace dialog: <tt>Shell[swt-data-class ~= 'org.eclipse.jface.dialogs.Dialog']</tt>
 
* widget data: SWT widgets carry a data dictionary.  These key-values can be queries through CSS selectors.  For example, a widget configured with:
 
* widget data: SWT widgets carry a data dictionary.  These key-values can be queries through CSS selectors.  For example, a widget configured with:
 
<source lang="java">
 
<source lang="java">
 
widget.setData("level", "basic");
 
widget.setData("level", "basic");
 
</source>
 
</source>
 
 
could be subsequently selected with <tt>*[level='basic']</tt>.
 
could be subsequently selected with <tt>*[level='basic']</tt>.
  
 
== SWT Properties ==
 
== SWT Properties ==
  
Incorporate the list from [[E4/CSS/SWT_Mapping | here]].
+
The CSS-SWT support largely provides the standard properties defined in the [http://www.w3.org/TR/CSS21/ CSS 2.1 standard].
 +
A list showing the mapping of supported properties to corresponding SWT methods is found [[E4/CSS/SWT_Mapping | here]].
  
== E4AP Themeing Support ==
+
== Installing / Configuring CSS Stylesheets ==
  
* Specifying CSS file as app property
+
There are three ways to configure a CSS stylesheet for an application.  The first three approaches are suited for RCP applications:
* Using the theme extension point
+
  
== Applying Rules Programmatically ==
+
# [Eclipse 4.2 only] Launch Eclipse with <tt>-applicationCSS url:to/cssfile</tt>. Resources referenced by CSS files will be looked up in locations specified with <tt>-applicationCSSResources url:prefix/for/resources</tt>.
 +
# Provide your own CSS-based theme using the <tt>org.eclipse.e4.ui.css.swt.theme</tt> extension point. This approach is discussed in the following section.
 +
# Programmatically obtain the <tt>org.eclipse.e4.ui.css.core.engine.CSSEngine</tt> and provide a style sheet. See the [http://git.eclipse.org/c/e4/org.eclipse.e4.tools.git/tree/bundles/org.eclipse.e4.tools.css.spy/src/org/eclipse/e4/tools/css/spy/CSSScratchPadWindow.java <tt>CSSScratchPadWindow.applyCSS()</tt>] for an example.
 +
 
 +
The other two ways are more intended for personal use or debugging/exploration:
 +
# [Eclipse 4.2 only] Install the CSS Editor and customize the CSS in <em>Preferences &rarr; General &rarr; Appearance</em>.
 +
# [Eclipse 4.2 only] Install the CSS Spy and use the CSS Scratchpad to define new CSS rules.
 +
 
 +
The CSS Editor and CSS Spy are add-on tools from the Platform/UI team that are available through the Eclipse Marketplace.
 +
 
 +
=== E4AP Themeing Support ===
 +
 
 +
A replacement Theme Manager is available in Eclipse 4 to manage multiple CSS-based themes.  A theme is provided using the <tt>org.eclipse.e4.ui.css.swt.theme</tt> extension point; there is support for restricting a theme to a particular operating system or windowing system.  The themes are managed by an <tt>org.eclipse.e4.ui.css.swt.theme.IThemeManager</tt>, available as an OSGi service.  On a theme change, an event is sent using the OSGi EventAdmin service; the event is described in <tt>IThemeEngine.Events.THEME_CHANGED</tt>.
 +
 
 +
On 4.2, the preferences include a theme selector in <em>Preferences &rarr; General &rarr; Appearance</em>. On 3.7 or 3.8, you will need to trigger the theme change programmatically using the, exposed as an OSGi service.
 +
 
 +
=== Applying Rules Programmatically ===
  
 
* Obtaining the IStylingEngine as a service
 
* Obtaining the IStylingEngine as a service
Line 43: Line 62:
 
Adding CSS support to a custom widget takes three steps:
 
Adding CSS support to a custom widget takes three steps:
 
# Set the widget's class and (optional) id using the <em>org.eclipse.e4.ui.services.IStylingEngine</em> service.
 
# Set the widget's class and (optional) id using the <em>org.eclipse.e4.ui.services.IStylingEngine</em> service.
# Define the widget's element adapter using the <tt>org.eclipse.e4.u.css.core.elementProvider</tt> extension point.
+
# Define the widget's element adapter using the <tt>org.eclipse.e4.ui.css.core.elementProvider</tt> extension point.
# Define the new properties using the <tt>org.eclipse.e4.ui.css.swt.property.handler</tt> extension point.
+
# Define the new properties using the <tt>org.eclipse.e4.ui.css.core.propertyHandler</tt> extension point.
  
 
=== Setting the Widget Class and Id ===
 
=== Setting the Widget Class and Id ===
 +
 +
The more generic approach to setting the id for a widget is through the methods on <tt>IStylingEngine</tt>.
 +
 +
For SWT widgets, the class and ids are stored in the ''widget data'' using specific keys:
 +
 +
; <tt>CSSSWTConstants.CSS_ID_KEY</tt> ("org.eclipse.e4.ui.css.id")
 +
: The CSS identifier for this widget.  Typically expected to be unique within the DOM (e.g., the Shell), though this is not enforced.  Identifiers should not contain periods as they cannot otherwise be referenced in a CSS selector!
 +
 +
; <tt>CSSSWTConstants.CSS_CLASS_NAME_KEY</tt> ("org.eclipse.e4.ui.css.CssClassName")
 +
: The space-separated list of CSS classes for this widget.
 +
 +
The ''org.eclipse.e4.ui.css.swt.dom.WidgetElement'' class provides some helper methods for setting these values.
 +
 +
Note that setting the CSS id or classes does not trigger a refresh of the element.
  
 
=== Defining the Widget Element ===
 
=== Defining the Widget Element ===
  
The element adapter is the CSS dual of the widget, responsible for translating a widget into a <tt>CSSStylableElement</tt>, essentially DOM Node as used in CSS.  A Node provides a simplified interface to get the widget's parent and children. The element is also responsible for re-applying styles in response to changes on the widget.  For example, <tt>ControlElement</tt> installs focus and mouse event handlers to trigger CSS <tt>:focus</tt> and <tt>:hover</tt> changes.
+
The element adapter is the CSS dual of the widget, responsible for translating a widget into a <tt>CSSStylableElement</tt>, essentially DOM Node as used in CSS.  A Node provides a simplified interface to get the widget's parent and children. The element is also responsible for re-applying styles in response to changes on the widget.  For example, <tt>ControlElement</tt> installs focus and mouse event handlers to trigger CSS <tt>:focus</tt> and <tt>:hover</tt> changes (currently disabled by default; see {{bug|362532}}).  Typically most widgets can simply use <tt>ControlElement</tt>.  These element classes must be registered using the <tt>org.eclipse.e4.ui.css.core.elementProvider</tt> extension point.
  
See [http://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/bundles/org.eclipse.e4.ui.css.swt/src/org/eclipse/e4/ui/css/swt/dom/CompositeElement.java CompositeElement] for an example.
+
See [http://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/bundles/org.eclipse.e4.ui.css.swt/src/org/eclipse/e4/ui/css/swt/dom/CompositeElement.java CompositeElement] for an example of an element.
  
 
=== Defining the CSS Property Handlers ===
 
=== Defining the CSS Property Handlers ===
  
There are a number of predefined interfaces and abstract CSS property handlers in <em>org.eclipse.e4.ui.css.core.dom.properties.css2</em>.  Most implementations typically extend <tt>AbstractCSSPropertySWTHandler</tt>.   
+
There are a number of predefined interfaces and abstract CSS property handlers in <em>org.eclipse.e4.ui.css.core.dom.properties.css2</em>.  Most implementations typically extend <tt>AbstractCSSPropertySWTHandler</tt>.  A property handler must be registered with  the <tt>org.eclipse.e4.ui.css.core.propertyHandler</tt> extension point.
  
 
For example, the <tt>AbstractCSSPropertyTextHandler</tt> provides base support for handling <tt>color</tt> and <tt>text-transform</tt> properties.
 
For example, the <tt>AbstractCSSPropertyTextHandler</tt> provides base support for handling <tt>color</tt> and <tt>text-transform</tt> properties.

Revision as of 15:03, 5 October 2012

One area of improvement with the E4AP was to rethink how to approach themeing or styling an application — to change its look and feel. E4AP supports radical changes through the use of CSS, or cascading style sheets, the same technology used in HTML.

In brief, CSS supports separating how content is shown from how the content is presented (e.g., colors, fonts). CSS applies rules to affect the appearance of some subset of elements within a document. These elements are selected using selectors that identify elements based on element properties or their relationship to other elements within the document's container hierarchy. A general discussion of CSS is beyond the scope of this document, but as the CSS support is largely based on the same CSS standard as HTML and SVG CSS, many of the CSS tutorials and guides are mostly applicable to the E4AP [1].

Applying CSS to styling widgets, windows, and dialogs, may seem a bit strange at first. But a UI forms a hierarchy just like an HTML document. For example, an SWT window or dialog has a Shell as a root container, which contains a number of Composite or Group elements, each containing other widgets such as a CTabFolder, Text, Tree, or Table.

Contents

CSS Mapping

CSS selectors support identifying elements by their type, class, or id, in the form "type#id.class". In the CSS-SWT mapping:

  • The type corresponds to the simple class name of the widget (e.g., Button, Composite).
  • The CSS specification defines that the id must be unique within the document (i.e., within the window). A widget's id may be set by calling WidgetElement.setId(widget, "unique-id").
  • An element may have a number of classes. The set of classes may be specified using WidgetElement.setCSSClass(widget, "space delimited set of classes"). CSS-SWT also exposes SWT's widget's data values through the class attribute.

The E4AP further annotates the widgets used for rendering the modelled elements. Specifically:

  • A Modeled UI element's interface type (e.g., MPart, MTrimmedWindow) and its tags are exposed as CSS classes.
  • The id corresponds to the modelled element's elementId, with periods replaced with dashes.

Using Selectors

Some nifty ways that selectors can be used:

  • Selecting on style bits: SWT widget style bits are exposed through the "style" attribute allowing queries like Button[style~='SWT.CHECK']
  • Selecting by modelled element type. For example, to style partstacks shown within the editor area, to differentiate editors from views: #org-eclipse-ui-editorss .MPartStack
  • Some JFace-created elements, such as instances of org.eclipse.jface.dialogs.Dialog and org.eclipse.jface.windows.Window install the JFace object as the top-level widget's data object. The class hierarchy of this object can be queried using the "swt-data-class" attribute. So the following selector will identify all Shells that are from a JFace dialog: Shell[swt-data-class ~= 'org.eclipse.jface.dialogs.Dialog']
  • widget data: SWT widgets carry a data dictionary. These key-values can be queries through CSS selectors. For example, a widget configured with:
widget.setData("level", "basic");

could be subsequently selected with *[level='basic'].

SWT Properties

The CSS-SWT support largely provides the standard properties defined in the CSS 2.1 standard. A list showing the mapping of supported properties to corresponding SWT methods is found here.

Installing / Configuring CSS Stylesheets

There are three ways to configure a CSS stylesheet for an application. The first three approaches are suited for RCP applications:

  1. [Eclipse 4.2 only] Launch Eclipse with -applicationCSS url:to/cssfile. Resources referenced by CSS files will be looked up in locations specified with -applicationCSSResources url:prefix/for/resources.
  2. Provide your own CSS-based theme using the org.eclipse.e4.ui.css.swt.theme extension point. This approach is discussed in the following section.
  3. Programmatically obtain the org.eclipse.e4.ui.css.core.engine.CSSEngine and provide a style sheet. See the CSSScratchPadWindow.applyCSS() for an example.

The other two ways are more intended for personal use or debugging/exploration:

  1. [Eclipse 4.2 only] Install the CSS Editor and customize the CSS in Preferences → General → Appearance.
  2. [Eclipse 4.2 only] Install the CSS Spy and use the CSS Scratchpad to define new CSS rules.

The CSS Editor and CSS Spy are add-on tools from the Platform/UI team that are available through the Eclipse Marketplace.

E4AP Themeing Support

A replacement Theme Manager is available in Eclipse 4 to manage multiple CSS-based themes. A theme is provided using the org.eclipse.e4.ui.css.swt.theme extension point; there is support for restricting a theme to a particular operating system or windowing system. The themes are managed by an org.eclipse.e4.ui.css.swt.theme.IThemeManager, available as an OSGi service. On a theme change, an event is sent using the OSGi EventAdmin service; the event is described in IThemeEngine.Events.THEME_CHANGED.

On 4.2, the preferences include a theme selector in Preferences → General → Appearance. On 3.7 or 3.8, you will need to trigger the theme change programmatically using the, exposed as an OSGi service.

Applying Rules Programmatically

  • Obtaining the IStylingEngine as a service
  • Fetching the CSSEngine for a Display

Extending CSS to handle new widgets

Adding CSS support to a custom widget takes three steps:

  1. Set the widget's class and (optional) id using the org.eclipse.e4.ui.services.IStylingEngine service.
  2. Define the widget's element adapter using the org.eclipse.e4.ui.css.core.elementProvider extension point.
  3. Define the new properties using the org.eclipse.e4.ui.css.core.propertyHandler extension point.

Setting the Widget Class and Id

The more generic approach to setting the id for a widget is through the methods on IStylingEngine.

For SWT widgets, the class and ids are stored in the widget data using specific keys:

CSSSWTConstants.CSS_ID_KEY ("org.eclipse.e4.ui.css.id")
The CSS identifier for this widget. Typically expected to be unique within the DOM (e.g., the Shell), though this is not enforced. Identifiers should not contain periods as they cannot otherwise be referenced in a CSS selector!
CSSSWTConstants.CSS_CLASS_NAME_KEY ("org.eclipse.e4.ui.css.CssClassName")
The space-separated list of CSS classes for this widget.

The org.eclipse.e4.ui.css.swt.dom.WidgetElement class provides some helper methods for setting these values.

Note that setting the CSS id or classes does not trigger a refresh of the element.

Defining the Widget Element

The element adapter is the CSS dual of the widget, responsible for translating a widget into a CSSStylableElement, essentially DOM Node as used in CSS. A Node provides a simplified interface to get the widget's parent and children. The element is also responsible for re-applying styles in response to changes on the widget. For example, ControlElement installs focus and mouse event handlers to trigger CSS :focus and :hover changes (currently disabled by default; see bug 362532). Typically most widgets can simply use ControlElement. These element classes must be registered using the org.eclipse.e4.ui.css.core.elementProvider extension point.

See CompositeElement for an example of an element.

Defining the CSS Property Handlers

There are a number of predefined interfaces and abstract CSS property handlers in org.eclipse.e4.ui.css.core.dom.properties.css2. Most implementations typically extend AbstractCSSPropertySWTHandler. A property handler must be registered with the org.eclipse.e4.ui.css.core.propertyHandler extension point.

For example, the AbstractCSSPropertyTextHandler provides base support for handling color and text-transform properties.

Differences from HTML and SVG CSS

Resources