E4/CSS/Add Styleable Property

This page has been migrated to to https://github.com/eclipse-platform/eclipse.platform.ui/blob/master/docs/CSS.md.

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