7 Using the Style Object

The Style object sets colors, fonts, transparency, margin, padding, images, and borders to define the style for a given component. Each Component contains a selected Style Object and allows Style modification at runtime using component.getSelectedStyle() and component.getUnselectedStyle(). The style is also used in Theming (Chapter 8). When a Theme is changed, the Style objects are updated automatically.

Color

Each Component has two adjustable colors:

Foreground color	The component foreground color that usually refers to the component text color. For example, for a Button it's the text color.
Background color	The component background color.

The color specification is RGB. There is no alpha channel within the color (the background transparency is separate).

Valid values are integers ranging from 0x000000 to 0xffffff (black to white respectively) or a decimal number.

Font

Fonts are set with the Font object (see the Font API in the API documentation located in install-dir/docs/api/lwuit. Lightweight UI Toolkit supports both for Bitmap fonts and for system fonts, similar to common MIDP fonts. Fonts are discussed in Chapter 9.

Transparency

Lightweight UI Toolkit style supports background component transparency, to add flexibility and appeal to the UI. To set a component transparency level, call setBgTransparency and specify an integer or a byte. The integer value must range between 0 to 255, where 255 (the default) is opaque.

Margin and Padding

Margin and Padding are inspired by the CSS Box Model. Each component has a main content area (for example, text or icon) and optional surrounding padding and margin areas. The size of each area is specified by four integers that represent the top, bottom, left and right space (similar to component Insets terminology in SWING). The following diagram shows the placement of the areas in relation to the component content area:

Figure 7-1 Padding and Margin Relationships

Description of "Figure 7-1 Padding and Margin Relationships"

Padding and margins can be set as follows:

// Setting padding with positive values
setPadding(int top, int bottom, int left, int right)
 
// orientation can be Component.TOP, BOTTOM, LEFT or RIGHT
setPadding(int orientation, int gap)
 
// Setting margin with positive values
setMargin(int top, int bottom, int left, int right)
 
// orientation can be Component.TOP, BOTTOM, LEFT or RIGHT
setMargin(int orientation, int gap)

Images

In Style, Images refer to a component background image. By default components do not have a background image, so the bgImage parameter is null by default. For more details about images, please refer to Chapter 9.

Borders

The Style object supports defining custom rendering of a border. There are several default built-in border types (see the Javadoc™ of the Border class). Borders can either replace the background painter (as is the case with round borders and sometimes with image borders) or they can be rendered after the component itself is rendered. A custom border can be built by deriving the Border class and overriding the appropriate methods.

A border is rendered into the padding area of the component so it is important that the component padding is large enough to contain the border drawing.

Bevel

The bevel border type presents a simple 3D style border that can appear lowered or raised, providing simple depth perception for actions such as button presses.

Figure 7-2 Bevel Lowered Border

Description of "Figure 7-2 Bevel Lowered Border"

Figure 7-3 Bevel Raised Border

Description of "Figure 7-3 Bevel Raised Border"

Etched

The etched border type provides a look similar to an engraved line. Like the bevel border, it too can appear raised or lowered.

Figure 7-4 Etched Lowered Border

Description of "Figure 7-4 Etched Lowered Border"

Figure 7-5 Etched Raised Border

Description of "Figure 7-5 Etched Raised Border"

Line

The line border just draws a rectangle around the component with the option of defining the thickness and color of the rectangle.

Round

The round border draws a rounded rectangle and optionally fills the background appropriately.

PERFORMANCE WARNING:

The round border might be very expensive! A round border is cheap for a completely opaque solid color. However, when using features such as gradients, images or alpha channel the round border effect is calculated on the fly! This is computationally expensive. We recommend trying to achieve these same effects with image borders which are cheaper.

The round border supports defining its color (or using the theme color) and defining the size of the arcs rounding the border.

Figure 7-6 Round Border

Description of "Figure 7-6 Round Border"

Image

The image border option will only appear when images exist in the resource file, you can read more on creating image borders in the image border wizard. Image borders come in 4 flavors:

9 Part

Uses 9 or 8 images to represent the border for the component. The structure is as shown in Figure 7-7:

Figure 7-7 9-Part Image Border

Description of "Figure 7-7 9-Part Image Border"

Notice that the center image is optional. The top, bottom, left and right images are tiled while the corners (Top Left, Top Right, Bottom Left, and Bottom Right) are kept in place. The center image (if defined) is also tiled. This allows LWUIT to resize the component without any scaling, degradation, performance cost, or memory overhead.

Remember that drawing an image is an expensive operation, so images in the image border shouldn't be too small. For example, a common designer mistake is to produce a single pixel image for tiling. LWUIT seamlessly crops tiled images, so you should make an effort to make images a reasonable size (when in doubt use something in the area of 80-100 pixels).

3 Part

The 3 Part is somewhat unique to LWUIT and relies on MIDP's fast rotation drawing. It assumes perfectly rectangular images and draws the top left image rotated to produce all corners and does the same for the top image (center is again optional and used as usual). Thus the 3 part border can produce some attractive results in a smaller size.

Horizontal/Vertical

The image border is highly biased to symmetric shapes that can be enlarged to all directions. However, some shapes (such as the iPhone's angular back button) cannot be cut into a 9-patch image without causing artifacts.

The Horizontal and Vertical Image borders accept 3 images each and only grow on one axis. We don't recommend using them freely, even when text (which can vary wildly in size) isn't used, one often needs to align to text which requires resizing.

Style Listener

The Style listener gives you the ability to track changes in a certain component style object. For example you might want to monitor changes in the background color of a component, and react accordingly.

The following code shows how to add a listener and track any style property change to the Font.

myComponent.getStyle().addStyleListener(new StyleListener() {
   public void styleChanged(String propertyName, Style source) {
      if (propertyName.equals(Style.FONT)) {
         System.out.println("Font of myComponent got changed.");
      }
   }
});

Painters

Painters in Style refers to the component's background drawing. The Painter draws itself and then the component draws itself on top. For more information please refer to Chapter 10.

To set a painter, use the setBgPainter method. For example to set myPainter as the component background painter, write:

mycomponent.getStyle().setBgPainter(myPainter);