dev|sushi

Recently I became frustrated with the state of free games for the Blackberry platform. BrickBreaker is really hard and choppy on the newer devices so I decided to do something about it. I also have a Blackberry Pearl just sitting at home since my recent upgrade to the Blackberry Curve. So frustration + extra device + time = development on the Blackberry platform. After wading through some web pages on the developer site and running into more than one snag I decided to document to process in tutorial form. I hope this helps you get starting with the Blackberry JDE. Please feel free to drop questions in the comments or to email me at ahewgill@gmail.com.

Installation

The first step is to install the Blackberry Java Development Environment (JDE) available on from the Blackberry Developer website. (As of this writing the latest version is 4.5.0). You have to register for an account and verify via email in order to download the software which is very annoying. It took them 24 hours to send me the verification link so that I could sign in and begin the download. It is best to download the full JDE rather than the individual pieces in my opinion but this is up to you and your bandwidth constraints.

Setting up the PATH

In order to run the Java compiler, JDE requires it be in the system PATH. To do this right click on My Computer and click Properties. Now click the Advanced tab and then the Environment Variables button. In the system variables (lower) part find and select the PATH variable and then click the Edit button. Now at the very end of the string add ;C:\Program Files\Java\jdk1.x.x_yy\bin;C:\Program Files\Research In Motion\BlackBerry JDE 4.x.x\bin (make sure you have the semi-colon at the front). Click Ok, then Ok again and finally one last time. You will have to check for the relevant version numbers on your own computer to fill in above.

Running a few samples

Once you have the JDE installed it is time to try out a few of the samples provided. First open the editor by clicking Start -> Programs -> Research in Motion -> Blackberry JDE 4.x.x -> JDE. Windows Firewall may ask if you want to allow JDE to access the Internet; I let it so I don’t know if it will work if blocked. Once in the editor click File -> Open Workspace… and browse to C:\Program Files\Research in Motion\Blackberry JDE 4.x.x\samples and select samples.jdw.

Let’s run the HelloWorldDemo sample. First thing you must do it set HelloWorldDemo to be the only active project. Click Project -> Set Active Projects… and then in the dialog that appears click Clear All and then check off HelloWorldDemo (formerly com_rim_helloworld) and click Ok. You are now ready to build and run the project. Click Debug -> Go to build the code and run the simulator (can take time to load so be patient).

The first thing you will notice is that you’re presented with a Blackberry 8300 Curve in its default configuration. Click the menu key and find HelloWorldDemo in the application list. Click the trackball to run it, voila! To exit the application click the menu key and then click the close option. Simple right! I encourage you to take a look through the code of the various demos at some point to become familiar with the Blackberry APIs. I have also created a Blackberry API UI reference with screenshots and sample code.

In the editor click File -> Close Workspace and then close any code windows you might have open on the right before continuing.

Creating your own HelloWorld

Now that you know how to use the editor and run an application it is time to start your first program. I’m going to give you the code but the idea of this section is to learn how to create a new workspace, project, and code file. Click File -> New Workspace… and then give your program a name like MyHelloWorld. In the second box add MyHelloWorld to the end of the creation path leaving off the last backslash. Click Ok and then Yes to the directory creation question. You now have a new workspace in which to put your project.

To create the project simply click Project -> Create New Project… and enter the project name (eg HelloWorld) into the first box. This time you don’t have to mess with the directory, just click Ok.

Now it is time to add a code file to your empty project. On the left click the HelloWorld project in the Files tree view. Now click Project -> Create New File in Project… and enter a file name (eg HelloWorld.java) into the first box. In the second box we need to add at least one directory because Java likes to organize things into packages. Add \com\sample to the end of the second box and note that the automatically generated code has the line package com.sample;. You’ll notice this type of thing throughout the Java APIs, this is how classes are organized.

Now that we have a code file it is time to add some code. Replace the tiny little empty class stub (everything below the package com.sample line) with the follow code (I stole this directly from the HelloWorld sample we ran above).

import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.system.*;

/*
 * BlackBerry applications that provide a user interface
 * must extend UiApplication.
 */
public class HelloWorld extends UiApplication
{
        public static void main(String[] args)
        {
                //create a new instance of the application
                //and start the application on the event thread
                HelloWorld theApp = new HelloWorld();
                theApp.enterEventDispatcher();
        }

        public HelloWorld()
        {
                //display a new screen
                pushScreen(new HelloWorldScreen());
        }
}

//create a new screen that extends MainScreen, which provides
//default standard behavior for BlackBerry applications
final class HelloWorldScreen extends MainScreen
{
        public HelloWorldScreen()
        {
                //invoke the MainScreen constructor
                super();

                //add a title to the screen
                LabelField title = new LabelField("HelloWorld Sample",
                       LabelField.ELLIPSIS | LabelField.USE_ALL_WIDTH);
                setTitle(title);

                //add the text "Hello World!" to the screen
                add(new RichTextField("Hello World!"));
        }

        //override the onClose() method to display a dialog box to the user
        //with "Goodbye!" when the application is closed
        public boolean onClose()
        {
            Dialog.alert("Goodbye!");
            System.exit(0);
            return true;
        }
}

Click Build -> Build (or hit F7) to make sure it compiles with no errors. Any syntax errors or other messages will appear in the bottom Build window so make sure to look there before assuming everything worked. Now hit Debug -> Go to run the code in the Blackberry simulator.

Installation on a physical device

Once you have an application and have run the simulator a few times you might get the desire to install your app on an actual device. It is fairly easy to do this once you have setup the PATH variable. Open a command window by clicking Start -> Run… type cmd and hit enter. In the little black window go to the location of your application and find the .cod file. Make sure you’ve connected your device with the USB cable and then run the following command.

javaloader -usb load HelloWorld.cod

You’re handset will go white with a spinning hour glass for a few seconds and then back to normal. You will now see the application icon installed on the device. Congratulations you are now a Blackberry developer!