Terminally Incoherent

Last week I wrote about developing a simple hello world app for your blackberry. Today I want to go one step further and show you how to make a real world application that actually does something. Of course since we are all learning to use this new API I want to keep it simple, bare bones and straightforward. We can add bells and whistles later.

For now I just wanted to get a handle on using the basic GUI components, and capturing events such as pressing a button. I don’t particularly care how the app will look. I also don’t care about fancy stuff such as detecting the orientation flip in Storm.

What kind of application would fit all these criteria? Simple? Straightforward? No frills? And yet somehow useful. I pondered this for a little while and came up with this: a dice rolling application. You know, something that emulates rolling one or more dice of a certain type. It’s basically a random number generator attached to a GUI front end. And it’s useful too. Well, for me at least. The ability to generate random numbers in your phone comes in handy when you are into pen & paper RPG games like me.

So I drew up a simple design in my mind. The app would essentially have two input fields. One field would accept the number of dice to be rolled, while the other field would accept the type of dice. For those of you who don’t know this: yes, there are many types of dice. The die you usually see in casinos is what we call a d6 – a six sided dice. We role players also use d4, d8, d10, d12 and d20. When needed we also simulate a d100 by rolling two d10’s (you pick one dice to signify the tens and the other the ones).

The user will type in the values into the two fields, press a button and get the results. Simple and easy to develop. The end result should look like this:

Blackberry Dice Roller App

How do we do this? Let me show it to you. I apologize for the wall of text code segment but the app is just a single class and a fairly short one at that. It really doesn’t make much sense to break this code up. Note that this project uses a driver class just like the one I shown you in the Halo World example. I omitted it here because it is all uninteresting boilerplate code. To actually run this code however, you will need to create one yourself.

import java.util.Random;
import net.rim.device.api.ui.Field;
import net.rim.device.api.ui.FieldChangeListener;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.text.NumericTextFilter;
 
 
public class DiceScreen extends MainScreen 
{
   private EditField howmany, dice;
 
   public DiceScreen()
   {
 
      super();
      LabelField applicationTitle = 
        new LabelField("Luke's Dice Roller");
 
      setTitle(applicationTitle);
 
      howmany = 
        new EditField("How Many? ", "2", 10, Field.EDITABLE);
 
      howmany.setFilter(new NumericTextFilter());
      add(howmany);
 
      dice = new 
        EditField("What kind of dice? ", "6", 10, 
        Field.EDITABLE);
 
      dice.setFilter(new NumericTextFilter());
      add(dice);
 
      ButtonField roll = new ButtonField("Roll");
      add(roll);
 
      FieldChangeListener listener = new FieldChangeListener() 
      {
         public void fieldChanged(Field field, int context) 
         {
            int h = Integer.parseInt(howmany.getText());
            int d = Integer.parseInt(dice.getText());
 
            String result = randomize(h, d);
            Dialog.alert("Results: " + result);  
         }
      };
 
      roll.setChangeListener(listener);
   }
 
   private String randomize(int howmany, int dice)
   {
      String out = "";
      Random generator = new Random();
 
      for(int i=0; i<howmany; i++)
      {
         int temp = generator.nextInt(dice) +1;
         out += temp + ", ";
      }
 
      return out;
   }
 
}

Very straightforward stuff. The EditField component is basically a combination of a label and input box. Instead of using two components you just do one, and it accepts a string argument that will display some text to the left of the input box. It also accepts the initial value, maximum length and style indicator (in that order).

Each EditField (or rather each Field) defines a setFilter method that lets you pass in a filter object that will prohibit imputing certain values. I’m passing in a NumericTextFilter object which is why the Blackberry Storm displays the numeric keyboard when that field is active.

Finally, I create a listener for my button by defining FieldChangeListener instance as an inner class. I then attach it to my button just like I would do it a Swing application.

I don’t think I need to explain the random number generation procedure, since that’s something you should already know how to do. If you don’t, I recommend cracking open any Java book, or online tutorial. Random number stuff will probably be like on page 3 or something.

To keep things simple, I made the results appear in a modal dialog:

Blackberry Dice Roller in Action!

It works! Happy dance!

Of course this app has some serious problems. For one, it is ugly as hell. At least compared to most native Storm applications. It is also infuriatingly hard to navigate using the touch screen. You can’t really see this in the emulator, but once you load this ting onto your phone, changing fields becomes frustrating. Because they are so close, a downward finger swipe will almost always skip the second field and highlight the button. And upward swipe on he other hand will highlight the first field. Getting to the second field is then a matter of careful finger placement.

This is an usability issue that needs to be resolved before this little simplistic app can be considered worth while. So this is what I want to talk about in the next post in this series. Adding bells and whistles. I want to make this app look pretty, and somehow space the fields out so that they can be easily navigated.

I’d also like to do something fancy – for example remove the button and attach the dice rolling action to the orientation switch event. This way you could actually roll the dice with a flick of your wrist. How awesome would that be? Of course it would require some testing to see how sensitive the device really is, and whether or not the roll would be accidentally t triggered during normal use.

I almost forgot about this post. It got stuck in the draft queue for a few weeks now, but since I’m running low on postable content, I decided to resurrect it, clean it up and post it.

As promised, I wanted to show you how to create a simple Blackberry application in Java. Of course since this is Java, we will be typing way more than it is logically necessary. For example, a simple Hello World application requires no less than two classes, with a full complement of boring boilerplate code. If you are a long time Java programmer you probably just went “Only two? Phew! I thought it was worse”.

Our first class is basically there just to hold the main function, because that’s what you do in Java. You create a class, then you declare your main function, and then you writhe your procedural code inside:

import net.rim.device.api.ui.UiApplication;
 
public class HelloWorld extends UiApplication
{
	public HelloWorld()
	{
		pushScreen(new HelloScreen());
	}
 
	public static void main(String[] args)
	{
		HelloWorld instance = new HelloWorld();
		instance.enterEventDispatcher();
	}
}

There are two things here that might require explanation. The pushScreen method takes an UI container as a parameter and then paints it on screen. In our case this container is going to be a class extending net.rim.device.api.ui.container.MainScreen – I will show you how to create one in just a second.

The enterEventDispatcher method enters the main loop and handles capturing and dispatching events. The rest should be self explanatory.

Now for the actual GUI container:

import net.rim.device.api.ui.component.LabelField;
import net.rim.device.api.ui.container.MainScreen;
 
public class HelloScreen extends MainScreen
{
	public HelloScreen()
	{
		super();
		LabelField applicationTitle = 
			new LabelField("My First Applicaiton");
		setTitle(applicationTitle);
 
		LabelField hello = 
			new LabelField("Hello World!");
		add(hello);
	}
}

As you can see, blackberry apps are built just like any other Java GUI apps. You initialize container, label, field and button objects, you add them to each other creating hierarchies. There are some layout classes that can help you out and if you need to capture events you attach a listener to an object just like you would do it in Swing app. This is how our app looks like in the emulator:

A simple hello world app is not very pretty too look at. Click to embigen.

It’s simple and kinda ugly, but that’s really all we were going for. It is remarkably easy to create simple, create apps this way. You will however quickly notice that slapping few fields and labels together may work OK for other blackberry models, but is not the best way to make an app for the storm. Because of the way the interface works, it can be sometimes difficult to switch between fields that are very close to each other. Designing usable and good looking Storm apps takes a little practice. But more on that later..