# Class: DeviceOrientation

## ol.DeviceOrientation

The ol.DeviceOrientation class provides access to DeviceOrientation information and 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 targetting 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.

#### new ol.DeviceOrientation(opt_options) experimental

src/ol/deviceorientation.js, line 76

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

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

  ##### Fires:

  - `beforepropertychange` (ol.ObjectEvent) experimental - Triggered before a property is changed.
  - `change` experimental - Triggered when the device orientation changes.
  - `change:alpha` (ol.ObjectEvent) experimental
  - `change:beta` (ol.ObjectEvent) experimental
  - `change:gamma` (ol.ObjectEvent) experimental
  - `change:heading` (ol.ObjectEvent) experimental
  - `change:tracking` (ol.ObjectEvent) experimental
  - `propertychange` (ol.ObjectEvent) experimental - Triggered when a property is changed.

### Extends

- ol.Object

### Observable Properties

Name | Type | Settable | ol.ObjectEvent 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` | The status of tracking changes to alpha, beta and gamma. If true, changes are tracked and reported immediately.

### Methods

#### bindTo(key, target, opt_targetKey){ol.ObjectAccessor} inherited experimental

src/ol/object.js, line 257

  The bindTo method allows you to set up a two-way binding between a `source` and `target` object. The method returns an ol.ObjectAccessor with a transform method that lets you transform values on the way from the source to the target and on the way back.

  For example, if you had two map views (sourceView and targetView) and you wanted the target view to have double the resolution of the source view, you could transform the resolution on the way to and from the target with the following:

      sourceView.bindTo('resolution', targetView)
        .transform(
          function(sourceResolution) {
            // from sourceView.resolution to targetView.resolution
            return 2 * sourceResolution;
          },
          function(targetResolution) {
            // from targetView.resolution to sourceView.resolution
            return targetResolution / 2;
          }
        );

  Name | Type | Description
  --- | --- | ---
  `key` | string | Key name.
  `target` | ol.Object | Target.
  `targetKey` | string | optional Target key.

#### dispatchChangeEvent() inherited experimental

src/ol/observable.js, line 41

  Dispatches a `change` event.

  ##### Fires:

  - `change` experimental

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

src/ol/object.js, line 314

  Gets a value.

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

  ##### Returns:

  Value.

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

src/ol/deviceorientation.js, line 145

  ##### Returns:

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

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

src/ol/deviceorientation.js, line 161

  ##### Returns:

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

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

src/ol/deviceorientation.js, line 177

  ##### Returns:

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

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

src/ol/deviceorientation.js, line 193

  ##### Returns:

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

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

src/ol/object.js, line 342

  Get a list of object property names.

  ##### Returns:

  List of property names.

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

src/ol/object.js, line 374

  Get an object of all property names and values.

  ##### Returns:

  Object.

#### getTracking(){boolean} experimental

src/ol/deviceorientation.js, line 210

  Are we tracking the device's orientation?

  ##### Returns:

  The status of tracking changes to alpha, beta and gamma. If true, changes are tracked and reported immediately.

#### notify(key) inherited experimental

src/ol/object.js, line 394

  Notify all observers of a change on this property. This notifies both objects that are bound to the object's property as well as the object that it is bound to.

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

#### on(type, listener, opt_this){goog.events.Key} inherited experimental

src/ol/observable.js, line 63

  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 | optional The object to use as `this` in `listener`.

  ##### Returns:

  Unique key for the listener.

#### once(type, listener, opt_this){goog.events.Key} inherited experimental

src/ol/observable.js, line 76

  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 | optional The object to use as `this` in `listener`.

  ##### Returns:

  Unique key for the listener.

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

src/ol/object.js, line 425

  Sets a value.

  Name | Type | Description
  --- | --- | ---
  `key` | string | Key name.
  `value` | * | Value.

#### setTracking(tracking) experimental

src/ol/deviceorientation.js, line 244

  Enable or disable tracking of DeviceOrientation events.

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

#### setValues(values) inherited experimental

src/ol/object.js, line 454

  Sets a collection of key-value pairs.

  Name | Type | Description
  --- | --- | ---
  `values` | Object.<string, *> | Values.

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

src/ol/observable.js, line 88

  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 | optional The object to use as `this` in `listener`.

#### unbind(key) inherited experimental

src/ol/object.js, line 468

  Removes a binding. Unbinding will set the unbound property to the current value. The object will not be notified, as the value has not changed.

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

#### unbindAll() inherited experimental

src/ol/object.js, line 492

  Removes all bindings.

#### unByKey(key) inherited experimental

src/ol/observable.js, line 98

  Removes an event listener using the key returned by `on()` or `once()`.

  Name | Type | Description
  --- | --- | ---
  `key` | goog.events.Key | Key.