CIS 136 Building Mobile Apps Compass CIS 136 Building Mobile Apps

Compass Plug-in 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

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

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)

navigator.compass.getCurrentHeading() $(document).on("deviceready", function() { 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 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 $(document).on("deviceready", function() { var options = { frequency: 3000 }; // Update every 3 seconds var watchID = navigator.compass.watchHeading(success,error,options); }); function success(heading) { $(‘#heading’).html = 'Heading: ' + heading.magneticHeading; } function error(compassError) $(‘#msg’).html = 'Compass error: ' + compassError.code

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 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

navigator.compass Compass Error object function error(compassError) { $(‘#msg’).html = 'Compass error: ' + compassError.code } Compass Error object 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