Working with BlackBerry screens – Tutorial

Posted by

Introduction

In this tutorial, I will show you how to quickly manage screens using the RIM UI API. The BlackBerry OS maintains a stack of screens, and your app can be pushed and popped from this stack. These are normal screen display operations. You can even hide your screen from the display, and it will show the BlackBerry home screen. You can close the screen as well. For the basics of creating a simple GUI BlackBerry app, click here.

The following is a class hierarchy diagram that shows you the different kinds of screens in the RIM API.

Modal vs Normal

In addition to normal placement (or display) of your screen on the display (stack), you can also perform modal push/display. There are some pretty big differences in these 2 approaches. Using normal screen display, by using UiApplication.getUiApplication().pushScreen(..), the statement after this line of code will be executed without blocking. So you can push a screen to the display stack and the statement in your code after the call to pushScreen() will run. When you perform a modal screen display/push, using UiApplication.getUiApplication().pushModalScreen(..), the statement following this one does not get executed until after the screen you just pushed has closed (you can call close() on the screen object to close it). Not only can you close a screen, but you can also remove it from the display stack using UiApplication.getUiApplication().popScreen(..).

Modal screens normally make sense when you want the execution of your code to block until the screen is closed, like a Dialog class. For example, if you want to block your program until the user provides some feedback, modal is the way to go. Alternatively, you can accomplish that via a callback, so you don’t have to use modal. It’s your choice to use it or not.

There is one more way to push/display your screen onto the display stack. You can push it globally. This will push your screen above all normal and modal screen into the global screen stack. Read more about it here.

Popup Screen

Also keep in mind that you can create a PopupScreen, not just a MainScreen or FullScreen. A popup screen allows you to display a floating screen that hovers on top of whatever is behind it. You can push/display this popup screen normally or modally. This is much like a dialog box frame in Swing.

Source code

Normal push/display

Here’s some code that shows you how to display a screen normally:

// MAIN CLASS

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

  NormalDemo theApp = new NormalDemo();
  UiApplication.getUiApplication().pushScreen(new SampleScreen());
  theApp.enterEventDispatcher();

}

..

}

// SAMPLE SCREEN
public class SampleScreen extends MainScreen {

  public SampleScreen(){

    // create a manager and allow scrolling when lots of fields are added
    VerticalFieldManager vfm = new VerticalFieldManager(Manager.VERTICAL_SCROLL);
    
    // add a label
    vfm.add(new LabelField("First Screen"));
    
    // add vfm to screen
    add(vfm);
    
    // show the 2nd screen... run later in EDT...
    UiApplication.getApplication().invokeLater(new Runnable(){
      public void run(){
        SampleScreen2 screen2 = new SampleScreen2();
        System.out.println("About to show screen2");
        UiApplication.getUiApplication().pushScreen(screen2);
        System.out.println("Have already shown screen2");
      }
    });


  }

}

// SAMPLE SCREEN2
public class SampleScreen2 extends MainScreen {

  public SampleScreen2(){

    // create a manager and allow scrolling when lots of fields are added
    VerticalFieldManager vfm = new VerticalFieldManager(Manager.VERTICAL_SCROLL);
    
    // add a label
    vfm.add(new LabelField("Second Screen"));
    
    // add vfm to screen
    add(vfm);

  }

}

This is what’s going on in the code:

  1. The NormalDemo class simply launches the program and adds a SampleScreen object to the display stack (normally).
  2. As soon as the SampleScreen is created, it creates a Runnable object that will be executed in the EDT just a few moments later. This Runnable creates a new screen – SampleScreen2, which is displayed normally. The 2 System.out.println statements will execute as soon you see the 2nd screen displayed. This just shows non-modal, or normal, display of the 2nd screen.

Modal push/display

Here’s some code that shows you how to display a screen modally:

// MAIN CLASS

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

  ModalDemo theApp = new ModalDemo();
  UiApplication.getUiApplication().pushScreen(new SampleScreen());
  theApp.enterEventDispatcher();

}

..

}

// SAMPLE SCREEN
public class SampleScreen extends MainScreen {

  public SampleScreen(){

    // create a manager and allow scrolling when lots of fields are added
    VerticalFieldManager vfm = new VerticalFieldManager(Manager.VERTICAL_SCROLL);
    
    // add a label
    vfm.add(new LabelField("First Screen"));
    
    // add vfm to screen
    add(vfm);
    
    // show the 2nd screen... run later in EDT...
    UiApplication.getApplication().invokeLater(new Runnable(){
      public void run(){
        SampleScreen2 screen2 = new SampleScreen2();
        System.out.println("About to show screen2");
        UiApplication.getUiApplication().pushModalScreen(screen2);
        System.out.println("Have already shown screen2... this won't run until 2nd screen is closed!");
      }
    });


  }

}

// SAMPLE SCREEN2
public class SampleScreen2 extends MainScreen {

  public SampleScreen2(){

    // create a manager and allow scrolling when lots of fields are added
    VerticalFieldManager vfm = new VerticalFieldManager(Manager.VERTICAL_SCROLL);
    
    // add a label
    vfm.add(new LabelField("Second Screen"));
    
    // add vfm to screen
    add(vfm);

  }

}

This is what’s going on in the code:

  1. The ModalDemo class simply launches the program and adds a SampleScreen object to the display stack (normally).
  2. As soon as the SampleScreen is created, it creates a Runnable object that will be executed in the EDT just a few moments later. This Runnable creates a new screen – SampleScreen2, which is displayed modally. The 2 System.out.println statements will not execute as soon you see the 2nd screen displayed. The first System.out.println statement will be shown to the console, then the SampleScreen2 will be displayed (modally). When you hit the ESC key/BACK button the SampleScreen2 will be closed, and then the 2nd System.out.println statement will execute and you will see output in the console. This shows the blocking behavior of pushModalScreen().

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.