C H A P T E R 3 - Customizing the skin.xml File

C H A P T E R 3

Customizing the skin.xml File

The Java Wireless Client software Adaptive User Interface Technology default skin is customized by modifying the contents of the skin.xml file and assigning new values to the property settings defined there. The skin.xml file gets its property definitions from the adaptive user interface reference file, skin_constants.xml.

For more information about the skin.xml file and its relationship to the skin_constants.xml file, see Chapter 2.

The Java Wireless Client software adaptive user interface default skin is made up of eighteen different graphical components. These graphical components are separated into the following groups:

System components

System widgets

Each graphical component is composed of a number of unique property settings, each of which is defined in the skin_constants.xml file. The values for these property settings are assigned in the skin.xml file. For a complete list of adaptive user interface graphical components, their property settings, and the values assigned to them, see Chapter 4.

The property settings used to define a graphical component in the skin_constants.xml file has a value assigned to it in the skin.xml file. All property settings in the skin.xml file are grouped into one of six property types. Once you understand how these property types are structured and modified, it is easy to assign unique values to them to customize your own adaptive user interface skin.

This chapter describes the six kinds of property definitions used in the skin.xml file. For more information, see Property Definitions.

Property Definitions

The adaptive user interface uses the following six kinds of property definitions in the skin.xml file:

integer. The value assigned to integer is a number.

integer_seq. The value assigned is a sequence of comma-separated integers (numbers).

font. The value assigned is the name of a font identifier defined in the Java class library FontResources.

For a complete list of font identifiers, see Appendix A.

string. The value assigned is a string of text (for example, this can be a letter, a word, a phrase, or several sentences).

image. The value assigned is an image file, without an extension (for example, without .png or .raw).

For more information on images and file extensions, see Chapter 2.

composite_image. The value assigned is not a single image file, but a collection of image files corresponding to some part of the skin.

The remainder of this chapter provides an explanation of these property definitions and examples of how they are used.

Defining Integer Properties

The following two kinds of integer properties are defined in the skin.xml file:

integer

integer_seq (integer sequence)

`integer` Property

The integer property setting defines a number assigned in your adaptive user interface. This number can be a single digit, such as the number of pixels defined for padding in a form (2), or a hexidecimal number with several characters, such as a color specification (0x000000). An integer property can also be a Java programming language constant, as defined in one of the Java Wireless Client software source files.

For example, the property setting, SCREEN_BORDER_STYLE (defined in the skin_constants.xml file as part of the Screen component) is defined in the skin.xml file as an Integer, as shown in CODE EXAMPLE 3-1.

CODE EXAMPLE 3-1 Integer Property Definition With Java Platform Constant

____________________________________________________________

<integer

Key="SCREEN_BORDER_STYLE"

Value="Graphics.SOLID"/>

____________________________________________________________

The Value assigned to the Key in CODE EXAMPLE 3-1 is Graphics.SOLID, a Java programming language constant. When the Java Wireless Client software implementation is built, the elements defined by this constant are included in the skin.

In CODE EXAMPLE 3-2, the property setting SCREEN_COLOR_FG is assigned the value 0x000000, a hexidecimal number designating the color black.

CODE EXAMPLE 3-2 Integer Property Definition With Screen Color

____________________________________________________________

<integer

Key="SCREEN_COLOR_BG"

Value="0x000000"/>

____________________________________________________________

As shown in CODE EXAMPLE 3-2, the integer property is commonly used to define color in an adaptive user interface skin.

`integer_seq` Property

The integer_seq (integer sequence) property setting defines not just one integer, but a sequence of integers (or Java platform constant names specified in a Java programming language source file) that define an action or state of a component in the skin.

For example, a Busy Cursor component may define a sequence of frames to be displayed to indicate a specific state of the cursor. Or an Update Bar may define a sequence of frames to show the state of the bar as an update takes place, as shown in CODE EXAMPLE 3-3.

CODE EXAMPLE 3-3 Integer Sequence Property Definition, with Update Bar Frames

____________________________________________________________

<integer_seq

Key="UPDATE_FRAME_SEQU"

Value="1,2,3,4,5,6,5,4,3,2"/>

____________________________________________________________

As shown in CODE EXAMPLE 3-3, the Value assigned to this integer sequence property setting defines the number and sequence of the frames used in the Update Bar component. You can include an unlimited number of integers in an integer sequence property setting Value list.

Java platform constants can also be assigned as values in an integer sequence property setting as shown in CODE EXAMPLE 3-4.

CODE EXAMPLE 3-4 Integer Sequence Property Definition With Java Platform Constants

____________________________________________________________

<integer_seq

Key="SOFTBTN_BUTTON_ALIGN_X"

Value="Graphics.LEFT,Graphics.RIGHT"/>

____________________________________________________________

The Value assigned to the Key in CODE EXAMPLE 3-4 is Graphics.LEFT,Graphics.RIGHT. When the Java Wireless Client software implementation is built, the elements defined by these constants are included in the adaptive user interface skin.

Defining Font Properties

The Font property setting assigns a font identifier used for a graphical component element. This font identifier is defined by the Java programming language class FontResources.

For example, in CODE EXAMPLE 3-5, the font identifier is FontResources.PROP_P_M, which defines a proportional font (PROP) with a plain style (P) and medium size (M). As more than one type of font that fits this designation (for example, Times and Palatino are both proportional fonts) the decision as to which one is used is determined by the FontResources class.

CODE EXAMPLE 3-5 Font Property Definition

____________________________________________________________

<font

Key="SCREEN_FONT_LABEL"

Value="FontResources.PROP_P_M"/>

____________________________________________________________

Defining String Properties

The string property setting assigns a text string to a graphical component. For example, CODE EXAMPLE 3-6 shows the value assigned to the title of an Information Alert screen, ALERT_TEXT_TITLE_INFO, in the Alert system component.

The Value assigned in CODE EXAMPLE 3-6 is a text string that defines the title of the Alert (Information).

CODE EXAMPLE 3-6 String Property Definition

____________________________________________________________

<string

	Key="ALERT_TEXT_TITLE_INFO"

	Value="Information"/>

____________________________________________________________

As text needs to be displayed on screen, a specific font style and setting is needed to render this display. In the Alert system component, a font is assigned to the Alert title using the ALERT_FONT_TITLE property setting.

Defining Graphic Image Properties

The following two kinds of graphic image properties are defined in the skin.xml file:

image

composite_image

`image` Property

The image property setting defines a single image used in your adaptive user interface. For example, the skin.xml file contains an image definition for the property setting, SCREEN_IMAGE_BG (defined in the skin_constants.xml file as part of the Screen component), as shown in CODE EXAMPLE 3-7.

CODE EXAMPLE 3-7 Image Property Definition

____________________________________________________________

<image

Key="SCREEN_IMAGE_BG"

Value="screen.image_bg"

Romized="false"/>

____________________________________________________________

In CODE EXAMPLE 3-7, the Key is set to SCREEN_IMAGE_BG and the Value setting is assigned to the default graphic image file screen.image_bg.

Note - In the image and composite_image property settings, if the Value field is set as Value="" (that is, with no value assignment), the system reads it as null. This enables the skin designer to set the background color using a background color setting instead of an image.

The Romized property setting is a declaration that allows the adaptive user interface designer to make choices as to whether graphic images should load faster by being ROMized (true) or use less memory by not being ROMized (false). For more information on ROMizing graphic images, see Chapter 2.

`composite_image` Property

The composite_image property setting defines not just one image, but a number of images that correspond to some part of the skin. For example, a tiled background image designed to scale to more than one type of device may require as many as nine separate images to make the background appear correctly on screen.

In a composite image, the graphic files used to create the overall image are named using a defined pattern, as shown in CODE EXAMPLE 3-8.

CODE EXAMPLE 3-8 Composite Image Property Definition in skin_constants.xml

____________________________________________________________

<constant Type="int"

Name="ALERT_IMAGE_BG"

Comment="A 9-piece background to use for an Alert.

Piece 0: Top left corner of the tope-bar.

Piece 1: Middle tile for the top-bar.

Piece 2: Top right corner of the top-bar

Piece 3: Left edge of the middle bar.

Piece 4: Middle tile for the middle-bar.

Piece 5: Right edge of the middle-bar.

Piece 6: Bottom left corner of the bottom-bar.

Piece 7: Middle tile for the bottom-bar.

Piece 8: Bottom right corner of the bottom-bar

The top-bar is the area where the Alert icon and

title are drawn. If there is no Alert title, the

top-bar may be very short, and serves to visually

cap the top of the Alert.

The middle-bar is the background `tile' for a row

of the middle of the Alert. It will be repeatedly

drawn vertically to accommodate the height of the

Alert.

The bottom-bar is the bottom border of the Alert

and serves to visually cap the bottom of the Alert.

All three bars are divided into three pieces, a

left, a middle, and a right. If the combined widths

of the left, middle, and right images is less than

the overall width of the Alert, the middle image

will be tiled horizontally to make up the

difference.

If the file names aren't specified or cannot be

loaded, solid fill color is used instead of the

image background./>

____________________________________________________________

A composite image is defined in the skin.xml file using the following XML property setting, as shown in CODE EXAMPLE 3-9.

CODE EXAMPLE 3-9 Composite Image Property Definition in skin.xml

____________________________________________________________

<composite_image

	Key="ALERT_IMAGE_BG"

	Value="alert.image_bg"

	 Pieces="9"

	Romized="false"/>

____________________________________________________________

In CODE EXAMPLE 3-9, the Key is set to ALERT_IMAGE_BG, and the Pieces setting indicates that nine graphic files are used to create this one composite background image for the Alert adaptive user interface component.

All composite_image property definitions use the same graphic file naming scheme as shown in CODE EXAMPLE 3-9. That is, the top left corner of the top-bar is file 0 and the remaining files are numbered left to right, in sequence from there:

alert.image_bg0

alert.image_bg1

alert.image_bg2

alert.image_bg3

alert.image_bg4

alert.image_bg5

alert.image_bg6

alert.image_bg7

alert.image_bg8

You must number the graphic images yourself when you create them. Once created, the numbered graphic image files for the composite image in your customized adaptive user interface skin must be placed in the default graphics directory of your Java Wireless Client software implementation.

Assigning Graphic Images Without File Extensions

When assigning graphic image files as values in the property settings of the skin.xml file, it is important that you do not include the .png or .raw file extension when the file is defined. The adaptive user interface adds the file extension for you, by attaching it to the filename defined in the Value property setting, as shown in CODE EXAMPLE 3-10.

CODE EXAMPLE 3-10 Image File Definition Without File Extension

____________________________________________________________

<image

	Key="SCROLL_IMAGE_UP"

	 Value="scroll.image_up"

	Romized="true"/>

____________________________________________________________

If the graphic image specified in the Value setting is a PNG file and the property Romized="true" is also set, as shown in CODE EXAMPLE 3-10, at build time the SkinRomizationTool takes the following steps:

1. Adds a .png extension to the image file.

2. Converts the image into RAW format.

3. ROMizes the image.

For example, in CODE EXAMPLE 3-10, it looks for scroll.image_up.png.

Note - Only PNG files are ROMized at build time by the SkinRomizationTool.

If the graphic image is not ROMized (Romized="false"), then at runtime the Java Wireless Client software determines the image type by adding a file suffix to the image file, in the following sequence:

1. Adds a .png extension and, if it is a PNG file, loads the file

2. If the image is not a PNG file, the Java Wireless Client adds a .raw extension to the image and loads the file

At runtime, both PNG and RAW format graphic files can be loaded by the Java Wireless Client software, using the sequence shown previously. As shown in CODE EXAMPLE 3-10, the Java Wireless Client software attempts first to load scroll.image_up.png and then to load scroll.image_up.raw.

Note - Leaving the file extension off a graphic image file is only done when defining the file name in the Value setting of the skin.xml file. Graphic images must have the file extension attached when stored in the default image directory, src/highlevelui/lcdlf/lfjava/resource/skin.

Attaching a file extension to the name of the image file defined in the Value setting of an image property in the skin.xml file can cause the loading process to break.

Property Definitions

Defining Integer Properties

integer Property

integer_seq Property

Defining Font Properties

Defining String Properties

Defining Graphic Image Properties

image Property

composite_image Property

Assigning Graphic Images Without File Extensions

`integer` Property

`integer_seq` Property

`image` Property

`composite_image` Property