Namespace: Proximity

CB_Device. Proximity

Static class to manage the device's proximity 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 Proximity Sensor API or the Proximity Sensor Events as "ondeviceproximity" or "onuserproximity" are supported or not.

Source:
Returns:
Type
boolean

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

Normalizes the data gotten from the the Proximity Sensor API or the Proximity Sensor Events as "ondeviceproximity" or "onuserproximity" to try to match the Proximity 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' | 'deviceproximity' | 'userproximity'

The name of the event that we want to normalize. Case sensitive.

sensor ProximitySensor <optional>

ProximitySensor object used by the Proximity 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 [, detectNear] [, keepOldFunction] [, useCapture] [, callbackError]) → {undefined|false}

Sets the event to get the proximity or removes it. Uses the Proximity Sensor API or the Proximity Sensor Events as "ondeviceproximity" or "onuserproximity".


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 proximity which is supported by the client (if any) and the "detectNear" parameter. It will use the following logic order:


If "detectNear" is not set to true, Proximity Sensor API is used as the first option (if available) and "event.value" will contain the units in centimeters (depending on the implementation, "event.near" will also be present, containing a boolean depending on whether an object is near or not).


If "detectNear" is not set to true, Proximity Sensor Events ("ondeviceproximity") is used as the second option (if available) and "event.value" will contain the units in centimeters.


If "detectNear" is set to true, "onuserproximity" event is the unique option used (if available) and "event.near" will be a boolean which tell us whether something is near or not.

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.Proximity.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 proximity which is supported by the client (if any). If a null value is used, the event will be removed.

detectNear boolean <optional>
false

Defines whether we want to detect when a physical object is nearby. If it is set to true, it will use the "onuserproximity" event.

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 proximity. Only used by the Proximity Sensor API (if available).

Source:
Returns:

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

Type
undefined | false