# 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:
  - CrossBase/device/CB_Device.js, line 746
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:
    - CrossBase/device/CB_Device.js, line 976

#### <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:
    - CrossBase/device/CB_Device.js, line 1002

#### <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:
    - CrossBase/device/CB_Device.js, line 989

#### <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:
    - CrossBase/device/CB_Device.js, line 785

  ##### 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:
    - CrossBase/device/CB_Device.js, line 858

  ##### 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:
    - CrossBase/device/CB_Device.js, line 875

  ##### 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:
    - CrossBase/device/CB_Device.js, line 841

  ##### 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:
    - CrossBase/device/CB_Device.js, line 824

  ##### 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:
    - CrossBase/device/CB_Device.js, line 765

  ##### 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:
    - CrossBase/device/CB_Device.js, line 891

  ##### 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:
    - CrossBase/device/CB_Device.js, line 905

  ##### 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:
    - CrossBase/device/CB_Device.js, line 919

  ##### 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:
    - CrossBase/device/CB_Device.js, line 933

  ##### 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

#### Search results