recursal/MDN huggingface dataset:
SerialPort: close() method
==========================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`SerialPort.close()`** method of the `SerialPort` interface returns a `Promise` that resolves when the port closes.

Syntax
------


```js
close()
```

### Parameters

None.

### Return value

A `Promise`.

Specifications
--------------

| Specification |
| --- |
| Web Serial API # dom-serialport-close |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
SerialPort: connect event
=========================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`connect`** event of the `SerialPort` interface is fired when a port has connected to the device. This event is only fired for ports associated with removable devices such as those connected via USB.

This event bubbles to the instance of `Serial` that returned this interface.

Syntax
------

Use the event name in methods like `addEventListener()`, or set an event handler property.


```js
addEventListener("connect", (event) => {});

onconnect = (event) => {};
```

Event type
----------

A generic `Event`.

Bubbling
--------

This event bubbles to `Serial`. The `event.target` property refers to the `SerialPort` object that bubbles up.

For more information, see Event bubbling.

Examples
--------

### Notify when a specific port connects

The `Serial.requestPort()` method returns a `Promise` that resolves with a `SerialPort` chosen by the user.


```js
// Prompt user to choose a serial port
const port = await navigator.serial.requestPort();

port.addEventListener("connect", (event) => {
  // notify that the chosen port is connected
});
```

### Listening for any newly-connected ports

The `connect` event bubbles up to the `Serial` object where you can listen for any newly-connected ports.


```js
navigator.serial.addEventListener("connect", (event) => {
  // notify that a new port is available
  // use `event.target` to refer to the newly-added port
});
```

Specifications
--------------

| Specification |
| --- |
| Web Serial API # dfn-connect |
| Web Serial API # dom-serialport-onconnect |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `disconnect` event
SerialPort: readable property
=============================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`readable`** read-only property of the `SerialPort` interface returns a `ReadableStream` for receiving data from the device connected to the port. Chunks read from this stream are instances of `Uint8Array`. This property is non-null as long as the port is open and has not encountered a fatal error.

Value
-----

A `ReadableStream`.

Examples
--------

The following example shows how to read data from a port. The outer loop handles non-fatal errors, creating a new reader until a fatal error is encountered and `readable` becomes `null`.


```js
while (port.readable) {
  const reader = port.readable.getReader();
  try {
    while (true) {
      const { value, done } = await reader.read();
      if (done) {
        // |reader| has been canceled.
        break;
      }
      // Do something with |value|…
    }
  } catch (error) {
    // Handle |error|…
  } finally {
    reader.releaseLock();
  }
}
```

Specifications
--------------

| Specification |
| --- |
| Web Serial API # dom-serialport-readable |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
SerialPort: forget() method
===========================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`SerialPort.forget()`** method of the `SerialPort` interface returns a `Promise` that resolves when the serial port is closed and is forgotten.

Syntax
------


```js
forget()
```

### Parameters

None.

### Return value

A `Promise` that resolves with `undefined` once the connection is closed, the device is forgotten, and the permission is reset.

Specifications
--------------

| Specification |
| --- |
| Web Serial API # dom-serialport-forget |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
SerialPort: setSignals() method
===============================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`setSignals()`** method of the `SerialPort` interface sets control signals on the port and returns a `Promise` that resolves when they are set.

Syntax
------


```js
setSignals()
setSignals(options)
```

### Parameters

`options` Optional

An object with any of the following values:

`dataTerminalReady`

A boolean indicating whether to invoke the operating system to either assert (if true) or de-assert (if false) the "data terminal ready" or "DTR" signal on the serial port.

`requestToSend`

A boolean indicating whether to invoke the operating system to either assert (if true) or de-assert (if false) the "request to send" or "RTS" signal on the serial port.

`break`

A boolean indicating whether to invoke the operating system to either assert (if true) or de-assert (if false) the "break" signal on the serial port.


### Return value

A `Promise`.

### Exceptions

`InvalidStateError` `DOMException`

Returned if the port is not open. Call `SerialPort.open()` to avoid this error.

`NetworkError` `DOMException`

Returned if the signals on the device could not be set.

Specifications
--------------

| Specification |
| --- |
| Web Serial API # dom-serialport-setsignals |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
SerialPort: disconnect event
============================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`disconnect`** event of the `SerialPort` interface is fired when the port has disconnected from the device. This event is only fired for ports associated with removable devices such as those connected via USB.

This event bubbles to the instance of `Serial` that returned this interface.

Syntax
------

Use the event name in methods like `addEventListener()`, or set an event handler property.


```js
addEventListener("disconnect", (event) => {});

ondisconnect = (event) => {};
```

Event type
----------

A generic `Event`.

Bubbling
--------

This event bubbles to `Serial`. The `event.target` property refers to the `SerialPort` object that bubbles up.

For more information, see Event bubbling.

Examples
--------

### Notify when a specific port disconnects

Here the event listener is installed on a specific `SerialPort` object.


```js
port.addEventListener("disconnect", (event) => {
  // notify that the port has become unavailable
});
```

### Listening for any ports that become unavailable

The `disconnect` event bubbles up to the `Serial` object where you can listen for any ports that become unavailable.


```js
navigator.serial.addEventListener("disconnect", (event) => {
  // notify that a port has become unavailable
  // use `event.target` to refer to the unavailable port
});
```

Specifications
--------------

| Specification |
| --- |
| Web Serial API # dfn-disconnect |
| Web Serial API # dom-serialport-ondisconnect |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `connect` event
SerialPort: getSignals() method
===============================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`SerialPort.getSignals()`** method of the `SerialPort` interface returns a `Promise` that resolves with an object containing the current state of the port's control signals.

Syntax
------


```js
getSignals()
```

### Parameters

None.

### Return value

Returns a `Promise` that resolves with an object containing the following members:

`clearToSend`

A boolean indicating to the other end of a serial connection that is clear to send data.

`dataCarrierDetect`

A boolean that toggles the control signal needed to communicate over a serial connection.

`dataSetReady`

A boolean indicating whether the device is ready to send and receive data.

`ringIndicator`

A boolean indicating whether a ring signal should be sent down the serial connection.

### Exceptions

`InvalidStateError` `DOMException`

Returned if the port is not open. Call `SerialPort.open()` to avoid this error.

`NetworkError` `DOMException`

Returned if the signals on the device could not be read.

Specifications
--------------

| Specification |
| --- |
| Web Serial API # dom-serialport-getsignals |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
ContactsManager: getProperties() method
=======================================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

 The **`getProperties()`** method of the
 `ContactsManager` interface returns a `Promise` which resolves
 with an `Array` of `strings` indicating which contact
 properties are available.

Syntax
------


```js
getProperties()
```

### Parameters

This method receives no parameters.

### Return value

Returns a `Promise` that resolves with an `Array` of `strings` naming the contact properties that can be returned by the current system.

Properties can include the following:

* `'name'`: The contact's name.
* `'tel'`: The telephone number(s) of the contact.
* `'email'`: The email address of the contact.
* `'address'`: The contact's postal address.
* `'icon'`: The avatar of the contact.
### Exceptions

No exceptions are thrown.

Examples
--------

### Verify Property Support

 The following asynchronous function uses the `getProperties()` method to check
 whether the current system supports the `icon` property.


```js
async function checkProperties() {
  const supportedProperties = await navigator.contacts.getProperties();
  if (!supportedProperties.includes("icon")) {
    console.log("Your system does not support getting icons.");
  }
}
```

### Select Using Only Supported Properties

The following example is similar to one for the `select()` method. Instead of hard-coding the properties passed to `select()`, it uses `getProperties()` to ensure that only supported properties are passed. Otherwise, `select()` might throw a `TypeError`. `handleResults()` is a developer defined function.


```js
const supportedProperties = await navigator.contacts.getProperties();

async function getContacts() {
  try {
    const contacts = await navigator.contacts.select(supportedProperties);
    handleResults(contacts);
  } catch (ex) {
    // Handle any errors here.
  }
}
```

Specifications
--------------

| Specification |
| --- |
| Contact Picker API # contacts-manager-getproperties |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
MutationObserver: takeRecords() method
======================================

 The `MutationObserver` method
 **`takeRecords()`** returns a list of all matching DOM changes
 that have been detected but not yet processed by the observer's callback function,
 leaving the mutation queue empty.

 The most common use case for this is to
 immediately fetch all pending mutation records immediately prior to disconnecting the
 observer, so that any pending mutations can be processed when shutting down the
 observer.

Syntax
------


```js
takeRecords()
```

### Parameters

None.

### Return value

 An array of `MutationRecord` objects, each describing one change applied to
 the observed portion of the document's DOM tree.


**Note:** The queue of mutations which have occurred, but not been
 delivered to the observer's callback is left empty after calling
 `takeRecords()`.


Examples
--------

 In this example, we demonstrate how to handle any undelivered
 `MutationRecord`s by calling `takeRecords()` just before
 disconnecting the observer.


```js
const targetNode = document.querySelector("#someElement");
const observerOptions = {
  childList: true,
  attributes: true,
};

const observer = new MutationObserver(callback);
observer.observe(targetNode, observerOptions);

/\* later, when it's time to stop observing… \*/

/\* handle any still-pending mutations \*/

let mutations = observer.takeRecords();

observer.disconnect();

if (mutations.length > 0) {
  callback(mutations);
}
```


 The code in lines 12–17 fetches any unprocessed mutation records, then invokes the
 callback with the records so that they can be processed. This is done immediately prior
 to calling `disconnect()` to stop observing
 the DOM.

Specifications
--------------

| Specification |
| --- |
| DOM Standard # ref-for-dom-mutationobserver-takerecords① |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
MutationObserver: disconnect() method
=====================================

 The `MutationObserver` method
 **`disconnect()`** tells the observer to stop watching for
 mutations.

 The observer can be reused by calling its
 `observe()` method again.

Syntax
------


```js
disconnect()
```

### Parameters

None.

### Return value

`undefined`.

**Note:** All notifications of mutations that have already been
 *detected*, but *not yet reported* to the observer, are discarded.
 To hold on to and handle the detected but unreported mutations, use
 the `takeRecords()` method.


Usage notes
-----------

 If the element being observed is removed from the DOM, and then subsequently released
 by the browser's garbage collection mechanism, the `MutationObserver` will stop observing
 the removed element. However, the `MutationObserver` itself can continue to exist to observe
 other existing elements.

Examples
--------

 This example creates an observer, then disconnects from it, leaving it available for
 possible reuse.


```js
const targetNode = document.querySelector("#someElement");
const observerOptions = {
  childList: true,
  attributes: true,
};

const observer = new MutationObserver(callback);
observer.observe(targetNode, observerOptions);

/\* some time later… \*/

observer.disconnect();
```

Specifications
--------------

| Specification |
| --- |
| DOM Standard # ref-for-dom-mutationobserver-disconnect① |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
XRCPUDepthInformation: data property
====================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The *read-only* **`data`** property of the `XRCPUDepthInformation` interface is an `ArrayBuffer` containing depth-buffer information in raw format.

The data is stored in row-major format, without padding, with each entry corresponding to distance from the view's near plane to the users' environment, in unspecified units. The size of each data entry and the type is determined by `depthDataFormat`. The values can be converted from unspecified units to meters by multiplying them by `rawValueToMeters`. The `normDepthBufferFromNormView` property can be used to transform from normalized view coordinates (an origin in the top left corner of the view, with X axis growing to the right, and Y axis growing downward) into the depth buffer's coordinate system.

Value
-----

An `ArrayBuffer`.

Examples
--------

Use `XRFrame.getDepthInformation()` to obtain depth information. The returned `XRCPUDepthInformation` object will contain the `data` buffer.

For CPU depth information and a buffer that has "luminance-alpha" format:


```js
const uint16 = new Uint16Array(depthInfo.data);
const index = column + row \* depthInfo.width;
const depthInMeters = uint16[index] \* depthInfo.rawValueToMeters;
```


(Use `Float32Array` for a "float32" data format.)

Note that the depth in meters is in depth-buffer coordinates. Additional steps are needed to convert them to normalized view coordinates, or the `XRCPUDepthInformation.getDepthInMeters()` method can be used.

Specifications
--------------

| Specification |
| --- |
| WebXR Depth Sensing Module # dom-xrcpudepthinformation-data |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
XRCPUDepthInformation: getDepthInMeters() method
================================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`getDepthInMeters()`** method of the `XRCPUDepthInformation` interface returns the depth in meters at (x, y) in normalized view coordinates (origin in the top left corner).

Syntax
------


```js
getDepthInMeters(x, y)
```

### Parameters

`x`

X coordinate (origin at the left, grows to the right).

`y`

Y coordinate (origin at the top, grows downward).

### Return value

None (`undefined`).

### Exceptions

* A `RangeError` is thrown if `x` or `y` are greater than 1.0 or less than 0.0.
Examples
--------


```js
const distance = depthInfo.getDepthInMeters(x, y);
```

Specifications
--------------

| Specification |
| --- |
| WebXR Depth Sensing Module # dom-xrcpudepthinformation-getdepthinmeters |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
GamepadButton: touched property
===============================

 The **`touched`** property of the
 `GamepadButton` interface returns a `boolean` indicating whether
 a button capable of detecting touch is currently touched (`true`) or not touched (`false`).

If the button is not capable of detecting touch but can return an analog value, the property will be `true` if the value is greater than `0`, and `false` otherwise. If the button is not capable of detecting touch and can only report a digital value, then it should mirror the `GamepadButton.pressed` property.

Value
-----

A `Boolean`. True if touched.

Examples
--------


```js
let gp = navigator.getGamepads()[0]; // Get the first gamepad object

if (gp.buttons[0].touched) {
  // respond to button being touched
}
```

Specifications
--------------

| Specification |
| --- |
| Gamepad # dom-gamepadbutton-touched |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Using the Gamepad API
GamepadButton: value property
=============================

 The **`GamepadButton.value`** property of the
 `GamepadButton` interface returns a double value used to represent the
 current state of analog buttons on many modern gamepads, such as the triggers.

 The values are normalized to the range `0.0` — `1.0`, with
 `0.0` representing a button that is not pressed, and 1.0 representing a
 button that is fully pressed.

Examples
--------


```js
let gp = navigator.getGamepads()[0];

if (gp.buttons[0].value > 0) {
  // respond to analog button being pressed in
}
```

Value
-----

A double.

Specifications
--------------

| Specification |
| --- |
| Gamepad # dom-gamepadbutton-value |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

Using the Gamepad API
GamepadButton: pressed property
===============================

 The **`GamepadButton.pressed`** property of the
 `GamepadButton` interface returns a `boolean` indicating whether
 the button is currently pressed (`true`) or unpressed (`false`).

Examples
--------


```js
let gp = navigator.getGamepads()[0]; // Get the first gamepad object

if (gp.buttons[0].pressed) {
  // respond to button being pressed
}
```

Value
-----

A boolean value.

Specifications
--------------

| Specification |
| --- |
| Gamepad # dom-gamepadbutton-pressed |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Using the Gamepad API