CrossBrowdy API documentation

Namespace: Battery

CB_Device. Battery

Static class to manage the device's battery. It will return itself if it is tried to be instantiated.

Source:
To Do:
  • Normalize more differences between web clients.

Methods

<static> cordova_onChange(eventFunction [, keepOldFunction] [, useCapture])

Sets a function to execute when the "batterystatus" event of the battery is fired or removes it. Using the Apache Cordova's Battery Status plugin.

Parameters:
Name Type Argument Default Description
eventFunction function | null

The function that will be called when the event is fired. Following the same rules as in https://github.com/apache/cordova-plugin-battery-status. If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener or not.
useCapture float <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
Source:

<static> cordova_onCritical(eventFunction [, keepOldFunction] [, useCapture])

Sets a function to execute when the "batterycritical" event of the battery is fired or removes it. Using the Apache Cordova's Battery Status plugin.

Parameters:
Name Type Argument Default Description
eventFunction function | null

The function that will be called when the event is fired. Following the same rules as in https://github.com/apache/cordova-plugin-battery-status. If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener or not.
useCapture float <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
Source:

<static> cordova_onLow(eventFunction [, keepOldFunction] [, useCapture])

Sets a function to execute when the "batterylow" event of the battery is fired or removes it. Using the Apache Cordova's Battery Status plugin.

Parameters:
Name Type Argument Default Description
eventFunction function | null

The function that will be called when the event is fired. Following the same rules as in https://github.com/apache/cordova-plugin-battery-status. If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener or not.
useCapture float <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
Source:

<static> get( [callbackOk] [, chargingOnFail] [, levelOnFail] [, chargingTimeOnFail] [, dischargingTimeOnFail]) → {Object|Promise}

Gets the battery object (BatteryManager) using the Battery Status API (or compatible one) if available or falling back to Apache Cordova's Battery Status plugin emulating the object if possible or a fake object otherwise. It could be synchronous or asynchronous depending on the client.


When the Battery Status API (or compatible one) is not available, the generated object will always contain null values for the "onchargingchange", "onchargingtimechage", "ondischargingtimechange" and "onlevelchange" properties. The "charging" and "level" properties will be tried to be calculated by using Apache Cordova's Battery Status plugin if possible.


The return will be synchronous only when getBattery function is not available. The best practice is to ignore the immediate return value and just trust the first parameter passed to the "callbackOk" function once it is called, since this one will be the final battery object (real or fake).

Parameters:
Name Type Argument Description
callbackOk function <optional>

The callback function that will be called once the final battery object (real or fake one) is gotten (passed as the first and unique parameter). Highly recommended since it is the unique way to always get the final battery object (due the fact that some clients will execute the function asynchronously).
chargingOnFail boolean <optional>

Desired value for the "charging" property of the fake battery object when neither the Battery Status API (or compatible one) nor Apache Cordova's Battery Status plugin are available. It should follow the same rules as the real property of the BatteryManager object.
levelOnFail float <optional>

Desired value for the "level" property of the fake battery object when neither the Battery Status API (or compatible one) nor Apache Cordova's Battery Status plugin are available. It should follow the same rules as the real property of the BatteryManager object.
chargingTimeOnFail integer <optional>

Desired value for the "chargingTime" property of the fake battery object when the Battery Status API (or compatible one) is not available. It should follow the same rules as the real property of the BatteryManager object.
dischargingTimeOnFail integer <optional>

Desired value for the "dischargingTime" property of the fake battery object when the Battery Status API (or compatible one) is not available. It should follow the same rules as the real property of the BatteryManager object.
Source:
Returns:

Returns the battery object (fake or real) synchronously only when the native getBattery function is not available. Otherwise it returns a Promise (the result of calling navigator.getBattery().then(callbackOk)). It is highly recommended to ignore this returned value.

Type
Object | Promise

<static> getChargingTime( [callbackOk] [, valueOnFail]) → {integer|Promise}

Returns the time (in seconds) that the battery needs to be completely charged. Using the CB_Device.Battery.get function internally. It could be synchronous or asynchronous depending on the client.


The return will be synchronous only sometimes (when it is asynchronous it will just return a Promise), following the same rules as the CB_Device.Battery.get function which is called internally. The best practice is to ignore the immediate return value and just trust the first parameter passed to the "callbackOk" function once it is called, since this one will be the final value that we want to get (real or fake).

Parameters:
Name Type Argument Description
callbackOk function <optional>

The callback function that will be called once the final value (real or fake one) is gotten (passed as the first and unique parameter). Highly recommended since it is the unique way to always get the final value (due the fact that some clients will execute the function asynchronously).
valueOnFail integer <optional>

Desired value to use when it fails getting the real one. It should follow the same rules as the real "chargingTime" property of the BatteryManager object.
Source:
Returns:

Returns the desired value only when the function is executed synchronously (following the same rules as the CB_Device.Battery.get function which is called internally). It is highly recommended to ignore this returned value.

Type
integer | Promise

<static> getDischargingTime( [callbackOk] [, valueOnFail]) → {integer|Promise}

Returns the time (in seconds) that the battery needs to be completely discharged (or when the device will shutdown, depending on the client). Using the CB_Device.Battery.get function internally. It could be synchronous or asynchronous depending on the client.


The return will be synchronous only sometimes (when it is asynchronous it will just return a Promise), following the same rules as the CB_Device.Battery.get function which is called internally. The best practice is to ignore the immediate return value and just trust the first parameter passed to the "callbackOk" function once it is called, since this one will be the final value that we want to get (real or fake).

Parameters:
Name Type Argument Description
callbackOk function <optional>

The callback function that will be called once the final value (real or fake one) is gotten (passed as the first and unique parameter). Highly recommended since it is the unique way to always get the final value (due the fact that some clients will execute the function asynchronously).
valueOnFail integer <optional>

Desired value to use when it fails getting the real one. It should follow the same rules as the real "dischargingTime" property of the BatteryManager object.
Source:
Returns:

Returns the desired value only when the function is executed synchronously (following the same rules as the CB_Device.Battery.get function which is called internally). It is highly recommended to ignore this returned value.

Type
integer | Promise

<static> getLevel( [callbackOk] [, valueOnFail]) → {float|Promise}

Returns tha current charging level of the battery. Using the CB_Device.Battery.get function internally. It could be synchronous or asynchronous depending on the client.


The return will be synchronous only sometimes (when it is asynchronous it will just return a Promise), following the same rules as the CB_Device.Battery.get function which is called internally. The best practice is to ignore the immediate return value and just trust the first parameter passed to the "callbackOk" function once it is called, since this one will be the final value that we want to get (real or fake).

Parameters:
Name Type Argument Description
callbackOk function <optional>

The callback function that will be called once the final value (real or fake one) is gotten (passed as the first and unique parameter). Highly recommended since it is the unique way to always get the final value (due the fact that some clients will execute the function asynchronously).
valueOnFail float <optional>

Desired value to use when it fails getting the real one. It should follow the same rules as the real "level" property of the BatteryManager object.
Source:
Returns:

Returns the desired value only when the function is executed synchronously (following the same rules as the CB_Device.Battery.get function which is called internally). It is highly recommended to ignore this returned value.

Type
float | Promise

<static> isCharging( [callbackOk] [, valueOnFail]) → {boolean|Promise}

Returns whether the battery is charging or not. Using the CB_Device.Battery.get function internally. It could be synchronous or asynchronous depending on the client.


The return will be synchronous only sometimes (when it is asynchronous it will just return a Promise), following the same rules as the CB_Device.Battery.get function which is called internally. The best practice is to ignore the immediate return value and just trust the first parameter passed to the "callbackOk" function once it is called, since this one will be the final value that we want to get (real or fake).

Parameters:
Name Type Argument Description
callbackOk function <optional>

The callback function that will be called once the final value (real or fake one) is gotten (passed as the first and unique parameter). Highly recommended since it is the unique way to always get the final value (due the fact that some clients will execute the function asynchronously).
valueOnFail boolean <optional>

Desired value to use when it fails getting the real one. It should follow the same rules as the real "charging" property of the BatteryManager object.
Source:
Returns:

Returns the desired value only when the function is executed synchronously (following the same rules as the CB_Device.Battery.get function which is called internally). It is highly recommended to ignore this returned value.

Type
boolean | Promise

<static> isSupported() → {boolean}

Tells whether the Battery Status API (or compatible one) is available or not.

Source:
Returns:
Type
boolean

<static> onChargingChange(eventFunction [, keepOldFunction] [, useCapture]) → {undefined|false|Promise}

Sets a function to execute when the "onchargingchange" event of the battery is fired or removes it. This should happen whenever the charging status changes (is charging now but before it was not or vice versa). Using the Battery Status API (or compatible one).

Parameters:
Name Type Argument Default Description
eventFunction function | null

The function that will be called when the event is fired. Following the same rules as in https://developer.mozilla.org/docs/Web/Events/chargingchange. If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener or not.
useCapture float <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
Source:
Returns:

Returns false when the Battery Status API (or compatible one) is not available. Returns a Promise when the native getBattery function is available. Otherwise, it returns undefined.

Type
undefined | false | Promise

<static> onChargingTimeChange(eventFunction [, keepOldFunction] [, useCapture]) → {undefined|false|Promise}

Sets a function to execute when the "onchargingtimechage" event of the battery is fired or removes it. This should happen whenever the charging time changes. Using the Battery Status API (or compatible one).

Parameters:
Name Type Argument Default Description
eventFunction function | null

The function that will be called when the event is fired. Following the same rules as in https://developer.mozilla.org/docs/Web/Events/chargingtimechange. If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener or not.
useCapture float <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
Source:
Returns:

Returns false when the Battery Status API (or compatible one) is not available. Returns a Promise when the native getBattery function is available. Otherwise, it returns undefined.

Type
undefined | false | Promise

<static> onDischargingTimeChange(eventFunction [, keepOldFunction] [, useCapture]) → {undefined|false|Promise}

Sets a function to execute when the "ondischargingtimechange" event of the battery is fired or removes it. This should happen whenever the discharging time changes. Using the Battery Status API (or compatible one).

Parameters:
Name Type Argument Default Description
eventFunction function | null

The function that will be called when the event is fired. Following the same rules as in https://developer.mozilla.org/docs/Web/Events/dischargingtimechange. If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener or not.
useCapture float <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
Source:
Returns:

Returns false when the Battery Status API (or compatible one) is not available. Returns a Promise when the native getBattery function is available. Otherwise, it returns undefined.

Type
undefined | false | Promise

<static> onLevelChange(eventFunction [, keepOldFunction] [, useCapture]) → {undefined|false|Promise}

Sets a function to execute when the "onlevelchange" event of the battery is fired or removes it. This should happen when the battery level changes. Using the Battery Status API (or compatible one).

Parameters:
Name Type Argument Default Description
eventFunction function | null

The function that will be called when the event is fired. Following the same rules as in https://developer.mozilla.org/docs/Web/Events/levelchange. If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener or not.
useCapture float <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
Source:
Returns:

Returns false when the Battery Status API (or compatible one) is not available. Returns a Promise when the native getBattery function is available. Otherwise, it returns undefined.

Type
undefined | false | Promise