Figure 1. The main screen of the surreal theme.

Figure 2. The main screen of the surreal theme in menu mode.

I’m not sure if all models of Blackberry devices have access to this theme or not—I have the Curve. If you would like to download this theme follow these steps…

1. Open the Browser (not the carrier encumbered WAP browser)
2. Click the Menu key and select Bookmarks from the list of options
3. Under Blackberry Bookmarks select Home Page
4. Scroll down and select Fun & Games
5. Scroll down and select Themes (notice the other free stuff available here too, some of the free and classic games are good)
6. Select I Accept on the terms and conditions page
7. Scroll down until you see the Surreal theme and click the Download link just under the picture
8. Click Download to begin the download process (you must have a data plan for this to work)
9. Once completed close the Browser by clicking the End key
10. Open the Options (usually a wrench icon) and scroll down and select Theme
11. Select Surreal and then close Options using the End key

Now take the time to select the most important six icons and move them to the top of the menu. These six with show on the main screen view (Figure 1). Clicking the Menu key will reveal the rest of the icons (Figure 2).

Enjoy!

First off for those out there only interested in the download-able code example — here you go. Simply open the FieldExample.jdw workspace in the JDE editor and click Debug -> Go.
Field Examples source code (.zip)

The following field objects are found in the net.rim.device.api.ui.component package. These objects are built-in time savers for building GUIs for Blackberry applications. One of the key benefits is that it provides your application with a consistent interface experience which guarantees users will feel right at home. Custom widgets are great and can make your application unique but each has a learning curve which could frustrate users. We’ll start with the easiest and move to the more complex.

Quick Reference

• NullField
• SeparatorField
• LabelField
• TextField
• RichTextField
• EditField
• PasswordEditField
• BitmapField
• RadioButtonField
• CheckboxField
• ObjectChoiceField
• NumericChoiceField
• GaugeField
• DateField
• ListField
• ButtonField

Note: The API version pointed to by this article is currently v4.5.0 so all API URLs point there. Please utilize the documentation for the version installed with the development kit. It should be available in the start menu alongside the editor.

NullField

I don’t actually have one of these in the code example since to me they seem completely pointless. I’m sure some programmers rely on them for various weird hacks but for the most part I would avoid them. They are invisible but can have focus.
NullField API reference

SeparatorField

In the standard MainScreen layout it is usually necessary to use these. They are very simple to add and provide a single pixel grey horizontal line on the screen from one side to the other. The general purpose is to separate two sections of UI elements. It is possible to override the drawing behavior and change the color/shape of the line but that is a more advanced topic for a future post.
SeparatorField API reference

add(new SeparatorField());

LabelField

This element is essentially a glorified String which knows how to draw itself on the screen. As with all text based Fields you can change the drawing Font and use it as the Screen title. By default this element does not accept focus but as will all Fields you can change this by setting the Field.FOCUSABLE style.
LabelField API reference

// LabelField variations

add(new LabelField("LabelField"));

add(new LabelField("LabelField 2", 0, -1, Field.FIELD_RIGHT));

LabelField lbl = new LabelField("LabelField 3", 0, -1, Field.FIELD_HCENTER);
Font fnt = this.getFont().derive(Font.BOLD | Font.ITALIC);
lbl.setFont(fnt);
add(lbl);

TextField

This class seems to be abstract since it has no constructors listed in the APIs. You can create a TextField but I would avoid it since from everything I have seen it is not used. It is the parent class of RichTextField and BasicEditField which are the fields you should actually use for selectable and editable text respectively.
TextField API reference

RichTextField

TextFields provide the equivalent of standard TextBox from other platforms. Each letter of the text is focusable and selectable. The RichTextField is not editable by default but can made editable by setting the Field.EDITABLE style. The major benefit of using a RichTextField over other text based fields is the configurability of the text formatting. It is quite cumbersome to setup as you can see by the following code example but is handy.
RichTextField API reference

// RichTextField variations

add(new RichTextField("RichTextField"));

String str[] = new String[] {"RichTextField:", "Value"};
int off[] = new int[] {0, str[0].length(), str[0].length() + str[1].length()};
byte attr[] = new byte[] {0, 1};
FontFamily fontfam[] = FontFamily.getFontFamilies();
Font fon[] = new Font[2];
fon[0] = fontfam[0].getFont(FontFamily.SCALABLE_FONT, 16);
fon[1] = fontfam[1].getFont(FontFamily.SCALABLE_FONT, 18);
add(new RichTextField(str[0] + str[1], off, attr, fon, RichTextField.TEXT_ALIGN_HCENTER));

EditField

Pretty much the equivalent of the LabelField but is focusable, selectable and editable. There are some mechanisms included which allow configuration of how the key presses interact with the field but overall it is very simple.
EditField API reference

// EditField

EditField edit = new EditField("Username: ", "");
add(edit);

PasswordEditField

As you might expect this is exactly the same as the EditField but replaces keystrokes with asterisk’s. Both Fields are children of the BasicEditField class. On the Pearl there is a short delay where it shows the actual character before switching it to the asterisk (another benefit of using the built in Fields). Some of the standard features like cut/copy and the auto manipulators are disabled.
PasswordEditField API reference

// PasswordEditField

PasswordEditField pass = new PasswordEditField("Password: ", "");
add(pass);

BitmapField

The BitmapField allows you to add a Bitmap to your application. It can be aligned just like any other field with Field.FIELD_RIGHT or Field.FIELD_HCENTER and additionally can have border padding. I haven’t looked to far into positioning beyond the standard but I will get into more complex layouts in a future post. The Bitmap class can load PNG, GIF or JPEG images along with raw byte data. If you include an image in the project it is automatically added to the .cod file as a resource which can be loaded using getBitmapResource(). When targeting a resource the path begins at the root project level. I’ve made the image focusable just as an example, I belive you can also turn an image into a button.
BitmapField API reference

// BitmapField
Bitmap img = Bitmap.getBitmapResource("com/examples/img/rainbow.png");
BitmapField bf = new BitmapField(img, BitmapField.FOCUSABLE);
add(bf);

RadioButtonField

There are the implementation of the standard radio selection object where you put a bunch into a group and then the user can select one (and only one) of those options. If you have a fairly small set of options these can be nicer than a choice field (a.k.a. drop-down list) since a user doesn’t have to click into the list and then pick an option. You must place the RadioButtonField objects into a RadioButtonGroup or an error will occur.
RadioButtonField API reference

// RadioButtonField (must be part of group)
RadioButtonGroup rgrp = new RadioButtonGroup();
RadioButtonField radio = new RadioButtonField("Radio Button", rgrp, true);
RadioButtonField radio2 = new RadioButtonField("Radio 2", rgrp, false);
add(radio);
add(radio2);

CheckboxField

Again the standard implementation of a checkbox where each is individual and you can check as many as you want. It appears that you are unable to set the checkbox state to other than on or off. Other platforms generally have a third version representing half checked but it appears the user would need to extend this control to provide that functionality.
CheckboxField API reference

// CheckboxField
CheckboxField chk = new CheckboxField("Checkbox 1", true);
CheckboxField chk2 = new CheckboxField("Checkbox 2", false);
add(chk);
add(chk2);

ObjectChoiceField

The object choice field is essentially what most programmers would know as a drop-down box or list. You provide a list of objects that have the toString() method and it uses that to generate the list the user chooses from. Hitting the space key will roll through the options or the user can click to see all options at one is a list (as seen in the screenshot below). These fields are very handy when you have many options to present or when screen space is at a premium (as it is on most options pages).
ObjectChoiceField API reference

// ObjectChoiceField
String choicestrs[] = {"Opt 1", "Opt 2", "Opt 3"};
ObjectChoiceField choice = new ObjectChoiceField("Object Choice Field: ", choicestrs, 0);
add(choice);

NumericChoiceField

My only guess is that the RIM developers needed lots of choice fields that were numeric. I’m not sure why but that is the only reason to create this very limited field. It simply creates a standard choice field with numeric choices within the range given in the constructor. You can specify a start number, end number and the increment. For the most part I would recommend just using an ObjectChoiceField since it is more flexible.
NumericChoiceField

// NumericChoiceField
NumericChoiceField numeric = new NumericChoiceField("Numeric Choice Field: ", 1, 10, 1, 4);
add(numeric);

GaugeField

The gauge is a very handy field which allows you to show a progress bar style value selector. If the ObjectChoiceField wasn’t enough for you never to use NumericChoiceField then perhaps this field could shoulder the load. It can be a straight uneditable field or it can allow focus and edit so the user can change the value. Overall this control is great and would be handy for anybody working on game programming.
GaugeField API reference

// GaugeField
GaugeField gauge = new GaugeField("Gauge Field: ", 1, 100, 50, Field.EDITABLE | Field.FOCUSABLE);
add(gauge);

DateField

I’ve never actually seen one of these in the standard suite of applications on the blackberry so it took me a bit to figure out how to use it properly. First you get down to the field and click the trackball on it. The appearance of the field will change to be the same as the screenshot below and the date, if not already set, will change to be today. You can then use the trackball to choose the date part and roll through the various dates. When finished click the trackball again to complete. Of all the fields this one has the most configuration options for what I can see. You can choose from many different date input formats and representations, overall it probably needs a full post just for itself.
DateField API reference

// DateField
DateField dte = new DateField("Date Field: ", Long.MIN_VALUE, DateField.DATE);
add(dte);

ListField

This element is what set me on this project in the first place. I was looking to recreate the Status screen under the Wrench icon which has a list with left and right aligned text. I wanted to make an About screen for my game that included device specs like screen size, etc and figured that would be a good way to lay it out. It certainly wasn’t easy to find out how to do it even after I discovered that ListField was the basis for it. The ListFieldCallback is more complicated than I figure is necessary but the most important part is the drawListRow method. drawText defaults to drawing left aligned text which works for the label of the field and if you add the DrawStyle.RIGHT style it will draw right aligned, voila!
ListField API reference

// Listfield (must have a callback)
ListField list = new ListField();
list.setEmptyString("Nothing to see here", DrawStyle.LEFT);
list.setSize(3);
list.setCallback(new TestListCallback());
add(list);

…

final class TestListCallback implements ListFieldCallback {
    public void drawListRow(ListField list, Graphics g, int index, int y, int w) {
        g.drawText("Testing:", 0, y, 0, w);
        g.drawText(String.valueOf(index * 111), 0, y, DrawStyle.RIGHT, w);
    }
    public Object get(ListField listField, int index) {
        return null;
    }
    public int getPreferredWidth(ListField listField) {
        return Graphics.getScreenWidth();
    }
    public int indexOfList(ListField listField, String prefix, int start) {
        return listField.indexOfList(prefix, start);
    }
}

ButtonField

The API had to have a button field and here it is but I don’t feel it is very useful overall. I’ve never seen one in use in the applications on the blackberry but I haven’t dug to deeply. Most applications use a ListField for their buttons instead of actual buttons. The FieldChangeListener is used to catch the click event after it is attached to the ButtonField. You can also attach the listener to any Field since the setChangeListener function is in the parent class so you could easily make a BitmapField clickable using this technique.
ButtonField API reference

// ButtonField
ButtonField btn = new ButtonField("myButton");
btn.setChangeListener(new ButtonListener());
add(btn);

…

final class ButtonListener implements FieldChangeListener {
    public void fieldChanged(Field field, int context) {
        ButtonField btn = (ButtonField) field;
        Status.show("Button pressed: " + btn.getLabel());
    }
}

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.

Java Required

In order to develop using the Blackberry JDE you must first have installed the Sun Java Development Kit (JDK) (more than just the JRE). This package will give you access to the java compiler which the Blackberry JDE requires.

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!

I’ve been considering writing a game for the Blackberry since the free ones you get from MagMic are fairly pedestrian. The other day I looked into the pay games and a vendor is selling Mahjong for ten bucks talk about a rip off. I’m not sure what type of game to make yet but I can guarantee that it will be better than Brick Breaker, I hate that game. The only game that I can stand is Ka-Glom! but it becomes boring after a while. Any suggestions out there for what type of game would hold your attention? Consider the platform, 3D is out, any idea has to pretty much be moving sprite based.

Note: In order to use the Pearl as an MP3 player you must have added a MicroSD card to store the music on since the device memory is insufficient.

Loading music on the device

Windows with Desktop Manager

1. Install Desktop Manager software from the included Blackberry CD
2. Plug in the device using the USB cable. On screen you should receive a message about using the memory card in mass storage mode or not. Select NO

3. Open Desktop Manager
4. Double click Media Manager

5. On the Blackberry side (marked A) select Media Card then blackberry then Music
6. On the local computer side (marked B) find your music collection
7. Select the song or folder you wish to upload and click the right pointing arrow (marked C)

8. Once the music is copied you can close Desktop Manager and disconnect the device

MacOSX and Windows

1. Plug in the device using the USB cable. On screen you should receive a message about using the memory card in mass storage mode or not. Select YES
2. On MacOSX a new drive will appear (probably called NO NAME). On Windows a new USB drive will be found
3. Open the drive, the blackberry folder and finally the music folder.
4. Copy and paste your songs to the drive
5. On MacOSX eject the drive. On Windows click the Safely Remove Hardware icon in the system tray (grey box with left facing green arrow) then click Safely remove USB Mass Storage Device
6. Disconnect the device

Playing music on the device

1. Open the Media Center on the device (film reel icon) select Music then Media Card
2. Clicking a song will play it on the built-in speaker or on the headphones if they are connected

3. Clicking on a song to play it will only play that one song. When it is over the music will stop or repeat
4. To play all songs or to play all songs including sub-folders you must click the menu key with a song highlighted then click Play Folder or Play All respectively
5. To shuffle your playlist click the menu key while the player is playing and select Shuffle from the list

So I’ve had the weekend to play around with the new Blackberry Pearl and I have to say it has been fun. There are some pretty cool features in there that I’ve never had a chance to play with before. First let me set the stage, I have only briefly used a Blackberry before (several different models though) so I don’t really know all the standard features. If I seem impressed about something that is not new to the Pearl that is why. I’ve only ever used business style cell phones before so MP3 playing and stuff seem incredibly novel to me. Ok, on to the review.

Blackberry Pearl Pictures

The device itself has a 1.3 mega pixel camera with flash, it is small and light weight, it has a beautiful color screen with a decent resolution and brightness. Out of the box it comes with a mini-USB cable, ear buds and the power adapter with many international plug styles. You can also insert a MicroSD card to expand the system memory from the (measly) 64MB internal memory to whatever you can afford. I didn’t have enough time to figure out battery life under high-use and low-use conditions but a rough approximation is about a day under high-use. The lit trackball on the front of the device is a welcome change to the typical side scroll on previous models. It is nice to be able to move in two dimensions in games and menus instead of having to use a key combination to change directions. Clicking the trackball takes a bit of practice though, sometimes it will roll when you click. I had this same issue on the old scroll as well so it might just be me. An issue that I noticed was that the menus and applications would sometimes take a very long pause before starting to work again.

The media center seems to be one of the key features of the Pearl; it includes music, video, ringtones and pictures. The device has some built-in samples in each category. You can also takes pictures and set them as your wallpaper which works quite well since you can rotate and zoom the picture in the viewer before setting it as your wallpaper. The ringtones provided are alright but I went out and and downloaded a cool Super Mario Bros. tune that ups the geek factor 10x or so. By default the phone is essentially useless as a MP3 player since the internal memory is so small and has a file size limit of 2.86MB, we all know that MP3s are 3-5MB on average. To test MP3 playback I created a music directory on the internal memory and uploaded a short file, the sounds quality was great. It looks like you must have a MicroSD card to use the Pearl as an MP3 player, thankfully you can get a 1GB card for $50CDN.

The browser works pretty well on sites that have a mobile version and even on some that provide navigation links at the top. I was impressed by the free stuff on the Blackberry network website. There are a few select games, ringtones, themes and wallpapers. A must have is the Today Plus theme which provides a great standard menu and Sodoku a great puzzle game. One issue is that Flash isn’t supported (as far as I could tell) so you can’t hear any music on MySpace or watch videos on YouTube.

All Blackberry’s utilize the Desktop Manager Software for connecting the device to a PC. Pearl comes with version 4.2 which adds a tool to interact with the Media Center on the phone. You can upload/download anything including pictures you’ve taken and MP3s from your collection (don’t forget about the default limitation I mentioned earlier). You can also do the standard Blackberry stuff like add/remove applications and synchronize your Outlook calendar, tasks, memos, etc. It is functional and it certainly is nice not to have to buy a special cable to download stuff from your phone or pay transfer costs to send it to your email.

A very cool feature that I enjoyed is the voice dialing application. It allows you to say “Call Ted Denslow” and it will look up the number from your address book and call it. If there are multiple that are similar it will give you a list to chose from. You can also say “Call 519-888-4567″, it will come back and make sure it heard the number correctly then call it hands free. The best part is you don’t have to go through a voice setup process it just uses the persons name from the address book. You do need to speak clearly and there are some options for how loose the fit is to your voice. One annoying part of the voice dialing is that you have to say the full name as entered in the address book. I put myself in as Mr. Adam Hewgill and then had to say exactly that for it to come up with the match. So I got rid of the Mr. part and just had to say Adam Hewgill. It should be able to do partials so if I say “Call Adam” it should give me a list of all the Adams’ to pick from. Overall a great and well executed feature.

Last week I noticed on the sign-in page GMail that they had launched a new mobile application that would check your account. I’ve used GMail’s mobile friendly version a few times and was impressed but the new GMail app blew me away. You have to have this if you have a GMail account and a mobile phone that supports it (couldn’t find a list sorry). Just point your browser at http://www.gmail.com/app to check it out. One major issue is that you can’t get MSN on this device (as far as I could tell) it does however have Yahoo messenger that is now supposed to be able to add MSN contacts but I don’t know if that is the case with the mobile version yet. It also has google Talk if that makes you happy.

All in all this device is great for the active Business person who is a bit hipper than those that currently use the Blackberry line-up but for sure it is not a cool enough phone for the younger non-business types. I think they are marketing it correctly because they are not competing with the Motorola RAZR or Sony Ericsson Walkman line-up. The Motorola Q and the Palm Treo 700wx are the competing products, they are all very similar it seems but I have a feeling the other two support flash in the browser. All in all a great device.

The i850 is from Telus and the Pearl is from Rogers. I don’t pay for them so I have no idea what they cost but I think it is a lot. Our Telus phones are all on the Mike network so they are 2-way radios as well as cell phones this is apparently why they have to be so big. They are getting pretty close to the size of a standard flip phone though which is nice. The camera on the i850 is 0.3 mega pixels and takes terrible pictures even at the best quality. You would need a tripod for an arm to keep them from being blurry. The Pearl has a 1.3 mega pixel camera that takes far better pictures despite my unsteady hand. The sound quality on the Pearl is very good compared to the i850 and the videos on the Pearl look great.

Each phone is full of features that are pretty standard but the Pearl has all the same extras that other Blackberry phones have so in that sense it is far superior. To be fair you can’t really compare the two phones since they are targeted at two completely different audiences. I’ll probably write some more about the Pearl after this weekend of testing (playing).