Contents Previous Next Index

Appendix   A

Application Demonstrations


This appendix describes the application demonstrations that are bundled with the J2ME Wireless Toolkit.

A.1 Overview

The J2ME Wireless Toolkit includes demonstration applications that highlight some of the technologies and APIs that are supported by the emulator.

The following table lists all the demonstration applications that are included in this release. The demonstrations that are new or enhanced in this release are marked with new.

The goal of these demonstrations is to give you a glimpse of the API features of the emulator and the enhancements throughout the toolkit.

Most demonstration applications are simple to run. The next section contains instructions for running most demonstrations. Demonstrations that have additional documentation are linked in the table below.

The source code for every demonstration application is available in the {toolkit}\apps directory. Subdirectories contain projects, and each project has a src directory that contains Java source code. For example, if the toolkit is installed in \WTK22, the source code for the SMS sender MIDlet (example.sms.SMSSend) in WMADemo is contained in \WTK22\apps\WMADemo\src\example\sms\SMSSend.java.

TABLE 8  –  Application demonstrations
 
Demonstration
APIs
Description
Special Instructions
 
Audiodemo
MMAPI 1.1
Demonstrates audio capabilities, including mixing and playing audio with an animation
 
 
new
BluetoothDemo
JSR 82 Bluetooth
Demonstrates device discovery and data exchange using Bluetooth
 
Demo3D
JSR 184 Mobile 3D Graphics
Contains MIDlets that demonstrate how to use 3D graphics, both immediate mode and retained mode
 
Demos
MIDP 2.0
Includes various examples: animation, color, networking, finance, and others
 
 
FPDemo
CLDC 1.1
Simple floating point calculator
 
 
Games
MIDP 2.0
Includes TilePuzzle, WormGame, and PushPuzzle
 
 
JSR172Demo
Web services
Demonstrates how to use the JSR 172 API to connect to a web service from a MIDlet
new
mmademo
MMAPI 1.1
Demonstrates MMAPI features, including tone sequences, MIDI playback, sampled audio playback, and video
 
NetworkDemo
MIDP 2.0
Shows how to use datagrams and serial connections
 
new
ObexDemo
JSR 82 OBEX
Demonstrates transferring data using OBEX over IrDA
new
PDAPDemo
JSR 75 PIM and FileConnection
Shows how to manipulate contacts, calendar items, and to-do items. Demonstrates accessing local files.
 
Photoalbum
MIDP 2.0
Demonstrates a variety of image formats
 
 
UIDemo
MIDP 2.0
Showcases the breadth of MIDP 2.0's user interface capabilities
 
new
WMADemo
WMA 2.0
Shows how to send and receive SMS, and CBS, and MMS messages

A.2 General Instructions

It's usually very simple to run one of the demonstration applications. This section describes the general procedure. More detailed instructions for specific demonstrations are referenced in the table above.

The first step is to run KToolbar. To do this, go to the Windows Start menu and choose Start > Programs > J2ME Wireless Toolkit 2.2 > KToolbar. The KToolbar window pops up:

FIGURE 40  –  KToolbar

KToolbar

Click on the Open Project... button to open a demonstration application. You'll see a list of all the available applications.

FIGURE 41  –  Opening a demonstration application project

Opening a demonstration application project

Select one and click on the Open Project button in the dialog.

Once the application is opened, all you need to do is press the Run button. The device emulator will pop up running the example application. Choose a specific demonstration to run from the menu and press the soft button for Launch.

Some demonstrations require other setup and instructions. Check the full list to see if there are specific instructions for a demonstration.

A.3 BluetoothDemo

This application contains a MIDlet that demonstrate the use of JSR 82’s Bluetooth API.

Bluetooth Demo shows how images can be transferred between devices using Bluetooth. You will need to run two instances of the emulator to see how this demonstration works.

In the first emulator, choose Bluetooth Demo, then Server. The emulator will ask you if you want to allow a Bluetooth connection. Choose Yes. The server starts up and displays a list of images. At the beginning, none of the images are being made available on the Bluetooth network. To make images available, select them and choose Publish image from the menu. Images with a green icon are published, while those with a purple icon are not.

FIGURE 42  –  Running the Bluetooth Demo server

Running the Bluetooth Demo server

On the second emulator, choose Bluetooth Demo, then Client. The MIDlet tells you it’s ready to search for images. Choose Find. The MIDlet will find the other emulator and get a list of images from it. Select one from the list and choose Load. The emulator asks if you want to allow the connection. Choose Yes.

In the first emulator, the server, a prompt appears, asking if you want to authorize the connection from the client. Choose Yes. The image is transferred via simulated Bluetooth and shown on the client emulator.

FIGURE 43  –  An image transferred via simulated Bluetooth

An image transferred via simulated Bluetooth

You can avoid the permission prompts by running the demonstration in the trusted protection domain.

A.4 Demo3D

This application contains three MIDlets that show off the emulator's support of JSR 184, the Mobile 3D Graphics API.

A.4.1 Life3D

Life3D implements the popular Game of Life in three dimensions. Live cells are represented by cubes. Each cell has 26 possible neighbors (including diagonals). For each step of the animation, cells with fewer than 4 neighbors die of loneliness, while cells with more than 5 neighbors die of overcrowding. An empty cell with exactly 4 neighbors will become a new live cell.

The view of the playing board rotates slowly so you can view the board from all angles.

FIGURE 44  –  The Game of Life in three dimensions

The Game of Life in three dimensions

The keypad buttons provide control over the game.

TABLE 9  –  Controls for Life3D
Button
Description
0
Pause the animation
1
Resume the animation at its default speed
2
Speed up the animation
3
Slow down the animation
4
Choose the previous preset configuration from a list that includes gems like P4 Glider, Skew beehive plus, and P4 Rotor.
5
Choose the next preset configuration from the list.
*
Generate a random configuration and animate until it stabilizes or dies. If it dies, generate a new random configuration.

This source code for this example is particularly well-documented. Take a look at {toolkit}\apps\Demo3D\src\com\superscape\m3g\wtksamples\life3d\Life3D.java.

A.4.2 PogoRoo

PogoRoo shows you the rear end of a kangaroo bouncing up and down on a pogo stick.

FIGURE 45  –  A bouncing kangaroo

A bouncing kangaroo

You can get the kangaroo to bounce around the landscape by using the arrow keys. Push up to go forward, down to go backward, and left and right to change direction. You might need to hold down the keys to see an effect.

A.4.3 retainedmode

The retainedmode MIDlet plays back a scene file that shows a tireless skateboarder in an endless loop.

FIGURE 46  –  A tireless skateboarder

A tireless skateboarder

A.5 JSR172Demo

JSR172Demo shows how to access a web service from a MIDlet. The web service is already running on an Internet server. You should be able to simply build and run the example.

If you are behind a firewall, you’ll need to configure the emulator’s proxy server settings. Choose Edit > Preferences... from the KToolbar menu, then select the Network Preferences tab. Fill in the proxy server addresses and ports.

JSR172Demo contains a single MIDlet, Server Script. Launch it and follow the prompts. You can browse through simulated news headlines, all of which are retrieved from the web service.

To see what’s going on behind the scenes, use the network monitor.

A.6 mmademo

The mmademo application contains four MIDlets that showcase the multimedia capabilities of the J2ME Wireless Toolkit. This section describes the MIDlets and includes additional information about using multimedia from your applications.

A.6.1 Simple Tones

The Simple Tones example demonstrates how to use interactive synthetic tones. The first menu entries play tones with different pitch and duration using Manager.playTone(). Choosing the third menu item will play a chord on the interactive MIDI device (locator "device://midi"). The shortMidiEvent() method of MIDIControl is used to trigger the notes of the chord.

A.6.2 Simple Player

The Simple Player application demonstrates the range of audio and video capabilities of the emulator. It includes example files in a variety of formats and can play files from the emulator's persistent storage or from HTTP URLs.

The player portion uses a generic javax.microedition.media.Player interface. The player displays duration, media time, and controls for running the media file. If metadata is available in a file, the player enables you to view the information, such as author and title. In the case of MIDI files, if karaoke text is present in the file, it displays on the screen during play. Graphical user interface controls can be viewed on the display screen if applicable. You can access these controls by selecting one of the media samples in Simple Player, then pressing the Menu button to view and select the desired command.

The demo includes the following media samples:

In addition, Simple Player parses ring tones in Ringing Tones text transfer language (RTTTL). See http://www.convertyourtone.com/rtttl.html for information on RTTTL.

A key feature of Simple Player is a common set of commands that control media playback. The commands are available from the Simple Player menu, and some have associated keypad buttons. The following table describes these commands.

TABLE 10  –  Simple Player commands
Command
Key
Description
Mute/Unmute
0
Turns off sound but the file continues to play. This command toggles to Unmute.
Volume
* and #
Increases or decreases loudness.
META Data
 
Displays information provided by the media file such as copyright information, title, and track list.
Stop in 5 seconds
 
Pauses the audio play in five seconds when set during playback.
Rate
4 and 6
Alters the rate of speed of playback.
Tempo
 
Increases or decreases the tempo of the tone sequence or MIDI file.
Pitch
Up and down
Lowers or raises the notes in a MIDI file.
Start/Stop Recording
 
Records the audio playback. A file is created containing the recorded audio in the directory in which the emulator is running. If you do not specify a filename, a file called recording.wav is created. This command toggles to Stop Recording.
Step Frame
7 and 9
Jumps forward or backward one frame at a time in a video file.
Play/Stop
2 and Select
Starts or stops the media.
Loop Mode
 
Plays back the audio file immediately after completion of play. Running Loopmode once plays the audio file once. Pressing a second time plays the file three times. Pressing a third time plays the file repeatedly. Pressing a fourth time returns to single play.
Skip
1 and 3
Skips forward or backward five percent of the duration of the media file. The sound track syncs to the video.
Rewind
 
Returns to the start time of the audio playback.
Stop and Rewind
5
Stops plaback and rewinds to the start time.
Quick Help
 
Displays a list of commands and keypad buttons.

The commands may or may not be available depending on the media type that Simple Player is playing. In addition, some commands can be invoked using the keypad buttons. The following table describes the availability of commands, their keypad equivalents, and the relevant class from MMAPI.

Note that a short list of commands and the corresponding keypad buttons is available in the Simple Player application itself. Just choose the Quick Help command from the menu.

A.6.3 PausingAudioTest

This MIDlet exists to demonstrate how the J2ME Wireless Toolkit will warn you if a paused MIDlet has not stopped its running Players. After you launch the MIDlet, choose the Play command to start playing some audio. The screen displays a status, which is either “Well-behaved” or “Not Well-Behaved.”

Pause the MIDlet by choosing MIDlet > Pause from the emulator window’s menu. As expected, the MIDlet is paused and no message is displayed on the KToolbar console. Restart the MIDlet by choosing MIDlet > Resume from the emulator window’s menu.

Now choose the Misbehave command. Pause the MIDlet again. In the KToolbar console, you will receive a short lecture about how well-behaved MIDlets release resources when they are paused.

A.6.4 Video

The Video application illustrates how the emulator is capable of playing animated GIF files and capturing video. On a real device with a camera, video capture can be used to show the user what the camera sees.

Animated GIFs and video capture can be implemented using either a Form Item or a Canvas. The Video demonstration includes all the possibilities:

A.6.5 Attributes for mmademo

The mmademo applications have the following attributes that you can modify in the User Defined tab of the project settings dialog box:

TABLE 11  –  Descriptions of MMAPI-specific MIDlet attributes
Attribute
Description
PlayerTitle-<n>
Name of the nth media title to be played back by the Simple Player MIDlet.
PlayerURL-<n>
Location of the nth media title, PlayerTitle-<n>, to be played back by the Simple Player MIDlet.
VideoTest-<n>
The name of the nth media title to be played back by the Video application.
VideoTest-URL<n>
Location of the nth media title, VideoTest-<n>, to be played back by the Video application.

A.7 ObexDemo

This application shows how to transfer image files between emulator instances using the OBEX API. This demonstration shows the use of OBEX over a simulated infrared connection.

Run two instances of the emulator. One listens for incoming connections, while the other attempts to send an image. In the first emulator, choose Obex Demo, then Receive Image. The emulator will ask for permission to listen. Choose Yes. The emulator will display a screen that indicates it’s waiting for incoming connections.

FIGURE 47  –  Waiting for an OBEX connection

Waiting for an OBEX connection

In the second emulator, launch Obex Demo, then choose Send Image. You’ll see a list of images. Select one and choose Send. The emulator will ask for permission to make the outgoing connection. Choose Yes.

Back in the first (listening) emulator, you’ll see a prompt asking whether you want to accept the incoming connection.

FIGURE 48  –  Prompting to accept a connection

Prompting to accept a connection

Choose Yes. The image you selected is transferred over the simulated infrared link and displayed on the first emulator.

FIGURE 49  –  A successfully transferred image

A successfully transferred image

A.8 PDAPDemo

PDAPDemo shows how to use the PIM and FileConnection APIs that are part of the JSR 75 specification.

A.8.1 Browsing Files

To run the file browser, you’ll need to give the MIDlet appopriate security authorization. The easiest way to do this is to choose Edit > Preferences... from the KToolbar menu. Click on the Security tab. Change the Security domain to trusted and press OK.

Now open and run the PDAPDemo project. Launch the FileBrowser MIDlet. You will see a directory listing. You can browse through the available directories and files. By default there is one directory, root1.

FIGURE 50  –  Browsing files

Browsing files

Select a directory and press the select button to enter it. The root1 directory contains a single file, Readme.

FIGURE 51  –  Contents of the root1 directory

Contents of the root1 directory

Using the commands in the demonstration, you can view the file or see its properties. Try selecting the file and choosing Properties or View from the menu.

FIGURE 52  –  Viewing file properties and contents

Viewing file properties and contents

The actual files are located in {toolkit}\appdb\DefaultColorPhone\filesystem, assuming you are using the DefaultColorPhone emulator skin. You can add files and root directories as you wish and they will be visible to the JSR 75 File API. See Chapter 10 for more information.

A.8.2 The PIM API

The JSR75 PIM APIs example demonstrates how to access personal information, like contact lists, calendars, and to-do lists. After you launch the example, choose a type of list from the main menu.

In this example application, each type of list works the same way and each list type contains a single list. For example, if you choose Contact Lists, there is a single contact list called Contacts. Event Lists contains a single list called Events, and To-Do Lists conatains a single list called To do.

FIGURE 53  –  Choosing a list type

Choosing a list type

Once you've selected a list type and chosen the specific list, you'll see all the items in the list. If this is the first time you've run the example, the list is probably empty.

FIGURE 54  –  An empty contact list

An empty conact list

To add an item, choose New from the menu. The application prompts you for a Formatted Name for the item. You can add more data fields to this item using Add Field in the menu. You'll see a list of field names. Pick one, then enter the value for the new field.

FIGURE 55  –  Adding contact fields

Adding contact fields

To actually save the list item, choose Commit from the menu.

FIGURE 56  –  Saving an item

Saving an item

You can return to the list by choosing the Back command. You'll see the item you just created in the list.

The items that you create are stored in standard vCard or vCalendar format in the {toolkit}\appdb\{skin}\pim directory. See Chapter 10 for more information.

The PIM API allows for exporting contact, calender, and to-do items in a standard format. The exact format depends on the list type. When you are viewing an item in any list, the menu contains a command for viewing the exported item.

For example, when you are viewing a contact list item, the menu contains Show vCard. When you choose this command, the exported item is shown on the screen. Calendar items and to-do items both get exported as vCalendar.

A.9 WMADemo

This application shows how to send and receive SMS, CBS, and MMS messages. The J2ME Wireless Toolkit offers a flexible emulation environment to support messaging. Messages can be exchanged between emulator instances and can be generated or received using the WMA console utility.

Because this example makes use of the push registry, you can't see all of its features just by using the Run button. You need to use the Run via OTA feature to install the application into the emulator in a process that mirrors how applications are installed on real devices. If you don’t know how to do this, read about it in Chapter 2, “Developing MIDlet Suites.”

To see the magic of the push registry, use the WMA console to send the emulator a message. Launch the console by choosing File > Utilities... from the KToolbar menu. Click on the Open Console button in the WMA box to launch the WMA console.

Click on the Send SMS... button in the WMA console window. Choose the number that corresponds to the emulator, probably +5550000. If you're not sure what number the emulator is using, look in its title bar. Choose the number in the SMS message window, then fill in a port number of 50000. Then type in your text message and click on Send.

FIGURE 57  –  Sending a text message

Sending a text message

The emulator will spring to life. First it politely asks if it can launch the WMADemo application.

FIGURE 58  –  The push registry springs to life

The push registry springs to life

Choose Yes. The SMSReceive MIDlet is launched and immediately displays the incoming SMS message.

FIGURE 59  –  An incoming text message

An incoming text message

You can also use the WMA console to send and receive CBS and MMS messages. See Chapter 7, “Using the Wireless Messaging API,” for more information.

If you are attempting to send text messages to WMADemo using the WMA console, make sure to specify the port number as 50000. Use port 50001 for CBS messages. For MMS messages, use example.mms.MMSDemo as the application ID.

For example, to send an MMS message from the WMA console to the emulator, make sure that WMADemo has been installed using Run via OTA as described above. Leave the emulator running.

In the WMA console, click on Send MMS... to pop up the MMS composition window. Fill in a message subject, the application ID example.mms.MMSDemo, and the telephone number of the running emulator.

FIGURE 60  –  Addressing an MMS message

Addressing an MMS message

Next, click on the Parts tab. The WMA console allows you to select files from your hard disk that you wish to send as parts of the MMS message. Click Add to add a file to the message. Use the file browser to find the file you want to send and click OK.

FIGURE 61  –  Adding parts to an MMS message

Adding parts to an MMS message

Click on Send to send the message.

The emulator asks if it can launch WMADemo. Click on Yes. The image and its information are displayed.

FIGURE 62  –  WMADemo receives the image

WMADemo receives the image

 


Contents Previous Next Index J2ME Wireless Toolkit User's Guide
J2ME Wireless Toolkit 2.2