public class Orientation
extends java.lang.Object
It is not expected that all terminals will support all of these parameters. If a terminal supports getting the Orientation, it MUST provide the compass azimuth information. Providing the pitch and roll is optional. Most commonly, this class will be used to obtain the current compass direction.
It is up to the terminal to define its own axes, but it is generally recommended that the longitudinal axis is aligned with the bottom-to-top direction of the screen. This means that the pitch is positive when the top of the screen is up and the bottom of the screen down (when roll is zero). The roll is positive when the device is tilted clockwise looking from the direction of the bottom of the screen, i.e. when the left side of the screen is up and the right side of the screen is down (when pitch is zero).
No accuracy data is given for Orientation.
This class is only a container for the information. The constructor does not validate the parameters passed in but just retains the values. The get* methods return the values passed in the constructor. When the platform implementation returns Orientation objects, it MUST ensure that it only returns objects where the parameters have values set as described for their semantics in this class.
Constructor and Description |
---|
Orientation(float azimuth,
boolean isMagnetic,
float pitch,
float roll)
Constructs a new Orientation object with the compass azimuth, pitch and roll
parameters specified.
|
Modifier and Type | Method and Description |
---|---|
float |
getCompassAzimuth()
Returns the terminal's horizontal compass azimuth in degrees relative to either
magnetic or true north.
|
static Orientation |
getOrientation()
Returns the terminal's current orientation.
|
float |
getPitch()
Returns the terminal's tilt in degrees defined as an angle in the vertical plane
orthogonal to the ground, and through the longitudinal axis of the terminal.
|
float |
getRoll()
Returns the terminal's rotation in degrees around its own longitudinal axis.
|
boolean |
isOrientationMagnetic()
Returns a boolean value that indicates whether this Orientation is relative to the
magnetic field of the Earth or relative to true north and gravity.
|
public Orientation(float azimuth, boolean isMagnetic, float pitch, float roll)
If the pitch or roll is undefined, the parameter shall be given as Float.NaN.
Note that this class is only a container for the information. The constructor does not validate the parameters passed in but just retains the values.
azimuth
- the compass azimuth relative to true or magnetic north. Valid range:
[0.0, 360.0). For example, value 0.0 indicates north, 90.0 east, 180.0
south and 270.0 west.isMagnetic
- a boolean stating whether the compass azimuth is given as relative to
the magnetic field of the Earth (=true) or to true north and gravity
(=false)pitch
- the pitch of the terminal in degrees. Valid range: [-90.0, 90.0]roll
- the roll of the terminal in degrees. Valid range: [-180.0, 180.0)public static Orientation getOrientation() throws LocationException, java.lang.SecurityException
LocationException
- if the implementation does not support orientation determinationjava.lang.SecurityException
- if the calling application does not have a permission to query the
orientationpublic float getCompassAzimuth()
isOrientationMagnetic()
public float getPitch()
public float getRoll()
public boolean isOrientationMagnetic()
getCompassAzimuth()