OpenLayers v4.0.1 API - Class: DeviceOrientation

# Class: DeviceOrientation

This documentation is for OpenLayers v4.0.1. The latest is v.

## ol.DeviceOrientation

The ol.DeviceOrientation class provides access to information from DeviceOrientation events. See the HTML 5 DeviceOrientation Specification for more details.

Many new computers, and especially mobile phones and tablets, provide hardware support for device orientation. Web developers targeting mobile devices will be especially interested in this class.

Device orientation data are relative to a common starting point. For mobile devices, the starting point is to lay your phone face up on a table with the top of the phone pointing north. This represents the zero state. All angles are then relative to this state. For computers, it is the same except the screen is open at 90 degrees.

Device orientation is reported as three angles - `alpha`, `beta`, and `gamma` - relative to the starting position along the three planar axes X, Y and Z. The X axis runs from the left edge to the right edge through the middle of the device. Similarly, the Y axis runs from the bottom to the top of the device through the middle. The Z axis runs from the back to the front through the middle. In the starting position, the X axis points to the right, the Y axis points away from you and the Z axis points straight up from the device lying flat.

The three angles representing the device orientation are relative to the three axes. `alpha` indicates how much the device has been rotated around the Z axis, which is commonly interpreted as the compass heading (see note below). `beta` indicates how much the device has been rotated around the X axis, or how much it is tilted from front to back. `gamma` indicates how much the device has been rotated around the Y axis, or how much it is tilted from left to right.

For most browsers, the `alpha` value returns the compass heading so if the device points north, it will be 0. With Safari on iOS, the 0 value of `alpha` is calculated from when device orientation was first requested. ol.DeviceOrientation provides the `heading` property which normalizes this behavior across all browsers for you.

It is important to note that the HTML 5 DeviceOrientation specification indicates that `alpha`, `beta` and `gamma` are in degrees while the equivalent properties in ol.DeviceOrientation are in radians for consistency with all other uses of angles throughout OpenLayers.

To get notified of device orientation changes, register a listener for the generic `change` event on your `ol.DeviceOrientation` instance.

#### new ol.DeviceOrientation(opt_options)

src/ol/deviceorientation.js, line 65

  Name | Type | Description
  --- | --- | ---

  `options`

  Options.

  Name | Type | Description
  --- | --- | ---
  `tracking` | boolean | undefined | Start tracking. Default is `false`.

  See:
    - http://www.w3.org/TR/orientation-event/

  ##### Fires:

  - `change` (ol.events.Event) - Generic change event. Triggered when the revision counter is increased.
  - `change:alpha` (ol.Object.Event)
  - `change:beta` (ol.Object.Event)
  - `change:gamma` (ol.Object.Event)
  - `change:heading` (ol.Object.Event)
  - `change:tracking` (ol.Object.Event)
  - `propertychange` (ol.Object.Event) - Triggered when a property is changed.

### Extends

- ol.Object

### Observable Properties

Name | Type | Settable | ol.Object.Event type | Description
--- | --- | --- | --- | ---
`alpha` | number | undefined | no | `change:alpha` | The euler angle in radians of the device from the standard Z axis.
`beta` | number | undefined | no | `change:beta` | The euler angle in radians of the device from the planar X axis.
`gamma` | number | undefined | no | `change:gamma` | The euler angle in radians of the device from the planar Y axis.
`heading` | number | undefined | no | `change:heading` | The heading of the device relative to north, in radians, normalizing for different browser behavior.
`tracking` | boolean | yes | `change:tracking` | Changes in device orientation are being tracked.

### Methods

#### changed() inherited

src/ol/observable.js, line 58

  Increases the revision counter and dispatches a 'change' event.

#### dispatchEvent(event) inherited

src/ol/observable.js, line 75

  Dispatches an event and calls all listeners listening for events of this type. The event parameter can either be a string or an Object with a `type` property.

  Name | Type | Description
  --- | --- | ---
  `event` | Object | ol.events.Event | string | Event object.

#### get(key){*} inherited

src/ol/object.js, line 101

  Gets a value.

  Name | Type | Description
  --- | --- | ---
  `key` | string | Key name.

  ##### Returns:

  Value.

#### getAlpha(){number|undefined}

src/ol/deviceorientation.js, line 133

  Rotation around the device z-axis (in radians).

  ##### Returns:

  The euler angle in radians of the device from the standard Z axis.

#### getBeta(){number|undefined}

src/ol/deviceorientation.js, line 146

  Rotation around the device x-axis (in radians).

  ##### Returns:

  The euler angle in radians of the device from the planar X axis.

#### getGamma(){number|undefined}

src/ol/deviceorientation.js, line 159

  Rotation around the device y-axis (in radians).

  ##### Returns:

  The euler angle in radians of the device from the planar Y axis.

#### getHeading(){number|undefined}

src/ol/deviceorientation.js, line 172

  The heading of the device relative to north (in radians).

  ##### Returns:

  The heading of the device relative to north, in radians, normalizing for different browser behavior.

#### getKeys(){Array.<string>} inherited

src/ol/object.js, line 115

  Get a list of object property names.

  ##### Returns:

  List of property names.

#### getProperties(){Object.<string, *>} inherited

src/ol/object.js, line 125

  Get an object of all property names and values.

  ##### Returns:

  Object.

#### getRevision(){number} inherited

src/ol/observable.js, line 84

  Get the version number for this object. Each time the object is modified, its version number will be incremented.

  ##### Returns:

  Revision.

#### getTracking(){boolean}

src/ol/deviceorientation.js, line 184

  Determine if orientation is being tracked.

  ##### Returns:

  Changes in device orientation are being tracked.

#### on(type, listener, opt_this){ol.EventsKey|Array.<ol.EventsKey>} inherited

src/ol/observable.js, line 99

  Listen for a certain type of event.

  Name | Type | Description
  --- | --- | ---
  `type` | string | Array.<string> | The event type or array of event types.
  `listener` | function | The listener function.
  `this` | Object | The object to use as `this` in `listener`.

  ##### Returns:

  Unique key for the listener. If called with an array of event types as the first argument, the return will be an array of keys.

#### once(type, listener, opt_this){ol.EventsKey|Array.<ol.EventsKey>} inherited

src/ol/observable.js, line 124

  Listen once for a certain type of event.

  Name | Type | Description
  --- | --- | ---
  `type` | string | Array.<string> | The event type or array of event types.
  `listener` | function | The listener function.
  `this` | Object | The object to use as `this` in `listener`.

  ##### Returns:

  Unique key for the listener. If called with an array of event types as the first argument, the return will be an array of keys.

#### set(key, value, opt_silent) inherited

src/ol/object.js, line 150

  Sets a value.

  Name | Type | Description
  --- | --- | ---
  `key` | string | Key name.
  `value` | * | Value.
  `silent` | boolean | Update without triggering an event.

#### setProperties(values, opt_silent) inherited

src/ol/object.js, line 170

  Sets a collection of key-value pairs. Note that this changes any existing properties and adds new ones (it does not remove any existing properties).

  Name | Type | Description
  --- | --- | ---
  `values` | Object.<string, *> | Values.
  `silent` | boolean | Update without triggering an event.

#### setTracking(tracking)

src/ol/deviceorientation.js, line 214

  Enable or disable tracking of device orientation events.

  Name | Type | Description
  --- | --- | ---
  `tracking` | boolean | The status of tracking changes to alpha, beta and gamma. If true, changes are tracked and reported immediately.

#### un(type, listener, opt_this) inherited

src/ol/observable.js, line 147

  Unlisten for a certain type of event.

  Name | Type | Description
  --- | --- | ---
  `type` | string | Array.<string> | The event type or array of event types.
  `listener` | function | The listener function.
  `this` | Object | The object which was used as `this` by the `listener`.

#### unset(key, opt_silent) inherited

src/ol/object.js, line 184

  Unsets a property.

  Name | Type | Description
  --- | --- | ---
  `key` | string | Key name.
  `silent` | boolean | Unset without triggering an event.