Home

Sun Microsystems 820-6799

1. Example The following definition allows only the command types BACK EXIT CANCEL and STOP to be mapped to the SOFTI key command exclusive SOFT1 BACK EXIT CANCEL STOP 36 Wireless Toolkit Basic Customization Guide December 2003 The Abstract Command Menu When there are more abstract commands specified by an application than there are buttons to which they can be mapped the unmapped abstract commands are placed in a command menu The following operations are defined for the command menu m Display hide menu m Select menu item m Scroll Traverse up menu m Scroll Traverse down menu These menu operations are assigned to buttons as described below One button is used to alternately display and hide the menu It is defined by the property command menu activate using the format command menu activate lt button_name gt The buttons used to navigate the menu are defined using the following properties command menu select lt menu_select_key gt command menu up lt menu_up_key gt command menu down lt menu_down_key gt The default values for these properties are command menu select SELECT command menu up UP command menu down DOW Example This example sets the menu to be activated by the SOFT2 key and to be navigated with the standard keys command menu activate SOFT2 Customizing Menu Title and Soft Button You can customize the title of the menu as well as the label of th
2. Referring to the left image in FIGURE 5 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 Chapter 3 Examining Device Property Files 25 screen x lt horizontal distance in pixels gt screen y lt vertical distance in pixels gt For example screen x 38 screen y 82 Total Screen Size Referring to the left image in FIGURE 5 on page 25 you specify the total screen size by two lines of the form screen width lt horizontal distance in pixels gt screen height lt vertical distance in pixels gt For example screen width 96 screen height 128 Display Area Referring to the right image in FIGURE 5 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 lt horizontal distance to display area gt screenPaintableRegion y lt vertical distance to display area gt screenPaintableRegion width lt width of display area gt screenPaintableRegion height lt height of display area gt For example screenPaintabl 0 Region x 4 Region y 8 screenPaintableRegion width 88 screenP
3. See Chapter 3 Examining Device Property Files for information on how to define devices with different numbers of soft buttons 12 Wireless Toolkit Basic Customization Guide December 2003 Soft Button Display Area Full Dimension Name softbutton lt dimension gt Soft button labels x gt 4 width FIGURE3 Soft Button Label Areas on the Emulated Device Display A soft button label display is defined by a line of the form softbutton lt number gt lt x gt lt y gt lt width gt lt height gt lt font gt lt align gt where the parameters are defined as follows m The coordinates of the soft button label area m x The x coordinate of the left edge of the label area in pixels relative to the left edge of the screen area m y The y coordinate of the top edge of the label area in pixels relative to the top edge of the screen area m width The width of the label in pixels m height The height of the label in pixels m font The font of the soft button label m align The alignment of the text of the soft button label within its area left right or center 2 Enter the following measured values for the soft button properties in NewPhone properties Chapter 2 Creating Device Property Files 3 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
4. When using the Qwert yKeyboardHandler you can also specify the character generated by a button press either alone or in combination with the Shift or Alt buttons You use a line of the form keyboard handler qwerty lt button_name gt lt base character gt lt shift character gt lt alternate character gt where base character is the character the button normally generates shift character is the character used when the button is pressed at the same time as Shift and alternate character is the character generated when the button is pressed at the same time as Alt 32 Wireless Toolkit Basic Customization Guide December 2003 There are two ways you can do a button press at the same time as pressing Shift or Alt m Map the buttons to the keyboard as in the previous section and press the key associated with the button at the same time as the Shift or Alt keys m Press the button Shift Lock or Alt Lock and then do the button press Press Shift Lock or Alt Lock again to revert to the initial state For example keyboard handler qwerty A a A Assigning Abstract Commands to Buttons Abstract commands are provided in the MIDP specification in order to allow an application to issue a screen command without having to take into account how the user selects that command on a specific device making the application more portable The idea is to separate the semantics of the command from its execution on the device T
5. 1 Menu operations 2 Abstract command precedence 3 Abstract command priority First the menu operations are assigned to the buttons that are defined for them Then the abstract commands are assigned Abstract command precedence is taken into account before abstract command priority Thus if a command of type BACK with priority 2 and a command of type EXIT with priority 1 are competing for a button the BACK command will get the assignment due to its higher precedence Command priority is taken into account only when the two commands have the same type Assigning an Abstract Command Type to a Button You assign an abstract command type to a button using a property definition of the form command keys lt type gt lt button_name gt where lt type gt is one of the abstract command types shown in TABLE 3 on page 33 The button name is one of the names listed in TABLE 2 on page 29 Example If you want to assign command types to the two soft buttons as follows m Left soft button command types BACK EXIT CANCEL and STOP m Right soft button command types OK SCREEN ITEM HELP you would enter the following definitions in the main device property file Chapter 3 Examining Device Property Files 35 command keys BACK 1 command keys EXIT 1 command keys CANCEL SOFTI command keys STOP SOFTI command keys OK SOFT2 command keys SCREEN SOFT2 1 H command keys ITEM 2 command keys
6. microsystems 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 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 athttp www sun com patents and one or more additional patents or pending patent applications in the U S and in other countries 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 Java Solaris Sun tm ONE Studio Java 2 Platform Micro Edition Wireless Toolkit J2SE JDK and the Java Coffee Cup logo are trademarks or registered trademarks of Sun Microsystems Inc in the U S and other countries UNIX is a registered trademark in the U S and other countries exclusively licensed through X Open Company Ltd The Adobe logo is a registered trademark of Adobe Systems Incorporated Products covered by and information contained in this service manual are controlled by U S E
7. Sound Alerts Sounds that are played when alert with sound is displayed can be specified Default sound can be specified by setting the option alert default sound lt sound_file gt This sound file will be used for all alerts where an alert specific sound is not defined Sound for each alert can be defined by 40 Wireless Toolkit Basic Customization Guide December 2003 alert lt alert_type gt sound lt sound_file gt where the possible values of lt alert_type gt are as defined by MIDP specification as follows TABLE 4 Alert Type Values Alert Type Description info Typically provides non threatening information to the user error Alerts the user to an erroneous operation warning Warns the user of a potentially dangerous operation confirmation Confirms user actions alarm Alerts the user to an event for which the user has previously requested to be notified If no sound file is defined no alert specific sound and no default sound for a particular alert the emulator does not play the sound and the corresponding MIDP API method AlertType playSound method returns the value false The Emulator supports all sound file formats currently supported by JDK1 4 m Audio file formats AIFF AU and WAV m Music file formats MIDI Type 0 MIDI Type 1 and Rich Music Format RMF m Sound formats 8 bit and 16 bit audio data in mono and stereo with sample rates from 8 kHz to 48 kHz m Linear A law and mu law enco
8. Use 1s a to list all files 2 You have mail su Password Read Chapter 6 in the User s Guide These are called class options You must be superuser to do this To delete a file type rm filename Shell C shell Microsoft Windows Prompt machine_name lt directory gt Related Documentation Application Title J2ME Wireless Toolkit J2ME Wireless Toolkit MIDP JSR 37 MIDP JSR 118 J2ME Wireless Toolkit User s Guide J2ME Wireless Toolkit Release Notes Mobile Information Device Profile for the J2ME Platform Mobile Information Device Profile 2 0 Preface xiii 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 Connection web 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 Wireless Toolkit Basic Customization Guide December 2003 CHAPTER 1 Customizing the Wireless
9. screenPixelRatio y vertical_image_pixels vertical_device_pixels For most devices use the following values screenPixelRatio x 1 screenPixelRatio y 1 The values of screenPixelRatio x and screenPixelRatio y must be whole numbers Screen Background 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 Oxffffff and red would be Oxff0000 The background color is defined with the property screenBGColor For example screenBGColor 0x64b890 Chapter 3 Examining Device Property Files 7 Screen Border Color You have the option of setting the color of the icon area the softbutton area non paintable areas and the device menu Screen background color is used if this value is not defined 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 Oxfff ff and red would be 0x f0000 The screen border color is defined with the property screenBorderColor For example screenBorderColor 8 Touch Screen You can define whether or not your device should respo
10. 7 VK 7 VK NUMPAD7 key 8 VK 8 VK NUMPAD8 key 9 VK 9 VK_NUMPAD9 key POUND VK_SUBTRACT key ASTERISK VK MULTIPLY key POWER VK ESCAPE key UP VK_UP key DOWN VK_DOWN key LEF VK_LEFT key RIGHT VK_RIGHT key SELECT VK ENTER key SOFTI VK 1 key SOFT2 VK F2 key SEND VK HOME key END VK END key CLEAR VK BACK SPACE Mul fon Whe re tiple font support t lt face gt lt style gt lt size gt lt font properties filename gt lt system font definition gt Wireless Toolkit Basic Customization Guide December 2003 lt face gt is one of system monospace proportional lt style gt is one of plain bold italic lt size gt is one of small medium large Default font is defined by font default lt font properties filename gt lt system font definition gt Soft Button font defined by font softButton lt font properties filename gt lt system font definition gt font default SansSerif plain 10 font softButton SansSerif plain 11 font system plain small SansSerif plain 9 font system plain medium SansSerif plain 11 font system plain large SansSerif plain 14 font system bold small SansSerif bold 9 font system bold medium SansSerif bold 11 font system bold large SansSerif bold 14 font system italic small SansSerif italic 9 font system italic medium SansSerif italic 11 font system italic large SansSerif italic 14
11. Files This chapter explains in detail the structure and content of device property files for an emulated device The following is the list of the main behavior items that can be specified in the device property files device image locations of buttons and association of PC keys with device buttons screen location and resolution fonts displayed icons location font and alignment of soft buttons color support MIDP abstract command implementation By creating a new set of device property files you can customize the behavior of the items that are described above to fit with the behavior of the real device The folder wtklib devices in the binary release of the J2ME Wireless Toolkit contains the device property files The syntax of device property files is that of the standard Java 2 Standard Edition property resources For a description of the syntax see the method detail for the load method for the Properties class at the following website http java sun com j2se 1 4 docs api java util Properties html load java io InputStream For a description of the structure and content of device property files see Device Property Files on page 18 Note If you would like to have a new device property file posted on the J2ME Wireless Toolkit web site or distributed with the next version of the J2ME Wireless Toolkit send email to wtk comments sun com 17 Device Property Files The device property files consist o
12. HI SOFT2 1 Il In cases of conflict in the mapping of actual commands to keys commands are mapped first by command type and then by priority Secondary Button Assignments Secondary buttons may be defined for a command type If a command is unable to be assigned to the preferred button for its type because another command with higher precedence due to either its type or its priority has taken the button the command can be assigned to an alternative button This is done by specifying more than one button name in the property definition where the names are separated by spaces command keys lt type gt lt button_name gt lt button_name gt lt button_name gt Example The first definition below assigns commands of type BACK to the END key and alternatively to the SOFT1 key The second definition assigns commands of type OK to the SEND key and alternatively to the SOFT2 key command keys BACK END SOFTI command keys OK SEND SOFT2 Restricting the List of Command Types for a Soft Button Only certain command types might be allowed for a specific soft button which means that other command types will not be assigned to that soft button in any case even if that soft button is left unassigned You restrict command types to a button by specifying a list of one or more command types in the property definition command exclusive lt button_name gt lt type gt lt type gt lt type gt
13. 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 toa 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 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 Default Emulator Device Property Files 45 Property Files 45 DefaultGrayPhone properties 46 Device Image Files 53 Icon Image Files 53 Support for ByteCode Obfuscators 55 Adding a ByteCode Obfuscator 55 Example 56 Connecting to the Wireless Toolkit s WMA Emulation Environment 59 Index 61 33 Contents v vi Wireless Toolkit Basic Customization Guide December 3 FIGURE 1 FIGURE 2 FIGURE 3 FIGURE 4 FIGURE 5 FIGURE 6 FIGURE 7 FIGURE 8 Figures Specifying Screen Properties 9 Specifying a Button Location 1 Soft Button Label Areas on the Emulated Device Display 13 Specifying Emulator Fonts 21 Specifying Screen Properties 25 Specifying a Button Location 31 Soft Button Labels on the Emulated Device Display 39 Images of Device Key Press States 53 vi viii Wireless Toolkit Basic Customiza
14. Toolkit The Java 2 Platform Micro Edition Wireless Toolkit J2ME 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 This chapter gives an overview of customizing the J2ME Wireless Toolkit and includes the following topics m How to Customize the Wireless Toolkit m 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 c
15. font system bold italic small SansSerif bolditalic 9 font system bold italic medium SansSerif bolditalic 11 font system bold italic large SansSerif bolditalic 14 font monospace plain small Monospaced plain 9 font monospace plain medium Monospaced plain 11 font monospace plain large Monospaced plain 14 font monospace bold small Monospaced bold 9 font monospace bold medium Monospaced bold 11 font monospace bold large Monospaced bold 14 font monospace italic small Monospaced italic 9 font monospace italic medium Monospaced italic 11 Appendix A Default Emulator Device Property Files 9 font monospace italic large Monospaced italic 14 font monospace bold italic small Monospaced bolditalic 9 font monospace bold italic medium Monospaced bolditalic 11 font monospace bold italic large Monospaced bolditalic 14 font proportional plain small SansSerif plain 9 font proportional plain medium SansSerif plain 11 font proportional plain large SansSerif plain 14 font proportional bold small SansSerif bold 9 font proportional bold medium SansSerif bold 11 font proportional bold large SansSerif bold 14 font proportional italic small SansSerif italic 9 font proportional italic medium SansSerif italic 11 font proportional italic large SansSerif italic 14 font proportional bold italic small SansSerif bolditalic 9 font proportional bold italic medium SansSerif bolditalic 11 font proportional bold italic large SansSerif boldit
16. 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 m width The width of the button image in pixels m height The height of the button image in pixels For example button LEFT 13 197 20 20 For the second form polygonal the definitions for button_name x and y are the same as for the rectangular form The polygonal form can consist of multiple points defined by x and y coordinates A minimum of three sets of x and y coordinates are required to use this form For example if the LEFT button were polygonal it could have the following values button LEFT 166 420 143 432 143 406 The button location and dimensions are used for two purposes m To define the active region in which a mouse click is interpreted as a button press m 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 6 Wireless Toolkit Basic Customization Guide December 2003 E 5550000 DefaultColorPhones MIDlet Help 5 aliya FontTestet Stock IE Tickets 3 ManyBalls lt gt width Rectangular B
17. in FIGURE 2 on page 11 10 Wireless Toolkit Basic Customization Guide December 2003 height FIGURE2 Specifying a Button Location 2 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 Chapter 2 Creating Device Property Files 11 button 7 button 8 button 9 21 384 41 22 65 384 41 22 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 DOW 70 284 34 21 un button UP 1 4 87 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 1 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 on page 13 shows the soft button labels Undo and Menu on the lower part of the device screen Note
18. 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 1 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 14 Wireless Toolkit Basic Customization Guide December 2003 icon lt name gt lt x_location gt lt y location gt lt initial_state gt The icon states are defined by lines of the form icon lt name gt lt state 1 gt lt state 1 image_filename gt icon lt name gt lt state n gt lt state n image_filename gt 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 of
19. specify the thickness of the line used for underlining by a line of the form font lt face gt lt style gt lt size gt underline width lt width in pixels gt The default width of the line is one pixel for plain and italic font styles and two pixels for the bold font style It is also possible to specify the distance of the line used for underlining from the font baseline by a line of the form font lt face gt lt style gt lt size gt underline offset lt offset from baseline in pixels gt The default offset is one pixel for all fonts The Device Image To specify the device image you need to specify three separate device graphic images These image files should differ only in their representation of active buttons those buttons that are to be used in the emulation of the device in the J2ME Wireless Toolkit The image files are m A base image with all active buttons in a neutral state not pressed or highlighted 22 Wireless Toolkit Basic Customization Guide December 2003 m An image with all the active buttons pressed to show a button being pressed when the user selects it m An image with all the active buttons highlighted to provide a visual indication that the pointer is sufficiently positioned over a button that a mouse click will activate the button Image files can be in GIF PNG or JPEG format Image without Buttons Pressed To specify a device image without the buttons pressed enter a
20. S OU TACITES SONT FORMELLEMENT EXCLUES DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE Y COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE A L APTITUDE A UNE UTILISATION PARTICULIERE OU A L ABSENCE DE CONTREFA ON Please 6 24 Adobe PostScript Contents Preface xi Customizing the Wireless Toolkit 1 How to Customize the Wireless Toolkit 1 Customization Steps 2 Device Property Files and the Default Emulator 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
21. 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 X containing a Main Device Property file named X properties 2 Wireless Toolkit Basic Customization Guide December 2003 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 T
22. abels on the Emulated Device Display A soft button label display is defined by a line of the form Chapter 3 Examining Device Property Files 9 softbutton lt number gt lt x gt lt y gt lt width gt lt height gt lt font gt lt align gt where the parameters are defined as follows m The coordinates of the soft button label m x The x coordinate of the left edge of the label area in pixels relative to the left edge of the screen area m y The y coordinate of the top edge of the label area in pixels relative to the top edge of the screen area m width The width of the label in pixels m height The height of the label in pixels m font The font of the soft button label m align The alignment of the text of the soft button label within its area left right or center For example softbutton 0 0 110 36 18 softButton left softbutton 1 60 110 36 18 softButton right Color Three properties are provided to control the color in the Emulator m The isColor property determines whether the display is grayscale false or color true m 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 m The gamma property determines the level of gamma correction to be used when displaying the device s screen The default value of this property is 1 0 For example isColor false colorCount 256 gamma 2 0
23. aintableRegion height 100 screenPaintabl D Note If you do not specify the paintable region the entire screen is used by an application Display Area in Full Screen Mode The MIDP 2 0 specification allows applications to use the full screen area 26 Wireless Toolkit Basic Customization Guide December 2003 Referring to the right image in FIGURE 5 the full screen display area is defined as the upper left coordinate of the display area screenPaintableRegion x screenPaintableRegion y and 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 Screen Pixel Ratio The following commands enable you to compensate for the difference in aspect ratio between the actual device screen and the device image on the PC screen The pixel size ratio property defines the number of pixels in the device s PC image that correspond to a single pixel on the real device in both the horizontal and vertical direction Note MIDP requires that pixels be square Therefore you should only use pixel ratios that preserve the square for example x y 2 2 or 3 3 that is magnifying the image and you should not use pixel ratios that distort the square for example xy 1 2 or 2 1 The ratios are defined as follows screenPixelRatio x horizontal_image_pixels horizontal_device_pixels
24. alic 14 Font underlining Font underlining is enabled by default font underlining with It is possible to disable font all underlin nabled fals or per font with font lt face gt lt style gt lt size gt underline enabled fals Multistate icons support icon lt name gt lt x location gt lt y location gt lt initial state gt icon lt name gt lt state 1 gt lt state 1 image file name gt icon lt name gt lt state n gt lt stat n image file name gt 86 icon up off icon up 192 off icon up on Share up gif icon down 86 198 off icon down off 50 Wireless Toolkit Basic Customization Guide December 2003 icon down on Share down gif icon left 78 194 off icon left off icon left on Share left gif icon right 94 194 off icon right off icon right on Share right gif icon internet 64 1 off icon internet off icon internet on Share internet gif icon reception 2 1 on icon reception on Share reception gif icon battery 164 2 on icon battery on Share batt gif icon inmode 83 2 off icon inmode off icon inmode ABC Share ABC gif icon inmode abc Share abc_lower gif icon inmode 123 Share 123 gif icon inmode kana Share kana gif icon inmode hira Share hira gif icon inmode sym Share sym gif icon domain 149 0 off icon domain off icon domain trusted Share trusted png Sound support al
25. button press Assigning a game key to a button press Specifying the character generated by a button press Assigning an abstract command to a button press Keyboard Handler The set of names available for device buttons depends on the keyboard handler being used There are two built in keyboard handlers in the Toolkit m ITU T telephone keypad handler the class DefaultKeyboardHandler m A QWERTY keypad handler the class Qwert yKeyboardHandler You specify the keyboard handler by the keyboard handler property which gives the name of the class to be used For example keyboard handler com sun kvem midp DefaultKeyboardHandler Defining a Device Button A button on the emulated device is defined in the main device property file by name and screen location in one of the following forms button lt button_name gt x y width height button lt button_name gt x1 yl x2 y2 x3 y3 For the first form rectangular the parameters are as follows m button name The set of button names available is determined by the keyboard handler in use as shown in TABLE 2 TABLE 2 Button Names Available Keyboard Handler Button Names com sun kvem midp DefaultKeyboardHandler 0 1 2 3 4 5 6 7 8 9 POUND ASTERISK POWER SEND END LEFT RIGHT UP DOWN SELECT SOFT1 SOFT2 SOFT3 SOFT4 CLEAR USERI through USER10 Chapter 3 Examining Device Property Files 9 30 m x The x coordinate of the left edge of the button
26. 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 m The left right up and down icons indicate the possible scrolling operations m The inmode icon indicates the current text input mode Capital letters small letters or numbers m The domain icon indicates whether the current MIDlet suite is assigned a trusted domain An icon is defined by m 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 m 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 m A default state The icon is initially in this state m 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
27. cs html The bitmap font property file contains a list of properties of the form ascii x lt n gt lt horizontal pixel location in the image gt where lt n gt is a number between 0 and 256 and the given pixel location refers to the start of that character s definition in the font bitmap The characters must be adjacent in the image so that one character ends where another begins The following image shows the interpretation of the horizontal pixel locations ASCII character OO N Ve pR 0123456709 gt lt ABCDERGHUELMANOPORET UMA 20 abedefghiikininopgrstuyy Distance to character h FIGURE 4 Specifying Emulator Fonts Example ascii_x 0 0 ascii x 1 0 ascii 32 0 ascii x 33 8 Chapter 3 Examining Device Property Files 1 8850111 4 1149 ascii x 255 1154 1160 8850111 6 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 fals It is also possible to disable underlining for a specific font by setting the property font lt face gt lt style gt lt size gt underline enabled 8 Where face style and size are as described in Fonts Used by the MIDP APIs on page 19 It is possible to
28. ded data in any of the supported audio file formats Device Software Capabilities The Default Emulator in the J2ME Wireless Toolkit enables you to define device emulations with additional capabilities that are not required by the MIDP specification Specifically m You can specify a default locale m You can specify what character encodings are available in the device emulation m You can disallow use of transparent images in the device emulation This section describes how to use these options Chapter 3 Examining Device Property Files 1 Locales A locale is a geographic or political region or community that shares the same language customs or cultural convention In software a locale is a collection of files data and code which contains the information necessary to adapt software to a specific geographical location Some operations are locale sensitive and require a specified locale to tailor information for users such as m Messages displayed to the user m Cultural information such as dates and currency formats In the Default Emulator the default locale is determined by the platform s locale To define a default locale use the following definition microedition locale lt default_locale gt A locale name is comprised of two parts separated by an dash for example en US is the locale designation for english United States while en AU is the designation for english Australia The first part is a valid ISO Lan
29. e December 2003 device property files 1 WMA messages customizing 59 Index 3 64 Wireless Toolkit Basic Customization Guide December 2003
30. e resident PC fonts to display text on the device screen Use the font specification in the form font lt name gt lt system font definition gt Example font softButton Arial plain 12 Bitmap Fonts To tell the Emulator to use a bitmap font you need to specify a font property file that describes the font font lt font name gt lt font property filename gt 20 Wireless Toolkit Basic Customization Guide December 2003 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 lt image_filename gt font_height lt pixel_height_font gt font_ascent lt pixel_ascent_font gt font_descent lt pixel_descent_font gt font_leading lt pixel_space_between_lines_of_text gt The first property font_image refers to an image file in PNG GIF or JPEG format that contains the font bitmap The form of the bitmap should be a row of characters as shown in FIGURE 4 The other properties listed above define other characteristics of the font height the height of a character ascent the part of the character that is above the base line descent the part of a character that is below the base line leading the spacing between lines For a complete description of height ascent descent and leading as they relate to fonts see http java sun com j2se 1 4 docs api java awt FontMetri
31. e soft button used to display and hide the menu Use the following properties menu text title lt menu title gt menu title activate lt soft button label gt The default values for these properties are menu text title Menu menu title activate Menu Note Real devices can have alternate human interfaces that employ means other than menus to handle commands that cannot be mapped to keys Chapter 3 Examining Device Property Files 7 Displayed Icons 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 An icon is defined by m A name This name must be known to the Java code that uses the icon For example the code to implement scrolling indicators looks for icons named up and down m 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 m A default state The icon is initially in this state m 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 di
32. ed by the application to be a subregion of the screen by four lines of the form screenPaintableRegion x lt horizontal distance to display area gt screenPaintableRegion y lt vertical distance to display area gt screenPaintableRegion width lt width of display area gt screenPaintableRegion height lt height of display area gt 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 Wireless Toolkit Basic Customization Guide December 2003 Screen Location Full Dimension Name screen lt dimension gt A Display Area Full Dimension Name y screenPaintableRegion lt dimension gt v width p A 7 lt heig full screen height height v FIGURE1 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 m Upper left coordinate the upper left coordinate of the display area screenPaintableRegion x screenPaintableRegion y Chapter 2 Creating Device Property Files 9 m 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 fu
33. ename 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 NewPhon 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 m a default image file showing the active buttons in normal unpressed position m an image file showing the active buttons in a pressed position m an image file showing the active buttons highlighted and an indicator light to indicate that backlighting is turned on the device m 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
34. ert lt alert_type gt sound lt sound_file gt Where possible lt alert_type gt are alarm info warning error confirmation Default sound type is used for all alerts where specific sound is not defined alert default sound lt sound_file gt alert alarm sound Share mid_alarm wav alert info sound Share mid_info wav alert warning sound Share mid_warn wav Appendix A Default Emulator Device Property Files 1 52 alert error sound Share mid_err wav alert confirmation sound Share mid_confirm wav Softbuttons support softbutton lt number gt lt x location gt lt y location gt lt width gt lt height gt lt font gt Coordinates are relative to the origin of the screen area softbutton 021 192 78 16 softButton left softbutton 1 99 192 78 16 softButton right Gamma value for gamma correction Default value is 1 which means that no gamma correction is actually performed gamma 2 Color Grayscale screen support colorCount 0x100 isColor false individually rather than globally Se SE RHE menu text title Menu menu text activate Menu Wireless Toolkit Basic Customization Guide December 2003 These are the labels for the menu softbutton and the menu screen in the device They are here so the phones can be localized Device Image Files ph1_neut png ph1_press png ph1_highlight png FIGURE8 Images of Device Key Press States Icon Ima
35. f Chapter 2 Creating Device Property Files 15 Enter Color Properties Two properties are provided to control the color in the Emulator m The isColor property determines whether the display is grayscale false or color true m 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 Oxffffff and red would be Oxff0000 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 16 Wireless Toolkit Basic Customization Guide December 2003 CHAPTER 3 Examining Device Property
36. f 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 The device property directory must be located in j2mewtk dir wtklib devices so that it can be used by the J2ME Wireless Toolkit For example TABLE 1 lists the device property file for a device named DefaultGrayPhone and the shared property files used by all the devices provided with the Wireless Toolkit The DefaultGrayPhone device property file is located at j2mewtk dir wtklib devices DefaultGrayPhone in the binary installation The shared device property files are located at j2mewtk dir wtklib devices Share in the binary installation TABLE 1 Example of Device Property Files and DefaultGrayPhone Property File Property File Description DefaultGrayPhone DefaultGrayPhone properties Main Device Property File j2mewtk dir wtklib devices Share phl_neut png Device image with buttons not pressed j2mewtk dir wtklib devices Share phl_press png Device image with buttons pressed j2mewtk dir wtklib devices Share phl_highlight png Device image with buttons highlighted j2mewtk dir wtklib devices Share batt gif Icon used in
37. ge Files The following table lists filenames and their associated images TABLE 6 Icon Image Files Filename Image batt gif FE down gif up gif Appendix A Default Emulator Device Property Files 3 TABLE 6 Icon Image Files Filename Image internet gif i reception gif Faull right gif left gif sym gif sut kana gif P hira gif ABC gif ABC abc_lower gif dbe 123 gif 123 secure gif 8 unsecure gif EY trusted gif ft 54 Wireless Toolkit Basic Customization Guide December 2003 APPENDIX B Support for ByteCode Obfuscators The Wireless Toolkit contains a support framework for bytecode obfuscators It also includes a plug in for this framework for the ProGuard and Retroguard bytecode obfuscators You can use a bytecode obfuscator other than ProGuard or RetroGuard however you must manually implement the plug in for it This appendix describes the implementation procedure Adding a ByteCode Obfuscator To plug in a bytecode obfuscator of your choice into the Wireless Toolkit s packaging process you must follow these steps Write your own Java class that implements the com sun kvem environment Obfuscator interface The class file for this interface is located in the j2mewtk dir wtklib kenv zip file The implementation class needs to implement the following two interface methods m createScriptFile File jadFilename File projectDir 55 m run File jarFileObfuscated String wtkB
38. global region of device j2mewtk dir wtklib devices Share down gif Icon used in global region of device j2mewtk dir wtklibdevices Share internet gif Icon used in global region of device j2mewtk dir wtklib devices Share reception gif Icon used in global region of device j2mewtk dir wtklib devices Share up gif Icon used in global region of device See Appendix A Default Emulator Device Property Files for a full example of device property files 18 Wireless Toolkit Basic Customization Guide December 2003 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 lt device_name gt properties and is located in the directory lt device_name gt 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 Main Device Property file contains the information needed to define the device s appearance and behavior as well as pointers to associated property files The Main Device Property file contains definitions for the following items Each is discussed in detail in the sections below Fonts The Device Image Screen Properties Device Buttons Displayed Icons Soft Button Label Display Color Sound Alerts Device Software Capabilities Fonts There a
39. guage Code These codes are the lower case two letter codes as defined by ISO 639 You can find a full list of these codes at a number of sites such as http www ics uci edu pub ietf http related iso639 txt The second part is a valid ISO Country Code These codes are the upper case two letter codes as defined by ISO 3166 You can find a full list of these codes at a number of sites such as http www chemie fu berlin de diverse doc ISO_3166 html Character Encodings The input output APIs in CLDC use named character encodings to convert 8 bit characters into 16 bit Unicode characters and vice versa A MIDP implementation might make only a small set of encodings available for MIDlets to use In the Default Emulator the default encoding is default encoder of the platform you are running on Your emulator might use other encodings such as UTF 8 and UTF 16 providing they are available in the J2SE platform To define the default character encoding used by the emulator use the following definition microedition encoding lt default_encoding gt To define the set of all available encodings use the following definition microedition encoding supported lt list of encodings gt For example 42 Wireless Toolkit Basic Customization Guide December 2003 microedition encoding UTF 8 microedition encoding supported UTF 8 UTF 16 ISO 8859 1 ISO 8859 2 Shift JIS To support all encodings supported by the J2ME platform
40. he semantics are defined in the application and the execution is defined in the implementation of MIDP on the specific device The semantics of an abstract command include m Label the command name for display purposes m Type the category of the command for example BACK or HELP The command type is used to help determine how a command is mapped onto a device m Priority a priority number The command priority is used to help determine how a command is mapped onto a device In the MIDP Reference Implementation which underlies the J2ME Wireless Toolkit there is an implicit order of precedence among the command types This command precedence also impacts on the assignment of a command to a preferred button If two commands of different types are vying for the same button the command whose type has higher precedence prevails TABLE 3 shows the abstract command types in order of precedence in the J2ME Wireless Toolkit and the MIDP Reference Implementation TABLE 3 Abstract Command Types in Order of Precedence Command Type Description BACK Returns the user to the logically previous screen EXIT Exits from the application CANCEL Standard negative answer to a dialog implemented by the current screen STOP Stop some currently running process or operation Chapter 3 Examining Device Property Files 3 TABLE 3 Abstract Command Types in Order of Precedence Command Type Description OK Standard positive answer to a dialog
41. highlight png screen properties Screen location relative to the top left corner of the telephone s image FE EE screen x 3 Screen size in pixels EH screen width 180 screen height 208 0 screen y 131 i The region of the screen available to graphics commands This section is optional It defines the drawable region of the screen to be a subregion of the whole screen area AEE EAEE EE H screenPaintableRegion x 0 screenPaintableRegion y 11 screenPaintableRegion width 180 screenPaintableRegion height 178 pixel size ratio shape of each pixel example 1xl square pixel 1x2 rectangular pixel HEE RHE EH HEH 46 Wireless Toolkit Basic Customization Guide December 2003 screenPixelRatio x screenPixelRatio y 1 Touchscreen support HEE AE SEE EERE HE HH touch_screen false Screen Background RGB Color examples Oxffffff white 0x000000 black HEHEHE HE HEHE HH screenBGColor 0x8f9f8f Screen border RGB color is a color of softbuttons and icons area If not defined screen background color is used example screenBorderColor 25 EH HE EH HEH screenBorderColor 0xb6b6aa Transparency support SRC_OVER alpha composition rule supported by deafult HEE EH HEH enableAlphaChannel true netindicator image Share indicator png netindicat
42. 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 xii 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 Wireless Toolkit Basic Customization Guide December 2003 Typographic Conventions Typeface AaBbCc123 AaBbCc123 AaBbCc123 Meaning The names of commands files and directories on screen computer output What you type when contrasted with on screen computer output Book titles new words or terms words to be emphasized Command line variable replace with a real name or value Shell Prompts Examples Edit your login file
43. implemented by current screen SCREEN Specifies an application defined command that pertains to the current screen for example Load and Save ITEM The command is specific to a particular item on the screen HELP Request for on line help The MIDP implementation in the Wireless Toolkit allocates a command issued by the application to a device button based on the following considerations 1 The first consideration is the natural correspondence between the command s type and a input signal such as a button press For example if the BACK command type is usually associated with the left soft button then the implementation first tries to assign it there If there is no such preferred button for a command type this consideration is not relevant 2 The secondary consideration is assignment of the remaining commands that could not be assigned to their preferred buttons The command precedence and the command priority are used to assign these commands to alternate buttons or to a command menu The J2ME Wireless Toolkit allows a variety of abstract command mapping policies to be implemented An emulated device can use a combination of soft buttons and dedicated command buttons to implement abstract commands or it can have none of these and just present all abstract commands to the user in an on screen menu The J2ME Wireless Toolkit includes examples of different configurations see the Wireless Toolkit User s Guide Note The mappi
44. in the screen properties m Screen Location m Total Screen Size m 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 lt horizontal distance in pixels gt screen y lt vertical distance in pixels gt 6 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 8 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 lt horizontal distance in pixels gt screen height lt vertical distance in pixels gt 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 us
45. inDir String wtkLibDir String jarFilename String projectDir String classPath String emptyApi where jarFileObfuscated is the file that holds the obfuscated JAR wtkBinDir is the directory holding the Wireless Toolkit binary files wtkLibDir is the directory holding the Wireless Toolkit JAR files jarFilename is the full path to the JAR file to be obfuscated projectDir is the full path to the main directory of your project classPath is the full path to the set of files that make up the API classpath for the project based on your API selections in the Project Settings dialog box for example the paths for the cldcapi10 jar and midpapi20 jar files emptyApi is the full path to the version of the MIDP API containing stub methods that is method signatures without method bodies in the j2mewtk dir wtklib directory The first method creates a script file that is used by most obfuscators as a method of input to determine which classes and methods are not to be obfuscated The second method is called when the Wireless Toolkit attempts to execute the obfuscator 2 You must add the following properties to the ktools properties file located in j2mewtk dir wtklib Windows m obfuscator runner class name The fully qualified name of the class implementing the obfuscator interface This property tells the Wireless Toolkit the class name it needs to load to execute the obfuscator m obfuscator runner classpath The location of the impleme
46. leave the microedition encoding supported definition blank as in microedition encoding supported Note The encoding ISO 8859 1 is always available to applications running on emulated devices whether or not it is listed in the microedition encoding supported entry Transparent Images The Default Emulator supports the alpha channel in the image data by default To disable the alpha channel in the image data change the value of the enableAlphaChannel property from true to false enableAlphaChannel false Chapter 3 Examining Device Property Files 3 44 Wireless Toolkit Basic Customization Guide December 2003 APPENDIX A Default Emulator Device Property Files This appendix presents a list of the device property files provided with the Default Emulator and information on the Default Emulator properties Property File TABLE 5 Property Files The following property files are used Example of Device Property Files Description DefaultGrayPhone DefaultGrayPhone properties j2mewtk dir j2mewtk dir j2mewtk dir j2mewtk dir j2mewtk dir j2mewtk dir j2mewtk dir j2mewtk dir j2mewtk dir j2mewtk dir j2mewtk dir j2mewtk dir j2mewtk dir wt wt w w w w w w w w wt w wt K K K ib devices s ib devices s ib devices s lib devices s lib devices s lib devices s lib devices s lib devices s lib devices s lib devices s lib devices s
47. lib devices s lib devices s hare 123 gif hare ABC gif hare batt gif hare down gif hare hira gif hare kana gif hare left gif hare phl_neut png hare phl_press png hare phl_highlight png hare abc_lower gif hare indicator png hare internet gif Main Device Property File Device image with buttons not pressed Device image with buttons pressed Device image with buttons highlighted Icon used on device screen Icon used on device screen Icon used on device screen Icon used on device screen Icon used on device screen Icon used on device screen Device image of backlight indicator LED Icon used on device screen Icon used on device screen Icon used on device screen 45 TABLE 5 Example of Device Property Files Property File Description j2mewtk dir wtklib devices Share reception gif Icon used on device screen j2mewtk dir wtklib devices Share right gif Icon used on device screen j2mewtk dir wtklib devices Share secure gif Icon used on device screen j2mewtk dir wtklib devices Share sym gif Icon used on device screen j2mewtk dir wtklib devices Share trusted png Icon used on device screen j2mewtk dir wtklib devices Share unsecure gif Icon used on device screen j2mewtk dir wtklib devices Share up gif Icon used on device screen DefaultGrayPhone properties default_image Share phl_neut png pressed_buttons_image Share phl_press png highlighted_image Share phl_
48. line of the form default_image lt image_filename gt For example default_image phone_base png Image with Buttons Pressed To specify a device image with the buttons pressed enter a line of the form pressed_buttons_image lt image_filename gt For example pressed_buttons_image phone_pressed png Image with Buttons Highlighted and Backlight On To specify a device image with the buttons highlighted and backlighting on enter a line of the form highlighted_image lt image_filename gt For example highlighted_image phone_highlight png Scaling To scale the device image use an entry of the following form scale lt magnification_factor gt For example the following entry expands the device image to twice its original width and height scale 2 Chapter 3 Examining Device Property Files 3 Screen Properties In this section you specify the properties of the image of the device screen You need to specify the following screen properties Screen Location Total Screen Size Display Area optional Screen Pixel Ratio optional Screen Background Color optional Touch Screen optional 24 Wireless Toolkit Basic Customization Guide December 2003 Screen Location Full Dimension Name screen lt dimension gt Display Area Full Dimension Name screenPaintableRegion lt dimension gt full screen height FIGURES Specifying Screen Properties Screen Location
49. m 19 font default property 20 61 font_image property 21 G game actions mapping to buttons 32 generated characters assigning to buttons 32 icons setting initial state 14 setting properties 14 setting screen location 14 image files creating and modifying 6 formats 23 isColor property 40 K keyboard keys setting to buttons 31 keyboard handler property 29 Main Device Property file 2 path 19 N NewPhone tutorial 5 0 order of preference button assignment 35 P plug in for code obfuscator 55 ProGuard byte code obfuscator 55 proguard jar 57 R RetroGuard byte code obfuscator 55 5 screen icons 38 definition 38 setting initial state of 38 setting location 38 screen properties 24 background color 27 buffering 28 defining display area 8 display area 26 full screen display area 27 location 25 pixel size ratio 27 setting location 7 setting screen size 8 size 26 touch screen 28 screenBGColor property 27 screenDoubleBuffer property 28 screenPixelRatio property 27 secondary button assignments 36 soft buttons label display 39 setting properties 12 sound alert types table of 41 sound file formats 41 sound properties 40 system font definition 20 T touch screen property 28 transparent images use of 43 U underlined fonts 22 W Wireless Messaging API WMA 59 Wireless Toolkit 62 Wireless Toolkit Basic Customization Guid
50. nd to mouse activity on its screen This is done by defining a property touch_screen to be either true or false For example setting touch_screen true causes the device to respond to mouse activity on its screen The default value is touch_screen false Note You only see the effect of the touch screen property in MIDIets that are specifically written for touch screens such as the PushPuzzle demonstration game included with the J2ME Wireless Toolkit The user interface widgets in the Default Emulator do not respond to touch screen events for example you cannot select an item from a list by clicking on it with the mouse Screen Buffering By default output from a MIDlet to the screen is buffered so the screen is not updated every time the application draws a line or writes some text Instead when the application is ready it signals MIDP that its drawing operations are complete and only then is the screen updated To see screen updates happen immediately use the following entry screenDoubleBuffer fals Use this entry if you want your applications to perform fewer drawing operations or if you are emulating a device that does not buffer screen output 28 Wireless Toolkit Basic Customization Guide December 2003 Device Buttons This section describes how to define a button on an emulated device and also describes the assignments associated with the buttons including Assigning a keyboard key press to a
51. ng policy for abstract commands can vary across actual devices For example command type precedence may differ Emulating Abstract Command Button Assignments The Emulator provides the device property file definitions command keys lt command_type gt and command menu lt action gt to emulate the way a MIDP implementation on the corresponding real device assigns abstract commands to buttons and menus You specify the button assignments following the considerations specified at the end of the previous section 1 Use the definitions command menu activate and command menu lt action gt to assign the menu operations to buttons See The Abstract Command Menu on page 37 34 Wireless Toolkit Basic Customization Guide December 2003 2 Use the definition command keys lt command_type gt to assign command types to preferred buttons according to their natural correspondence See Assigning an Abstract Command Type to a Button on page 35 3 Use the secondary button assignments to specify alternate buttons for assigning commands of lower priority See Secondary Button Assignments on page 36 Note To achieve an accurate emulation these assignments need to be made in accordance with the way the MIDP implementation for the specific device would make them Precedence of Assigning Commands to a Button In the J2ME Wireless Toolkit commands are assigned to buttons according to the following order of preference
52. ntation class The location can either be a directory path absolute or relative to j2mewtk dir ora jar or zip filename m obfuscate script name The name of a static script file that you use to append to your script which is generated through the createScriptFile method Example For example the Wireless Toolkit has an implementation that executes the ProGuard obfuscator The class name is com sun kvem ktools RunPro and it is located in the ktools zip file in the wtklib directory The properties values are m obfuscator runner class name com sun kvem ktools RunPro m obfuscator runner classpath wtklib ktools zip m obfuscate script name ignore rgs 56 Wireless Toolkit Basic Customization Guide December 2003 You can get the proguard jar file by downloading the zip file from http proguard sourceforge net and extracting the jar file The proguard jar file must be placed in the Wireless Toolkit s bin directory j2mewtk dir bin Appendix B Support for ByteCode Obfuscators 7 58 Wireless Toolkit Basic Customization Guide December 2003 APPENDIX Connecting to the Wireless Toolkit s WMA Emulation Environment The J2ME Wireless Toolkit supports the Wireless Messaging API WMA which enables you to send and receive SMS or CBS messages The Wireless Toolkit s support for messaging includes automatically assigning phone numbers to emulators and routing messages between them You can develop and tes
53. ontain 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 comment s sun com Device Property Files and the Default Emulator The Default Emulator is the customizable device emulator supplied with the J2ME Wireless
54. oolkit 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 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 m m m m m m m m 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 r
55. or bounds 17 82 19 19 button 0 98 578 47 35 button 1 33 459 45 35 button 2 98 464 47 30 button 3 166 459 45 35 button 4 36 498 45 35 button 5 98 503 47 30 button 6 162 498 45 35 bucton 43 537 AT 35 button 8 98 542 47 30 button 9 154 537 47 35 button POUND 151 578 45 29 button ASTERISK 48 578 45 30 button SEND 24 384 39 39 button END 181 384 39 39 button LEFT 71 352 26 63 button RIGHT 147 352 26 63 button UP 97 348 50 22 Appendix A Default Emulator Device Property Files 47 48 button SELECT 97 370 50 28 button DOWN 97 398 50 22 button CLEAR 92 426 58 31 button SOFT1 31 350 39 31 button SOFT2 175 350 36 31 button POWER 157 53 30 30 command keys BACK SOFTI command keys EXIT 1 command keys CANCEL SOFTI command keys STOP SOFTI command keys OK 2 command keys SCREEN SOFT2 command keys ITEM 2 command keys HELP SOFT2 command exclusive SOFT1 BACK EXIT CANCEL STOP command menu activate SOFT2 keyboard handler com sun kvem midp DefaultKeyboardHandler key 0 VK 0 VK_NUMPADO key 1 VK 1 VK NUMPADI key 2 VK 2 VK NUMPAD2 key 3 VK 3 VK NUMPAD3 key 4 VK 4 VK NUMPADA key 5 VK 5 VK NUMPADS5 key 6 VK 6 VK NUMPADG key
56. re two types of fonts available for displaying text on the device screen m Bitmap fonts configured for the Emulator m System fonts of the host PC The device property file can specify the fonts used by the implementation of the MIDP graphics API Fonts Used by the MIDP APIs A font is specified by the MIDP APIs by the property font lt face gt lt style gt lt size gt lt font definition gt where vow m face system monospace or proportional m style plain bold or italic m size small medium or large Chapter 3 Examining Device Property Files 9 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 default lt font properties filename gt lt system font definition gt Example font default Arial plain 12 System Fonts A system font definition is in the standard Java format for specifying such a font For details see http java sun com j2se 1 4 docs api java awt Font html You can tell the Emulator to use th
57. 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 phl_neut png wtklib devices NewPhone phl_press png wtklib devices NewPhone phl_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 phl_neut png 6 Wireless Toolkit Basic Customization Guide December 2003 pressed_buttons_image phl_press png highlighted_image phl_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 obta
58. splayed when the icon is in that state Defining the Icon Location and States The screen location and initial state of the icon is defined by a line of the form icon lt name gt lt x location gt lt y location gt lt initial state gt The icon states are defined by lines of the form icon lt name gt lt state 1 gt lt state 1 image_filename gt icon lt name gt lt state n gt lt state n image filename gt 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 For example icon up 44 110 off icon up off icon up on up gif icon down 44 118 off icon down off icon down on down gif icon internet 64 0 off icon internet off icon internet on internet gif 38 Wireless Toolkit Basic Customization Guide December 2003 icon reception 0 0 on icon reception on reception gif icon battery 80 0 full icon battery full batt_3 gif icon battery half batt_2 gif icon battery low batt_l gif icon battery none batt_0O gif Soft Button Label Display On devices with soft buttons soft button labels are displayed in the area of the screen that is available to icons This area is not directly accessible to the application FIGURE 7 shows the soft button labels Undo and Menu on the lower part of the device screen Soft button labels FIGURE7 Soft Button L
59. t le logo Java Coffee Cup sont des marques de fabrique ou des marques d pos es de Sun Microsystems Inc aux Etats Unis et dans d autres pays UNIX est une marque d pos e aux Etats Unis et dans d autres pays et licenci e exlusivement par X Open Company Ltd Le logo Adobe est une marque d pos e de Adobe Systems Incorporated Les produits qui font l objet de ce manuel d entretien et les informations qu il contient sont r gis par la l gislation am ricaine en mati re de contr le des exportations et peuvent tre soumis au droit d autres pays dans le domaine des exportations et importations Les utilisations finales ou utilisateurs finaux pour des armes nucl aires des missiles des armes biologiques et chimiques ou du nucl aire maritime directement ou indirectement sont strictement interdites Les exportations ou r exportations vers des pays sous embargo des Etats Unis ou vers des entit s figurant sur les listes d exclusion d exportation am ricaines y compris mais de mani re non exclusive la liste de personnes qui font objet d un ordre de ne pas participer d une facon directe ou indirecte aux exportations des produits ou des services qui sont r gi par la l gislation am ricaine en mati re de contr le des exportations et la liste de ressortissants sp cifiquement d sign s sont rigoureusement interdites LA DOCUMENTATION EST FOURNIE EN L TAT ET TOUTES AUTRES CONDITIONS DECLARATIONS ET GARANTIES EXPRESSE
60. t WMA applications entirely within the WTK environment For information on the WMA see http java sun com products wma However if you want to send or receive WMA messages to programs outside of the Wireless Toolkit environment you can use the extension API that is provided by the Wireless Toolkit By using the extension API you can m Send or receive SMS or CBS messages from the emulation environment in the Wireless Toolkit to or from J2SE programs outside the Wireless Toolkit environment This enables you to communicate through WMA messages between MIDlets within the Wireless Toolkit emulators and an external J2SE program This external program can provide whatever functionality you program it to have for example imitating a service that responds to WMA messages m Create a component that acts as a messaging gateway You can write your own J2SE program that registers itself with the Wireless Toolkit as a default gateway The Wireless Toolkit will forward all messages from within the Wireless Toolkit environment that do not have a recognized destination phone number to the default gateway This enables you to extend the Wireless Toolkit WMA environment to other message routing environments for example an actual Short Message Service Center SMSC For information on the extension API see the j2mewtk dir docs wtk wmaBridge directory 59 60 Wireless Toolkit Basic Customization Guide December 2003 Index A abstract command
61. tion Guide December 2003 TABLE 1 TABLE 2 TABLE 3 TABLE 4 TABLE 5 TABLE 6 Tables Example of Device Property Files and DefaultGrayPhone Property File Button Names Available 29 Abstract Command Types in Order of Precedence 33 Alert Type Values 41 Example of Device Property Files 45 Icon Image Files 53 18 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 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 xi screen properties button properties soft button label areas and
62. ture 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 lt button_name gt x y width height where the parameters are as follows m 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 m x The x coordinate of the left edge of the button image in pixels relative to the left edge of the device image m y The y coordinate of the top edge of the button image in pixels relative to the top edge of the device image m width The width of the button image in pixels m height The height of the button image in pixels The button location and dimensions are used for two purposes m To define the active region in which a mouse click is interpreted as a button press m 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
63. types assigning to a button 35 abstract commands assigning to buttons 33 menu operations 37 table of 33 abstract commands types of 33 ascii_x n 21 B bitmap font definition 20 button assignments emulating 34 button properties setting 10 byte code obfuscator 55 C character encodings 42 code obfuscators adding support for 55 color properties 40 setting 16 setting background color 16 colorCount property 40 command menu changing title of 37 D Default Emulator customizing 1 DefaultGrayPhone properties settings 46 device buttons 29 assigning abstract command types 35 assigning abstract commands 33 assigning command keys 35 assigning game actions 32 assigning keys 31 assigning menu operations 34 assignment policies 34 changing soft button labels 37 command precedence 33 defining 29 keyboard handler types 29 order of preference 35 specifying alternate buttons 35 specifying generated characters 32 specifying secondary buttons 36 device image files 22 table of 53 device images scaling 23 specifying image type 23 device property directory 18 device property files 1 adding 2 creating 2 5 structure of 17 syntax 17 table of 45 table of example files 18 display coordinates 26 F font definition 20 font properties ascent 21 descent 21 height 21 leading 21 underlined 22 font property 19 font types bitmap 19 default 19 syste
64. utton Form Polygon Button Form FIGURE6 Specifying a Button Location Assigning a PC Keyboard Key to a Button You can assign a key on the PC keyboard to a device button in order to simulate a button press by pressing the key instead of clicking on the button with the mouse You use a line of the form key lt button_name gt lt virtual key code gt Chapter 3 Examining Device Property Files 1 Note Virtual key codes are defined by the Abstract Window Toolkit in Java 2 Standard Edition The definitions are found in the class java awt event KeyEvent at http java sun com j2se 1 4 docs api java awt event KeyEvent html For example key LEFT VK LEFT More than one PC key may be assigned to a single button using the form key lt button name gt lt list of virtual key codes gt where the virtual key codes are separated by spaces For example key 0 VK 0 VK NUMPADO Assigning a Game Action to a Button The OwertyKeyboardHandler also allows the MIDP game actions to be mapped to device buttons You use a line of the form game lt function gt lt button name gt where function can be one of LEFT RIGHT UP DOWN and SELECT and button name is the name of a button as shown in TABLE 2 on page 29 The default settings are game UP UP game DOWN DOWN game LEFT LEFT game RIGHT RIGHT game SELECT SELECT Specifying the Characters Generated by a Button Press
65. xport 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 Copyright 2003 Sun Microsystems Inc 4150 Network Circle Santa Clara California 95054 Etats Unis Tous droits r serv s Sun Microsystems Inc a les droits de propri t intellectuels relatants la technologie incorpor e dans le produit qui est d crit dans ce document En particulier et sans la limitation ces droits de propri t intellectuels peuvent inclure un ou plus des brevets am ricains num r s a http www sun com patents et unou les brevets plus suppl mentaires ou les applications de brevet en attente dans les Etats Unis et dans les autres pays Sun Sun Microsystems le logo Sun Java Solaris Sun tm ONE Studio Java 2 Platform Micro Edition Wireless Toolkit J2SE JDK e

Sun Microsystems 820-6799

Contents

Download Pdf Manuals

Related Search

Related Contents