tree: a2e3e93c65f21207f32842239596b3ef11b00a5b [path history] [tgz]
  1. doc/
  2. src/
  3. tests/
  4. www/
  5. .gitignore
  6. .jshintrc
  7. .travis.yml
  8. CONTRIBUTING.md
  9. LICENSE
  10. NOTICE
  11. package.json
  12. plugin.xml
  13. README.md
  14. RELEASENOTES.md
README.md

Build Status

cordova-plugin-battery-status

This plugin provides an implementation of an old version of the Battery Status Events API.

It adds the following three window events:

  • batterystatus
  • batterycritical
  • batterylow

Installation

cordova plugin add cordova-plugin-battery-status

batterystatus

This event fires when the percentage of battery charge changes by at least 1 percent, or if the device is plugged in or unplugged.

The battery status handler is passed an object that contains two properties:

  • level: The percentage of battery charge (0-100). (Number)

  • isPlugged: A boolean that indicates whether the device is plugged in. (Boolean)

Applications typically should use window.addEventListener to attach an event listener after the deviceready event fires.

Supported Platforms

  • Amazon Fire OS
  • iOS
  • Android
  • BlackBerry 10
  • Windows Phone 7 and 8
  • Windows (Windows Phone 8.1 only)
  • Tizen
  • Firefox OS
  • Browser

Android and Amazon Fire OS Quirks

  • Warning: the Android + Fire OS implementations are greedy and prolonged use will drain the user's battery.

Windows Phone 7 and 8 Quirks

Windows Phone 7 does not provide native APIs to determine battery level, so the level property is unavailable. The isPlugged parameter is supported.

Windows Quirks

Windows Phone 8.1 does not support isPlugged parameter. The level parameter is supported.

Browser Quirks

Supported browsers are Chrome, Firefox and Opera.

Example

window.addEventListener("batterystatus", onBatteryStatus, false);

function onBatteryStatus(info) {
    // Handle the online event
    console.log("Level: " + info.level + " isPlugged: " + info.isPlugged);
}

batterycritical

The event fires when the percentage of battery charge has reached the critical battery threshold. The value is device-specific.

The batterycritical handler is passed an object that contains two properties:

  • level: The percentage of battery charge (0-100). (Number)

  • isPlugged: A boolean that indicates whether the device is plugged in. (Boolean)

Applications typically should use window.addEventListener to attach an event listener once the deviceready event fires.

Supported Platforms

  • Amazon Fire OS
  • iOS
  • Android
  • BlackBerry 10
  • Tizen
  • Firefox OS
  • Windows (Windows Phone 8.1 only)
  • Browser

Windows Quirks

Windows Phone 8.1 will fire batterycritical event regardless of plugged state as it is not supported.

Example

window.addEventListener("batterycritical", onBatteryCritical, false);

function onBatteryCritical(info) {
    // Handle the battery critical event
    alert("Battery Level Critical " + info.level + "%\nRecharge Soon!");
}

Browser Quirks

Supported browsers are Chrome, Firefox and Opera.

batterylow

The event fires when the percentage of battery charge has reached the low battery threshold, device-specific value.

The batterylow handler is passed an object that contains two properties:

  • level: The percentage of battery charge (0-100). (Number)

  • isPlugged: A boolean that indicates whether the device is plugged in. (Boolean)

Applications typically should use window.addEventListener to attach an event listener once the deviceready event fires.

Supported Platforms

  • Amazon Fire OS
  • iOS
  • Android
  • BlackBerry 10
  • Tizen
  • Firefox OS
  • Windows (Windows Phone 8.1 only)
  • Browser

Windows Quirks

Windows Phone 8.1 will fire batterylow event regardless of plugged state as it is not supported.

Example

window.addEventListener("batterylow", onBatteryLow, false);

function onBatteryLow(info) {
    // Handle the battery low event
    alert("Battery Level Low " + info.level + "%");
}

Browser Quirks

Supported browsers are Chrome, Firefox and Opera.