Adjusting device's orientation

API contents

The Orientation API consists of the following class and interface (packaged as part of the Nokia UI API):

• Orientation

  Use the Orientation class to change the UI orientation, determine the current UI orientation, determine the current display orientation, or register or remove an OrientationListener.

• OrientationListener

  Use the OrientationListener interface to implement a listener for receiving a notification whenever the display orientation changes.

The Orientation API also provides the com.nokia.mid.ui.orientation.version system property, which MIDlets can use to query the Orientation API version supported by the device.

The Orientation API is supported since Nokia UI API 1.6.

Device compatibility

The Orientation API is supported on Series 40 devices with Java Runtime 2.0.0 for Series 40 or newer.

Setting the UI orientation

To adjust the MIDlet UI orientation whenever the display orientation changes:

1. In the MIDlet JAD file, declare the Nokia-MIDlet-App-Orientation JAD attribute with the value manual:

   Nokia-MIDlet-App-Orientation: manual

   The value manual specifies that the MIDlet supports both portrait and landscape modes. When the MIDlet starts, its UI orientation follows the display orientation of the device. The MIDlet can then adjust its orientation using the Orientation API.

2. Register an OrientationListener using the static Orientation.addOrientationListener method.

   Orientation.addOrientationListener(orientationListener);

3. Implement the OrientationListener by defining the displayOrientationChanged method. The method is called every time the display orientation changes. Use the displayOrientationChanged method to set the UI orientation by calling the static Orientation.setAppOrientation method. You can set the UI orientation to either ORIENTATION_LANDSCAPE or ORIENTATION_PORTRAIT.

   /** Orientation listener callback */
     public void displayOrientationChanged( int newDisplayOrientation ){
   
       /** Check display orientation */
       switch( newDisplayOrientation ){
         case Orientation.ORIENTATION_PORTRAIT:
         case Orientation.ORIENTATION_PORTRAIT_180:
           /** Change MIDlet UI orientation to portrait */
           Orientation.setAppOrientation(Orientation.ORIENTATION_PORTRAIT);        
           break;
   
         case Orientation.ORIENTATION_LANDSCAPE:
         case Orientation.ORIENTATION_LANDSCAPE_180:
           /** Change MIDlet UI orientation to landscape */
           Orientation.setAppOrientation(Orientation.ORIENTATION_LANDSCAPE);        
           break;
       }    
     } 

4. The platform calls the sizeChanged method of the current Displayable. If you are using low-level UI elements, implement sizeChanged methods for them that redraw the elements with new dimensions appropriate to the new UI orientation. If you are using high-level UI elements, the platform adjusts their orientation automatically, meaning you do not need to override the default sizeChanged implementation. In either case, do not modify the MIDlet UI between the setAppOrientation and sizeChanged calls.

More information

For example MIDlets that show you how to use the Orientation API, see:

• ImageViewer

• MMSMIDlet

• Scalable 2D vector graphics examples

• SystemProperties

• WeatherApp