Technical Manual Motorola T720 Handset Developer Guide Version 1.
Table of Contents INTRODUCTION ............................................................................................................................4 DOCUMENT HISTORY .....................................................................................................................4 OVERVIEW ....................................................................................................................................5 GLOSSARY ...................................................................
Table of Contents CODING EXAMPLE .....................................................................................................................40 BUTTON OVERVIEW .....................................................................................................................40 CHARACTERISTICS OF LWT BUTTONS ..........................................................................................40 ROUNDBUTTON CLASS CODE TOUR ......................................................................
Introduction Welcome to the Motorola T720 Handset Developer’s Guide. This manual contains all the information you need to get started developing software that operates on the Motorola T720 handset.
Introduction Overview The chapters in this manual cover all aspects of developing programs that operate on the Motorola T720 handset.
References The following references provide information related to developing software for wireless devices in general. 6 Organization URL 3GPP www.3gpp.org Brew Development www.qualcomm.com/brew Infrared Data Association www.irda.org JPEG Organization www.jpeg.org Motorola Developer Program www.motocoder.com Open Mobile Alliance www.openmobilealliance.org Qualcomm www.qualcomm.com Sun Microsystems wireless.java.sun.com WAP Forum www.wapforum.org World Wide Web Consortium www.w3.
Hardware Environment Hardware Environment This chapter describes the hardware characteristics of the Motorola T720 handset. Use it to understand the hardware environment in which your software will operate. Hardware Overview The Motorola T720 mobile phone represents the latest generation of 2.5G capable mobile phones from Motorola. For domestic USA and European markets, the Motorola T720 uses GSM/GPRS wireless communications.
CDMA Networks The Motorola T720 uses CDMA wireless technology (in the Asian and S. American versions) to manage voice calls and transfer data. Two channels are allocated for downstream data, and one channel is dedicated to upstream data. This gives the Motorola T720 a theoretical download rate of 153 Kbps. This rate will vary according to the network operator's channel allocation and the signal quality. Connectivity The Motorola T720 handset contains the following connectors: • USB 1.
Hardware Environment Figure 1. The Motorola T720 internal display. The Motorola T720’s display hardware supports a 12-bit pixel depth, with a screen capable of producing up to 4096 colors. With the larger color range, images on the Motorola T720 appear at a much higher quality than on devices whose display hardware limits the palette to 256 colors.
Software Environment This chapter describes the environment of the Motorola T720 handset. Use it to understand the operating system and software environment in which your software will operate. Java™ Support This device supports the following Java™ technologies and their respective APIs: • Java 2 Standard, Micro Edition • MIDP™ 1.0 • CLDC™ 1.0 Devices that support J2ME development are available for the GSM and GPRS networks.
Software Environment MIDP 1.0 The J2ME™ Mobile Information Device Profile (MIDP) lets you write downloadable applications and services for network-connectable, battery-operated mobile handheld devices. For information and documentation, visit: wireless.java.sun.com/midp/ BREW Support The Binary Runtime Environment for Wireless (BREW) is an open-source on-line application development platform for wireless CDMA devices. BREW is designed to allow developers to write in whatever language they choose.
Bundle ID 12 Language Bundle 0005 UK English, French, German, Dutch 0006 n/a 0007 n/a 0008 n/a 000A UK English, Spanish, Portuguese, Greek 000B UK English, Norwegian, Danish, Swedish 000C UK English, Swedish, Finnish, Estonian 000D UK English, Lithuanian, Latvian, Russian 000E UK English, Polish, Czech, Slovak 000F UK English, Hungarian, Turkish, Bulgarian 0010 UK English, Serbian, Slovenian, Croatian 0011 UK English, Russian, Ukranian, Romanian 0012 UK English, Arabic, Hebrew, R
Software Environment Application Language Checking The Motorola T720 supports the ISO-639A language standard. When writing programs that use a specific language, use these guidelines. Upon startup, a MIDlet that supports multiple languages should query the handset to determine which display language is supported by that model. If the language is supported, the MIDlet can then use the language; otherwise, it should use the default language (normally English).
Development Tools This chapter describes the development tools and associated software development kits, and application program interfaces required to create programs that operate on the Motorola T720 handset. NOTE: There are two different development paths for the Motorola T720 depending upon which network the phone is deployed on. For GSM and GPRS networks, the path to use is J2ME. For CDMA networks, the required path is BREW.
Development Tools Licensee Open Class APIs The Motorola Software Development Kit includes several Licensee Open Class (LOC) API packages that make programming specific functionality easier. Just because an LOC is included does not mean it will work on all devices. Always refer to the documentation to find out which mobile devices are supported by a particular LOC. The table below lists each LOC API and provides a brief description. Package Description com.mot.tcc.
needed to write these applications by providing a powerful set of extensible classes ready for use. Registered developers can download a copy of LWT from www.motorola.com/ developers/wireless/.
Developing for the Motorola T720 Handset Developing for the Motorola T720 Handset This chapter provides the information you need in order to create, debug, download, and packaging of programs written for the Motorola T720 handset. Developing Programs This section provides the basic resources available and key mapping information needed to develop applications for the Motorola T720 handset.
~500 Max number of Files/RMS* Java VM 512 KB Heap Space Program Space Data Space* Recommended JAR Size Maximum JAR Size Motorola T720 Motorola T720i 640K 512K Motorola T720 Motorola T720i 384K 512K 50-100 KB 200 KB * These resources are shared with the rest of the phone and there could be less available to Java at any given time. Zoom In and Zoom Out Modes The Motorola T720 supports zoom in and zoom out modes on the display.
Developing for the Motorola T720 Handset Key Mapping Information The key map information for the Motorola T720 handset is as follows: Key Number (KN) Key Code (KC) Game Action (GA) # (pound) 35 0 * (asterisk) 42 0 0 48 0 1 49 GAME_A 2 50 0 3 51 GAME_B 4 52 0 5 53 0 6 54 0 7 55 GAME_C 8 56 0 9 57 GAME_D Down Arrow -11 DOWN Left Arrow -12 LEFT Left Soft Key -20 0 Right Arrow -13 RIGHT Right Soft Key -21 7 Send (Enter) -14 FIRE Up Arrow -10 UP - (min
KN: RIGHT SOFT KEY KC: -21 GA: 7 KN: LEFT SOFT KEY KC: -20 GA: 0 KN: RIGHT ARROW KC: -13 GA: RIGHT KN: UP ARROW KC: -10 GA: UP KN: DOWN ARROW KC: -11 GA: DOWN KN: LEFT ARROW KC: -12 GA: LEFT KN: 3 KC: 51 GA: GAME_B KN: 2 KC: 50 GA: 0 KN: 6 KC: 54 GA: 0 KN: 1 KC: 49 GA: GAME_A KN: 9 KC: 57 GA: GAME_D KN: 4 KC: 52 GA: 0 KN: 7 KC: 55 GA: GAME_C KN: 8 KC: 56 GA: 0 KN: * KC: 42 GA: 0 KN: # KC: 35 GA: 0 KN: 5 KC: 53 GA: 0 Figure 2.
Developing for the Motorola T720 Handset Creating Programs This section explains how to use the CodeWarrior™ IDE to create MIDlets. A MIDlet is a Java™ application that conforms to two specifications defined by Sun® Microsystems: • the Connected, Limited Device Configuration (CLDC) and • the Mobile Information Device Profile (MIDP) These specifications define requirements that Java applications must adhere to in order to run on a mobile device.
Figure 3. New window 2 Select Java J2ME Stationery. 3 Name the project. Type a name for the project in the text field labeled Project Name. If you want your project to be recognized by all versions of CodeWarrior tools on all host platforms, the filename extension must be .mcp. If you do not type a filename extension, the IDE automatically adds the .mcp extension to the filename. 4 Specify the project directory Click the Set... button. The Create New Project... window appears (Figure 4).
Developing for the Motorola T720 Handset Check the Create Folder check box to indicate that you want to create a new folder that will contain all of the project files. The new folder has the same name as the project file without the file extension. 6 Click the Save button to create the new project directory, and return to the New dialog box. 7 Click the OK button. The IDE displays the New Project window. 8 Click on the tree control (+) to expand the list of Generic stationery.
Figure 6. Project Window displaying project created from J2ME Stationery The CodeWarrior project manager also creates a directory named ProjectName Data, where ProjectName is the name of your project. The CodeWarrior IDE uses this directory to store internal data. Do not modify or move any files in this directory. A project that is created from stationery contains example source files, and other files that provide you with a starting point for your project.
Developing for the Motorola T720 Handset Figure 7. New Window 2 Select MIDP Midlet Wizard. 3 Name the project. Type a name for the project in the text field labeled Project Name. If you want your project to be recognized by all versions of CodeWarrior tools on all host platforms, the filename extension must be .mcp. If you do not type a filename extension, the IDE automatically adds the .mcp extension to the filename. 4 Specify the project directory. Click the Set... button. The Create New Project..
The IDE saves the location and returns to the New window. 6 Click the OK button. The IDE displays the New MIDP MIDlet: Page 1 of 3 window (Figure 9). MIDlet Wizard - Page 1 of 3 The first page of the wizard (Figure 9) lets you define basic properties of the MIDlet, such as the class and package name. Fill in the appropriate fields and click Next button to show the next page of the wizard. Figure 9.
Developing for the Motorola T720 Handset MIDlet Wizard - Page 2 of 3 Page 2 of 3 (Figure 10) of the wizard lets you specify information about the form class for the MIDlet. Fill in the appropriate fields and click Next button to show the next page of the wizard. NOTE: Skip this section if you did not check the Create an initial form check box in the MIDlet Wizard - Page 1 of 3. Figure 10.
MIDlet Wizard - Page 3 of 3 This page of the wizard (Figure 11) contains information that the IDE can insert into each of the source code files it generates. Fill in the appropriate fields and click Finish button to show the Summary page of the wizard. Figure 11. New MIDlet MIDlet: Page 3 of 3 The components found in Page 3 of 3 include: 28 Component Description Application Type the title for the MIDlet.
Developing for the Motorola T720 Handset MIDlet Wizard - Summary To complete the wizard and generate the project just review the attributes that you have specified, then click the Generate button. The CodeWarrior IDE creates the project files and a project folder for a new MIDlet project. The CodeWarrior IDE displays a new Project window (Figure 4.11). Figure 12.
2 Access the Java Output settings panel (Figure 13). Select Java Output in the Target Settings Panels list on the left side of the window. The IDE displays the Java Output settings panel. Figure 13. Java Output Settings Panel with Preverification Enabled 3 Check the Preverify check box. 4 Click on the Apply button. The IDE saves the change to the target settings for this build target. The next time that you build the build target, the IDE will run the preverification tool against the MIDlet.
Developing for the Motorola T720 Handset 5 Click the Apply button. Figure 14. Java Target settings panel with Virtual Machine list Running a MIDlet To run a MIDlet: 1 Make sure the MIDlet project is open in the Project window. 2 Make sure the current build target is the one you want to run. 3 Select Project > Run from the main menu bar. The CodeWarrior IDE starts the VM you specified in Java Target settings panel, and runs the MIDlet in that VM.
MIDlet Debugging Setup In CodeWarrior Wireless Studio, use the Java Target settings panel (Figure 15) in the Target Settings window to specify: • Virtual Machine: Mot J2ME SDK 3 E7.5 • Target device: Simulator • Simulator Config. File: Motorola T720 Figure 15. Java Target settings panel showing debug setting for Motorola T720 Debugging a MIDlet To debug a MIDlet using the CodeWarrior IDE: 1 Make sure the MIDlet project is open in the Project window.
Developing for the Motorola T720 Handset Downloading Programs This section explains how to download a MIDlet program to the Motorola T720 handset. Serial Downloading By default, the serial downloading of programs is disabled on Motorola T720 handsets. It is recommended that you use OTA instead to load programs on the device for testing.
For more information on downloading files using a WAP Browser, see the WAP SDK Browser User Guide. Installing Programs This section provides a program checklist, and information on the running and exiting programs on the Motorola T720 handset. Installation Checklist Here is a checklist of items to review before attempting to download a program to the Motorola T720 handset for testing. Following this checklist will ensure that you don’t waste testing time.
Developing for the Motorola T720 Handset Note, there are exceptions to this size limitation, typically related to the number of class files versus resource files in the JAR file. • Memory Full–There is not enough data space to both install the JAR file and store MIDlet resources. There must be enough room to both uncompress the JAR file in heap space and store the resources associated with it in data space. Once uncompressed into a MIDlet, the JAR file is deleted.
Packaging Programs When developing applications, there are two situations to be aware of when packaging your applications for loading on the device. 36 • Accessing external libraries or resources–in this situation, make sure that all the necessary libraries and resources are placed in the JAR file so that the application has access to them on the device.
Developing for the Motorola T720 Handset Troubleshooting This section describes some common troubleshooting issues and their solutions. Title Applications consume more space on the Motorola T720 than other devices. Problem The application consumes much more size when downloaded to Motorola T720 devices or use Motorola T720 emulator. The Motorola i95cl (actual device as well as emulator) uses approx 340KB of heap.
Title OTA installation failed on Motorola T720. Problem While downloading an application to the Motorola T720, an OTA failed message comes up:"File corrupt". Does this mean the JAD/manifest files are incorrect, class files are not correctly preverified…etc.? Solution In the event you experience problems, check the following: 1. Make sure ALL the fields in JAD file are EXACTLY IDENTICAL to the fields in the manifest inside the JAR. And I mean *EXACTLY*.
Developing for the Motorola T720 Handset Title Determining the font size used in the Motorola T720 in various regions. Problem Different regions use different font sizes in the device. A program needs to consider the font size when it comes to drawing to the screen to avoid display errors. Solution You can use the Java method Font.getHeight() to determine the size of the visible font for all regions. The method returns the standard height of a line of text in the current font.
Coding Example This chapter explores how you can extend the capabilities of the Lightweight Windowing Toolkit’s (LWT) Button class to enhance a program with unique components. It is not meant to be a tutorial on LWT or using the Button class, but to demonstrate how easy it is to expand LWT for special purposes. Button Overview The program displays several LWT Buttons and two custom RoundButtons on the device's screen. You use the navigation keys to select the different Buttons.
Coding Example This lesson demonstrates the capabilities of one LWT UI component, the Button class. The Button class provides a simple and effective way to add interactive buttons to your application’s interface. LWT buttons have the following features: • They can have different, descriptive labels. Within limits, a button automatically resizes itself to accommodate the text string that makes up the label. • They can be placed on the screen using a variety of offset schemes.
Figure 16. The simulator displaying LWT buttons. You’ll notice that where LWT objects can’t fit entirely on the screen, the LWT displays a scrollbar at the right of the screen. You can’t interact with the scrollbar; it’s used to indicate that some of the application’s UI is off-screen. You use the navigation button to see these hidden UI elements. Step 3: Observe the button’s behavior Click on the Motorola T720’s navigation button or use the keyboard’s arrow keys to navigate down the screen.
Coding Example Press on the phone simulator’s End key (which represents the LWT’s Enter key) and hold it down. Watch what happens to the button (Figure 18). Release the key, and the button reverts to its normal state. Figure 18. The LWT button when the Enter key (the End button) is pressed. The highlighting that occurs indicates that the button has received and accepted an Enter key press. This different appearance represents the button’s pressed state.
Figure 20. The second round button has focus ownership. Note that the screen has scrolled. Observe how the screen has automatically scrolled to fully display the second button. This vertical scrolling is a feature provided by the LWT. If you press the down arrow on the navigation button again, the focus jumps back to the topmost button on the screen. The screen also scrolls back up to the top, so that you’re looking at a screen that resembles Figure 17.
Coding Example public class RoundButton extends Button { String label; // The Button's text /** * Constructs a RoundButton with no label. */ public RoundButton() { this(""); } /** * Constructs a RoundButton with the specified label. * @param label the label of the button */ public RoundButton(String label) { int x, y; this.
/** * gets the label * @see setLabel */ public String getLabel() { return label; } /** * sets the label * @see getLabel */ public void setLabel(String label) { this.label = label; repaint(); } These methods, getLabel() and setLabel(), fetch the string that represents the RoundButton’s label or sets it, respectively.
Coding Example One thing to note is that we reduce the drawing rectangle’s size by five pixels. This is so that the button and its focus border (which must be slightly larger than the button) can be drawn safely within the rectangle that comprises the actual component. If you draw outside of the component’s rectangle, a portion of the image is clipped. The next section of code tests to see if the round button component has focus ownership (isPressed() returns true).
Finally, the code draws the button’s label. It first sets the color that’s used to draw the string, based upon the buttons’s state. That is, for the normal state, the text is set to black, otherwise, it is set to white to represent the pressed state. The getFont() method fetches the string’s typeface information. The typeface’s dimension information is used to center the text string within the button.
Coding Example LWT manages this for you, and as the RoundButton code shows, you merely query these state values as you paint the component. The LWT will issue a repaint request every time a component’s state changes. Because of how getPreferredWidth() and getPreferredHeight() are implemented, the button automatically sizes itself to accommodate the label’s width. Feel free to try this by editing the label in the statements that make the round buttons.
Modify a Button’s Characteristics Let’s examine ButtonDemo’s constructor in more detail to see how LWT buttons are made, and how their visibility and screen location can be changed. Scroll through the Buttons.java file with the editor to find: // The constructor for our screen public ButtonScreen() { // First button b1 = new Button("Button"); add(b1); // Second button, set to fill the screen b2 = new Button("Large Button"); b2.setRightEdge(Component.SCREEN_RIGHT, 0); b2.setBottomEdge(Component.HEIGHT, b2.
Coding Example } // end constructor As the code shows, using an LWT button is straightforward. You use the new constructor and then the add() method to add the button to a LWT ComponentScreen. (The instance of a ComponentScreen is made in the class DemoScreen.) Making a RoundButton is no different: you use its new constructor and add it to the ComponentScreen. Finally, you assign each button a listener, even if it is disabled.
Figure 21. The screen after the second button was made invisible and the fourth button is disabled. Step 4: Watch the change of focus ownership. Use the navigation button to traverse the focus among the enabled buttons. You’ll see that only two of the buttons receive focus ownership: the first button b1, and the second round button, b5. There are several other statements in the ButtonDemo constructor that you can uncomment to disable other buttons or make them invisible.
Coding Example Step 1: Change a button’s offset scheme Locate the code for the fifth button, b5, in the ButtonScreen’s constructor. Uncomment the statement: // b5.setLeftEdge(Component.PREVIOUS_COMPONENT_RIGHT, 0); What this statement does is offsets b5’s left edge to the right edge of the previous component, which is the round button b4. Step 2: Build and start the program under debugger control Issue the Debug command (Project | Debug) to have CodeWarrior’s IDE make the program and start the debugger.
This statement has the b5 button’s top edge offset from the top edge of the preceding component, not from its bottom. The second argument can supply a pixel value to add to this offset. Since it’s zero for this example, the b5 button’s top will be aligned to the top of the button b4. Step 5: Run the program and observe the effect of the offset scheme Issue the Debug command (Project | Debug) to have CodeWarrior’s IDE make the program and start the debugger. Now issue the Run command (Project | Run).
Index Index 3GPP, 6 AMR, 5 battery info, 9 Binary Runtime Environment for Wireless, 11 BREW, 11 CDMA, 8, 11 CDMA 1XRTT, 7 CDMA 800/1900, 7 CLDC, see Connected Limited Device Configuration, 10 CodeWarrior Wireless Studio, 15 com.mot.tcc.media, 15 com.motorola.game, 15 com.motorola.lwt, 15 com.motorola.
VM, selecting, 30 W3C, 6 WAP, 5 56 WAP Forum, 6 WAP support, 11
MOTOROLA and the Stylized M Logo are registered in the U.S. Patent & Trademark Office. All other product or service names are the property of their respective owners. Java and all other Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. © Motorola, Inc. 2003.
