Print

Developing Applications for the RIM BlackBerry
Pages: 1, 2

A Sample App: Hangman for the BlackBerry

RIM applications -- whether in Java or in C++ -- use an event-oriented architecture. The main function sets up high-level application parameters, and then leaves it to the event dispatcher to do the right thing. Writing applications in Java seemed a lot simpler than C++, but that opinion is definitely colored by this writer's preference.

Figure 2. The larger models of the RIM BlackBerry have more screen real estate than the pager-sized models -- better for playing games (and other apps, too).

Obtaining these SDKs involves registering at developers.rim.net. This gets you an email with a login and password. At most developer sites, registering for downloading SDKs is usually a nuisance, resulting in a lot of useless emails, but RIM also gives you email access to a technical contact who you can pound with emails for more information. (I haven't done much pounding so I can't say how well this works.)



Our example application is a simple version of the game of Hangman. The user has to guess all the letters in a six-letter word, and in doing so, can make up to 10 errors. With every error, the gallows and the body are built incrementally in a graphic, adding some excitement to the game.

In building RIM applications, the constraints that jump out at you are the tiny screen and the keyboard (the latter may not be obvious if you use the PC-based simulator a lot, but the less your app uses keyboard input, the more usable it is). There are memory and file-system constraints you need to be aware of, but it's unlikely you'd thinking about these in the first pass of writing your app.

The Hangman example goes all the way in avoiding the keyboard. The entire game is played using only the thumbwheel. Scrolling the wheel chooses letters, and clicking makes a selection.

Since Hangman uses the RIM UI, it needs to extend the UiApplication class. UiApplication keeps track of multiple screens that your app uses. Your app pushes screens to the foreground (or pops screens to the background) and UiApplication repaints the screen as necessary.

Related Links

http://developers.rim.net The "official" site for RIM development

www.rimsource.com Just-started website on RIM development

www.rimroad.com Part of the PDAStreet.com website. Small but growing collection of RIM apps. Empty message boards though.

RIM and BlackBerry Developer Resources. Numerous articles, developer resources, including a RIM SDK for Linux

www.handango.com Among other PDA paraphernalia, the must see RIM applications RIMReader and BerryChess

www.bellsouthwd.com/developers/ For developers who want to build applications that use the Cingular Wireless Network (Mobitex-based).

www.mobitex.org The Mobitex site

www.dopforum The DataTAC site

www.apriva.com RIM-based point-of-sale solutions (with a magnetic card reader attachment) and wireless barcode solutions.

Applications extending UiApplication usually also use one of the many screen classes available in Java. The simplest one to use is the MainScreen. It comes packaged with a title bar on top, a separator element (fancy name for a horizontal line) under the title bar, and a main area that is scrollable. MainScreen descends from a long lineage of classes, and you can choose to use one of the more complex parent classes to get more flexibility.

Most apps would also need to use listeners (as Java interfaces) to handle information from the user, the device, and the network. Hangman uses just one listener for listening to thumbwheel input, but there are other listeners for keypad, radio, system menu and even holster (like a belt clip) events.

As you would have guessed, the ThumbListener is simple, defining only four events (wheel clicked, unclicked, rolled up and rolled down). Its quite amazing how much can be done with such a small selection of events. In fact, Hangman does not even use the wheel unclicked event. And there isn't a double-click event at all.

You would need to do three things with every MainScreen: add graphic elements like labels, edit boxes etc.; add one or more listeners; and finally "push" the screen to the top of the UI stack so that UiApplication can set about painting it.

Here is the basic framework for most RIM applications:

public class SomeApp extends UiApplication implements ThumbListener 
        // and any more listeners you may need
{

	// Class variable definitions etc.

	public static void main(String[] args)
	{
		SomeApp someapp=new SomeApp();
        		someapp.enterEventDispatcher();
	}

public void activate()
   	{
		// activate() is called when the application is brought to the foreground
		// Initialize data, add UI elements etc.

myScreen = new MainScreen();

myScreen.addTitle(new TitleField("Hangman!")); // a TitleField give you the app title
myScreen.add( … ); // Other UI elements
	}

	public boolean thumbClick(int status, int time)
	{
		// Stuff you want happen on a click
	}

public boolean thumbUnclick(int status, int time)
{
	// Stuff you want happen on an un-click
}

public boolean thumbRollUp(int status, int time, int amount)
{
	// Stuff you want happen on an wheel roll-up
}

public boolean thumbRollDown(int status, int time, int amount)
{
	// Stuff you want happen on a wheel roll-down
}
}

The regular programming needed for the Hangman game -- picking a secret word, taking letters as input, keeping track of errors or lives, and so on -- is pretty simple if you know your Java. If you are into this sort of thing, take a look at the source code.

 
Figure 3. Programming the RIM in a Java Integrated Development Environment.  

Adding Graphics

Adding graphics to your application is a little less intuitive (but really easy!), and the SDK documentation is silent on the issue. Thankfully, one of the demo applications included with the SDK jumps right into this subject.

First, all the bitmaps necessary for Hangman were painfully created using Paint. Remember to use monochrome, and keep the size of your pictures small. These bitmaps need to be saved in GIF format. Here are the Hangman bitmaps (the last one is for winners, and whole thing reminiscent of The Dancing Men):

Figure 4. The 10 bitmap graphics that are called to play Hangman.

To add these pictures to the project, right-click on the project name and select "Add file to Hangman" (there is no multi-select!). The RIM Java IDE automatically creates a class containing resources for your application. You can see the name of this resources class by viewing your project properties, but it defaults to <your app name>Resources. The HangmanResources class lets you convert these GIFs to arrays -- with rows and rows of hexadecimal numbers. Such arrays are necessary to create objects of the class Bitmap, which is how pictures are represented within RIM applications. You could create these byte arrays by hand (no mean feat) or simply call the getBitmap("mypic.gif") function of your app's resources class. Just make sure mypic.gif is added to your project. Here is a code fragment from the Hangman app:

Bitmap win={ HangmanResources.getBitmap("win.gif") };

Hangman uses objects of the Dialog class to show these pictures, as well as small text messages, such as:

i=new Dialog("Well done!", s, m, 0, win).doModal();
Source Code

Download the source code for the RIM Hangman game here.

This shows the "win" Bitmap along with a congratulatory message. If you take a look at the code you will find that "s" is an array of strings that represent choices presented to the user as part of the dialog box. In this case the choices are "Play again" and "Bye."

Creating an application icon for Hangman involves no programming at all. Simply add the GIF file as a resource under the project, and set its properties, indicating that it will be used as an application icon. The IDE takes care of creating the appropriate resources, so that the icon appears as part of the ribbon (the series of icons that form the RIM toolbar).

That's all there is to the Hangman: some text processing, pictures and a couple of dialog boxes.

Of course, the magic in the BlackBerry is wireless communications, which we are not making any use of in creating our rather naïve Hangman game. Building wireless into Hangman gives rise to enormous possibilities: a list of news words transmitted over the air refreshing your game's database, two-player duels, and a whole society addicted to wireless Hangman. This isn't all fantasy, simply because its being done even as we speak. Take a look at Four Pegs on RimRoad, PDAStreet.com's site for RIM enthusiasts. Four Pegs lets you play with another gamer over the wireless network, and all you need to know is your opponent's PIN number.

And no one seems to have developed wireless Tetris yet, so hurry.

In our next article, we'll look at Glenayre's AccessLink, a simple two-way pager with an infrared port that can be used for inputting and outputting data.

P.V. Subramanian works as a product manager for a telecom company, but is a secret programmer after hours. His current interests are programming handheld devices, JDMK, and PoV-Ray.