DeviceOrientationEvent Class Reference

Inherits from
Event
Companion guide
Availability
Available in iOS 4.2 and later.

Overview

Instances of the DeviceOrientationEvent class are fired only when the device has a gyroscope and while the user is changing the orientation. The DeviceOrientationEvent class encapsulates the angles of rotation in degrees and heading.

The angles of rotation—the alpha, beta, and gamma properties—do not represent the real world orientation. They are defined as an offset from an arbitrary direction—typically, the direction in which the device was held when the orientation was first obtained. Therefore, you can only use the angles to track changes in orientation, you cannot derive the direction in which the device is currently facing. To track changes, save the first device orientation event and use it as a reference for subsequent values. If you want a real world heading, use the webkitCompassHeading property.

Because some devices may not have a gyroscope, you can listen for this event. If it does not occur, use the DeviceMotionEvent class to receive raw accelerometer events. From these events you can determine an approximate orientation.

You register for device orientation events using the window’s addEventListener method by passing deviceorientation as the event type.

Tasks

Creating Orientation Events

Getting Orientation Event Properties

Getting Compass Properties

Properties

alpha

The rotation, in degrees, of the device frame around its z-axis.

readonly attribute double alpha
Discussion

Values are between 0 and 360. This property is null if the device cannot provide this angle.

Availability

beta

The rotation, in degrees, of the device frame around its x-axis.

readonly attribute double beta
Discussion

Values are between -90 and 90. This property is null if the device cannot provide this angle.

Availability

gamma

The rotation, in degrees, of the device frame around its y-axis.

readonly attribute double gamma
Discussion

Values are between -180 and 180. This property is null if the device cannot provide this angle.

Availability

webkitCompassAccuracy

The accuracy of the compass data in degrees.

readonly attribute double webkitCompassAccuracy
Discussion

For example, if this property value is 10, the heading is off by plus or minus 10 degrees. A value of -1 means that the compass is not calibrated and not giving usable readings.

Availability

webkitCompassHeading

A direction that is measured in degrees relative to magnetic north.

readonly attribute double webkitCompassHeading
Discussion

Direction values are measured in degrees starting at due north and continuing clockwise around the compass. Thus, north is 0 degrees, east is 90 degrees, south is 180 degrees, and so on. A negative value indicates an invalid direction.

Availability

Methods

initDeviceOrientationEvent

Initializes a new device orientation event.

void initDeviceOrientationEvent (in DOMString type, in boolean bubbles, in boolean cancelable, in double alpha, in double beta, in double gamma, in double compassHeading, in double compassAccuracy);
Parameters
type

The type of event. Pass deviceorientation.

bubbles

A Boolean value that indicates whether this event is a bubbling event.

cancelable

A Boolean value that indicates whether this event can be canceled.

alpha

The rotation, in degrees, of the device frame around its z-axis.

beta

The rotation, in degrees, of the device frame around its x-axis.

gamma

The rotation, in degrees, of the device frame around its y-axis.

compassHeading

A direction that is measured in degrees relative to magnetic north.

compassAccuracy

The accuracy of the compass data in degrees.

Availability
  • Available in iOS 4.2 and later.