dev|sushi

When I first dug into programming with the RIM APIs installed with the Blackberry JDE I ran into quite a few roadblocks that took a while to circumvent. Most stemmed with my unfamiliarity with Java and the standard Java UI toolkits (Swing and AWT). After figuring out how to create and display each of the most interesting fields I figured I might as well document them, provide screenshots, and sample application code to help others like myself.

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 latest API available online is v4.2.1 so all API URLs point there. Please utilize the documentation for the latest version installed with the development kit. It should be available in the start menu alongside the editor. Hopefully RIM will fix this issue soon, sorry for the inconvienience.

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());
    }
}