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.