Respond to low battery conditions

If the BlackBerry device battery drains completely, the device closes all applications and turns off until the battery recharges. Your application can receive notifications about changes in battery power level and state, so you can evaluate the remaining battery power level and respond by saving the application state and warning the BlackBerry device user before the system turns off. The BlackBerry 10 SDK for Adobe AIR provides APIs that allow access to information about the battery properties, and that dispatch events when the value of those properties change. The Device class provides properties that you can use to check the status of the battery.

Property

Description

Device.device.batteryMonitoringEnabled

Turns on or turns off battery monitoring.

Device.device.batteryLevel

If battery monitoring is turned on, this property returns an integer between 0 and 100, representing the percentage of battery power remaining. If battery monitoring is turned off, this property returns a value of -1.

Device.device.batteryState

If battery monitoring is turned on, this property returns the state of the battery. The battery state can be either FULL, CHARGING, or UNPLUGGED. If battery monitoring is not turned on, this property returns a value of UNKNOWN.

The BatteryEvent class in the qnx.events package includes events you can use to watch for changes in the status of the battery.

Event

Description

DeviceBatteryEvent.LEVEL_CHANGE

Dispatched when a change to the battery power level occurs.

DeviceBatteryEvent.STATE_CHANGE

Dispatched whenever a change to the battery state occurs (that is, when the battery begins charging, has completed charging but is still plugged in, or is unplugged and discharging).

To receive information about the battery, you must set the Boolean property batteryMonitoringEnabled to true. With this property set you can add event listeners that listen for changes in the value of the battery power level or state property, and you can evaluate and respond, by saving the application state and asking users to charge their device when possible.

Battery monitoring cannot be tested on the BlackBerry 10 Device Simulator. Because the BlackBerry 10 Device Simulator does not have a battery to monitor, the Device.device.batteryLevel and the Device.device.batteryState properties always return values of -1 and UNKNOWN, respectively.

Listen for a low battery condition

How to

Listen for a low battery condition.

Solution

Define the variables for the battery power level and battery state.

public static var bLevel:int;
public static var bState:int;

Set the deviceBatteryMonitoring property to true to access the values for the battery power level and state so you can initialize the values of the bLevel and bState variables.

Device.device.batteryMonitoringEnabled = true;
bLevel = Device.device.batteryLevel;
bState = Device.device.batteryState;

Set up event listeners to listen for the DeviceBatteryEvent.LEVEL_CHANGE and DeviceBatteryEvent.STATE_CHANGE events.

Device.device.addEventListener(DeviceBatteryEvent.LEVEL_CHANGE, onLevelChange);
Device.device.addEventListener(DeviceBatteryEvent.STATE_CHANGE, onStateChange);

Define the callback methods for the event listeners. In the following code sample, the appropriate variable is updated to reflect the new level or state of the battery.

public function onLevelChange(evt:DeviceBatteryEvent):void
{
   bLevel = evt.batteryLevel;
   evaluate();
}
public function onStateChange(evt:DeviceBatteryEvent):void 
{
   bState = evt.batteryState;
   evaluate();
}

Evaluate the new battery properties and respond as appropriate.

public function evaluate()
{                                  
   if( bState == DeviceBatteryState.UNPLUGGED || bLevel < 10)
   {                                        
      // Save state 
      displayWarning();                          
   }
}

Build requirements

import qnx.system.Device;
import qnx.events.DeviceBatteryEvent;

Discussion

You must set the deviceBatteryMonitoring property to true to access the values for the battery power level and state.

The trace comments can be used to test and troubleshoot your application. Trace statements are displayed in the debug console of Adobe Flash Builder or Powerflasher FDT when testing your application in the debug configuration.

comments powered by Disqus