You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by db...@apache.org on 2016/03/04 00:28:18 UTC
cordova-plugin-battery-status git commit: CB-10720 Reorganizing and
rewording docs.
Repository: cordova-plugin-battery-status
Updated Branches:
refs/heads/master 367aefb72 -> a544d4cda
CB-10720 Reorganizing and rewording docs.
Project: http://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status/commit/a544d4cd
Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status/tree/a544d4cd
Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status/diff/a544d4cd
Branch: refs/heads/master
Commit: a544d4cda0bc6bc756361f35b600e56004e0cb03
Parents: 367aefb
Author: Dmitry Blotsky <dm...@gmail.com>
Authored: Fri Feb 26 18:32:59 2016 -0800
Committer: Dmitry Blotsky <dm...@gmail.com>
Committed: Wed Mar 2 18:48:51 2016 -0800
----------------------------------------------------------------------
README.md | 129 +++++++++++++++++++--------------------------------------
1 file changed, 42 insertions(+), 87 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status/blob/a544d4cd/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index e4ac8c0..03ab0ad 100644
--- a/README.md
+++ b/README.md
@@ -21,33 +21,36 @@
# cordova-plugin-battery-status
-
-This plugin provides an implementation of an old version of the [Battery Status Events API](http://www.w3.org/TR/2011/WD-battery-status-20110915/).
-
-It adds the following three `window` events:
+This plugin provides an implementation of an old version of the [Battery Status Events API][w3c_spec]. It adds the following three events to the `window` object:
* batterystatus
* batterycritical
* batterylow
+Applications may use `window.addEventListener` to attach an event listener for any of the above events after the `deviceready` event fires.
+
## Installation
cordova plugin add cordova-plugin-battery-status
-## batterystatus
+## Status object
-This event fires when the percentage of battery charge changes by at
-least 1 percent, or if the device is plugged in or unplugged.
+All events in this plugin return an object with the following properties:
-The battery status handler is passed an object that contains two
-properties:
+- __level__: The battery charge percentage (0-100). _(Number)_
+- __isPlugged__: A boolean that indicates whether the device is plugged in. _(Boolean)_
-- __level__: The percentage of battery charge (0-100). _(Number)_
+## batterystatus event
-- __isPlugged__: A boolean that indicates whether the device is plugged in. _(Boolean)_
+Fires when the battery charge percentage changes by at least 1 percent, or when the device is plugged in or unplugged. Returns an [object][status_object] containing battery status.
-Applications typically should use `window.addEventListener` to
-attach an event listener after the `deviceready` event fires.
+### Example
+
+ window.addEventListener("batterystatus", onBatteryStatus, false);
+
+ function onBatteryStatus(status) {
+ console.log("Level: " + status.level + " isPlugged: " + status.isPlugged);
+ }
### Supported Platforms
@@ -57,120 +60,72 @@ attach an event listener after the `deviceready` event fires.
- BlackBerry 10
- Windows Phone 7 and 8
- Windows (Windows Phone 8.1 only)
-- Tizen
- Firefox OS
-- Browser
+- Browser (Chrome, Firefox, Opera)
-### Android and Amazon Fire OS Quirks
+### Quirks: Android & Amazon Fire OS
-- Warning: the Android + Fire OS implementations are greedy and prolonged use will drain the user's battery.
+**Warning**: the Android and Fire OS implementations are greedy and prolonged use will drain the device's battery.
-### Windows Phone 7 and 8 Quirks
+### Quirks: Windows Phone 7 & Windows Phone 8
-Windows Phone 7 does not provide native APIs to determine battery
-level, so the `level` property is unavailable. The `isPlugged`
-parameter _is_ supported.
+The `level` property is _not_ supported on Windows Phone 7 because the OS does not provide native APIs to determine battery level. The `isPlugged` parameter _is_ supported.
-### Windows Quirks
+### Quirks: Windows Phone 8.1
-Windows Phone 8.1 does not support `isPlugged` parameter.
-The `level` parameter _is_ supported.
+The `isPlugged` parameter is _not_ supported on Windows Phone 8.1. The `level` parameter _is_ supported.
-### Browser Quirks
+## batterylow event
-Supported browsers are Chrome, Firefox and Opera.
+Fires when the battery charge percentage reaches the low charge threshold. This threshold value is device-specific. Returns an [object][status_object] containing battery status.
### Example
- window.addEventListener("batterystatus", onBatteryStatus, false);
+ window.addEventListener("batterylow", onBatteryLow, false);
- function onBatteryStatus(info) {
- // Handle the online event
- console.log("Level: " + info.level + " isPlugged: " + info.isPlugged);
+ function onBatteryLow(status) {
+ alert("Battery Level Low " + status.level + "%");
}
-## 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
+- Browser (Chrome, Firefox, Opera)
-### Windows Quirks
+### Quirks: Windows Phone 8.1
-Windows Phone 8.1 will fire `batterycritical` event regardless of plugged state as it is not supported.
+The `batterylow` event fires on Windows Phone 8.1 irrespective of whether the device is plugged in or not. This happens because the OS does not provide an API to detect whether the device is plugged in.
+
+## batterycritical event
+
+Fires when the battery charge percentage reaches the critical charge threshold. This threshold value is device-specific. Returns an [object][status_object] containing battery status.
### Example
window.addEventListener("batterycritical", onBatteryCritical, false);
- function onBatteryCritical(info) {
- // Handle the battery critical event
- alert("Battery Level Critical " + info.level + "%\nRecharge Soon!");
+ function onBatteryCritical(status) {
+ alert("Battery Level Critical " + status.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
+- Browser (Chrome, Firefox, Opera)
-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 + "%");
- }
+### Quirks: Windows Phone 8.1
-### Browser Quirks
+The `batterycritical` event fires on Windows Phone 8.1 irrespective of whether the device is plugged in or not. This happens because the OS does not provide an API to detect whether the device is plugged in.
-Supported browsers are Chrome, Firefox and Opera.
+[w3c_spec]: http://www.w3.org/TR/2011/WD-battery-status-20110915/
+[status_object]: #status-object
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org