Phonegap Bridge – Compass API CIS 136 Building Mobile Apps 1

Compass API 2

Compass Plug-in org.apache.cordova. device-orientation 3  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  0 is north  navigator.compass is the global object

navigator.compass 4  navigator.compass object has 3 methods  getCurrentHeading  watchHeading  clearWatch  Exposes 1 object  Heading

navigator.compass.getCurrentHeading 5  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 at a single moment in time. (Number)  trueHeading:  The heading relative to the geographic North Pole in degrees 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)

navigator.compass.getCurrentHeading 6 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 }

navigator.compass.watchHeading 7  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

navigator.compass.watchHeading 8 document.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);

navigator.compass.clearWatch 9  Stops watching the compass referenced by the watch ID parameter  watchID: The ID returned by navigator.compass.watchHeading navigator.compass.clearWatch(watchID);

navigator.compass.clearWatch 10  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);

navigator.compass quirkiness 11  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

navigator.compass 12  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