mozilla

Revision 536585 of Proximity Events

  • Revision slug: Web/API/Proximity_Events
  • Revision title: Proximity
  • Revision id: 536585
  • Created:
  • Creator: teoli
  • Is current revision? No
  • Comment Editorial reviewWeb/API/Proximity Web/API/Proximity_Events

Revision Content

{{ SeeCompatTable }}

Summary

The proximity events are a handy way to know when a user is close to a device. These events make it possible to react to such a change, for example by shutting down the screen of a smartphone when the user is having a phone call with the device close to their ear.

Note: Obviously, the API requires the device to have a proximity sensor, which are mostly available only on mobile devices. Devices without such a sensor may support those events but will never fire them.

Proximity Events

When the device proximity sensor detects a change between the device and an object, it notifies the browser of that change. When the browser gets such a notification, it fires a {{domxref("DeviceProximityEvent")}} for any change, and a {{domxref("UserProximityEvent")}} event in the case of a more rough change.

This event can be captured at the window object level by using the {{domxref("EventTarget.addEventListener","addEventListener")}} method (using the {{event("deviceproximity")}} or {{event("userproximity")}} event name) or by attaching an event handler to the {{domxref("window.ondeviceproximity")}} or {{domxref("window.onuserproximity")}} properties.

Once captured, the event object gives access to different kinds of information:

  • The {{domxref("DeviceProximityEvent")}} event provides an exact match for the distance between the device and the object through its {{domxref("DeviceProximityEvent.value","value")}} property. It also provides the closest and farthest distance the device is able to detect something through its {{domxref("DeviceProximityEvent.min","min")}} and {{domxref("DeviceProximityEvent.max","max")}} properties.
  • The {{domxref("UserProximityEvent")}} event provides a rough approximation of the distance, expressed through a boolean. The {{domxref("UserProximityEvent.near")}} property is true if the object is close or false if the object is far.

Example

window.addEventListener('userproximity', function(event) {
  if (event.near) {
    // let's power off the screen
    navigator.mozPower.screenEnabled = false;
  } else {
    // Otherwise, let's power on the screen
    navigator.mozPower.screenEnabled = true;
  }
});

Specifications

Specification Status Comment
{{ SpecName('Proximity Events', '', 'Proximity Events') }} {{ Spec2('Proximity Events') }} Initial specification

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
{{domxref("DeviceProximityEvent")}} {{CompatNo()}} {{CompatVersionUnknown()}} {{CompatNo()}} {{CompatNo()}} {{CompatNo()}}
{{domxref("UserProximityEvent")}} {{CompatNo()}} {{CompatVersionUnknown()}} {{CompatNo()}} {{CompatNo()}} {{CompatNo()}}
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
{{domxref("DeviceProximityEvent")}} {{CompatNo()}} {{CompatNo()}} {{ CompatGeckoMobile("15.0") }} {{CompatNo()}} {{CompatNo()}} {{CompatNo()}}
{{domxref("UserProximityEvent")}} {{CompatNo()}} {{CompatNo()}} {{CompatVersionUnknown()}} {{CompatNo()}} {{CompatNo()}} {{CompatNo()}}

See also

  • {{domxref("DeviceProximityEvent")}}
  • {{domxref("UserProximityEvent")}}
  • {{event("deviceproximity")}}
  • {{event("userproximity")}}

Revision Source

<p>{{ SeeCompatTable }}</p>
<h2 id="Summary">Summary</h2>
<p>The proximity events are a handy way to know when a user is close to a device. These events make it possible to react to such a change, for example by shutting down the screen of a smartphone when the user is having a phone call with the device close to their ear.</p>
<div class="note">
  <p><strong>Note:</strong> Obviously, the API requires the device to have a proximity sensor, which are mostly available only on mobile devices. Devices without such a sensor may support those events but will never fire them.</p>
</div>
<h2 id="Proximity_Events">Proximity Events</h2>
<p>When the device proximity sensor detects a change between the device and an object, it notifies the browser of that change. When the browser gets such a notification, it fires a {{domxref("DeviceProximityEvent")}} for any change, and a {{domxref("UserProximityEvent")}} event in the case of a more rough change.</p>
<p>This event can be captured at the <code>window</code> object level by using the {{domxref("EventTarget.addEventListener","addEventListener")}} method (using the {{event("deviceproximity")}} or {{event("userproximity")}} event name) or by attaching an event handler to the {{domxref("window.ondeviceproximity")}} or {{domxref("window.onuserproximity")}} properties.</p>
<p>Once captured, the event object gives access to different kinds of information:</p>
<ul>
  <li>The {{domxref("DeviceProximityEvent")}} event provides an exact match for the distance between the device and the object through its {{domxref("DeviceProximityEvent.value","value")}} property. It also provides the closest and farthest distance the device is able to detect something through its {{domxref("DeviceProximityEvent.min","min")}} and {{domxref("DeviceProximityEvent.max","max")}} properties.</li>
  <li>The {{domxref("UserProximityEvent")}} event provides a rough approximation of the distance, expressed through a boolean. The {{domxref("UserProximityEvent.near")}} property is <code>true</code> if the object is close or <code>false</code> if the object is far.</li>
</ul>
<h2 id="Example">Example</h2>
<pre class="brush: js">
window.addEventListener('userproximity', function(event) {
  if (event.near) {
    // let's power off the screen
    navigator.mozPower.screenEnabled = false;
  } else {
    // Otherwise, let's power on the screen
    navigator.mozPower.screenEnabled = true;
  }
});</pre>
<h2 id="Specifications" name="Specifications">Specifications</h2>
<table class="standard-table" height="49" width="1000">
  <thead>
    <tr>
      <th scope="col">Specification</th>
      <th scope="col">Status</th>
      <th scope="col">Comment</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>{{ SpecName('Proximity Events', '', 'Proximity Events') }}</td>
      <td>{{ Spec2('Proximity Events') }}</td>
      <td>Initial specification</td>
    </tr>
  </tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Chrome</th>
        <th>Firefox (Gecko)</th>
        <th>Internet Explorer</th>
        <th>Opera</th>
        <th>Safari</th>
      </tr>
      <tr>
        <td>{{domxref("DeviceProximityEvent")}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatVersionUnknown()}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
      </tr>
      <tr>
        <td>{{domxref("UserProximityEvent")}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatVersionUnknown()}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Chrome for Android</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>IE Mobile</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>{{domxref("DeviceProximityEvent")}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{ CompatGeckoMobile("15.0") }}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
      </tr>
      <tr>
        <td>{{domxref("UserProximityEvent")}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatVersionUnknown()}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
        <td>{{CompatNo()}}</td>
      </tr>
    </tbody>
  </table>
</div>
<h2 id="See_also">See also</h2>
<ul>
  <li>{{domxref("DeviceProximityEvent")}}</li>
  <li>{{domxref("UserProximityEvent")}}</li>
  <li>{{event("deviceproximity")}}</li>
  <li>{{event("userproximity")}}</li>
</ul>
Revert to this revision