Custom themes

The Lightweight UI Toolkit library supports pluggable themes, similar to CSS and somewhat simpler than Swing's pluggable Look And Feel.

Every LWUIT component has a style associated with it. This style can be manipulated manually and can be customised using a set of definitions for a specific component type. For example, in order to make the backgrounds for all the buttons red, you can use the following theme:

Button.bgColor=ff0000

This theme sets the background in the style object within the button object to red. A theme can be packaged into a resource file (see the Resources section) and it can be loaded or switched in runtime. In order to update a theme after switching, you must refresh the root component (the Form/Dialog containing our component tree) using the refreshTheme method to update all styles.

Note:

Manually modified style elements are not updated when switching a theme.

For example, if you have a button whose background is customised to blue, and you load or refresh a theme with a different background color for buttons, the new theme affects all button instances except for the one you have modified manually.

This allows you to determine styles for specific components, yet still be able to use themes for the general look of the application without worrying about how they affect your changes.

A theme file is very similar in spirit to CSS, yet it is much simpler and it is structured like a Java properties file. A theme file is comprised of key-value pairs. The key acts in a similar way to a CSS selector that indicates the component or attribute affected by the theme value. For example:

Button.font – font for all buttons.
font – default application font applied to all components where no default is defined.

The key element is comprised of an optional unique identifier ID for the component (the UIID) and a required attribute type. Unlike CSS, themes do not support elements such as hierarchy or more complex selectors.

Component UIIDs correspond to the component class name by convention. For example: Button, Label, CheckBox, RadioButton, Form, etc.

The supported attributes and their value syntax are illustrated in the following table:

Attribute	Value
`bgGradient`	Determines the values for the gradient of the image. Accepts source/destination colour, as well as X/Y of the center of a radial gradient.
`bgColor`	Hexadecimal number representing the background colour for the component in an unselected widget. For example, blue would be: `ff`
`bgImage`	Name of an image from within the resource that should be used as the background for this component. The image referenced must exist within the resource using the same name mentioned here. See the Resources chapter for further details about resources and theme files.
`bgType`	Allows determining the type of the background – whether it is an image, colour, or gradient. Valid values are: BACKGROUND_IMAGE_SCALED BACKGROUND_IMAGE_TILE_BOTH BACKGROUND_IMAGE_TILE_VERTICAL_ALIGN_LEFT BACKGROUND_IMAGE_TILE_VERTICAL_ALIGN_CENTER BACKGROUND_IMAGE_TILE_VERTICAL_ALIGN_RIGHT BACKGROUND_IMAGE_TILE_HORIZONTAL_ALIGN_TOP BACKGROUND_IMAGE_TILE_HORIZONTAL_ALIGN_CENTER BACKGROUND_IMAGE_TILE_HORIZONTAL_ALIGN_BOTTOM BACKGROUND_IMAGE_ALIGNED_TOP BACKGROUND_IMAGE_ALIGNED_BOTTOM BACKGROUND_IMAGE_ALIGNED_LEFT BACKGROUND_IMAGE_ALIGNED_RIGHT BACKGROUND_IMAGE_ALIGNED_TOP_LEFT BACKGROUND_IMAGE_ALIGNED_TOP_RIGHT BACKGROUND_IMAGE_ALIGNED_BOTTOM_LEFT BACKGROUND_IMAGE_ALIGNED_BOTTOM_RIGHT BACKGROUND_IMAGE_ALIGNED_CENTER BACKGROUND_GRADIENT_LINEAR_HORIZONTAL BACKGROUND_GRADIENT_LINEAR_VERTICAL BACKGROUND_GRADIENT_RADIAL
`fgColor`	Hexadecimal number representing the foreground colour for the component usually used to draw the font in an unselected widget. For example, red would be: `ff0000`
`font`	The name of the bitmap or system font from the build XML file.
`margin`	The amount of margin for the component defined as 4 comma-separated integer values representing top, bottom, left, and right. For example, 1, 2, 3, 4 results in 1 pixel margin top, 2 pixels margin bottom, 3 pixels margin left and 4 pixels margin right.
`padding`	Padding is identical to margin in terms of format but it updates the padding property of the component. To understand padding versus margin further, please refer to the box model explanation in the Margin and padding chapter in Styling individual components with Style Object section.
`transparency`	A number between 0 and 255 representing the opacity of a component's background. 0 means the background of the component does not draw at all (fully transparent) while 255 represents a completely opaque background. Notice that this value currently has no effect on background images (although this behaviour might change in a future release).

To install a theme you must load it from the Resources class (see the Resources section), from which you receive the already parsed hashtable containing the selectors (keys) and their appropriate values. You then submit this class to the UI manager's setThemeProps method in order to update the current theme. It is a good practice to call refreshTheme on all components in memory (even those that are not visible), otherwise behaviour is unpredictable.

Setting different theme for different devices

In LWUIT for Series 40, methods have been added to help developers set different themes for non-touch, touch & type and full touch.

    /**
     * Loads a theme from resource and applies it for defined device type.
     *
     * @param resRef a local reference to a resource using the syntax of
     * Class.getResourceAsStream(String)
     * @param deviceType device type as defined in Display class
     * @param themeId name of the theme resource
     */

public void loadThemeForDeviceType(String resRef, int deviceType, String themeId)

//example setting theme for full touch device
UIManager.getInstance().loadThemeForDeviceType("/theme-file.res", Display.FULL_TOUCH_DEVICE, "NameOfTheme");

//for the devices, we have flags in Display class
Display.NON_TOUCH_DEVICE;
Display.TOUCH_AND_TYPE_DEVICE;
Display.FULL_TOUCH_DEVICE;