To actually compile, be sure to include the API.jar file in your classpath. Assuming you installed the Siemens SDK to the C:SiemensJava directory, you could compile the Test.java program as follows:

javac –g –bootclasspath C:SiemensJavaSDKlibAPI.jar Test.java

You can then pre-verify in much the same way:

preverify –classpath C:SiemensJavaSDKlibAPI.jar;. Test

Finally, to package everything together you can use the JAR command:

jar cf test.jar Test.class

You can now create the JAD Application Descriptor File (ADF) as with any other MIDlet. Details on how to do this are discussed in Chapter 9, “Creating a MIDlet.”

The Siemens SDK comes with a neat little SL45i emulator that enables you to launch either JAD files or raw Java classes.

To load up a class file, click on the Start Java Application line in the Commands window. You can select a JAR file, a JAD file, or even a Java class.

After an application has been downloaded on the emulator, you can run it by selecting the Menu command on the phone itself, then choosing Surf/Fun, Java. Select the application you want, then choose the Option command. The application runs, as shown in Figure 23.1.

Figure 23.1. The Siemens emulator.

The easiest way to test your applications out is to copy the class files over using the Siemens DataExchange software.

Connect your phone to your PC using a valid cable—it should come with the phone, or you can obtain one from Siemens. You can now run the DataExchange software:

You can now run the MIDlet!

Finally, you can use the phone or emulator to actually download your MIDlet over the air (OTA). To do so, be sure to set up a valid JAD file with a MIDlet-JAR-URL attribute that points to a valid URL:

MIDlet-Jar-URL: http://www.myserver.com/MyGame.jar

If you want to test the download locally, just point to the phone's local /java/jam directory:

MIDlet-Jar-URL: file://a:/java/jam/games/MyGame.jar

To create a special Siemens image, just pass a normal Java image into the ExtendedImage class. Because of the way the image might be manipulated, the image width must be divisible by eight.

For example

ExtendedImage im = new (testimage);

You can then modify the image any way you want and use the getImage() method to retrieve a standard Java image.

After you create an ExtendedImage, you can perform all sorts of neat modifications. Many methods take a color parameter. If you are using 2 bits per pixel, then 0 is the transparent color, 1 is white, and 2 or 3 is black. Otherwise, if you are using only 1 bit per pixel, then 0 is white and 1 is black.

Commands include the following:

Alternatively, you can grab the information from an image using

public int getPixel(int x, int y)

or

public void getPixelBytes(byte[] pixels, int x, int y, int width, int height)

To create high-performance graphics, many games will directly modify the video screen, avoiding the overhead of fancy paint and double buffering routes. The process of copying a large array of bits directly into video memory is known as blitting.

You can easily blit with any ExtendedImage. Simply call the blitToScreen(int x,int y) routine, passing in the exact x and y positions you want your image to appear:

myimg.blitToScreen(10,15);

The most typical usage is to draw all sprites, tiles, and so on to an offscreen image, and then blit that big image onto the screen.

A typical game's paint routine would use a GraphicObjectManager to paint all sprites and tiles to an offscreen ExtendedImage, as shown in the following code snippet:

public void paint(Graphics g)
{
  gameScreen.clear((byte)0);
  try
  {
    gfxManager.paint(gameScreen, 0, 0);
    gameScreen.blitToScreen(0,0);
   }
   catch(Exception e) { }
}

A sprite basically consists of two images—a filmstrip of the animated graphic, and a simple black-and-white image representing a mask. A mask can be thought of as a specific shape that has been cut out of a black sheet of paper. The shape is then laid atop your graphic, as shown in Figure 23.2. Any pixels not covered by the cut-out will be transparent.

Figure 23.2. A sprite and its mask.

You can create a mask using most paint programs. Simply throw out the color information from your image, leaving a black silhouette of your sprite.

There are three ways to construct a Sprite using the Siemens API:

Each of these constructors will throw an IllegalArgumentException if the width of the image is not divisible by eight, if there is the wrong number of frames, or if a transparent color is used as either the source or mask image.

So, to create a quick game with a few sprites you could use code similar to the following:

Image frog=Image.createImage("/frog.png");
Image frogm=Image.createImage("/frog-mask.png");
Sprite frogsprite = new Sprite(frog, frogm, 1);
GraphicObjectManager spriteManager= new GraphicObjectManager();
spriteManager.addObject(frogsprite);
sprite.setPosition(10,10);
spriteManager.paint(offscreen, 0, 0);

In your paint method, you could then draw the game screen as follows:

g.drawImage(offscreen, 0, 0, Graphics.LEFT | Graphics.TOP)

Ultimately, you can layer multiple sprites on top of each other to create a full game, as shown in Figure 23.3.

Figure 23.3. Multiple sprites.

You can define your tile using any Java image, ExtendedImage, or a byte array.

Although tiles are often geometric, it often makes sense to use a byte array to create the pattern. Each byte in the array should either be 0 (white) or 1 (black). Each pattern within the array should be 8 pixels wide and 8 pixels high.

You can create as many images as you want within a given array. For example, the following code defines an array of two different tiles—the mountains and the forests. If you squint at the zeros and ones, you can almost make out what the pattern will look like. Figure 23.4 corresponds to the tiles created here:

final static private byte tiles_pixels[] = {
         0,0,0,0,0,0,0,0, // First tile: The mountain
         0,0,0,0,0,0,0,0,
         0,0,0,0,0,0,0,0,
         0,0,0,1,1,0,0,0,
         0,0,1,1,1,1,0,0,
         0,1,1,1,1,1,1,0,
         1,1,1,1,1,1,1,1,
         1,1,1,1,1,1,1,1,

         0,0,0,1,1,0,0,0, // Second tile: The tree
         0,0,1,1,1,1,0,0,
         0,1,1,1,1,1,1,0,
         0,1,1,1,1,1,1,0,
         0,0,1,1,1,1,0,0,
         0,0,0,1,1,0,0,0,
         0,0,0,1,1,0,0,0,
         0,0,0,1,1,0,0,0,
};

Figure 23.4. A custom tile.

Just as we used a byte array to define each tile, the TiledBackground itself can be designed using a byte array. Each byte has a different meaning:

For example, you can create a TiledBackground as follows:

final static private byte map[] = {
0,0,0,0,0,0,0,0, //line with predefined transparent tiles
1,1,1,1,1,1,1,1, //line with predefined white tiles
1,1,1,1,1,1,1,1, //line with predefined white tiles
2,2,2,2,2,2,2,2, //line with predefined black tiles
2,2,2,2,2,2,2,2, //line with predefined black tiles
3,3,3,3,3,4,4,4, //line of hills (3) and trees (4)
3,3,3,3,3,4,4,4, //line with mixed tiles
3,3,3,3,3,4,4,4, //line with mixed tiles
};

You could then draw the new TiledBackground as follows:

TiledBackground tiledBack = new TiledBackground(GraphicObjectManager. createTextureBits(8
,16,tiles_pixels), null, map, 8,8);
tiledBack.setPositionInMap(0,0);
GraphicObjectManager spriteManager= new GraphicObjectManager();
spriteManager.addObject(tiledBack);
spriteManager.paint(offscreen, 0, 0); //draw to doublebuffer image

You could then draw the double buffer offscreen image in your paint method:

g.drawImage(offscreen, 0, 0, Graphics.LEFT | Graphics.TOP)

A sample tiled screen appears as in Figure 23.5, with a bird sprite in the foreground, a ring pattern set of tiles behind that, an 8-ball graphic in the next layer, and a set of geometric tile shapes in the background. Everything moves at once, smoothly and easily. The code for creating this effect can be found in the src directory of the Siemens Toolkit.

Figure 23.5. A tiled background with sprites behind and in front.

Tiling, as you can see, is a great feature that really adds depth and texture to games.

In addition to the generic Sound method, the Siemens API also enables you to take predefined musical notes and piece them together, creating rich and beautiful sounding themes, sound effects, and melodies. Siemens extensions offer the com.siemens.mp.game.Melody class to play melodies composed with the com.siemens.mp.game.MelodyComposer class.

The melodies are based on the custom ring-tones that Siemens users can download to personalize their phones. The melodies have the following features:

For example, you can use various durations of the musical notes C, D, E, F, G, A, H (The H replaces the B in the Siemens API), as well as others, to easily compose complex, rich tunes.

Ais2(1/8) Ais3(1/8) F3(1/8) Gis3(1/8) Dis3(1/8) Cis3(1/16) Ais2(1/8) P(1/16) F3(1/8) Dis3
(1/8) Cis 3(1/16) A2(1/8) P(1/16) F3(1/8) Dis3(1/8) Cis3(1/8 ) Gis2(1/16) Cis3(1/16) C3(1
/16) Gis2(1/16) Ais2(1 /8) Ais3(1/8) F3(1/8) Gis3(1/8) Dis3(1/8) Cis3(1/1 6) Ais2(1/8) P(1
/16) F3(1/8) Dis3(1/8) Cis3(1/16) A2(1/8) P(1/16) F3(1/8) Dis3(1/8) Cis3(1/8)

private void checkCollision()
{
  // Other stuff goes here...
  if (player.getEnergy() <= 0)
  {
      running = false;
      MelodyComposer  comp = new MelodyComposer();
      comp.setBPM(120);
      try
      {
        comp.appendNote(MelodyComposer.TONE_E1,
            MelodyComposer.TONELENGTH_1_4);
        comp.appendNote(MelodyComposer.TONE_D1,
            MelodyComposer.TONELENGTH_1_2);
        comp.appendNote(MelodyComposer.TONE_C3,
            MelodyComposer.TONELENGTH_1_4);
      } catch (Exception ex) {}
      Melody melody = comp.getMelody();
      melody.play();
    }
  }

Would you like to create a game that actually dials the police department if your character performs an illegal action? Although it is highly not recommended to do so, you can using the Siemens API!

Simply call the static start() method of the com.siemens.mp.gsm.Call() object, passing in the phone number:

Call.start("212-555-1212");

Note that once you begin a call, the currently running Java application will automatically be terminated. An IllegalArgumentException is thrown if the number is in an illegal format, or if the phone does not allow calls to be made from Java.

To get all the Missed Dialing Numbers (MDN) currently within the phone's address book, call the getMDN() method within the com.siemens.mp.gsm.PhoneBook object:

String n[] = PhoneBook.getMDN();

If all goes well, a String array with all the numbers will be returned.

Yes, it's true! You can send an SMS message using the Siemens API. To do so, just activate the static send() method within the com.siemens.mp.gsm.SMS object, passing in the destination's phone number and the message you want to send:

SMS.send("212-555-1231","Hi there!");

Most phones will display a dialog box asking the user to confirm whether or not she wants to actually send the SMS.

If the number or the text message is missing or in an incorrect format, an IllegalArgumentException will be thrown. If the SMS network is not available, an IOException will be thrown.

To actually send some data, use the com.siemens.mp.io.Connection class. Construct the Connection class as follows:

Connection conn = new Connection(String connectTo);

The connectTo parameter can be one of several values:

You can then call the send(byte[] data) method to actually send some data. To get a response, use the setListener(ConnectionListener listener) method.

To create a listener, just create a class that implements com.siemens.mp.io.ConnectionListener. You must then add this method to the class

public void receiveData(byte[] data)

If any data is received from the given port, this method will be triggered.

The Siemens SL45i phone, unlike many other mobile devices, has an explicit file system with directories that you can read or write to.

The com.siemens.mp.io.File package contains a bunch of methods that enable you to easily create a file, write to a file, read from a file, or even delete a file.

For security reasons, you may only access files beneath the current Java applet's path. As such, only relative pathnames are valid, and you may not access parent directories using the .. directive.

The first time you run the File class, a special storage directory will be created beneath your applet's directory.