diff --git a/content/en-US/docs/tutorial/devices.md b/content/en-US/docs/tutorial/devices.md new file mode 100644 index 0000000000000..02194a79cae3b --- /dev/null +++ b/content/en-US/docs/tutorial/devices.md @@ -0,0 +1,99 @@ +# Device Access + +Like Chromium based browsers, Electron provides access to device hardware +through web APIs. For the most part these APIs work like they do in a browser, +but there are some differences that need to be taken into account. The primary +difference between Electron and browsers is what happens when device access is +requested. In a browser, users are presented with a popup where they can grant +access to an individual device. In Electron APIs are provided which can be +used by a developer to either automatically pick a device or prompt users to +pick a device via a developer created interface. + +## Web Bluetooth API + +The [Web Bluetooth API](https://web.dev/bluetooth/) can be used to communicate +with bluetooth devices. In order to use this API in Electron, developers will +need to handle the [`select-bluetooth-device` event on the webContents](../api/web-contents.md#event-select-bluetooth-device) +associated with the device request. + +### Example + +This example demonstrates an Electron application that automatically selects +the first available bluetooth device when the `Test Bluetooth` button is +clicked. + +```javascript fiddle='docs/fiddles/features/web-bluetooth' + +``` + +## WebHID API + +The [WebHID API](https://web.dev/hid/) can be used to access HID devices such +as keyboards and gamepads. Electron provides several APIs for working with +the WebHID API: + +* The [`select-hid-device` event on the Session](../api/session.md#event-select-hid-device) + can be used to select a HID device when a call to + `navigator.hid.requestDevice` is made. Additionally the [`hid-device-added`](../api/session.md#event-hid-device-added) + and [`hid-device-removed`](../api/session.md#event-hid-device-removed) events + on the Session can be used to handle devices being plugged in or unplugged during the + `navigator.hid.requestDevice` process. +* [`ses.setDevicePermissionHandler(handler)`](../api/session.md#sessetdevicepermissionhandlerhandler) + can be used to provide default permissioning to devices without first calling + for permission to devices via `navigator.hid.requestDevice`. Additionally, + the default behavior of Electron is to store granted device permision through + the lifetime of the corresponding WebContents. If longer term storage is + needed, a developer can store granted device permissions (eg when handling + the `select-hid-device` event) and then read from that storage with + `setDevicePermissionHandler`. +* [`ses.setPermissionCheckHandler(handler)`](../api/session.md#sessetpermissioncheckhandlerhandler) + can be used to disable HID access for specific origins. + +### Blocklist + +By default Electron employs the same [blocklist](https://github.com/WICG/webhid/blob/main/blocklist.txt) +used by Chromium. If you wish to override this behavior, you can do so by +setting the `disable-hid-blocklist` flag: + +```javascript +app.commandLine.appendSwitch('disable-hid-blocklist') +``` + +### Example + +This example demonstrates an Electron application that automatically selects +HID devices through [`ses.setDevicePermissionHandler(handler)`](../api/session.md#sessetdevicepermissionhandlerhandler) +and through [`select-hid-device` event on the Session](../api/session.md#event-select-hid-device) +when the `Test WebHID` button is clicked. + +```javascript fiddle='docs/fiddles/features/web-hid' + +``` + +## Web Serial API + +The [Web Serial API](https://web.dev/serial/) can be used to access serial +devices that are connected via serial port, USB, or Bluetooth. In order to use +this API in Electron, developers will need to handle the +[`select-serial-port` event on the Session](../api/session.md#event-select-serial-port) +associated with the serial port request. + +There are several additional APIs for working with the Web Serial API: + +* The [`serial-port-added`](../api/session.md#event-serial-port-added) + and [`serial-port-removed`](../api/session.md#event-serial-port-removed) events + on the Session can be used to handle devices being plugged in or unplugged during the + `navigator.serial.requestPort` process. +* [`ses.setPermissionCheckHandler(handler)`](../api/session.md#sessetpermissioncheckhandlerhandler) + can be used to disable serial access for specific origins. + +### Example + +This example demonstrates an Electron application that automatically selects +the first available Arduino Uno serial device (if connected) through +[`select-serial-port` event on the Session](../api/session.md#event-select-serial-port) +when the `Test Web Serial` button is clicked. + +```javascript fiddle='docs/fiddles/features/web-serial' + +``` diff --git a/stats.json b/stats.json index e5156bcf0518b..1a5baf651b4bd 100644 --- a/stats.json +++ b/stats.json @@ -2,10 +2,10 @@ { "name": "Chinese Simplified", "code": "zh-CN", - "phrases": "14788", + "phrases": "14789", "translated": "9278", "approved": "8230", - "words": "161050", + "words": "161068", "words_translated": "93240", "words_approved": "81999", "translated_progress": 57, @@ -15,23 +15,23 @@ { "name": "French", "code": "fr", - "phrases": "14788", - "translated": "8434", + "phrases": "14789", + "translated": "8435", "approved": "8146", - "words": "161050", - "words_translated": "78698", + "words": "161068", + "words_translated": "78716", "words_approved": "76460", "translated_progress": 48, "approved_progress": 47, - "qa_issues": 93 + "qa_issues": 94 }, { "name": "German", "code": "de", - "phrases": "14788", + "phrases": "14789", "translated": "3516", "approved": "3333", - "words": "161050", + "words": "161068", "words_translated": "25832", "words_approved": "23495", "translated_progress": 16, @@ -41,23 +41,23 @@ { "name": "Japanese", "code": "ja", - "phrases": "14788", + "phrases": "14789", "translated": "14788", "approved": "14337", - "words": "161050", + "words": "161068", "words_translated": "161050", "words_approved": "155552", - "translated_progress": 100, + "translated_progress": 99, "approved_progress": 96, "qa_issues": 25 }, { "name": "Portuguese, Brazilian", "code": "pt-BR", - "phrases": "14788", + "phrases": "14789", "translated": "3635", "approved": "3582", - "words": "161050", + "words": "161068", "words_translated": "30811", "words_approved": "30102", "translated_progress": 19, @@ -67,10 +67,10 @@ { "name": "Russian", "code": "ru", - "phrases": "14788", + "phrases": "14789", "translated": "6470", "approved": "6290", - "words": "161050", + "words": "161068", "words_translated": "58886", "words_approved": "56617", "translated_progress": 36, @@ -80,10 +80,10 @@ { "name": "Spanish", "code": "es-ES", - "phrases": "14788", + "phrases": "14789", "translated": "9863", "approved": "9645", - "words": "161050", + "words": "161068", "words_translated": "98002", "words_approved": "95612", "translated_progress": 60, diff --git a/wordcount.md b/wordcount.md index 7d86c06a4572a..89079105bffc6 100644 --- a/wordcount.md +++ b/wordcount.md @@ -4,10 +4,10 @@ Stat | Value ---- | ----- -total files | 218 -total words | 257015 -unique words | 11347 -average words per file | 1178 +total files | 219 +total words | 257676 +unique words | 11362 +average words per file | 1176 ## Blog English @@ -22,7 +22,7 @@ average words per file | 771 Stat | Value ---- | ----- -total files | 1730 -total words | 1250853 -unique words | 53630 +total files | 1731 +total words | 1251514 +unique words | 53643 average words per file | 723