# Namespace: AmbientLight

## CB_Device. AmbientLight

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

Source:
  - CrossBase/device/CB_Device.js, line 1063
To Do:
  - Normalize more differences between web clients.

### Methods

#### <static> isSupported() → {boolean}

  Tells whether the Ambient Light Sensor API or the Ambient Light Sensor Events ("ondevicelight") or "onlightlevel" event are supported or not.

  Source:
    - CrossBase/device/CB_Device.js, line 1070

  ##### Returns:

  Type
    boolean

#### <static> normalizeEvent(e, eventName [, sensor]) → {Event}

  Normalizes the data gotten from the the Ambient Light Sensor API or the Ambient Light Sensor Events ("ondevicelight") or "onlightlevel" event to try to match the Ambient Light Sensor API and follow always the same rules as much as possible.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `e` | Event |  | The event object that we want to normalize.
  `eventName` | 'change' | 'reading' | 'devicelight' | 'lightlevel' |  | The name of the event that we want to normalize. Case sensitive.
  `sensor` | AmbientLightSensor | <optional> | AmbientLightSensor object used by the Ambient Light Sensor API.

  Source:
    - CrossBase/device/CB_Device.js, line 1144
  To Do:
    - Normalize more differences between web clients.

  ##### Returns:

  Returns the given event object again but normalized (if possible).

  Type
    Event

#### <static> onChange(eventFunction [, keepOldFunction] [, useCapture] [, callbackError]) → {undefined|false}

  Sets the event to get the ambient light or removes it. Uses the Ambient Light Sensor API or the Ambient Light Sensor Events ("ondevicelight") or "onlightlevel" event.
  The given "eventFunction" will receive the event object as the first parameter but this event object will vary depending on the way to get the ambient light which is supported by the client (if any):
  First choice, if available, uses the Ambient Light Sensor API and "event.value" will contain the units in lux.
  Second choice, if available, uses the Ambient Light Sensor Events ("ondevicelight") and "event.value" will contain the units in lux.
  Third choice, if available, uses the "onlightlevel" event and "event.value" will be "" (an empty string), "dim", "normal" or "bright" instead of a number.

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `eventFunction` | function | null |  |  | The function that will be called when the event is fired. The event object received will already be normalized by the `CB_Device.AmbientLight.normalizeEvent` function automatically. Despite of this, due to the big differences between different clients, the event object received as the first parameter will vary depending on the way to get the ambient light which is supported by the client (if any). 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.
  `callbackError` | function | <optional> |  | Callback that will be called if there is any error getting the ambient light. Only used by the Ambient Light Sensor API (if available).

  Source:
    - CrossBase/device/CB_Device.js, line 1093

  ##### Returns:

  Returns false in the case that no way to get the ambient light is available or undefined otherwise.

  Type
    undefined | false

#### Search results