Safari Developer Library

Developer

DeviceOrientationEvent Class Reference

Options
Deployment Target:

On This Page

DeviceOrientationEvent

Inheritance


  • Event
  • DeviceOrientationEvent

Conforms To


Not Applicable

Import Statement


Not Applicable Not Applicable

Availability


Available in iOS 4.2 and later.

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.

  • Initializes a new device orientation event.

    Declaration

    JavaScript

    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.

  • alpha Property

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

    Declaration

    JavaScript

    readonly attribute double alpha

    Discussion

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

    Availability

    Available in iOS 4.2 and later.

  • beta Property

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

    Declaration

    JavaScript

    readonly attribute double beta

    Discussion

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

    Availability

    Available in iOS 4.2 and later.

  • gamma Property

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

    Declaration

    JavaScript

    readonly attribute double gamma

    Discussion

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

    Availability

    Available in iOS 4.2 and later.

  • The accuracy of the compass data in degrees.

    Declaration

    JavaScript

    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

    Available in iOS 5.0 and later.

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

    Declaration

    JavaScript

    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

    Available in iOS 5.0 and later.