OpenLayers 3 API Documentation - Class: ol.DeviceOrientation

new DeviceOrientation

The ol.DeviceOrientation class provides access to DeviceOrientation information and events, see the [HTML 5 DeviceOrientation Specification]( http://dev.w3.org/geo/api/spec-source-orientation) 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.

Parameters:

Name	Type	Argument	Description
`options`	ol.DeviceOrientationOptions	<optional>	(Optional) Options.

Source:

deviceorientation.js, line 73

See:

http://dev.w3.org/geo/api/spec-source-orientation

Extends

ol.Object

Members

<static, constant> SUPPORTED :boolean

Indicates if DeviceOrientation is supported in the user's browser.

Source:

deviceorientation.js, line 109

Methods

bindTo

Binds a View to a Model.

Parameters:

Name	Type	Argument	Description
`key`	string		Key.
`target`	ol.Object		Target.
`targetKey`	string	<optional>	(Optional) Target key.
`noNotify`	boolean	<optional>	(Optional) No notify.

Inherited From:

ol.Object#bindTo

Source:

object.js, line 147

get

Gets a value.

Parameters:

Name	Type	Description
`key`	string	Key.

Inherited From:

ol.Object#get

Source:

object.js, line 170

Returns:

Value.

Type: *

getAlpha

Source:

deviceorientation.js, line 147

Returns:

The alpha value of the DeviceOrientation, in radians.

Type: number | undefined

getBeta

Source:

deviceorientation.js, line 161

Returns:

The beta value of the DeviceOrientation, in radians.

Type: number | undefined

getGamma

Source:

deviceorientation.js, line 175

Returns:

The gamma value of the DeviceOrientation, in radians.

Type: number | undefined

getHeading

Source:

deviceorientation.js, line 189

Returns:

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

Type: number | undefined

getTracking

Are we tracking the device's orientation?

Source:

deviceorientation.js, line 203

Returns:

The current tracking state, true if tracking is on.

Type: boolean

notify

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.

Parameters:

Name	Type	Description
`key`	string	Key.

Inherited From:

ol.Object#notify

Source:

object.js, line 208

on

Listen for a certain type of event.

Parameters:

Name	Type	Argument	Description
`type`	string \| Array.<string>		The event type or array of event types.
`listener`	Function		The listener function.
`scope`	Object	<optional>	(Optional) Object is whose scope to call the listener.

Inherited From:

ol.Object#on

Source:

object.js, line 240

Returns:

Unique key for the listener.

Type: goog.events.Key

once

Listen once for a certain type of event.

Parameters:

Name	Type	Argument	Description
`type`	string \| Array.<string>		The event type or array of event types.
`listener`	Function		The listener function.
`scope`	Object	<optional>	(Optional) Object is whose scope to call the listener.

Inherited From:

ol.Object#once

Source:

object.js, line 253

Returns:

Unique key for the listener.

Type: goog.events.Key

set

Sets a value.

Parameters:

Name	Type	Description
`key`	string	Key.
`value`	*	Value.

Inherited From:

ol.Object#set

Source:

object.js, line 263

setTracking

Enable or disable tracking of DeviceOrientation events.

Parameters:

Name	Type	Description
`tracking`	boolean	True to enable and false to disable tracking.

Source:

deviceorientation.js, line 234

setValues

Sets a collection of key-value pairs.

Parameters:

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

Inherited From:

ol.Object#setValues

Source:

object.js, line 286

un

Unlisten for a certain type of event.

Parameters:

Name	Type	Argument	Description
`type`	string \| Array.<string>		The event type or array of event types.
`listener`	Function		The listener function.
`scope`	Object	<optional>	(Optional) Object is whose scope to call the listener.

Inherited From:

ol.Object#un

Source:

object.js, line 326

unbind

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.

Parameters:

Name	Type	Description
`key`	string	Key.

Inherited From:

ol.Object#unbind

Source:

object.js, line 305

unbindAll

Removes all bindings.

Inherited From:

ol.Object#unbindAll

Source:

object.js, line 344

unByKey

Removes an event listener which was added with listen() by the key returned by on().

Parameters:

Name	Type	Argument	Description
`key`	number	<nullable>	Key.

Inherited From:

ol.Object#unByKey

Source:

object.js, line 336