Themes HOWTO

Posted by pookzilla on November 23, 2005

Several people have recently asked me how to use themes. I posted a quick how-to on the Eclipse RCP newsgroup last year but it’s kind of hard to find so I’m reposting the contents of the message here, unedited, in the hope that Google will index it at some point. It’s a bit out of date but it’s a good place to start. I’ll attempt to freshen it up soon.

I’ve been meaning to write an article describing how to use themes but in the meantime here is the quick and dirty.

First, the extension point. The themes extension point allows you to define 4 things.

1) Color Definition. A color definition is some color that is identifiable by some ID. It has associated name and description elements, and its value may be specified in one of two ways. It can either be an explicit value (either a decimal RGB triple or the name of an SWT colour constant, such as COLOR_RED) or a inherited value (you specify another colour ID). Explicit values may also be specified using a colour factory. A colour factory is some class that can return an RGB triple.

2) Font Definition. Similar to a colour definition except that it’s possible to provide no value (resulting in a font that matches the system default font) and there is (as yet) no correspoding font factory class.

3) Data. Data is a simple key/value pair. The data provided here should be used in conjunction with visual presentation. Ie: “horizontal tab orientation”, “true”.

4) Themes. Themes are named collections of font, color and data overrides. When a theme is applied, it’s overrides are layed on top of the default values specified.

Examples:

<colorDefinition
    id="backgroundColor"
    name="My Plugin Views Background Color"
    description="The background color"
    value="COLOR_WHITE" />
<theme
    id="gaudy theme"
    name="A really gaudy theme"
    description="So...very...ugly...">
    <colorOverride
        id="backgroundColor"
        value="COLOR_CYAN" />
</theme>

In the above case, there would be a globally defined “background color” with a default value of white. If the user happens to have “gaudy theme” as their current theme, then the default value is cyan. Ewww.

Now…how do you use themes in your plugin in?

IWorkbench.getThemeManager() provides a means to access the colors, fonts and data defined in extension points. The most common usage of the manager is to get the elements that correspond to the currently active theme. For instance, in your view createPartControl(Composite) method you could do the following:


public void createPartControl(Composite composite) {
    IThemeManager themeManager =
        getSite()
        .getWorkbenchWindow()
        .getWorkbench()
        .getThemeManager();
    Label label = new Label(composite, SWT.NONE);
    label.setBackgroundColor(themeManager
        .getCurrentTheme()
        .getColorRegistry()
        .get("backgroundColor");

    ...
}

Note that you should never hold onto the result from IThemeManager.getCurrentTheme(). If the current theme changes then this value will be stale.

Now, the colors and fonts described in the themes extension point may be customized from the Workbench->Colors and Fonts preference page. Additionally, the user may choose to use a new theme. You probably want to honour these choices. In order to do this you’ll want to listen to theme changes. You can do this in the following manner:


themeManager
.addPropertyChangeListener(
new IPropertyChangeListener() {
    public void propertyChange(PropertyChangeEvent event) {
        // if the user is now using a new theme or if the user
        // has customized the value of the background color
        // update the control
        if (event
            .getProperty()
            .equals(IThemeManager.CHANGE_CURRENT_THEME)
            || event
                .getProperty()
                .equals("backgroundColor")) {
            label.setBackgroundColor(themeManager
                .getCurrentTheme()
                .getColorRegistry()
                .get("backgroundColor");
        }
    }
});

The default workbench presentation makes use of the font/colour/data ids found in org.eclipse.ui.internal.IWorkbenchThemeConstants. A theme writer can define a theme that overrides these values. Note however this class is internal – we dont want to expose these ids as API just yet as they may change in future versions of eclipse. For example, we may stop using gradients on tabs…or stop using tabs entirely. (This is just an example, so please no firestorms

So, that’s /basically/ how you make use of themes, but I’m not sure that answers Nicky’s question. Completely customizing the look and feel of eclipse is outside of the scope of themes alone. Themes just provide name-value pairs really. It takes code to actually make use of them. This is where presentations come into play. What are presentations? Well…that’s a completely different kettle of fish. If you’d like, I’ll prod the right people and see if they can’t shed some light on presentations for you…

Wow, that took a long time.