Sun Microsystems Computer Accessories User Manual

Basic Customization Guide

Wireless Toolkit, Version 2.1

Java

2 Platform, Micro Edition

Sun Microsystems, Inc. 4159 Network Circle Santa Clara, CA 95054 U.S.A. 650-960-1300

December 2003

Sun Microsystems,Inc. hasintellectual property rightsrelating totechnology embodiedin theproduct that is described in this document. Inparticular,and withoutlimitation, theseintellectual property rightsmay includeone ormore ofthe U.S.patents listed at http://www.sun.com/patentsand oneor moreadditional patentsor pendingpatent applicationsin theU.S. andin other countries.

U.S. GovernmentRights -Commercial software. Governmentusers aresubject tothe SunMicrosystems, Inc. standardlicense agreement andapplicable provisions ofthe FAR and its supplements.

Sun, SunMicrosystems, theSun logo,Java, Solaris,Sun[tm] ONEStudio, Java2 Platform,Micro Edition, Wireless Toolkit,J2SE, JDK, and theJava CoffeeCup logoare trademarks or registered trademarksof SunMicrosystems, Inc. in the U.S. and other countries.

UNIX isa registered trademarkin theU.S. andother countries,exclusively licensedthrough X/OpenCompany, Ltd.

The Adobe®logo isa registered trademarkof AdobeSystems, Incorporated.

Products covered byand informationcontained inthis servicemanual are controlled byU.S. ExportControl lawsand may be subject to theexport orimport lawsin othercountries. Nuclear, missile, chemical biological weapons or nuclear maritime enduses or end users, whetherdirect orindirect, are strictlyprohibited. Exportor reexport tocountries subjectto U.S.embargo orto entities identiﬁed onU.S. exportexclusion lists,including, butnot limitedto, thedenied personsand speciallydesignated nationalslists is strictly prohibited.

DOCUMENTATIONIS PROVIDED"AS IS"AND ALLEXPRESS ORIMPLIED CONDITIONS,REPRESENTATIONSAND WARRANTIES, INCLUDINGANY IMPLIEDWARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULARPURPOSE OR NON-INFRINGEMENT,ARE DISCLAIMED,EXCEPT TOTHE EXTENTTHATSUCH DISCLAIMERSARE HELD TO BE LEGALLY INVALID.

Sun Microsystems,Inc. ales droits depropriété intellectuelsrelatants à la technologie incorporée dans le produit quiest décritdans ce document.En particulier, et sans la limitation, ces droitsde propriétéintellectuels peuventinclure un ou plus des brevets américains énumérésà http://www.sun.com/patentset unou lesbrevets plussupplémentaires ou les applications de brevet en attentedans lesEtats -Unis etdans lesautres pays.

Sun, SunMicrosystems, lelogo Sun,Java, Solaris,Sun[tm] ONEStudio, Java2 Platform,Micro Edition, Wireless Toolkit,J2SE, JDKet le logoJava CoffeeCup sontdes marques defabrique oudes marquesdéposées deSun Microsystems, Inc.aux Etats-Uniset dans d’autres pays.

UNIX estune marquedéposée auxEtats-Unis etdans d’autres payset licenciéeexlusivement parX/Open Company, Ltd.

Le logoAdobe® estune marquedéposée deAdobe Systems,Incorporated.

Les produitsqui fontl’objet dece manueld’entretien et les informations qu’il contient sont régis par la législation américaine en matière decontrôle desexportations etpeuvent être soumisau droitd’autres paysdans le domaine des exportations et importations. Les utilisationsﬁnales, ouutilisateurs ﬁnaux,pour desarmes nucléaires,des missiles,des armesbiologiques etchimiques oudu nucléaire maritime,directement ou indirectement,sont strictementinterdites. Lesexportations ouréexportations versdes payssous embargo desÉtats-Unis, ouvers desentités ﬁgurantsur leslistes d’exclusiond’exportation américaines,y compris,mais demanière non exclusive, la liste depersonnes quifont objetd’un ordre dene pasparticiper,d’une façondirecte ou indirecte,aux exportations des produitsou desservices quisont régipar lalégislation américaineen matière decontrôle desexportations etla listede ressortissants spéciﬁquementdésignés, sontrigoureusement interdites.

LA DOCUMENTATION ESTFOURNIE "ENL’ÉTAT" ET TOUTESAUTRES CONDITIONS,DECLARATIONSET GARANTIES EXPRESSES OUTACITESSONT FORMELLEMENTEXCLUES, DANSLA MESUREAUTORISEE PARLA LOIAPPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIEIMPLICITE RELATIVE A LA QUALITE MARCHANDE, A L’APTITUDE AUNE UTILISATIONPARTICULIEREOU AL’ABSENCEDE CONTREFAÇON.

Please

Preface xi

1. Customizing the Wireless Toolkit 1

How to Customize the Wireless Toolkit 1

Customization Steps 2

Device Property Files and the Default Emulator 2

2. Creating Device Property Files 5

Make a Copy of an Existing Main Device Property File 5

Obtain and Enter Image Files 6

Obtain and Enter the Screen Properties 7

Screen Location 7

Total Screen Size 8

Display Area 8

Display Area in Full Screen Mode 9

Obtain and Enter the Button Properties 10

Obtain and Enter Soft Button Label Areas 12

Obtain and Enter Icon Properties 14

Defining the Icon Location and States 14

Enter Color Properties 16

Screen Background RGB Color 16

Run the Emulator for the New Device 16

Contents iii

3. Examining Device Property Files 17

Device Property Files 18

Main Device Property File 19

Fonts 19

Fonts Used by the MIDP APIs 19

Default Font 20

System Fonts 20

Bitmap Fonts 20

Font Underlining 22

The Device Image 22

Image without Buttons Pressed 23

Image with Buttons Pressed 23

Image with Buttons Highlighted and Backlight On 23

Scaling 23

Screen Properties 24

Screen Location 25

Total Screen Size 26

Display Area 26

Display Area in Full Screen Mode 26

Screen Pixel Ratio 27

Screen Background Color 27

Screen Border Color 28

Touch Screen 28

Screen Buffering 28

Device Buttons 29

Keyboard Handler 29

Defining a Device Button 29

Assigning a PC Keyboard Key to a Button 31

Assigning a Game Action to a Button 32

Specifying the Characters Generated by a Button Press 32

iv Wireless Toolkit Basic Customization Guide • December 2003

Assigning Abstract Commands to Buttons 33

Displayed Icons 38

Defining the Icon Location and States 38

Soft Button Label Display 39

Color 40

Sound Alerts 40

Device Software Capabilities 41

Locales 42

Character Encodings 42

Transparent Images 43

A. Default Emulator Device

Property Files 45

DefaultGrayPhone.properties 46

Device Image Files 53

Icon Image Files 53

B. Support for ByteCode Obfuscators 55

Adding a ByteCode Obfuscator 55

Example 56

C. Connecting to the Wireless Toolkit’s

WMA Emulation Environment 59

Index 61

Contents v

vi Wireless Toolkit Basic Customization Guide • December 2003

Figures

FIGURE 1 Specifying Screen Properties 9 FIGURE 2 Specifying a Button Location 11 FIGURE 3 Soft Button Label Areas on the Emulated Device Display 13 FIGURE 4 Specifying Emulator Fonts 21 FIGURE 5 Specifying Screen Properties 25 FIGURE 6 Specifying a Button Location 31 FIGURE 7 Soft Button Labels on the Emulated Device Display 39 FIGURE 8 Images of Device Key Press States 53

vii

viii Wireless Toolkit Basic Customization Guide • December 2003

Tables

TABLE 1 Example of Device Property Files and DefaultGrayPhone Property File 18 TABLE 2 Button Names Available 29 TABLE 3 Abstract Command Types in Order of Precedence 33 TABLE 4 Alert Type Values 41 TABLE 5 Example of Device Property Files 45

TABLE 6 Icon Image Files 53

x Wireless Toolkit Basic Customization Guide • December 2003

Preface

The Java™2 Platform, Micro Edition, Wireless Toolkit Basic Customization Guide describes how to customize the J2ME property files.

™

Wireless Toolkit by modifying device

Who Should Use This Book

This guide is intended for developers who need to configure the J2ME Wireless Toolkit to accommodate device emulators other than the ones provided by the Wireless Toolkit. This document assumes that you are familiar with Java programming, Mobile Information Device Profile (MIDP) and the Connected Limited Device Configuration (CLDC) specifications

How This Book Is Organized

This guide contains the following chapters and appendixes:

Chapter 1 describes briefly customization steps, device property files, and the

default emulator.

Chapter 2 explains, through a tutorial, how to create device property files that

enable the Wireless Toolkit to emulate devices other than the default devices supplied by the toolkit. The tutorial shows you how to obtain and enter image files,

screen properties, button properties, soft button label areas, and icon properties. The tutorial also explains how to set color properties and how to run the emulator for the new device.

Chapter 3 describes in depth the components of a device definition and explains

how to create a device definition.

Appendix A lists the property files for the default emulator, describes the

properties for it, and lists the image and icon files for the default emulator.

Appendix B explains how to add a bytecode obfuscator to the Wireless Toolkit

using the framework provided by the toolkit.

Appendix C describes the extension API provided with the Wireless Toolkit that

you can use to connect to the Wireless Toolkit’s WMA emulation environment.

Using Operating System Commands

This document may not contain information on basic UNIX®or Microsoft Windows commands and procedures such as opening a terminal window, changing directories, and setting environment variables. See the software documentation that you received with your system for this information.

xii Wireless Toolkit Basic Customization Guide • December 2003

Typographic Conventions

Typeface Meaning Examples

AaBbCc123 The names of commands, files,

and directories; on-screen computer output

AaBbCc123 What you type, when

contrasted with on-screen computer output

AaBbCc123 Book titles, new words or terms,

words to be emphasized

Edit your .login file. Use ls -a to list all files.

% You have mail. % su

Password:

Read Chapter 6 in the User’s Guide. These are called class options. Yo u must be superuser to do this.

Command-line variable; replace with a real name or value

To delete a file, type rm filename.

Shell Prompts

Shell Prompt

C shell machine_name%

Microsoft Windows <directory>

Accessing Sun Documentation Online

The Java Developer ConnectionSMweb site enables you to access Java™platform technical documentation on the Web.

http://developer.java.sun.com/developer/infodocs/

Sun Welcomes Your Comments

We are interested in improving our documentation and welcome your comments and suggestions. You can email your comments to us at:

wtk-comments@sun.com

xiv Wireless Toolkit Basic Customization Guide • December 2003

CHAPTER

Customizing the Wireless Toolkit

The JavaTM2 Platform, Micro Edition Wireless Toolkit (J2METMWireless Toolkit) provides an emulation environment for the development of applications compliant with the Mobile Information Device Profile (MIDP).

The Java 2 Platform, Micro Edition Wireless Toolkit Basic Customization Guide provides technical details for configuring the toolkit to accommodate new device emulators.

This chapter gives an overview of customizing the J2ME Wireless Toolkit and includes the following topics:

■ How to Customize the Wireless Toolkit

■ Device Property Files and the Default Emulator

Chapter 2, “Creating Device Property Files” presents a tutorial on how to adapt the

device definitions in J2ME Wireless Toolkit for a new device.

Chapter 3, “Examining Device Property Files” describes in more detail the

components of a device definition and how to create your own device definition.

How to Customize the Wireless Toolkit

One of the major benefits of the J2ME Wireless Toolkit is its ability to be customized: it can be readily adapted to provide a platform for developing Java applications that can run on many different devices, even from different manufacturers.

To do this, the J2ME Wireless Toolkit provides a Default Emulator that can be easily customized to provide high-fidelity emulation for many devices. The appearance and behavior of an emulated device is defined in the Default Emulator by a set of device property files, which contain the device’s images and property definitions. Thus, you can add a new device by simply creating a new set of device property files.

Customization Steps

You customize the J2ME Wireless Toolkit for a new device in three simple steps:

1. Obtain the default J2ME Wireless Toolkit.

The toolkit includes a default development environment and a Default Emulator. The Default Emulator is supplied with sets of device property files that enable the emulation of several generic wireless devices.

2. Create new device property files.

A company that wants to have applications developed for specific devices using the toolkit can modify the device property files and use them with the Default Emulator.

3. Add the new device property files to the J2ME Wireless Toolkit.

The set of device property files that was created for an additional device is copied to the folder in the J2ME Wireless Toolkit's installation that contains device definitions. The new device is automatically added to the device list.

Note – If you need to customize the J2ME Wireless Toolkit in a way that cannot be

achieved by producing a new set of device property files alone, please contact Sun Microsystems, Inc. for information about additional possibilities of customizing the J2ME Wireless Toolkit. Send email to

wtk-comments@sun.com

Device Property Files and the Default Emulator

The Default Emulator is the customizable device emulator supplied with the J2ME Wireless Toolkit. It contains the engine used to emulate J2ME applications, along with a highly configurable front end.

The basic definition of a device to be emulated by the Default Emulator is contained in its Main Device Property file. The Main Device Property file covers such features as the size of the screen that is emulated, the locations of image files used to display the device, and the active areas within these images that are used to represent buttons. Other device property files are also used to define a device's characteristics in the Default Emulator; these are mainly image files containing the device's image and images of any on-screen icons that are used in the device's emulation.

A device definition's Main Device Property file is located in the wtklib\devices subdirectory of the J2ME Wireless Toolkit's installation directory. Within the wtklib\devices directory, each emulated device X has a directory Main Device Property file named X.properties.

2 Wireless Toolkit Basic Customization Guide • December 2003

containing a

For example, suppose the J2ME Wireless Toolkit is installed in the directory

C:\WTK21. Then, the Main Device Property File for the device DefaultColorPhone is located at C:\WTK21\wtklib\devices\DefaultColorPhone\DefaultColorPhone.pro perties.

For the remainder of this document, {j2mewtk.dir}, denotes the installation directory of the J2ME Wireless Toolkit.

Chapter 1 Customizing the Wireless Toolkit 3

4 Wireless Toolkit Basic Customization Guide • December 2003

CHAPTER

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.)

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

2. 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.

1. 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.

2. 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

3. 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

6 Wireless Toolkit Basic Customization Guide • December 2003

pressed_buttons_image = ph1_press.png highlighted_image = ph1_highlight.png

4. 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 on page 9, 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

Chapter 2 Creating Device Property Files 7

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 on page 9, 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

8 Wireless Toolkit Basic Customization Guide • December 2003

Screen Location Full Dimension Name: screen.<dimension>

width

Display Area Full Dimension Name:

screenPaintableRegion.<dimension>

height

width

full screen height

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).

Chapter 2 Creating Device Property Files 9

■ 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

1. 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” on page 29.”

■ 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 on page 11.

10 Wireless Toolkit Basic Customization Guide • December 2003

+ 54 hidden pages