As a WebWorks developer, I can receive events when there is a change in the status of the battery

[kwallis]

The developer should be able to know when the device is plugged in, unplugged, or when the battery level changes by a percentage point. Additional, the developer can be notified when the device enters a low or critical battery level state. This is based on registering to receive events. Registration should occur after the device ready event is fired.

Acceptance Criteria

1. The "batterystatus" event should be triggered:
   • Whenever the battery level changes by a percentage point or greater.
   • When the device begins receiving a charge.
   • When the device is no longer receiving a charge.
2. The "batterylow" and "batterycritical" events will be triggered when the system enters a low or critical battery state, respectively. This is defined by the device platform.
3. The API should mimic the Cordova signature for these events:
   • a callback is passed into blackberry.event.addEventListener, associated with the "batterystatus", "batterycritical", or "batterylow" event.
   • Multiple callbacks can be passed in for each event and they should all be called. No guarantee on ordering of calls is required
   • Multiple attempts to register the same callback will be discarded, i.e. you cannot register the same callback function more than once.
   • eg. blackberry.event.addEventListener("batterystatus", batteryStatus);
4. The callback functions for all events will be passed an object having two properties
   • level: The percentage of the battery charge (0-100). (Number)
   • isPlugged: A boolean that represents whether or not the device is receiving a charge. (Boolean)
5. To remove a listener, the developer can use the blackberry.event.removeEventListener method, that takes the event string as parameter, and the callback to remove
   • eg. blackberry.event.removeEventListener("batterystatus", batteryStatus);
6. all events will fall into the "blackberry.event" feature id, which will be used for whitelisting.

[kwallis]

cc @nukulb @tohman

Updated description to add the "batterylow" and "batterycritical" events. Note the example code originally had the event passed in as "batteryStatus", not "batterystatus". This has been changed as well

[jeffheifetz]

I believe the phonegap/cordova signature has a specific removeEventListener method. Are we intentionally choosing to remove by null?

Additionally the phonegap/cordova method has 3 parameters mapping to the three w3c parameters. We have no parameter for whether the event should useCapture. Is this intentional?

Lastly there is no reference as to whether we should track multiple listeners. I believe the phonegap/cordova method does support multiple listeners.

[kwallis]

Update 2

Added support for multiple callbacks, and the removeEventListener method

[tohman]

There are no pps events for 'low' and 'critical' battery levels. We need to define what are battery levels when events for 'low' and 'critical' are fired.

[nukulb]

First thing to find out is if the NDK has similar events, if it does we copy their percentage.

If they don't, which I suspect they don't, we can make two numbers up like 9 for low and 4 for critical. If we change it later, there is no User impact so I don't think its that big a deal

[tohman]

Where do I check the values NDK has?

[erhorim]

Feature implemented by blackberry-webworks/BB10-Webworks-API#18