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.
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 . 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.
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.
The E4AP exposes 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 type, class, or id, in the form "type#id.class". In the E4AP/SWT mapping:
- The type corresponds to the Java class of the widget (e.g., Button, Composite).
- Elements may have a number of classes. The E4AP exposes the Modeled UI element's interface type (e.g., MPart, MTrimmedWindow) and its tags through the class attribute. The SWT's widget's data values are also available through the class attribute.
- The id corresponds to the modelled element's elementId, with periods replaced with dashes.
- Selecting on style bits: SWT widget style bits are exposed through the "style" attribute allowing queries like Button[style~='SWT.CHECK'].
- widget data: SWT widgets carry a data dictionary. These key-values can be queries through CSS selectors. For example, a widget configured with:
could be subsequently selected with *[level='basic'].
Incorporate the list from here.
E4AP Themeing Support
- Specifying CSS file as app property
- Using the theme extension point
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:
- Set the widget's class and (optional) id using the org.eclipse.e4.ui.services.IStylingEngine service.
- Define the widget's element adapter using the org.eclipse.e4.u.css.core.elementProvider extension point.
- Define the new properties using the org.eclipse.e4.ui.css.swt.property.handler extension point.
Setting the Widget Class and Id
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.
See CompositeElement for an example.
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.
For example, the AbstractCSSPropertyTextHandler provides base support for handling color and text-transform properties.