One of the interesting things added in PhoneGap 1.3.0 (and something I missed until fairly recently), was support for battery events. Using these events is pretty simple so I thought I'd whip up a quick demo.

Before going any further, note that there is currently a documentation bug. While the API as described works perfectly, you will not be able to use these events unless you do two things:

  1. Edit your plugins.xml file to include this: <plugin name="Battery" value="com.phonegap.BatteryListener"/>. You normally only edit this file when adding additional plugins. I'm betting that the PhoneGap devs forgot to update the default plugins.xml file.

  1. The second thing you need to do I was able to skip as my project already had it. You must ensure the BROADCAST_STICKY permission is enabled in AndroidManifest.xml. Again, for my project this was already done.

Big thanks to Simon Mac Donald for letting me know both of the above. Once I had these in (and fixed a stupid JavaScript error on my part, hint, avoid "status" as a variable name), my demo worked.

There are three main events you can listen to:

  • batterystatus: Fired when the battery level changes or if the device is plugged in/removed.
  • batterylow: Fired when the battery is low. The definition of "low" is device dependent.
  • batterycritical: Ditto the above.

Note that there is no generic way to get the status of the battery right now. In my testing, batterystatus seemed to fire immediately. So it's probably safe to use it to get your status on application startup, but keep in mind it may not be immediate for you.

All three events pass a simple object containing two keys: level and isPlugged. level is a numeric percentage value. isPlugged is a boolean representing if the device is plugged in or not.

Here's a simple demo:


<!DOCTYPE HTML>
<html>
  <head>
    <meta name="viewport" content="width=320; user-scalable=no" />
    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
    <title>Minimal AppLaud App</title>

	  <script type="text/javascript" charset="utf-8" src="phonegap-1.3.0.js"></script>
	  <script type="text/javascript" charset="utf-8">
		var statusdiv;

		var drawStatus = function(info){
			var s = "<p><b>Battery Status</b><br/>";
			s += "Level is "+info.level + "<br/>";
			s += "Plugged in is "+info.isPlugged;
			s += "</p>";
			statusdiv.innerHTML = s;
		};
				
      	var battCrit = function(info) {
			navigator.notification.alert("Your battery is SUPER low!");
			drawStatus(info);
		};

      	var battLow = function(info) {
			navigator.notification.alert("Your battery is low!");
			drawStatus(info);
		};

      	var battStat = function(info) {
			drawStatus(info);
		};
	  
        var onDeviceReady = function() {
			//listen for battery events
			window.addEventListener("batterycritical", battCrit, false);
			window.addEventListener("batterylow", battLow, false);
			window.addEventListener("batterystatus", battStat, false);
        };

        function init() {
            document.addEventListener("deviceready", onDeviceReady, true);
			statusdiv = document.getElementById("status");
        }   
	  </script>  
  </head>


  <body onload="init();">

    <h2>Battery Tester</h2>

	<div id="status"></div>

  </body>
</html>

As you can see, I've got listeners for all three events, with the low and critical going out of their way to warn the user that bad times are ahead. Here's a quick screen shot to give you an idea of how it renders.

So obviously you wouldn't typically need to show the battery status at all times. I could definitely see using the low/critical events to warn the user to save their work or perform some other safekeeping measures in case the device suddenly shuts down.

p.s. I can't post this blog entry without a quick shoutout to one of my coworker's recent PhoneGap demo. Batteries are boring. Multiple screens are freaking cool: Multi-Screen iOS Apps with PhoneGap