com.nokia.mid.ui.orientation
Class Orientation

java.lang.Object
  com.nokia.mid.ui.orientation.Orientation

public class Orientation
extends java.lang.Object

Orientation class is used for getting and setting UI orientation. It also provides methods for getting current display orientation and register functionality for display orientation change notifications.

Field Summary

static int	ORIENTATION_LANDSCAPE Constant for display and UI orientation mode (Landscape, right side up).
static int	ORIENTATION_LANDSCAPE_180 Constant for display orientation mode (Landscape, left side up).
static int	ORIENTATION_PORTRAIT Constant for display and UI orientation mode (Portrait, top side up).
static int	ORIENTATION_PORTRAIT_180 Constant for display orientation mode (Portrait, bottom side up).

Method Summary

static void	addOrientationListener(OrientationListener listener) Registers an orientation listener.
static int	getAppOrientation() Gets application's current UI orientation.
static int	getDisplayOrientation() Gets the current display orientation.
static void	removeOrientationListener(OrientationListener listener) Removes an orientation listener.
static void	setAppOrientation(int newAppOrientation) Sets the application's UI orientation.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ORIENTATION_PORTRAIT

public static final int ORIENTATION_PORTRAIT

Constant for display and UI orientation mode (Portrait, top side up).

ORIENTATION_PORTRAIT has the value 0x01.

See Also:

Constant Field Values

ORIENTATION_LANDSCAPE

public static final int ORIENTATION_LANDSCAPE

Constant for display and UI orientation mode (Landscape, right side up).

ORIENTATION_LANDSCAPE has the value 0x02.

See Also:

Constant Field Values

ORIENTATION_PORTRAIT_180

public static final int ORIENTATION_PORTRAIT_180

Constant for display orientation mode (Portrait, bottom side up).

ORIENTATION_PORTRAIT_180 has the value 0x03.

See Also:

Constant Field Values

ORIENTATION_LANDSCAPE_180

public static final int ORIENTATION_LANDSCAPE_180

Constant for display orientation mode (Landscape, left side up).

ORIENTATION_LANDSCAPE_180 has the value 0x04.

See Also:

Constant Field Values

Method Detail

setAppOrientation

public static void setAppOrientation(int newAppOrientation)

Sets the application's UI orientation.

This method instructs the Java platform to change application's UI orientation. The method call is asynchronous and will return immediately. After the UI orientation has been changed, the Java platform will call current Displayables sizeChanged() method. It is recommended that the application does not try to modify the display or use any classes that depend on display properties while the orientation change is ongoing.

After the UI orientation has been changed all previously acquired Graphics objects are considered invalid and must no longer be used. Applications using low-level UI components, for example Canvas or GameCanvas, should block until the sizeChanged() method has been called and then call the getGraphics() method.

For high-level UI components, for example Form, it is guaranteed that all platform classes have been re-initialized to reflect the new UI orientation after the sizeChanged() call has been completed.

If the Nokia-MIDlet-App-Orientation JAD attribute is missing or it is not set to manual, the setAppOrientation() method throws an IllegalArgumentException.

Parameters:

newAppOrientation - value of application's new UI orientation.
The value must be one of the following: ORIENTATION_PORTRAIT or ORIENTATION_LANDSCAPE

Throws:

java.lang.IllegalArgumentException - if parameter newAppOrientation value is not valid or not supported by device or if the JAD attribute Nokia-MIDlet-App-Orientation is not correctly set.

getAppOrientation

public static int getAppOrientation()

Gets application's current UI orientation.

Returns:

constant value of application's UI orientation.
The value can be one of the following: ORIENTATION_PORTRAIT or ORIENTATION_LANDSCAPE.

getDisplayOrientation

public static int getDisplayOrientation()

Gets the current display orientation.

Returns:

constant value of display orientation.
The value can be one of the following: ORIENTATION_PORTRAIT, ORIENTATION_LANDSCAPE, ORIENTATION_PORTRAIT_180 or ORIENTATION_LANDSCAPE_180.

addOrientationListener

public static void addOrientationListener(OrientationListener listener)

Registers an orientation listener. Applications that need information about events related to display orientation changes need to register with Orientation to get notifications of the events. Applications can register multiple listeners.

After receiving device's display orientation change notification via OrientationListener the application itself is responsible for setting its required orientation.

If the listener has already been registered then the addOrientationListener()method does nothing.

Parameters:

listener - the listener to register.

Throws:

java.lang.IllegalArgumentException - if listener is not instance of OrientationListener.

java.lang.NullPointerException - if listener is null.

removeOrientationListener

public static void removeOrientationListener(OrientationListener listener)

Removes an orientation listener. If the listener does not exist then this method does nothing.

Parameters:

listener - listener to be removed