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

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

  ##### Returns:

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

  Type
    undefined | false

#### Search results