Phonegap Bridge – Compass API

CIS 136 Building Mobile Apps

1

2

Compass API

3

Compass Plug-inorg.apache.cordova. device-orientation

provides access to the device's compass a sensor that detects the direction or heading that the

device is pointed measures the heading in degrees from 0 to 359.99

0 is north navigator.compass is the global object

4

navigator.compass navigator.compass object has 3 methods

getCurrentHeading watchHeading clearWatch

Exposes 1 object Heading

5

navigator.compass.getCurrentHeading Get the current compass heading If successful, the heading is returned in a CompassHeading object CompassHeading object has 4 properties:

magneticHeading: The heading in degrees from 0-359.99 at a single moment in time. (Number)

trueHeading: The heading relative to the geographic North Pole in degrees 0-359.99 at a single

moment in time A negative value indicates that the true heading can't be determined. (Number)

headingAccuracy: The deviation in degrees between the reported heading and the true heading.

(Number) timestamp:

The time at which this heading was determined. (milliseconds)

6

navigator.compass.getCurrentHeading

document.addEventListener("deviceready", onDeviceReady, false);

function onDeviceReady() {navigator.compass.getCurrentHeading(success,error); }function success(heading){ // gets compass heading object $(‘#heading‘).html=heading.magneticHeading);}function error(error){//gets error object}

7

navigator.compass.watchHeading Gets the device's current heading at a regular interval Can accept options

compass Options may contain the following keys: frequency: How often to retrieve the compass heading in milliseconds.

(Number) (Default: 100) filter: The change in degrees required to initiate a watchHeading success

callback (Number) When this value is set, frequency is ignored

Each time the heading is retrieved, the success function (aka callback function ) is executed

Returns data – in this example an object named watchID returned watch ID references the compass watch interval The watch ID can be used with navigator.compass.clearWatch

method to stop watching the navigator.compass

8

navigator.compass.watchHeadingdocument.addEventListener("deviceready", onDeviceReady, false);

function onDeviceReady() { navigator.compass.watchHeading(success,error,options); }function success(heading){ $(‘heading’).html = 'Heading: ' + heading.magneticHeading;}function error(compassError){$(‘#msg’).html = 'Compass error: ' + compassError.code}var options = { frequency: 3000 }; // Update every 3 seconds

var watchID = navigator.compass.watchHeading(success,error,options);

9

navigator.compass.clearWatch Stops watching the compass referenced by the watch ID

parameter watchID: The ID returned by navigator.compass.watchHeading

navigator.compass.clearWatch(watchID);

10

navigator.compass.clearWatch Stops watching the compass referenced by the watch ID

parameter watchID: The ID returned by navigator.compass.watchHeading

navigator.compass.clearWatch(watchID);

Full example:var watchID = navigator.compass.watchHeading(onSuccess, onError, options);

// ... later on ...

navigator.compass.clearWatch(watchID);

11

navigator.compass quirkiness Quirks

IOS Only one watchHeading can be in effect at one time The trueHeading property is only returned for location services enabled via

navigator.geolocation.watchLocation() heading factors in the device's current orientation

It does not reference its absolute position (for apps that supports that orientation).

Windows Phone No support for filter

Android The trueHeading property is not supported, but reports the same value as

magneticHeading The headingAccuracy property is always 0 because there is no difference

between the magneticHeading and trueHeading No support for filter

12

navigator.compass Compass Error

A CompassError object is returned to the error function (i.e. compassError callback function) when an error occurs

Provides 1 property: Code: predefined per these constants

CompassError.COMPASS_INTERNAL_ERR CompassError.COMPASS_NOT_SUPPORTED