Basic Customization Guide Wireless Toolkit, Version 2.1 JavaTM 2 Platform, Micro Edition Sun Microsystems, Inc. 4159 Network Circle Santa Clara, CA 95054 U.S.A.
Copyright © 2003 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S.
Contents Preface 1. xi Customizing the Wireless Toolkit 1 How to Customize the Wireless Toolkit Customization Steps 1 2 Device Property Files and the Default Emulator 2.
3.
Assigning Abstract Commands to Buttons Displayed Icons 38 Defining the Icon Location and States Soft Button Label Display Color 39 40 Device Software Capabilities Locales Transparent Images 42 43 Default Emulator Device Property Files 45 Property Files 45 DefaultGrayPhone.properties Device Image Files Icon Image Files 53 Support for ByteCode Obfuscators Example 46 53 Adding a ByteCode Obfuscator C. 41 42 Character Encodings B. 38 40 Sound Alerts A.
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 FIGURE 4 Specifying Emulator Fonts FIGURE 5 Specifying Screen Properties 25 FIGURE 6 Specifying a Button Location 31 FIGURE 7 Soft Button Labels on the Emulated Device Display FIGURE 8 Images of Device Key Press States 13 21 39 53 vii
viii Wireless Toolkit Basic Customization Guide • December 2003
Tables TABLE 1 Example of Device Property Files and DefaultGrayPhone Property File TABLE 2 Button Names Available TABLE 3 Abstract Command Types in Order of Precedence TABLE 4 Alert Type Values TABLE 5 Example of Device Property Files TABLE 6 Icon Image Files 53 18 29 33 41 45 ix
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™ Wireless Toolkit by modifying device property files. 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.
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.
Typographic Conventions Typeface Meaning Examples AaBbCc123 The names of commands, files, and directories; on-screen computer output Edit your .login file. Use ls -a to list all files. % You have mail. AaBbCc123 What you type, when contrasted with on-screen computer output % su Password: AaBbCc123 Book titles, new words or terms, words to be emphasized Read Chapter 6 in the User’s Guide. These are called class options. You must be superuser to do this.
Application Title CLDC - JSR 30, JSR 139 J2ME™ Connected Limited Device Configuration WMA - JSR 120 Wireless Messaging API (WMA) for Java™ 2 Micro Edition MMAPI - JSR 135 Mobile Media API JTWI - JSR 185 Java Technology for the Wireless Industry J2ME Web Services JSR 172 J2ME™ Web Services Specification Accessing Sun Documentation Online The Java Developer ConnectionSM web site enables you to access Java™ platform technical documentation on the Web. http://developer.java.sun.
CHAPTER 1 Customizing the Wireless Toolkit The JavaTM 2 Platform, Micro Edition Wireless Toolkit (J2METM Wireless 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.
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.
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.
4 Wireless Toolkit Basic Customization Guide • December 2003
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.
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.
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.
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 = screen.height = ● 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.
Screen Location Full Dimension Name: screen. x width Display Area Full Dimension Name: screenPaintableRegion. y width x y height full screen height 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.
■ 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.
Y Y height X FIGURE 2 width Specifying a Button Location 2. Enter the following measured values for the button properties in NewPhone.properties: button.0 button.1 button.2 button.3 button.4 button.5 button.
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.
Soft Button Display Area Full Dimension Name: softbutton. y Soft button labels height x FIGURE 3 width Soft Button Label Areas on the Emulated Device Display A soft button label display is defined by a line of the form: softbutton.
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.
icon. = ,, The icon states are defined by lines of the form: icon.. = .. icon.. = 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. 2. Enter the following measured values for the icons properties in NewPhone.properties: icon.
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.
CHAPTER 3 Examining Device Property Files This chapter explains in detail the structure and content of device property files for an emulated device.
Device Property Files The device property files consist of a set of files that define the device’s behavior and appearance. Each set of device property files is located in a directory whose name determines the name of the device. {j2mewtk.dir} is used to refer to the directory in which the J2ME Wireless Toolkit is installed. For example, if you installed the J2ME Wireless Toolkit in the default directory C:\WTK21 then {j2mewtk.dir}\wtklib represents C:\WTK21\wtklib.
Main Device Property File This section describes the device property file that the Default Emulator uses to emulate a device. The Main Device Property file is named .properties and is located in the directory where device_name is the name of the device being emulated. For example, the Main Device Property file for a device named DefaultGrayPhone would be at {j2mewtk.dir}\wtklib\devices\DefaultGrayPhone \DefaultGrayPhone.properties.
The font definition is according to the format for describing a system font (see “System Fonts” on page 20) or a bitmap font (see “Bitmap Fonts” on page 20). Example font.system.italic.small: Helvetica-italic-9 The default font (see “Default Font”) is used for any MIDP font combination that is not defined. Default Font A default font must be specified. This font is used in all cases where no other definition was given. The default font is specified as follows: font.
Example font.softButton = bitmap_font.properties font.system.bold.medium = bold_font.properties A font property file contains definitions for the following properties: font_image = font_height = font_ascent = font_descent = font_leading = The first property, font_image, refers to an image file, in PNG, GIF or JPEG format, that contains the font bitmap.
.. ascii_x-254 = 1149 ascii_x-255 = 1154 ascii_x-256 = 1160 Note – This type of font supports only eight bit ASCII values (256 characters) and not 16 bit unicode characters. Font Underlining The MIDP specification allows underlined fonts. By default, the emulator supports font underlining. You can disable this feature for all fonts by setting the property: font.all.underline.enabled = false It is also possible to disable underlining for a specific font by setting the property: font..
