Siemens

Like Nokia, Siemens seem to take J2ME development (especially game development) quite seriously. They have expanded beyond MIDP 1.0 with an SDK that provides access to many of the features of their handsets, including:

• Messaging using SMS

• Placing a call

• Play sounds and tunes

• Control-device features such as vibration and lights

• Advanced graphics tools that let you draw and manage sprites, create tiled backgrounds, and directly access pixel data (but don't get too excited)

In the next few sections, you'll take a closer look at these features.

Installing

To get started you should download the SMTK (Siemens Mobility Toolkit) for Java from the Siemens Developer Portal at https://communication-market.siemens.de/portal. The SMTK provides the core tools, including the Siemens MIDP extensions API, along with good integration with JBuilder and Sun ONE Studio. However, the SMTK does not include any emulators; you will need to download at least one emulator to get things moving. (The M55 is a good emulator to use.) Once you have downloaded the SMTK and your selected emulator, go ahead and install both.

You can use the SMTK Manager (shown in Figure 6.9) to verify that the emulator is installed and ready to go. If you have multiple emulators installed, you can use the SMTK Manager to switch between them.

Setup Development

To begin using the Siemens API in your MIDlets, you need to locate the library JAR, a file called api.jar (bet it took them a while to come up with that name), located in the lib subdirectory of your SMTK installation. Add this to your CLASSPATHor if you're like me, just copy it into a directory that is already on your CLASSPATH.

You can run any of the emulators you've downloaded by navigating to the associated directory and using Emulator.exe. Once this is loaded, use the Actions panel and choose Start Java Application. Figure 6.10 shows the SL55 emulator running a simple image-draw test. As you can see from the results, the SL55 emulator supports PNG transparency.

Now that you're set up for development, take a look at the Siemens API.

SMS and Phone API

You can use the Siemens GSM (Global System for Mobile Communications) tools to send an SMS and even initiate a phone call. These facilities are available through the com.siemens.mp.gsm package in the classes Call, Phonebook, and SMS. You can see a complete list of these classes in Table 6.9.

Table 6.9. com.siemens.mp.gsm Classes

Class	Description
Call
static void start(String number)	Initiates a call from the handset. (Watch outyour MIDlet will terminate after calling this method.)
PhoneBook
static String[] getMDN()	Returns a string array of the Missed Dialed Number list.
SMS
static int send(String number, byte[] data)	Sends a byte array as an SMS to a number.
static int send(String number, String data)	Sends a string as an SMS to a number.

Placing a call is extremely easy. Here's an example:

Call.start("555-5555-5555");

If you make this call and the phone doesn't support calling from a MIDlet, it will throw a com.siemens.mp.NotAllowedException. If the number is not valid, you'll get an IllegalArgumentException. One very important thing to keep in mind: If the call is successful (the number is okay and the MID supports this function), your MIDlet will immediately terminate. Doesn't sound so useful after all, eh?

Sending an SMS is just as simple, and you don't get rudely terminated. Here's an example:

SMS.send("555-5555-5555", "Hi mom!");

Incorrectly formatting the number will cause an IllegalArgumentException. If the function is not supported or the network is not available, an IOException will result. One thing to keep in mind: The phone might prompt the user to confirm that a message should be sent (given that a message usually has an associated cost).

Device Control

Two primary device control functions are available to a MIDletbacklight and vibration (Table 6.10 lists the API for these classes). Controlling the backlight is a pretty nice effect. For example, you can make it flash when a player wins a level. Unfortunately, just like with Nokia's UI API, you cannot determine the current state of the backlight before you enable or disable it. Take care when you turn it off because you might leave the player quite literally in the dark.

Table 6.10. Device Control Classes

Class	Description
com.siemens.mp.game.Light
static void setLightOn()	Turns on the backlight.
static void setLightOff()	Turns off the backlight.
com.siemens.mp.game.Vibrator
static void startVibrator()	Starts vibrating.
static void stopVibrator()	Stops vibrating.
static void triggerVibrator(int duration)	Sets vibration for a certain amount of time.

Here's an example of turning the light on and then off:

Light.setLightOn();
Light.setLightOff();

You have similar control over vibration on the device. This lets you add a nice sense of realism to those heavy weapon impacts or car smashes. To control vibration, use the startVibrator and stopVibrator methods, just like you did using the Light control. You can also use the triggerVibrator method to vibrate for a fixed period. For example:

Vibrator.startVibrator();
Thread.sleep(500);     // wait for half a second
Vibrator.stopVibrator();

Sounds and Tunes

The first and easiest way to get some sound out of a Siemens MID is by using the Sound class's playTone method (Table 6.11 has the full API). This simple method plays a sound at a particular frequency (in Hz) for a period of milliseconds. For example:

Sound.playTone(550, 1000);

Table 6.11. Device Control Classes

Class	Description
com.siemens.mp.game.Sound
static void playTone(int frequency, int time)	Plays a tone at a certain Hz for a period of time (in milliseconds).
com.siemens.mp.game.MelodyComposer
MelodyComposer()	Constructs a new MelodyComposer.
MelodyComposer(int[] notes, int bpm)	Constructs a new MelodyComposer with a list of notes and initial BPM.
void appendNote(int note, int length)	Appends a note to this object.
Melody getMelody()	Gets the Melody object ready for playback.
int length()	Returns the number of notes in the current melody.
static int maxLength()	Returns the maximum number of notes you can use.
void resetMelody()	Clears the current melody and starts again.
void setBPM(int bpm)	Sets the beats per minute.
com.siemens.mp.game.Melody
void play()	Starts playing the melody.
static void stop()	Stops the current melody. (Notice that this method is static.)

Thankfully there are other sound-playing options with a little more sophistication than playTone. Using the MelodyComposer class, you can use common musical constructs to create complex songs and then play them using the Melody class. (Refer to the Siemens API javadoc for a full list of the musical constructs available.) Here's an example that creates and plays a simple tune:

try
{
   MelodyComposer composer = new MelodyComposer();
   composer.setBPM(90);
   composer.appendNote(MelodyComposer.TONE_A2, MelodyComposer.TONELENGTH_1_4);
   composer.appendNote(MelodyComposer.TONE_C2, MelodyComposer.TONELENGTH_1_4);

   composer.getMelody().play();
}
catch(Exception e)
{
   // Handle the generic exception being thrown by the MelodyComposer class
}

In this code you simply construct a MelodyComposer, add some notes to it, and then extract the resulting melody, which you then play. The try-catch block is there because the MelodyComposer throws the generic exception. (There's no documentation as to why the MelodyComposer would throw a generic exception, and thus I have no idea how to handle itpoorly done.)

Advanced Graphics and Gaming

The good news is that the SMTK includes an extensive set of classes to assist with advanced graphics and other gaming requirements. The classes available are all within the com.siemens.mp.game package:

• Sprite. This is an animated graphic with basic collision detection.

• ExtendedImage. This provides functionality to manipulate 1- or 2-bit images (black and white or black, white, and transparent).

• GraphicObject. This is an abstract base class representing a visible graphical object.

• GraphicObjectManager. This is a manager class for ordered drawing of a collection of GraphicObjects.

• TiledBackground. This is a limited tiling system.

The bad news is that of these classes, the only particularly useful one is ExtendedImage, which provides a limited form of pixel manipulation for 1- or 2-bit graphics. The Sprite and other game-oriented classes (GraphicObject, GraphicObjectManager, and TiledBackground) are relatively poor implementations of what you'll be doing in later chapters. If you're just starting out, you only want to develop on Siemens phones, and if you like painting naked camels, then you might benefit from these classes. Frankly, I wish Siemens had spent their programmer time (and class space) on developing better device functionality, such as color pixel manipulation or image reflection and rotation. Sprites and object managers are a great idea, but only if implemented well (and the Siemens Game API is far from that). Look toward MIDP 2 for a better implementation of some of these concepts (such as layers).