Would you like to tell us how we are doing?

You bet No thanks

Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Screens

The main component of a BlackBerry device UI is the Screen object.

A BlackBerry device can have multiple screens open at the same time, but only one screen can be displayed at a time. The BlackBerry Java Virtual Machine maintains an ordered set of Screen objects in a display stack. The screen on the top of the stack is the active screen that the BlackBerry device user sees. When a BlackBerry device application displays a screen, it pushes the screen on the top of the stack. When a BlackBerry device application closes a screen, it pushes the screen off the top of the stack and displays the next screen on the stack, redrawing the screen as necessary.

Each screen can appear only once on the display stack. The BlackBerry JVM throws a runtime exception if a screen that the BlackBerry device application pushes on the stack already exists. A BlackBerry device application must push a screen off the display stack when the user finishes interacting with the screen so that the BlackBerry device application can use memory efficiently. You should use only a few modal screens at one time, because each screen uses a separate thread.

The UI APIs initialize simple Screen objects. After you create a screen, you can add fields and a menu, and display the screen to the user by pushing it on the display stack. You can change the BlackBerry device UI and implement new field types, as required. You can also add custom navigation.

The Screen class does not implement disambiguation, which is required for complex input methods, such as international keyboards. For the integration of the different input methods, you can extend the Field class or one of its subclasses. You should not use Screen objects for typing text.

Screen classes

Class

Description

Screen

You can use the Screen class to create a screen and use a layout manager to lay out the UI components on the screen. You can define a specific type of screen by using the styles that the constants in the Field superclass define.

FullScreen

You can use the FullScreen class to create an empty screen to which you can add UI components in a standard vertical layout. If you want to use another layout style, such as horizontal or diagonal, you can use the Screen class instead and add a layout manager to it.

MainScreen

You can use the MainScreen class to create a screen with the following standard UI components:

  • default screen title, with a SeparatorField after the title
  • main scrollable section contained in a VerticalFieldManager
  • default menu with a Close menu item
  • default close action that closes the screen when the BlackBerry device user clicks the Close menu item or presses the Escape key

You should consider using a MainScreen object for the first screen of your BlackBerry device application to maintain consistency with other BlackBerry device applications.

Developing applications for different screen sizes

BlackBerry devices have a wide range of screen sizes, including the following:

  • 360 x 480 pixels (BlackBerry Torch smartphone, BlackBerry Storm smartphone)
  • 480 x 320 pixels (BlackBerry Bold smartphone)
  • 240 x 260 pixels (BlackBerry Pearl smartphone)

When you create your applications, you should take into consideration the different screen sizes of the devices that your application might run on. You might need to resize any bitmaps that you use to make sure that they display correctly on each screen size. You might also need to arrange fields differently for different screen sizes.

Screen sizes can be placed into two categories, high resolution and low resolution. High resolution screen sizes include screens that have a width that is greater than 320 pixels. This category includes the 360 x 480, 480 x 360, and 480 x 320 resolutions. Low resolution screen sizes include screens that have a width that is less than or equal to 320 pixels. This category includes the 240 x 320, 240 x 260, and 320 x 240 resolutions. Because of this categorization, you need to maintain only two sets of bitmaps or layouts in your application, and switch between them based on the screen size of the device that your application is running on.

Comparison of different device screen sizes and resolutions.

To access the screen properties of the device, you can use the methods that are available in the Display class, which is included in the net.rim.device.api.system package. You can use this class to access information such as screen size, dimensions, and orientation. For example, to retrieve the width of the screen and switch bitmap sets or layouts accordingly, you can use the following code:

boolean lowRes = Display.getWidth() <= 320;

if (lowRes)
{
    // The device has a low resolution screen size.
}
else
{
    // The device has a high resolution screen size.
}