Creating Device Property Files

Chapter 2 Creating Device Property Files

This chapter presents a simple tutorial that walks you through the procedures for creating a device property file. You will learn how to use the new device property files to enable the J2ME Wireless Toolkit to emulate applications for the device. See Chapter 3, "Examining Device Property Files” for a detailed reference on device properties, the custom-tailoring options available, and how to use them.

In the following step-by-step tutorial, you will create a device definition for a device called NewPhone. Because of the similarity of NewPhone to the DefaultColorPhone device included with the J2ME Wireless Toolkit, the tutorial adapts the existing property file for DefaultColorPhone.

The steps of the tutorial are:

Make a Copy of an Existing Main Device Property File

Obtain and Enter Image Files

Obtain and Enter the Screen Properties

Obtain and Enter the Button Properties

Obtain and Enter Soft Button Label Areas

Obtain and Enter Icon Properties

Enter Color Properties

Run the Emulator for the New Device

Make a Copy of an Existing Main Device Property File

You will create a device property file for a new emulated device called NewPhone.

The first step in creating a property file for NewPhone is to copy the directory associated with the existing device, DefaultColorPhone, to the new directory NewPhone and to rename the main property file.

Note – All directory names in this chapter refer to the installation directory of the J2ME Wireless Toolkit. (If you chose the default option at installation, the directory is C:\WTK21.)

Copy the directory wtklib\devices\DefaultColorPhone and its contents as
wtklib\devices\NewPhone.

Rename the main device property file
wtklib\devices\NewPhone\DefaultColorPhone.properties to
wtklib\devices\NewPhone\NewPhone.properties.

Obtain and Enter Image Files

You need to provide image files for the new device. These image files should differ only in their representation of the active buttons. (Active buttons are those buttons used in the emulation of the device in the J2ME Wireless Toolkit.)

The image files are:

a default image file showing the active buttons in normal unpressed position

an image file showing the active buttons in a pressed position

an image file showing the active buttons highlighted and an indicator light to indicate that backlighting is turned on the device

an image of the network indicator icon in the enabled state

These images are used by the Emulator to show visual effects when the user moves the pointer over, or clicks on, a device button. The device backlight is turned when a MIDP API is being called or when communication over the network is taking place. An image file can be in JPEG, GIF, or PNG format.

Create the image files such that the size of the device's screen in each image is the same as the pixel size of the display on the real device.

For example, if the device has a screen of 96 pixels horizontally by 128 vertically, your images should have the same size as the screen.

Insert the new image files in the NewPhone directory in place of the following files, respectively:


wtklib\devices\NewPhone\ph1_neut.png 

wtklib\devices\NewPhone\ph1_press.png 

wtklib\devices\NewPhone\ph1_highlight.png 

wtklib\devices\NewPhone\indicator.png

Change the image file names in the following lines in NewPhone.properties, if they are different from the names already present.


default_image = ph1_neut.png 

pressed_buttons_image = ph1_press.png 

highlighted_image = ph1_highlight.png

Change the indicator image locations in the following lines in NewPhone.properties, if they are different from the existing locations. The network indicator location property has the following format:


netindicator.bounds = x, y, width, height

Where x is a horizontal distance in pixels to the network’s indicator left top corner, y is a vertical distance to the network’s indicator left top corner, width is and indicator’s image width and height is an indicator image’s height. For example:


netindicator.image = indicator.png 

netindicator.bounds = 17, 82, 19, 19

Obtain and Enter the Screen Properties

By measuring the image file, obtain the screen properties:

Screen Location

Total Screen Size

Display Area

Note – In the following sections, the values entered in the device property file are assumed to be values that you have measured on the image file and are intended to be an example.

Screen Location

Referring to the left image in FIGURE 1, you specify the location of the top left corner of the screen relative to the top left corner of the device image by two lines of the form:


screen.x = <horizontal distance in pixels> 

screen.y = <vertical distance in pixels>

Enter the following measured values for the screen location in NewPhone.properties:


screen.x = 38 

screen.y = 82

Total Screen Size

Referring to the left image in FIGURE 1, you specify the total screen size by two lines of the form:


screen.width = <horizontal distance in pixels> 

screen.height = <vertical distance in pixels>

Enter the following measured values for the total screen size in NewPhone.properties:


screen.width = 96 

screen.height = 128

Display Area

Referring to the right image in FIGURE 1, the display area (or paintable region) is that part of the screen that is available to applications. The remainder of the screen is for icons and soft button labels.

The coordinates of the display area are relative to the screen location.

You can specify the display area used by the application to be a subregion of the screen by four lines of the form:


screenPaintableRegion.x = <horizontal distance to display area> 

screenPaintableRegion.y = <vertical distance to display area> 

screenPaintableRegion.width = <width of display area> 

screenPaintableRegion.height = <height of display area>

Enter the following measured values for the screen display area in NewPhone.properties.


screenPaintableRegion.x = 0 

screenPaintableRegion.y = 10 

screenPaintableRegion.width = 96 

screenPaintableRegion.height = 100

Screen and display area dimensions of a device.

FIGURE 1 – Specifying Screen Properties

Display Area in Full Screen Mode

The MIDP 2.0 specification allows applications to use the full screen area. The Default Emulator defines the coordinates for a full screen as follows:

Upper left coordinate - the upper left coordinate of the display area: (screenPaintableRegion.x, screenPaintableRegion.y).

Bottom right coordinate - the bottom right coordinate of the screen area: (screen.x+screen.width, screen.y+screen.height).

Customization of the display area will be available in future versions of the Wireless Toolkit.

Obtain and Enter the Button Properties

By measuring the image file, obtain the button properties.

A button on the emulated device is defined in the main device property file by name and screen location in the following form:


button.<button_name> = x, y, width, height

where the parameters are as follows:

button_name: One of the button names defined for the DefaultColorPhone: 0, 1, 2, 3, 4, 5, 6, 7, 8,9, POUND, ASTERISK, SEND, END, LEFT, RIGHT, UP, DOWN, SELECT, SOFT1, SOFT2 and POWER. For information about how to use additional button names, see "Device Buttons" .”

x: The x-coordinate of the left edge of the button image, in pixels relative to the left edge of the device image

y: The y-coordinate of the top edge of the button image, in pixels relative to the top edge of the device image

width: The width of the button image, in pixels

height: The height of the button image, in pixels.

The button location and dimensions are used for two purposes:

To define the active region in which a mouse click is interpreted as a button press.

To define the region of the device image that is used to show graphic effects on device buttons.

The region for each button should be defined to be large enough to cover the button's area on all three device images. However, be careful not to allow the buttons' regions to overlap each other.

The button coordinates are shown in FIGURE 2.

Height and width dimensions of a device button.

FIGURE 2 – Specifying a Button Location

Enter the following measured values for the button properties in NewPhone.properties:


button.0 = 66, 417, 41, 22 

button.1 = 21, 319, 41, 22 

button.2 = 66, 320, 41, 22 

button.3 = 110, 320, 41, 22 

button.4 = 20, 352, 41, 22 

button.5 = 65, 352, 41, 22 

button.6 = 112, 352, 41, 22 

button.7 = 21, 384, 41, 22 

button.8 = 65, 384, 41, 22 

button.9 = 111, 384, 41, 22 

 

button.POUND = 110, 417, 41, 22 

button.ASTERISK = 21, 417, 41, 22 

 

button.SEND = 25, 295, 32, 17 

button.END = 114, 295, 32, 17 

button.LEFT = 37, 254, 26, 26 

button.RIGHT = 114, 253, 23, 27 

button.UP = 69, 232, 35, 22 

button.SELECT = 65, 257, 43, 23 

button.DOWN = 70, 284, 34, 21 

 

button.UP.1 = 4, 87, 10, 18 

button.DOWN.1 = 4, 189, 10, 20 

button.SOFT1 = 29, 228, 33, 20 

button.SOFT2 = 112, 227, 32, 20 

button.POWER = 33,  52, 18, 10

Obtain and Enter Soft Button Label Areas

By measuring the image file, obtain the soft button properties.

NewPhone has two soft buttons—similar to the DefaultColorPhone. Their label areas are displayed in the area of the screen that is available to icons. This area is not directly accessible to the application. FIGURE 3 shows the soft button labels Undo and Menu on the lower part of the device screen.

Note – See Chapter 3, "Examining Device Property Files” for information on how to define devices with different numbers of soft buttons.

Pointer to soft button labels in display area and dimensions of display area.

FIGURE 3 – Soft Button Label Areas on the Emulated Device Display

A soft button label display is defined by a line of the form:


softbutton.<number> = <x>,<y>,<width>,<height>,<font>,<align>

where the parameters are defined as follows:

The coordinates of the soft button label area:

x: The x-coordinate of the left edge of the label area, in pixels relative to the left edge of the screen area

y: The y-coordinate of the top edge of the label area, in pixels relative to the top edge of the screen area

width: The width of the label, in pixels

height: The height of the label, in pixels

font: The font of the soft button label

align: The alignment of the text of the soft button label within its area: "left", "right" or "center"

Enter the following measured values for the soft button properties in NewPhone.properties:


softbutton.0=1,112,40,16, softButton, left 

softbutton.1=56,112,40,16, softButton, right

Obtain and Enter Icon Properties

An icon in the context of the Emulator is any graphic, constant or variable, that is displayed on the device screen global region (the region that is outside of the drawable area). This includes scrolling indicators, the battery level indicator and any other images of a similar type. See Appendix A, "Default Emulator Device Property Files” for a list of the icons provided with the J2ME Wireless Toolkit.

Icons are used by the J2ME Wireless Toolkit emulator to indicate the status of several operations to the user:

The left, right, up and down icons indicate the possible scrolling operations.

The inmode icon indicates the current text input mode (Capital letters, small letters or numbers).

The domain icon indicates whether the current MIDlet suite is assigned a trusted domain.

An icon is defined by:

A name. One of a fixed set of icon names. DefaultColorPhone defines the following set of icon names: left, right, up, down, inmode, internet, reception, and battery.

A screen location. This is a coordinate pair giving the location of the top left corner of the icon, in pixels relative to the top left corner of the screen area of the device's image.

A default state. The icon is initially in this state.

A mapping of state names to image files. An icon can have any number of named states, as long as it has a line in the property file for each state giving the image associated with that state. If no image file is given for a particular state then no image is displayed when the icon is in that state.

Note – Image files for icons with multiple states should be aligned with one another, enabling a smooth visual transition on a change of state.

Defining the Icon Location and States

By measuring the image file, obtain the icons properties.

The screen location and initial state of the icon is defined by a line of the form:


icon.<name> = <x_location>,<y_location>,<initial_state>

The icon states are defined by lines of the form:


icon.<name>.<state #1> = <state #1 image_filename> 

.. 

icon.<name>.<state #n> = <state #n image_filename>

If an icon does not have an image for a particular state, only the name of the icon need be given, and the image field can be left blank.

Image files can be in GIF, PNG, or JPEG format.

Enter the following measured values for the icons properties in NewPhone.properties:


icon.up: 44, 112, off 

icon.up.off: 

icon.up.on: up.gif 

 

icon.down: 44, 118, off 

icon.down.off: 

icon.down.on: down.gif 

 

icon.left: 36, 114, off 

icon.left.off: 

icon.left.on: left.gif 

 

icon.right: 52, 114, off 

icon.right.off: 

icon.right.on: right.gif 

 

icon.internet: 64, 1, off 

icon.internet.off: 

icon.internet.on: internet.gif 

 

icon.reception: 2, 1, on 

icon.reception.on: reception.gif 

 

icon.battery: 78, 2, on 

icon.battery.on: batt.gif 

 

icon.inmode: 28, 2, off

Enter Color Properties

Two properties are provided to control the color in the Emulator:

The isColor property determines whether the display is grayscale (false) or color (true).

The colorCount property controls the number of colors available (when isColor is true) or the number of shades of gray available (when isColor is false).

Enter the following measured values for the color properties in NewPhone.properties.


colorCount = 0x100 

isColor = false

Screen Background RGB Color

For a device with a grayscale screen, the background color of the screen can be set. The color is defined as a hexadecimal integer according to the standard Java color map. That is, the integer has the form RRGGBB, where RR, GG and BB are the red, green and blue components of the color, respectively. For example, white would be 0xffffff and red would be 0xff0000.

The background color is defined with the property screenBGColor.

Enter the following measured values for the screen background color properties in NewPhone.properties.


screenBGColor = 0x64b890

Run the Emulator for the New Device

The new device, NewPhone, now appears in the list of available devices in KToolbar. If you are already running these tools, you must restart the application to see the updated list of devices.

Basic Customization Guide
Java™ 2 Platform, Micro Edition, Wireless Toolkit, Version 2.1