CrossBrowdy API documentation [printable]

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:
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:
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:
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:
Returns:

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

Type
undefined | false