3. Quick Start

To make sure you get off to a flying start, this chapter describes a few simple parts of MIDP so that you can get something running right away. You’ll also have a basic scaffolding upon which to build your later knowledge. Don’t worry if it doesn’t all make sense right away. Everything in this chapter is covered in more detail later in the book.

Fire up your development tool of choice and type as you go along. By the end of this chapter you will have your first running MIDlet.

3.1. Make Something That Runs

Phones and other MIDP devices know how to run MIDlets. A MIDlet is an application. To make your own MIDlet, you need to define a class that extends javax.microedition.midlet.MIDlet.

MIDlet has three methods that must be defined in subclasses:

• startApp() is called to initialize the MIDlet or to resume a paused MIDlet.

• pauseApp() is called whenever the system feels it should pause your application, perhaps in response to an incoming phone call.

• destroyApp() is called when it’s time to clean up your application.

These three methods are callback methods because you don’t get to call them yourself. The system calls them whenever it feels the urge.

For example, if I want to run a MIDlet on my Motorola RAZR V3, I have to go to a GAME.APP menu, which lists all the MIDlet suites installed on my phone. I choose the MIDlet suite I want to run, and if there is only one MIDlet in it, my V3 will create a new instance of the MIDlet class and call its startApp() method. If someone calls me while I’m running the application, my V3 will invoke the MIDlet’s pauseApp() method so I can answer the telephone call. After my conversation is over, my V3 calls startApp() again to resume the application. When I choose to exit the application, my V3 calls the MIDlet’s destroyApp() method.

On other devices (including emulators), the process for launching an application is likely to be different, but the basic life cycle of a MIDlet is the same.

Your first step is to create a new project in your build tool. In the Sun Java Wireless Toolkit, first launch KToolbar, then click on New Project…. Fill in KickButt for the project name and KickButtMIDlet for the class name. Click OK on the next screen. Then create a source code file, {toolkit}appsKickButtsrcKickButtMIDlet.java.

The next step is to write a MIDlet. Here is a simple one to get you started:

You can compile and run it if you wish, but you cannot see anything happening. It is an exceptionally boring MIDlet. I suggest you wait until the next section when you’ll get to see something on the screen.

Don’t worry about that boolean argument in the destroyApp() method. You can read all about it when you get to Chapter 5, “The MIDlet Habitat.”

3.2. Put Something on the Screen

MIDP includes a few ready-made screen classes in the javax.microedition.lcdui package. The one you’ll use first is Form. To create one, specify a title.

To put the TextBox on the screen, use the Display class, which represents the screen of the device. Here is how it works, with the new stuff shown in bold:

This one is worth building and running. It doesn’t do much, but at least you get to see something on the screen. It should look like Figure 3.1.

Figure 3.1. Your very first MIDlet

3.3. Give the User Something to Do

The next step is to let your user make something happen. To this end, MIDP uses a clever mechanism called a command. You create a command by specifying the label you want to appear on the screen. The device or emulator gets to figure out how to show it on the screen and how the user can invoke the command. Your application just has to respond to it.

This mechanism works well because MIDP devices are likely to have different ways for users to make things happen. Many mobile phones have soft buttons, unlabeled buttons that perform different actions depending on what is shown on the screen. Another device might have a click wheel or some more exotic type of input. Using commands ensures that your application can run correctly on a variety of devices.

Commands are fully explained in Chapter 7, “Basic User Interface.”

To respond to a command, you must provide a CommandListener. The listener has a single method, commandAction(), which is called whenever a command is invoked.

In the KickButt example, the MIDlet itself will be a CommandListener. The Command is created and added to the TextBox inside the startApp() method. The call to setCommandListener() tells the system that the MIDlet (this) should be told about any command action that happens on the TextBox.

In commandAction(), the MIDlet checks to see if the command in question is the exit command it created earlier. It should be, because there are no other commands in the application. If so, the application is shut down. Later you’ll use this same kind of logic with more commands.

Try this one on for size (Figure 3.2). In the Sun Java Wireless Toolkit emulator, commands are mapped to soft buttons. Press the soft button below the Exit text on the screen to shut down the application.

Figure 3.2. Now with a command

3.4. Get the Source Code Online

The source code for this book is online. I’m not going to tell you to type all the example code in yourself, but I do encourage you to read it carefully. It’s just as important to your understanding as reading along in the text.

The source code for this book is online at the book’s Web site:

http://kickbutt.jonathanknudsen.com/download.html

3.5. Summary

In this chapter, you built your first MIDlet. You got acquainted with whatever development environment you’re using, and you wrote an application that shows text on the screen and lets the user exit the application. Supported by these little wings, you can now fly into a sky full of the MSA APIs, starting with the basics and progressing through user interface, graphics, storage, networking, multimedia, and others.

At this point, you can pick and choose which topics you wish to read, although reading the rest of the book in order will give you an excellent grasp of the full MSA platform. If you’re going to skip some chapters, I suggest that at a minimum you read about MIDlets, the basic user interface classes, record stores, and basic networking. After that, the sky is the limit.