W3C Compass API vs theoretical new-fangled API

gistfile1.md

W3C Compass API

from: http://dev.w3.org/2009/dap/system-info/compass.html

interface Compass : Object {
    void getCurrentOrientation (
		CompassCallback successCallback, 
		[Optional] CompassPosition position, 
		[Optional] CompassErrorCallback errorCallback, 
		[Optional] CompassOptions options
	);
    int  watchOrientation (
		CompassCallback successCallback, 
		[Optional] CompassPosition position, 
		[Optional] CompassErrorCallback errorCallback, 
		[Optional] CompassOptions options
	);
    void updatePosition (
		int watchId, 
		CompassPosition compassPosition
	);
    void clearWatch (int watchId);
};

[Callback=FunctionOnly, NoInterfaceObject]
interface CompassCallback : Object {
    void handleEvent (Orientation orientation);
};

[Callback=FunctionOnly, NoInterfaceObject]
interface CompassErrorCallback : Object {
    void handleEvent (OrientationError error);
};

interface CompassPosition : Object {
    readonly attribute float        latitude;
    readonly attribute float        longitude;
    readonly attribute float        altitudeMeteres;
    readonly attribute DOMTimeStamp timestamp;
};

[Callback, NoInterfaceObject]
interface CompassOptions : Object {
             attribute unsigned int sampleInterval;
    readonly attribute boolean      enableHighAccuracy;
    readonly attribute long         timeout;
};

interface Orientation : Object {
    readonly attribute DOMTimeStamp timestamp;
    readonly attribute float        declination;
    readonly attribute float        fieldStrength;
    readonly attribute float        horizontalStrength;
    readonly attribute float        inclination;
    readonly attribute float        x;
    readonly attribute float        y;
    readonly attribute float        z;
};

interface OrientationError : Object {
    readonly attribute unsigned short UNKNOWN_ERROR;
    readonly attribute unsigned short PERMISSION_DENIED;
    readonly attribute unsigned short ORIENTATION_UNAVAILALBE;
    readonly attribute unsigned short TIMEOUT;
    readonly attribute unsigned short INVALID_VALUE;
    readonly attribute unsigned short code;
    readonly attribute DOMString      message;
};

new-fangled API

interface PGCompass : Object implements EventEmitter {
    void getCurrentOrientation (
		PGCompassOptions options
		PGCompassCallback callback
	);
    void updatePosition (
		CompassPosition compassPosition
	);
};

// same as CompassOptions, but includes position
interface PGCompassOptions : CompassOptions {
    attribute CompassPosition   position;
};

[Callback=FunctionOnly, NoInterfaceObject]
interface PGCompassCallback : Object {
    void handleEvent (OrientationError err,  Orientation orientation);
};

notes

• require("phonegap/compass") returns an instance of PGCompass

• instead of watchOrientation() and clearWatch(), you use the Node EventEmitter style:

  • compass.on("change", callback(anOrientation){...})
  • compass.removeListener("change", callback)
  • compass.removeAllListeners("change")

• the W3C API is a bit richer, in that using watch() gives you separately updateable orientation thingees. The doc notes that this doesn't seem to be required. If it actually was required, then require("phonegap/compass") would need to be changed to return a factory function to create a new compass, instead of returning a singleton compass instance