CB-5658 Add doc/index.md for Battery Status.
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/e736db3c Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status/tree/e736db3c Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status/diff/e736db3c Branch: refs/heads/master Commit: e736db3c4d5bb936bc38c4ae8df1d24d4a84116c Parents: 390655d Author: Andrew Grieve <[email protected]> Authored: Wed Dec 18 10:53:25 2013 -0500 Committer: Andrew Grieve <[email protected]> Committed: Wed Dec 18 10:58:04 2013 -0500 ---------------------------------------------------------------------- README.md | 3 +- doc/index.md | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 137 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status/blob/e736db3c/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index ece3efc..8e188db 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ cordova-plugin-battery-status ============================= -To install this plugin, follow the [Command-line Interface Guide](http://cordova.apache.org/docs/en/edge/guide_cli_index.md.html#The%20Command-line%20Interface). -If you are not using the Cordova Command-line Interface, follow [Using Plugman to Manage Plugins](http://cordova.apache.org/docs/en/edge/plugin_ref_plugman.md.html). +Plugin documentation: [doc/index.md](doc/index.md) http://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status/blob/e736db3c/doc/index.md ---------------------------------------------------------------------- diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000..90bdd0e --- /dev/null +++ b/doc/index.md @@ -0,0 +1,136 @@ +--- + license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--- + +# org.apache.cordova.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: + +* batterystatus +* batterycritical +* batterylow + +## Installation + + cordova plugin add org.apache.cordova.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 once the `deviceready` event fires. e.g.: + +### Supported Platforms + +- Amazon Fire OS +- iOS +- Android +- BlackBerry 10 +- Windows Phone 7 and 8 +- Tizen + +### 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. + +### 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 + +### Example + + window.addEventListener("batterycritical", onBatteryCritical, false); + + function onBatteryCritical(info) { + // Handle the battery critical event + alert("Battery Level Critical " + info.level + "%\nRecharge Soon!"); + } + +## 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 + +## Example + + window.addEventListener("batterylow", onBatteryLow, false); + + function onBatteryLow(info) { + // Handle the battery low event + alert("Battery Level Low " + info.level + "%"); + } +
