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. The HellowWorldApp constructor actually creates a screen class, called MyScreen, which and adds some components to a MainScreen object.
2. The pushScreen() method is then called to actually put the screen on the display stack.
3. 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.

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 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.

Training Services

Want to learn from the best in the business? We have training programs available for BlackBerry development, Android development, rich desktop apps, and UX design. We can give your development team a competitive edge, and make them experts in these technologies. Contact us if you are interesting in learning more about our training services & schedule.

Consulting Services

If you need help building web, mobile, and desktop apps that are all connected to the cloud, we can help. We can empower your business by bringing your ideas to life.

Our expertise: architecture, UX design, graphic design, and implementation services for BlackBerry, Android, GWT, desktop Java, and cloud computing.

Our specialties: crafting stunning UXes, LBS, real-time collaboration and syncing between services and web/mobile/desktop apps, location based mobile e-commerce, and location based mobile advertising.

Contact us if you have a project you need our help with and we will consider taking you on as a client.

ONE Platform Licensing

If you are not interested in our consulting or training services, but would like to build web, mobile, and desktop apps that are all connected to the cloud quickly, you can kick-start your development by leveraging the ONE Platform. You won’t have to build and test from scratch!

The ONE Platform SDK will accelerate the development and deployment of your connected/service-enabled web/mobile/desktop projects. Contact us for more information on licensing the ONE Platform.

This entry was posted on Thursday, September 24th, 2009 at 10:36 pm and is filed under BlackBerry. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.