Specifying the orientation and direction of the screen

In touch screen applications, you can take into account both the orientation and the direction of the screen. Orientation relates to the screen's aspect ratio. Direction relates to the drawing area of the screen.

Orientation

The user of a BlackBerry® device with a touch screen can change the orientation of the screen by rotating the device. If a user holds the BlackBerry device with the BlackBerry logo at the top, the screen is in portrait orientation. If the user rotates the device 90 degrees to the left or right, the screen is in landscape orientation.

You can use the net.rim.device.api.system.Display class to retrieve the orientation of the screen. The Display class contains the constants that correspond to the orientations that the device with a touch screen can use to display information. For example, the portrait, landscape, and square orientations correspond to the Display.ORIENTATION_PORTRAIT, Display.ORIENTATION_LANDSCAPE, and Display.ORIENTATION_SQUARE constants.

To retrieve the orientation of the screen, you can invoke the Display.getOrientation() method. This method returns an integer that corresponds to one of the orientations that the BlackBerry device can use.

To detect orientation changes, you can override Screen.sublayout(). In that method, invoke super.sublayout() and watch for changes in the width and height values.

Direction

A BlackBerry device with a touch screen can display information on the screen in different directions. Direction refers to the top of the drawing area of the screen, which is relative to the location of the BlackBerry logo. The direction is north when the top of the drawable area is the screen side closest to the BlackBerry logo; the direction is west when the top of the drawable area is to the left of the BlackBerry logo; the direction is east when the top of the drawable area is to the right of the BlackBerry logo.

You can use the net.rim.device.api.system.Display class, the net.rim.device.api.ui.Ui class, and the net.rim.device.api.ui.UiEngineInstance class to control the direction that the BlackBerry device uses to display information on the screen. The Display class contains constants that correspond to the directions that the device can use to display information. For example, the north, west, and east directions correspond to the Display.DIRECTION_NORTH, Display.DIRECTION_WEST, and Display.DIRECTION_EAST constants.

You can create an object of the net.rim.device.api.ui.Ui class and invoke Ui.getUiEngineInstance() to retrieve an object of the UiEngineInstance class. Invoking UiEngineInstance.setAcceptableDirections() with one of the constants that correspond to directions from the Display class sets the direction that the BlackBerry device can use to display information.

Code sample: Retrieving screen orientation

switch(Display.getOrientation()) 
{
   case Display.ORIENTATION_LANDSCAPE:
      Dialog.alert("Screen orientation is landscape"); break;
   case Display.ORIENTATION_PORTRAIT:
      Dialog.alert("Screen orientation is portrait"); break;
   case Display.ORIENTATION_SQUARE:
      Dialog.alert("Screen orientation is square"); break;
   default:
      Dialog.alert("Screen orientation is not known"); break;
}

Code sample: Forcing portrait view in a BlackBerry API application

// Use code like this before invoking UiApplication.pushScreen()
int direction = Display.DIRECTION_NORTH;
Ui.getUiEngineInstance().setAcceptableDirections(direction);

Code sample: Forcing landscape view in a MIDlet application

// Use code like this before invoking Display.setCurrent() in the MIDlet constructor
DirectionControl dc = 
  (DirectionControl) ((Controllable) Display.getDisplay(this)).
    getControl("net.rim.device.api.lcdui.control.DirectionControl"); 
int directions = DirectionControl.DIRECTION_EAST | DirectionControl.DIRECTION_WEST; 
dc.setAcceptableScreenDirections(directions);

Was this information helpful? Send us your comments.