Resource File Specification

version 1.3

This specification is part of the Java DTV specification and documents the format of the Resource File as required by the com.sun.dtv.lwuit.util.Resources class.

Version 1.0	Initial Version as for Java DTV 1.0
Version 1.1	Maintenance Version as for Java DTV 1.1
Version 1.2	Maintenance Version as for Java DTV 1.2.1
Version 1.3	Maintenance Version as for Java DTV 1.3

U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Sun, Sun Microsystems, the Sun logo and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.Products covered by and information contained in this service manual are controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited.

DOCUMENTATION IS PROVIDED AS IS AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

Content

1Resources

The resource file is comprised of chunks, each chunk type is described below. The first chunk in the resource file MUST be the header chunk type which describes the resource file.

Notice that while the resource files allow room for meta-data to be stored within, it is advised to make very limited use of such facilities to avoid size increases and exposure of information. The resource files are designed for shipping with an application and thus should remain compact with only the meta-data required by the end user remaining within the application.

Resource files are designed for reading/writing using Java based tools and are designed around the DataInputStream/DataOutputStream architecture. This implies several things regarding the specification and the file format:

UTF elements in the specification refer to the readUTF/writeUTF methods of DataInputStream and not to C style UTF null terminated strings.
The file uses big endian to represent all types
Color encoding uses ARGB model

1.1General Format

What	Type	Size (Byte)	Iteration factor
Magic identifier “LWUITRF\0”	BYTE[]	8
Number of Chunks > 1	SHORT	2
Chunks, first chunk must be of type header		individual	For any resource

1.2Chunks

What	Type	Size (Byte)	Iteration factor
Type of Resource - Theme: 0xF2 - L10N: 0xF9 - Data: 0xFA - Font: 0xFC - Image: 0xFD - Header: 0xFF	BYTE	1
Resource name	UTF	individual
Resource data	See Respective Chapter	individual

2Header

The header must be the first chunk of the file allowing tools and the application to identify details about the resource file and provide tools for future extensibility.

The current version of the specification has major version 1 and minor version 3.

What	Type	Size (Byte)	Iteration factor
Header Size	SHORT	2
Major Version	SHORT	2
Minor Version	SHORT	2
Meta data count	SHORT	2
Meta data Strings	UTF[]	Meta data count * individual

3Theme Chunk

Themes are a set of key value pairs where the key represents a well known string using the format of [ComponentUIID.]attribute. The ComponentUIID names are user defined, the attributes however are well known and determine the type of value stored in the resource file.

The following attribute mapping applies to the theme:

Attribute	Type
fgColor, bgColor, fgSelectionColor, bgSelectionColor	Color
font	Font
padding, margin	Spacing
transparency	Transparency
Background, selectionBackground	Background
border	Border

3.1Theme Resource Structure

What	Type	Size (Byte)	Iteration factor
Number of Properties	SHORT	2
Property Pair	See 3.2	individual	For any property

3.2Theme Property Pair

What	Type	Size (Byte)	Iteration factor
Property Key	UTF	individual
Property Value	See Respective Sub-Chapter of 3.3	individual

3.3Theme Property Values

3.3.1Theme Property Value: COLOR

The alpha component of the color is ignored regardless of its value

What	Type	Size (Byte)	Iteration factor
Color value	INT	4

3.3.2Theme Property Value: TRANSPARENCY

Represents alpha transparency value between 0x00 - 0xff

What	Type	Size (Byte)	Iteration factor
Transparency value	BYTE	1

3.3.3Theme Property Value: SPACING

What	Type	Size (Byte)	Iteration factor
Top Spacing	BYTE	1
Bottom Spacing	BYTE	1
Left Spacing	BYTE	1
Right Spacing	BYTE	1

3.3.4Theme Property Value: FONT

References a font chunk by name

What	Type	Size (Byte)	Iteration factor
Is new font	BOOLEAN	1
Font name	UTF	Individual	Only if new font = true
Font face	BYTE	1	Only if new font = false
Font style	BYTE	1	Only if new font = false
Font size	BYTE	1	Only if new font = false

3.3.5Theme Property Value: BACKGROUND

Represents the background drawing for a component, image behavior, gradient etc.

Radial gradients have a center position for the core of the radial effect, this center is determined relatively using the relative x/relative y variables. These variables are in the range of 0 .0 to 1.0 and they represent the position within the component relatively to its size, where 0.5/0.5 is the exact center of the component. The radial gradient will be drawn exactly in that range.

What	Type	Size (Byte)	Iteration factor
Type Scaled Image: 0xF1 Tiled Vertically Image: 0xF2 Tiled Horizontally Image: 0xF3 Tiled Both Image: 0xF4 Aligned Image 0xF5 Horizontal Linear Gradient: 0xF6 Vertical Linear Gradient: 0xF7 Radial Gradient: 0xF8	BYTE	1
Image	UTF (Image Reference id)	individual	Only for an image related type 0xf1-0xf5
Alignment Top: 0xf1 Bottom: 0xf2 Center: 0xf3 Left: 0xf4 Right: 0xf5	BYTE	1	Only for tiled vertically/horizontally & aligned images.
Start Color	INT	4	Only for gradient types
End Color	INT	4	Only for gradient types
Relative X	FLOAT	4	Only for gradient types
Relative Y	FLOAT	4	Only for gradient types
Relative Size	FLOAT	4	Only for gradient types

3.3.6Theme Property Value: BORDER

The border property allows the definition of a component border, corresponding to the behavior of the LWUIT Border class. This includes some built in border types which can be augmented in future LWUIT releases.

Every border type has a different set of variables to indicate its appearance.

Some borders support user determined colors as an option, the border can receive a flag indicating whether the color be extracted from the theme or should be specified specifically for this border instance.

3.3.6.1BORDER Structure

What

Type

Size (Byte)

Iteration factor

Border Type:

None: 0xff01

Line: 0xff02

Rounded: 0xff03

Etched Lowered: 0xff04

Etched Raised: 0xff05

Bevel Lowered: 0xff06

Bevel Raised: 0xff07

Image: 0xff08

SHORT

Data

Border Data

Individual (no content in the case of border “None”)

3.3.6.2BORDER Data: Line

What	Type	Size (Byte)	Iteration factor
Theme Colors	BOOLEAN	1
Thickness	BYTE	1
Color	INT	4	Only if theme color is false

3.3.6.3BORDER Data: Rounded

What	Type	Size (Byte)	Iteration factor
Theme Colors	BOOLEAN	1
Arc width	BYTE	1
Arc height	BYTE	1
Color	INT	4	Only if theme color is false

3.3.6.4BORDER Data: Etched Lowered/Raised

What	Type	Size (Byte)	Iteration factor
Theme Colors	BOOLEAN	1
Highlight Color	INT	4	Only if theme color is false
Shadow Color	INT	4	Only if theme color is false

3.3.6.5BORDER Data: Bevel Lowered/Raised

What	Type	Size (Byte)	Iteration factor
Theme Colors	BOOLEAN	1
Highlight Outer Color	INT	4	Only if theme color is false
Highlight Inner Color	INT	4	Only if theme color is false
Shadow Outer Color	INT	4	Only if theme color is false
Shadow Inner Color	INT	4	Only if theme color is false

3.3.6.6BORDER Data: Image

An image border supports two patterns 9 images or 3 images, the last of those images may be null hence the border can also support 2 or 8 images.

What	Type	Size (Byte)	Iteration factor
Image Count	BYTE	1
Images	UTF (Reference to Image Chunk)	Individual * Image Count

4Image Chunk

An image resource also represents a simple animation within the resource file. There are several different image types supported within the image chunk:

4.1Image Types

What

Type

Size (Byte)

Iteration factor

Image Type

PNG: 0xf1

JPEG: 0xf2

Indexed: 0xf3

Animation: 0xf4

SVG: 0xf5

BYTE

Image

individual

4.2Image PNG/JPEG

What	Type	Size (Byte)	Iteration factor
Length of image data	INT	4
Image data		individual

4.3Image Indexed

Indexed images are bitmaps based on a palette lookup value

What	Type	Size (Byte)	Iteration factor
Color palette size	BYTE	1
Color	INT[]	4	For any color in palette (0 indicates 256 colors!)
Image width	SHORT	2
Image height	SHORT	2
Color value per image pixel	BYTE	1	For any pixel of the image

4.4Image Animation

What	Type	Size (Byte)	Iteration factor
Color Palette Size	BYTE	1
Color	INT[]	4	For any color in palette (0 indicates 256 colors!)
Animation Width	SHORT	2
Animation Height	SHORT	2
Number of Animation Frames	BYTE	1
Total Animation Time	INT	4
Animation Loop indicator	BOOLEAN	1
Animation Frame Data	See 4.4.1	Individual	For any frame of the animation

4.4.1Animation Frame Data

Animation Frame Data represents a frame within the animation, the number of frames depends on the complexity of the animation. Frames should be read one by one with a special case for the first frame which is always just a bitmap.

What	Type	Size (Byte)	Iteration factor
First Frame	First Frame	Individual	1
Frame	Frame	Individual	Number of Animation Frames - 1

4.4.2First Frame

The first frame of an animation is always a key frame and does not need a time stamp. It is a palette bitmap of the first image within the animation.

What	Type	Size (Byte)	Iteration factor
Color Palette Index	BYTE[]	1	Animation Width * Animation height

4.4.3Frame

The key frame paints the entire animation, it is a bitmap and is thus expensive in memory/storage.

What	Type	Size (Byte)	Iteration factor
Time Stamp	INT	4
KeyFrame Indicator	BOOLEAN	1
KeyFrame (palette indexes)	BYTE[]	Animation Width * Animation height	Only if KeyFrame Indicator is true.
Previous Frame Drawing	BOOLEAN	1	Only if KeyFrame Indicator is false
Changed Rows	Changed Rows	individual	Only if KeyFrame Indicator is false

4.4.4Changed Rows

What	Type	Size (Byte)	Iteration factor
Row Offset	SHORT	2	Iterate over rows until row offset is -1
Row Data (palette indexes)	BYTE[]	Animation Width

4.5Image SVG

An SVG image can be rendered on devices that have built-in SVG image support, when no such support is available the fallback image is shown. Implementations that aren't targeted for non-SVG environments can set the fallback length to 0. A fallback has a width/height floating point ratio representing the ratio of the SVG fallback image to the screen size. This ratio allows tools to adapt the resource file for multiple screen resolutions while preserving a relative image ratio.

The base URL is used to lookup resources required by the SVG parser, if the URL is an empty string the implementation can look within the resource file itself or the classpath.

Notice that the fallback image data can be 0 indicating no fallback image.

What	Type	Size (Byte)	Iteration factor
Length of SVG File	INT	4
SVG data	BYTE[]	individual
Base URL	UTF	individual
Animated	BOOLEAN	1
Fallback Width	FLOAT	4
Fallback Height	FLOAT	4
Length of fallback image data	INT	4
Fallback Image data	BYTE[]	individual

5Font Chunk

A font contains a set of fallback optional values ordered by priority always ending with a system font definition. If a platform doesn't or shouldn't support a given font type it moves to the next available font in the chain.

There are 4 font types some of which might not be supported on a given platform. The only required font type is the system font which must work correctly for all platforms/character encodings and serves as a fallback:

System Font – Defines a font based on a few lowest common denominator attributes that would work on all devices.
Bitmap Font – Represents a bitmap and charset mapping to allow drawing the font in some platforms that don't support TrueType fonts or a lookup table.
TrueType – Supports embedding a true type font file into the resource file
Lookup – A string representing a font using a platform specific font lookup syntax e.g. Arial-Bold-16. This is a comma separated set of strings which allows LWUIT to try various strings based on font platform availability

Fonts are loaded as a fallback chain where each one of the font types is stored in order of quality, the first font that is stored in the file and supported by the platform will be used. The order of font storage/picking is:

TrueType font
Lookup
Bitmap
System

5.1Structure

What	Type	Size (Byte)	Iteration factor
systemFontFallback Bitwise value: - MONOSPACE : 32 - PROPORATIONAL : 64 - SYSTEM : 0 - BOLD: 1 - ITALIC: 2 - PLAIN: 0 - LARGE: 16 - SMALL: 8 - MEDIUM: 0	BYTE	1
isTrueTypeFontIncluded	BOOLEAN	1
TrueType size	INT	4	Only if the TrueType font is included
TrueType data	BYTE[]	TrueType size	Only if the TrueType font is included
isLookupIncluded	BOOLEAN	1
Lookup font name	UTF		Only if the lookup font is included
isBitmapIncluded	BOOLEAN	1
Image	Image (see theme image section)	Individual	Only if the Bitmap font is included
Character Count	SHORT	2	Only if the Bitmap font is included
Cut Offsets	SHORT	Character Count	Only if the Bitmap font is included
Char Widths	BYTE	Character Count	Only if the Bitmap font is included
Charset	UTF	Individual	Only if the Bitmap font is included
Rendering Hint	BYTE	1	Only if the Bitmap font is included

5.2Font Instance

The fonts in the table are organized by platform which represents a descriptive set of names to identify a specific platform, e.g. MIDP, PBP, RIM etc. The default platform fallback will have a 0 length String and would be attempted if no other platform string matches. Platforms would organize by priority, e.g. when running on a RIM device the RIM platform would be searched first, then the MIDP platform.

Platform names are subject to change and extensions as new LWUIT platforms are added. A platform name must only include alpha numeric characters ([A-Z][a-z][0-9]) and is treated as case insensitive. Platform names may be comma delimited to associate a single font with multiple platforms.

What	Type	Size (Byte)	Iteration factor
Default System Font	Font System	1
Table Size	BYTE	1
Platform	UTF	Individual for every table element (table size)
Font	UTF	Individual for every table element (table size)

A sample table can look like this:

System Font: BOLD

Table Size: 3

Platform: “RIM,MIDP”

Font: Bitmap Font (binary data)

Platform: “PBP”

Font: “Arial-Bold-14”

Platform: “HDTV”

Font: “Arial-Bold-30”

Since the table should be processed by priority a TV platform should pick the 30 pixel font rather than the 14 pixel font which should also be appropriate for PBP platforms. MIDP/RIM platforms can just ignore that font altogether.

Notice that the system font is the default and is always required as a valid fallback for all platforms.

5.2.1.1Font Instance: System

What

Type

Size (Byte)

Iteration factor

Bitwise value:

- MONOSPACE : 32

- PROPORATIONAL : 64

- SYSTEM : 0

- BOLD: 1

- ITALIC: 2

- PLAIN: 0
- LARGE: 16

- SMALL: 8

- MEDIUM: 0

BYTE

5.2.1.2Font instance: Bitmap

The bitmap font is essentially a horizontal PNG image with cutoff points, it is painted as shades of red that are manipulated by the font rendering code.

The font has a generating font property that allows editor tools to regenerate the font using the given font name/size/style information encoded within that string.

What	Type	Size (Byte)	Iteration factor
Image	Image (see theme image section)	Individual
Character Count	SHORT	2
Cut Offsets	SHORT	2 * Character Count
Char Widths	BYTE	Character Count
Charset	UTF	Individual
Rendering Hint	BYTE	1
Generating Font	UTF	Individual

5.2.1.3Font instance: TrueType

What	Type	Size (Byte)	Iteration factor
Size	INT	4
File	BYTE[]	Individual

5.2.1.4Font instance: Lookup

What	Type	Size (Byte)	Iteration factor
Lookup	UTF	Individual

6L10N Chunk

6.1L10N Resource

What	Type	Size (Byte)	Iteration factor
Number of L10N Property Keys	SHORT	2
Number of L10N Languages	SHORT	2
L10N Property Key	UTF	Individual	For any L10N property
L10N Property Values	See 6.2	Individual	For any L10N language

6.2L10N Property Values

What	Type	Size (Byte)	Iteration factor
L10N Language	UTF	Individual
L10N Property Value for this language	UTF	Individual	For any L10N Property

7Data Chunk

7.1Data Resource

What	Type	Size (Byte)	Iteration factor
Data Length	INT	4
Data		Individual