Creating your first GUI BlackBerry App – Tutorial

Posted September 24th, 2009 by

Introduction

This tutorial will simply walk you through creating your first GUI app using RIM’s UI API (not MIDP). Only a skeleton will be created, that you can later expand on to create your own projects.

The first thing to do is create a class with a main() function. Just like a normal Java program, the BlackBerry will run this method first. Keep in mind that when you create a project in the JDE for this code, it will automatically figure out which class has a main(), so don’t create more than 1 class with a main() in your JDE project. Also, you will need an icon (a PNG file) that will be assigned to your app in the JDE. To setup the JDE and create a project using it, click here. To setup Eclipse and create a project using it, click here.

Creating the class with the main function

Here’s the code to make this happen.

public class HelloWorldApp extends UiApplication {
// main method
public static void main(String[] args) {

  HelloWorldApp theApp = new HelloWorldApp();
  UiApplication.getUiApplication().pushScreen(new MyScreen());
  theApp.enterEventDispatcher();

}

..

}

Here’s what’s happening in this code:

  1. HelloWorldApp is a subclass of UiApplication, which is required in order to make RIM native API apps.
  2. MyScreen is a subclass of MainScreen; the MyScreen class’s constructor actually adds some components to a layout manager and then adds the layout manager to the screen itself.
  3. The pushScreen() method is then called to actually put the screen on the display stack.
  4. Finally, enterEventDispatcher() attaches this screen to the EDT (event dispatch thread) and there is NO returning from this method, so be sure not to put any code after that method!

EDT and process binding

If you’re wondering why you have to manually bind with the EDT, here’s the answer. When the user runs your GUI app by pressing enter/pressing trackwheel on its app-icon, it actually spawns a process that executes the code in your main(). Since this is a GUI app, you then create the UI elements/screens, etc. and then push the screen into the display stack. Then finally when you want to render everything and show the UI, you have to call enterEventDispatcher().

Stack of screens

The BlackBerry maintains a stack of screens, and the screen on the very top is what you see on the screen. So if you keep adding screens to the stack, only the last one you added is going to be shown. You can hide screens, and remove them from the stack when you are done. In fact, when your app is ready to quit, you have to remove all the screens that are placed in the display stack by your app, and it will exit. You can also call System.exit(0) to stop your app from executing. You can write code that runs just before a screen is closed to perform all your cleanup in as well. This is a very good practice to get into.

Layout managers

Each screen takes up the entire width and height of the display. Inside each screen, is a layout manager (field manager) which handles sizing and positioning field objects that are placed inside of the layout manager (which is inside of the screen, which is is stacked inside of the display). Keep in mind that a manager is also a field, so you can use them interchangeably for layout purposes. Here is a picture that depicts this:

Building the screen

Now I will show you how to create a MainScreen and add some components to it. Here’s the code.

public class MyScreen extends MainScreen {

  public MyScreen(){
    // create a label
    LabelField title = new LabelField("Title...",
                                      LabelField.ELLIPSIS | LabelField.USE_ALL_WIDTH);

    // create a label
    LabelField banner = new LabelField("Banner...",
                                      LabelField.ELLIPSIS | LabelField.USE_ALL_WIDTH);

    // create a label
    LabelField status = new LabelField("Status...",
                                      LabelField.ELLIPSIS | LabelField.USE_ALL_WIDTH);

    // create a label
    LabelField body1 = new LabelField("Body1...",
                                      LabelField.ELLIPSIS | LabelField.USE_ALL_WIDTH);

    // create a label
    LabelField body2 = new LabelField("Body2...",
                                      LabelField.ELLIPSIS | LabelField.USE_ALL_WIDTH);

    VerticalFieldManager vfm = new VerticalFieldManager(Field.FIELD_VCENTER);
    vfm.add(body1);
    vfm.add(body2);

    add(vfm);

    setTitle(title);
    setBanner(banner);
    setStatus(status);

  }

}

Here’s a screenshot of this code running in a simulator:

Here’s what’s happening in the code:

  1. The MyScreen class extends MainScreen, which is the base class for a display window that has a status area, title & banner area, and body area. MainScreen also handles MENU button presses for you. This is typically the screen that you see in most BlackBerry apps, like the Messaging app. The other base class for screens is the FullScreen, which does even less for you than the MainScreen – you don’t get a status, title, and banner areas.
  2. I create a few labels that I’m going to layout soon inside of the screen. Those directives in the constructor tell the label how to draw itself. I’m telling it to put an ellipsis if the width of the label is greater than the display area of the screen. I’m also telling the label to take up the entire screen.
  3. Then I create a layout manager called VerticalFieldManager, which simply lays out all components vertically from top to bottom. I’m also telling this layout manager to try and vertically center all the fields/components that are added to it.
  4. Then I add this layout manager to the MainScreen. Don’t forget this step in your code.
  5. And finally, I set the title, banner, and status with the label fields.

The nature of the MainScreen is such that the title, status, and banner are fixed. Anything you add to the MainScreen (like I added “vfm”) is subject to scrolling, so if you add a big text field in there and you type a lot of text in it, scrollbars will show up, and as you scroll up/down your text, the status, title, and banner will be fixed.

This is just a starting point for your GUI development efforts. There are lots more tutorials that will show you how to work with lists, and do advanced layout, etc.

Further reading

RIM has a video that talks about what a UIApplication, screen, fields, and manager is, which is quite informative. Check it out here.

Feedback & Comments

Please share your thoughts/comments on this tutorial here.


Comments are closed.