OpenLayers 3 API Documentation

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

Options.

Name Type Description
tracking boolean | undefined experimental

Start tracking. Default is false.
See:
Fires:

Extends

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 301

The bindTo method allows you to set up a two-way binding between a source and target object. The method returns an object with a transform method that you can use to provide from and to functions to 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

Target key.

dispatchChangeEvent() inherited experimental

src/ol/observable.js, line 42

Dispatches a change event.

Fires:
  • change experimental

get(key){*} inherited experimental

src/ol/object.js, line 358

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 386

Get a list of object property names.

Returns:
List of property names.

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

src/ol/object.js, line 418

Get an object of all property names and values.

Returns:
Object.

getRevision(){number} inherited experimental

src/ol/observable.js, line 52
Returns:
Revision.

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.

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

src/ol/observable.js, line 65

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.

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

src/ol/observable.js, line 78

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.

set(key, value) inherited experimental

src/ol/object.js, line 448

Sets a value.

Name Type Description
key string

Key name.
value *

Value.

setProperties(values) inherited experimental

src/ol/object.js, line 477

Sets a collection of key-value pairs.

Name Type Description
values Object.<string, *>

Values.

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.

un(type, listener, opt_this) inherited

src/ol/observable.js, line 91

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.

unbind(key) inherited experimental

src/ol/object.js, line 491

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 515

Removes all bindings.

unByKey(key) inherited

src/ol/observable.js, line 101

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

Name Type Description
key goog.events.Key

Key.