From 9ee726b015321972d1a793359d25a05d8776d4e7 Mon Sep 17 00:00:00 2001 From: Erick Zhao Date: Fri, 15 Nov 2024 14:17:22 -0800 Subject: [PATCH] chore: manually update website content (#673) --- docs/latest/README.md | 1 + docs/latest/api/app.md | 34 ++- docs/latest/api/base-window.md | 17 +- docs/latest/api/browser-view.md | 6 +- docs/latest/api/browser-window.md | 6 +- docs/latest/api/client-request.md | 2 +- docs/latest/api/command-line-switches.md | 2 +- docs/latest/api/dock.md | 2 +- docs/latest/api/incoming-message.md | 2 +- docs/latest/api/navigation-history.md | 17 +- docs/latest/api/net.md | 2 +- docs/latest/api/session.md | 23 +- docs/latest/api/shell.md | 2 +- .../api/structures/base-window-options.md | 7 +- .../api/structures/browser-window-options.md | 6 +- docs/latest/api/structures/ipc-main-event.md | 2 +- .../api/structures/ipc-main-invoke-event.md | 2 +- .../latest/api/structures/navigation-entry.md | 11 + .../structures/offscreen-shared-texture.md | 31 ++ docs/latest/api/structures/web-preferences.md | 6 +- docs/latest/api/utility-process.md | 31 +- docs/latest/api/view.md | 6 + docs/latest/api/web-contents.md | 84 ++++-- docs/latest/api/web-frame-main.md | 11 + docs/latest/api/web-frame.md | 2 +- docs/latest/api/web-request.md | 24 +- docs/latest/breaking-changes.md | 66 +++++ docs/latest/development/goma.md | 13 - docs/latest/development/patches.md | 2 + docs/latest/experimental.md | 4 +- .../features/navigation-history/index.html | 32 ++ .../features/navigation-history/main.js | 58 ++++ .../features/navigation-history/preload.js | 12 + .../features/navigation-history/renderer.js | 84 ++++++ .../features/navigation-history/style.css | 58 ++++ .../custom-drag-region/index.html | 14 + .../custom-drag-region/main.js | 16 + .../custom-drag-region/styles.css | 12 + .../custom-title-bar/index.html | 14 + .../custom-title-bar/custom-title-bar/main.js | 16 + .../custom-title-bar/styles.css | 12 + .../native-window-controls/main.js | 15 + .../custom-title-bar/remove-title-bar/main.js | 13 + .../custom-title-bar/starter-code/main.js | 10 + .../frameless-windows/main.js | 14 + .../transparent-windows/index.html | 15 + .../transparent-windows/main.js | 16 + .../transparent-windows/styles.css | 16 + docs/latest/images/frameless-window.png | Bin 0 -> 421997 bytes .../transparent-window-mission-control.png | Bin 0 -> 220551 bytes docs/latest/images/transparent-window.png | Bin 0 -> 100523 bytes docs/latest/tutorial/custom-title-bar.md | 189 ++++++++++++ .../tutorial/custom-window-interactions.md | 114 +++++++ docs/latest/tutorial/custom-window-styles.md | 56 ++++ docs/latest/tutorial/electron-timelines.md | 5 +- docs/latest/tutorial/navigation-history.md | 76 +++++ docs/latest/tutorial/offscreen-rendering.md | 36 ++- docs/latest/tutorial/window-customization.md | 278 +----------------- sidebars.js | 15 +- 59 files changed, 1258 insertions(+), 362 deletions(-) create mode 100644 docs/latest/api/structures/navigation-entry.md create mode 100644 docs/latest/api/structures/offscreen-shared-texture.md delete mode 100644 docs/latest/development/goma.md create mode 100644 docs/latest/fiddles/features/navigation-history/index.html create mode 100644 docs/latest/fiddles/features/navigation-history/main.js create mode 100644 docs/latest/fiddles/features/navigation-history/preload.js create mode 100644 docs/latest/fiddles/features/navigation-history/renderer.js create mode 100644 docs/latest/fiddles/features/navigation-history/style.css create mode 100644 docs/latest/fiddles/features/window-customization/custom-title-bar/custom-drag-region/index.html create mode 100644 docs/latest/fiddles/features/window-customization/custom-title-bar/custom-drag-region/main.js create mode 100644 docs/latest/fiddles/features/window-customization/custom-title-bar/custom-drag-region/styles.css create mode 100644 docs/latest/fiddles/features/window-customization/custom-title-bar/custom-title-bar/index.html create mode 100644 docs/latest/fiddles/features/window-customization/custom-title-bar/custom-title-bar/main.js create mode 100644 docs/latest/fiddles/features/window-customization/custom-title-bar/custom-title-bar/styles.css create mode 100644 docs/latest/fiddles/features/window-customization/custom-title-bar/native-window-controls/main.js create mode 100644 docs/latest/fiddles/features/window-customization/custom-title-bar/remove-title-bar/main.js create mode 100644 docs/latest/fiddles/features/window-customization/custom-title-bar/starter-code/main.js create mode 100644 docs/latest/fiddles/features/window-customization/custom-window-styles/frameless-windows/main.js create mode 100644 docs/latest/fiddles/features/window-customization/custom-window-styles/transparent-windows/index.html create mode 100644 docs/latest/fiddles/features/window-customization/custom-window-styles/transparent-windows/main.js create mode 100644 docs/latest/fiddles/features/window-customization/custom-window-styles/transparent-windows/styles.css create mode 100644 docs/latest/images/frameless-window.png create mode 100644 docs/latest/images/transparent-window-mission-control.png create mode 100644 docs/latest/images/transparent-window.png create mode 100644 docs/latest/tutorial/custom-title-bar.md create mode 100644 docs/latest/tutorial/custom-window-interactions.md create mode 100644 docs/latest/tutorial/custom-window-styles.md create mode 100644 docs/latest/tutorial/navigation-history.md diff --git a/docs/latest/README.md b/docs/latest/README.md index 7ab8862..5403335 100644 --- a/docs/latest/README.md +++ b/docs/latest/README.md @@ -44,6 +44,7 @@ an issue: * [Offline/Online Detection](latest/tutorial/online-offline-events.md) * [Represented File for macOS BrowserWindows](latest/tutorial/represented-file.md) * [Native File Drag & Drop](latest/tutorial/native-file-drag-drop.md) + * [Navigation History](latest/tutorial/navigation-history.md) * [Offscreen Rendering](latest/tutorial/offscreen-rendering.md) * [Dark Mode](latest/tutorial/dark-mode.md) * [Web embeds in Electron](latest/tutorial/web-embeds.md) diff --git a/docs/latest/api/app.md b/docs/latest/api/app.md index a84bc11..5018197 100644 --- a/docs/latest/api/app.md +++ b/docs/latest/api/app.md @@ -423,7 +423,7 @@ Returns: * `launch-failed` - Process never successfully launched * `integrity-failure` - Windows code integrity checks failed * `exitCode` number - The exit code for the process - (e.g. status from waitpid if on posix, from GetExitCodeProcess on Windows). + (e.g. status from waitpid if on POSIX, from GetExitCodeProcess on Windows). * `serviceName` string (optional) - The non-localized name of the process. * `name` string (optional) - The name of the process. Examples for utility: `Audio Service`, `Content Decryption Module Service`, `Network Service`, `Video Capture`, etc. @@ -1497,6 +1497,38 @@ This method can only be called after app is ready. Returns `Promise` - Resolves with the proxy information for `url` that will be used when attempting to make requests using [Net](latest/api/net.md) in the [utility process](latest/glossary.md#utility-process). +### `app.setClientCertRequestPasswordHandler(handler)` _Linux_ + +* `handler` Function\\> + * `clientCertRequestParams` Object + * `hostname` string - the hostname of the site requiring a client certificate + * `tokenName` string - the token (or slot) name of the cryptographic device + * `isRetry` boolean - whether there have been previous failed attempts at prompting the password + + Returns `Promise` - Resolves with the password + +The handler is called when a password is needed to unlock a client certificate for +`hostname`. + +```js +const { app } = require('electron') + +async function passwordPromptUI (text) { + return new Promise((resolve, reject) => { + // display UI to prompt user for password + // ... + // ... + resolve('the password') + }) +} + +app.setClientCertRequestPasswordHandler(async ({ hostname, tokenName, isRetry }) => { + const text = `Please sign in to ${tokenName} to authenticate to ${hostname} with your certificate` + const password = await passwordPromptUI(text) + return password +}) +``` + ## Properties ### `app.accessibilitySupportEnabled` _macOS_ _Windows_ diff --git a/docs/latest/api/base-window.md b/docs/latest/api/base-window.md index c1e5a25..f7f6d70 100644 --- a/docs/latest/api/base-window.md +++ b/docs/latest/api/base-window.md @@ -133,7 +133,7 @@ It creates a new `BaseWindow` with native properties as set by the `options`. * `show` boolean (optional) - Whether window should be shown when created. Default is `true`. * `frame` boolean (optional) - Specify `false` to create a - [frameless window](latest/tutorial/window-customization.md#create-frameless-windows). Default is `true`. + [frameless window](latest/tutorial/custom-window-styles.md#frameless-windows). Default is `true`. * `parent` BaseWindow (optional) - Specify parent window. Default is `null`. * `modal` boolean (optional) - Whether this is a modal window. This only works when the window is a child window. Default is `false`. @@ -154,7 +154,7 @@ It creates a new `BaseWindow` with native properties as set by the `options`. is only implemented on Windows and macOS. * `darkTheme` boolean (optional) - Forces using dark theme for the window, only works on some GTK+3 desktop environments. Default is `false`. - * `transparent` boolean (optional) - Makes the window [transparent](latest/tutorial/window-customization.md#create-transparent-windows). + * `transparent` boolean (optional) - Makes the window [transparent](latest/tutorial/custom-window-styles.md#transparent-windows). Default is `false`. On Windows, does not work unless the window is frameless. * `type` string (optional) - The type of window, default is normal window. See more about this below. @@ -227,8 +227,7 @@ Possible values are: -webkit-app-region: drag. This type is commonly used for splash screens. * The `notification` type creates a window that behaves like a system notification. * On macOS, possible types are `desktop`, `textured`, `panel`. - * The `textured` type adds metal gradient appearance - (`NSWindowStyleMaskTexturedBackground`). + * The `textured` type adds metal gradient appearance. This option is **deprecated**. * The `desktop` type places the window at the desktop background window level (`kCGDesktopWindowLevel - 1`). Note that desktop window will not receive focus, keyboard or mouse events, but you can use `globalShortcut` to receive @@ -287,10 +286,18 @@ or session log off. #### Event: 'blur' +Returns: + +* `event` Event + Emitted when the window loses focus. #### Event: 'focus' +Returns: + +* `event` Event + Emitted when the window gains focus. #### Event: 'show' @@ -640,7 +647,7 @@ Sets the content view of the window. #### `win.getContentView()` -Returns [View](latest/api/view.md) - The content view of the window. +Returns [`View`](latest/api/view.md) - The content view of the window. #### `win.destroy()` diff --git a/docs/latest/api/browser-view.md b/docs/latest/api/browser-view.md index 8377fbe..67d1715 100644 --- a/docs/latest/api/browser-view.md +++ b/docs/latest/api/browser-view.md @@ -146,10 +146,14 @@ deprecated: [browserWindow](latest/api/browser-window.md) has disabled `backgroundThrottling` then frames will be drawn and swapped for the whole window and other [webContents](latest/api/web-contents.md) displayed by it. Defaults to `true`. - * `offscreen` boolean (optional) - Whether to enable offscreen rendering for the browser + * `offscreen` Object | boolean (optional) - Whether to enable offscreen rendering for the browser window. Defaults to `false`. See the [offscreen rendering tutorial](latest/tutorial/offscreen-rendering.md) for more details. + * `useSharedTexture` boolean (optional) _Experimental_ - Whether to use GPU shared texture for accelerated + paint event. Defaults to `false`. See the + [offscreen rendering tutorial](latest/tutorial/offscreen-rendering.md) for + more details. * `contextIsolation` boolean (optional) - Whether to run Electron APIs and the specified `preload` script in a separate JavaScript context. Defaults to `true`. The context that the `preload` script runs in will only have diff --git a/docs/latest/api/browser-window.md b/docs/latest/api/browser-window.md index 8075e70..da09517 100644 --- a/docs/latest/api/browser-window.md +++ b/docs/latest/api/browser-window.md @@ -240,10 +240,14 @@ It creates a new `BrowserWindow` with native properties as set by the `options`. [browserWindow](latest/api/browser-window.md) has disabled `backgroundThrottling` then frames will be drawn and swapped for the whole window and other [webContents](latest/api/web-contents.md) displayed by it. Defaults to `true`. - * `offscreen` boolean (optional) - Whether to enable offscreen rendering for the browser + * `offscreen` Object | boolean (optional) - Whether to enable offscreen rendering for the browser window. Defaults to `false`. See the [offscreen rendering tutorial](latest/tutorial/offscreen-rendering.md) for more details. + * `useSharedTexture` boolean (optional) _Experimental_ - Whether to use GPU shared texture for accelerated + paint event. Defaults to `false`. See the + [offscreen rendering tutorial](latest/tutorial/offscreen-rendering.md) for + more details. * `contextIsolation` boolean (optional) - Whether to run Electron APIs and the specified `preload` script in a separate JavaScript context. Defaults to `true`. The context that the `preload` script runs in will only have diff --git a/docs/latest/api/client-request.md b/docs/latest/api/client-request.md index 0e0fdc5..d61689a 100644 --- a/docs/latest/api/client-request.md +++ b/docs/latest/api/client-request.md @@ -60,7 +60,7 @@ following properties: [`request.followRedirect`](#requestfollowredirect) is invoked synchronously during the [`redirect`](#event-redirect) event. Defaults to `follow`. * `origin` string (optional) - The origin URL of the request. - * `referrerPolicy` string (optional) - can be `""`, `no-referrer`, + * `referrerPolicy` string (optional) - can be "", `no-referrer`, `no-referrer-when-downgrade`, `origin`, `origin-when-cross-origin`, `unsafe-url`, `same-origin`, `strict-origin`, or `strict-origin-when-cross-origin`. Defaults to diff --git a/docs/latest/api/command-line-switches.md b/docs/latest/api/command-line-switches.md index 39286c4..0076ed3 100644 --- a/docs/latest/api/command-line-switches.md +++ b/docs/latest/api/command-line-switches.md @@ -45,7 +45,7 @@ Without `*` prefix the URL has to match exactly. ### --disable-ntlm-v2 -Disables NTLM v2 for posix platforms, no effect elsewhere. +Disables NTLM v2 for POSIX platforms, no effect elsewhere. ### --disable-http-cache diff --git a/docs/latest/api/dock.md b/docs/latest/api/dock.md index b63af35..0826ec8 100644 --- a/docs/latest/api/dock.md +++ b/docs/latest/api/dock.md @@ -87,4 +87,4 @@ Returns `Menu | null` - The application's [dock menu][dock-menu]. Sets the `image` associated with this dock icon. -[dock-menu]: https://developer.apple.com/macos/human-interface-guidelines/menus/dock-menus/ +[dock-menu]: https://developer.apple.com/design/human-interface-guidelines/dock-menus diff --git a/docs/latest/api/incoming-message.md b/docs/latest/api/incoming-message.md index ad11ff2..e5ff494 100644 --- a/docs/latest/api/incoming-message.md +++ b/docs/latest/api/incoming-message.md @@ -38,7 +38,7 @@ Emitted when a request has been canceled during an ongoing HTTP transaction. Returns: -`error` Error - Typically holds an error string identifying failure root cause. +* `error` Error - Typically holds an error string identifying failure root cause. Emitted when an error was encountered while streaming response data events. For instance, if the server closes the underlying while the response is still diff --git a/docs/latest/api/navigation-history.md b/docs/latest/api/navigation-history.md index 1ec7357..2bda173 100644 --- a/docs/latest/api/navigation-history.md +++ b/docs/latest/api/navigation-history.md @@ -42,10 +42,7 @@ Returns `Integer` - The index of the current page, from which we would go back/f * `index` Integer -Returns `Object`: - -* `url` string - The URL of the navigation entry at the given index. -* `title` string - The page title of the navigation entry at the given index. +Returns [`NavigationEntry`](latest/api/structures/navigation-entry.md) - Navigation entry at the given index. If index is out of bounds (greater than history length or less than 0), null will be returned. @@ -72,3 +69,15 @@ Navigates to the specified offset from the current entry. #### `navigationHistory.length()` Returns `Integer` - History length. + +#### `navigationHistory.removeEntryAtIndex(index)` + +* `index` Integer + +Removes the navigation entry at the given index. Can't remove entry at the "current active index". + +Returns `boolean` - Whether the navigation entry was removed from the webContents history. + +#### `navigationHistory.getAllEntries()` + +Returns [`NavigationEntry[]`](latest/api/structures/navigation-entry.md) - WebContents complete history. diff --git a/docs/latest/api/net.md b/docs/latest/api/net.md index 1c0cbd6..0f7d7b6 100644 --- a/docs/latest/api/net.md +++ b/docs/latest/api/net.md @@ -137,7 +137,7 @@ won't be able to connect to remote sites. However, a return value of whether a particular connection attempt to a particular remote site will be successful. -#### `net.resolveHost(host, [options])` +### `net.resolveHost(host, [options])` * `host` string - Hostname to resolve. * `options` Object (optional) diff --git a/docs/latest/api/session.md b/docs/latest/api/session.md index 95cb261..4977bfa 100644 --- a/docs/latest/api/session.md +++ b/docs/latest/api/session.md @@ -275,7 +275,8 @@ Returns: * `event` Event * `details` Object * `deviceList` [HIDDevice[]](latest/api/structures/hid-device.md) - * `frame` [WebFrameMain](latest/api/web-frame-main.md) + * `frame` [WebFrameMain](latest/api/web-frame-main.md) | null - The frame initiating this event. + May be `null` if accessed after the frame has either navigated or been destroyed. * `callback` Function * `deviceId` string | null (optional) @@ -339,7 +340,8 @@ Returns: * `event` Event * `details` Object * `device` [HIDDevice](latest/api/structures/hid-device.md) - * `frame` [WebFrameMain](latest/api/web-frame-main.md) + * `frame` [WebFrameMain](latest/api/web-frame-main.md) | null - The frame initiating this event. + May be `null` if accessed after the frame has either navigated or been destroyed. Emitted after `navigator.hid.requestDevice` has been called and `select-hid-device` has fired if a new device becomes available before @@ -354,7 +356,8 @@ Returns: * `event` Event * `details` Object * `device` [HIDDevice](latest/api/structures/hid-device.md) - * `frame` [WebFrameMain](latest/api/web-frame-main.md) + * `frame` [WebFrameMain](latest/api/web-frame-main.md) | null - The frame initiating this event. + May be `null` if accessed after the frame has either navigated or been destroyed. Emitted after `navigator.hid.requestDevice` has been called and `select-hid-device` has fired if a device has been removed before the callback @@ -480,7 +483,8 @@ Returns: * `event` Event * `details` Object * `port` [SerialPort](latest/api/structures/serial-port.md) - * `frame` [WebFrameMain](latest/api/web-frame-main.md) + * `frame` [WebFrameMain](latest/api/web-frame-main.md) | null - The frame initiating this event. + May be `null` if accessed after the frame has either navigated or been destroyed. * `origin` string - The origin that the device has been revoked from. Emitted after `SerialPort.forget()` has been called. This event can be used @@ -502,7 +506,7 @@ app.whenReady().then(() => { }) ``` -```js +```js @ts-nocheck // Renderer Process const portConnect = async () => { @@ -524,7 +528,8 @@ Returns: * `event` Event * `details` Object * `deviceList` [USBDevice[]](latest/api/structures/usb-device.md) - * `frame` [WebFrameMain](latest/api/web-frame-main.md) + * `frame` [WebFrameMain](latest/api/web-frame-main.md) | null - The frame initiating this event. + May be `null` if accessed after the frame has either navigated or been destroyed. * `callback` Function * `deviceId` string (optional) @@ -964,7 +969,8 @@ session.fromPartition('some-partition').setPermissionCheckHandler((webContents, * `handler` Function | null * `request` Object - * `frame` [WebFrameMain](latest/api/web-frame-main.md) - Frame that is requesting access to media. + * `frame` [WebFrameMain](latest/api/web-frame-main.md) | null - Frame that is requesting access to media. + May be `null` if accessed after the frame has either navigated or been destroyed. * `securityOrigin` String - Origin of the page making the request. * `videoRequested` Boolean - true if the web content requested a video stream. * `audioRequested` Boolean - true if the web content requested an audio stream. @@ -1165,7 +1171,8 @@ app.whenReady().then(() => { pin displayed on the device. * `providePin` This prompt is requesting that a pin be provided for the device. - * `frame` [WebFrameMain](latest/api/web-frame-main.md) + * `frame` [WebFrameMain](latest/api/web-frame-main.md) | null - The frame initiating this handler. + May be `null` if accessed after the frame has either navigated or been destroyed. * `pin` string (optional) - The pin value to verify if `pairingKind` is `confirmPin`. * `callback` Function * `response` Object diff --git a/docs/latest/api/shell.md b/docs/latest/api/shell.md index 76ffb44..e97149b 100644 --- a/docs/latest/api/shell.md +++ b/docs/latest/api/shell.md @@ -43,7 +43,7 @@ Open the given file in the desktop's default manner. ### `shell.openExternal(url[, options])` -* `url` string - Max 2081 characters on windows. +* `url` string - Max 2081 characters on Windows. * `options` Object (optional) * `activate` boolean (optional) _macOS_ - `true` to bring the opened application to the foreground. The default is `true`. * `workingDirectory` string (optional) _Windows_ - The working directory. diff --git a/docs/latest/api/structures/base-window-options.md b/docs/latest/api/structures/base-window-options.md index dfc7639..4d450f0 100644 --- a/docs/latest/api/structures/base-window-options.md +++ b/docs/latest/api/structures/base-window-options.md @@ -56,7 +56,7 @@ hide_title: false * `show` boolean (optional) - Whether window should be shown when created. Default is `true`. * `frame` boolean (optional) - Specify `false` to create a - [frameless window](latest/tutorial/window-customization.md#create-frameless-windows). Default is `true`. + [frameless window](latest/tutorial/custom-window-styles.md#frameless-windows). Default is `true`. * `parent` BaseWindow (optional) - Specify parent window. Default is `null`. * `modal` boolean (optional) - Whether this is a modal window. This only works when the window is a child window. Default is `false`. @@ -77,7 +77,7 @@ hide_title: false is only implemented on Windows and macOS. * `darkTheme` boolean (optional) - Forces using dark theme for the window, only works on some GTK+3 desktop environments. Default is `false`. -* `transparent` boolean (optional) - Makes the window [transparent](latest/tutorial/window-customization.md#create-transparent-windows). +* `transparent` boolean (optional) - Makes the window [transparent](latest/tutorial/custom-window-styles.md#transparent-windows). Default is `false`. On Windows, does not work unless the window is frameless. * `type` string (optional) - The type of window, default is normal window. See more about this below. @@ -150,8 +150,7 @@ Possible values are: -webkit-app-region: drag. This type is commonly used for splash screens. * The `notification` type creates a window that behaves like a system notification. * On macOS, possible types are `desktop`, `textured`, `panel`. - * The `textured` type adds metal gradient appearance - (`NSWindowStyleMaskTexturedBackground`). + * The `textured` type adds metal gradient appearance. This option is **deprecated**. * The `desktop` type places the window at the desktop background window level (`kCGDesktopWindowLevel - 1`). Note that desktop window will not receive focus, keyboard or mouse events, but you can use `globalShortcut` to receive diff --git a/docs/latest/api/structures/browser-window-options.md b/docs/latest/api/structures/browser-window-options.md index 3beafbe..f1a5df1 100644 --- a/docs/latest/api/structures/browser-window-options.md +++ b/docs/latest/api/structures/browser-window-options.md @@ -87,10 +87,14 @@ hide_title: false [browserWindow](latest/api/browser-window.md) has disabled `backgroundThrottling` then frames will be drawn and swapped for the whole window and other [webContents](latest/api/web-contents.md) displayed by it. Defaults to `true`. - * `offscreen` boolean (optional) - Whether to enable offscreen rendering for the browser + * `offscreen` Object | boolean (optional) - Whether to enable offscreen rendering for the browser window. Defaults to `false`. See the [offscreen rendering tutorial](latest/tutorial/offscreen-rendering.md) for more details. + * `useSharedTexture` boolean (optional) _Experimental_ - Whether to use GPU shared texture for accelerated + paint event. Defaults to `false`. See the + [offscreen rendering tutorial](latest/tutorial/offscreen-rendering.md) for + more details. * `contextIsolation` boolean (optional) - Whether to run Electron APIs and the specified `preload` script in a separate JavaScript context. Defaults to `true`. The context that the `preload` script runs in will only have diff --git a/docs/latest/api/structures/ipc-main-event.md b/docs/latest/api/structures/ipc-main-event.md index 1cacb50..650cd64 100644 --- a/docs/latest/api/structures/ipc-main-event.md +++ b/docs/latest/api/structures/ipc-main-event.md @@ -11,7 +11,7 @@ hide_title: false * `frameId` Integer - The ID of the renderer frame that sent this message * `returnValue` any - Set this to the value to be returned in a synchronous message * `sender` [WebContents](latest/api/web-contents.md) - Returns the `webContents` that sent the message -* `senderFrame` [WebFrameMain](latest/api/web-frame-main.md) _Readonly_ - The frame that sent this message +* `senderFrame` [WebFrameMain](latest/api/web-frame-main.md) | null _Readonly_ - The frame that sent this message. May be `null` if accessed after the frame has either navigated or been destroyed. * `ports` [MessagePortMain](latest/api/message-port-main.md)[] - A list of MessagePorts that were transferred with this message * `reply` Function - A function that will send an IPC message to the renderer frame that sent the original message that you are currently handling. You should use this method to "reply" to the sent message in order to guarantee the reply will go to the correct process and frame. * `channel` string diff --git a/docs/latest/api/structures/ipc-main-invoke-event.md b/docs/latest/api/structures/ipc-main-invoke-event.md index 75b6412..f22b6ab 100644 --- a/docs/latest/api/structures/ipc-main-invoke-event.md +++ b/docs/latest/api/structures/ipc-main-invoke-event.md @@ -10,4 +10,4 @@ hide_title: false * `processId` Integer - The internal ID of the renderer process that sent this message * `frameId` Integer - The ID of the renderer frame that sent this message * `sender` [WebContents](latest/api/web-contents.md) - Returns the `webContents` that sent the message -* `senderFrame` [WebFrameMain](latest/api/web-frame-main.md) _Readonly_ - The frame that sent this message +* `senderFrame` [WebFrameMain](latest/api/web-frame-main.md) | null _Readonly_ - The frame that sent this message. May be `null` if accessed after the frame has either navigated or been destroyed. diff --git a/docs/latest/api/structures/navigation-entry.md b/docs/latest/api/structures/navigation-entry.md new file mode 100644 index 0000000..970bda7 --- /dev/null +++ b/docs/latest/api/structures/navigation-entry.md @@ -0,0 +1,11 @@ +--- +title: "NavigationEntry Object" +description: "" +slug: navigation-entry +hide_title: false +--- + +# NavigationEntry Object + +* `url` string +* `title` string diff --git a/docs/latest/api/structures/offscreen-shared-texture.md b/docs/latest/api/structures/offscreen-shared-texture.md new file mode 100644 index 0000000..9671644 --- /dev/null +++ b/docs/latest/api/structures/offscreen-shared-texture.md @@ -0,0 +1,31 @@ +--- +title: "OffscreenSharedTexture Object" +description: "" +slug: offscreen-shared-texture +hide_title: false +--- + +# OffscreenSharedTexture Object + +* `textureInfo` Object - The shared texture info. + * `widgetType` string - The widget type of the texture. Can be `popup` or `frame`. + * `pixelFormat` string - The pixel format of the texture. Can be `rgba` or `bgra`. + * `codedSize` [Size](latest/api/structures/size.md) - The full dimensions of the video frame. + * `visibleRect` [Rectangle](latest/api/structures/rectangle.md) - A subsection of [0, 0, codedSize.width(), codedSize.height()]. In OSR case, it is expected to have the full section area. + * `contentRect` [Rectangle](latest/api/structures/rectangle.md) - The region of the video frame that capturer would like to populate. In OSR case, it is the same with `dirtyRect` that needs to be painted. + * `timestamp` number - The time in microseconds since the capture start. + * `metadata` Object - Extra metadata. See comments in src\media\base\video_frame_metadata.h for accurate details. + * `captureUpdateRect` [Rectangle](latest/api/structures/rectangle.md) (optional) - Updated area of frame, can be considered as the `dirty` area. + * `regionCaptureRect` [Rectangle](latest/api/structures/rectangle.md) (optional) - May reflect the frame's contents origin if region capture is used internally. + * `sourceSize` [Rectangle](latest/api/structures/rectangle.md) (optional) - Full size of the source frame. + * `frameCount` number (optional) - The increasing count of captured frame. May contain gaps if frames are dropped between two consecutively received frames. + * `sharedTextureHandle` Buffer _Windows_ _macOS_ - The handle to the shared texture. + * `planes` Object[] _Linux_ - Each plane's info of the shared texture. + * `stride` number - The strides and offsets in bytes to be used when accessing the buffers via a memory mapping. One per plane per entry. + * `offset` number - The strides and offsets in bytes to be used when accessing the buffers via a memory mapping. One per plane per entry. + * `size` number - Size in bytes of the plane. This is necessary to map the buffers. + * `fd` number - File descriptor for the underlying memory object (usually dmabuf). + * `modifier` string _Linux_ - The modifier is retrieved from GBM library and passed to EGL driver. +* `release` Function - Release the resources. The `texture` cannot be directly passed to another process, users need to maintain texture lifecycles in + main process, but it is safe to pass the `textureInfo` to another process. Only a limited number of textures can exist at the same time, so it's important + that you call `texture.release()` as soon as you're done with the texture. diff --git a/docs/latest/api/structures/web-preferences.md b/docs/latest/api/structures/web-preferences.md index bceaf93..5faed31 100644 --- a/docs/latest/api/structures/web-preferences.md +++ b/docs/latest/api/structures/web-preferences.md @@ -86,10 +86,14 @@ hide_title: false [browserWindow](latest/api/browser-window.md) has disabled `backgroundThrottling` then frames will be drawn and swapped for the whole window and other [webContents](latest/api/web-contents.md) displayed by it. Defaults to `true`. -* `offscreen` boolean (optional) - Whether to enable offscreen rendering for the browser +* `offscreen` Object | boolean (optional) - Whether to enable offscreen rendering for the browser window. Defaults to `false`. See the [offscreen rendering tutorial](latest/tutorial/offscreen-rendering.md) for more details. + * `useSharedTexture` boolean (optional) _Experimental_ - Whether to use GPU shared texture for accelerated + paint event. Defaults to `false`. See the + [offscreen rendering tutorial](latest/tutorial/offscreen-rendering.md) for + more details. * `contextIsolation` boolean (optional) - Whether to run Electron APIs and the specified `preload` script in a separate JavaScript context. Defaults to `true`. The context that the `preload` script runs in will only have diff --git a/docs/latest/api/utility-process.md b/docs/latest/api/utility-process.md index fd5c35d..33cc740 100644 --- a/docs/latest/api/utility-process.md +++ b/docs/latest/api/utility-process.md @@ -93,9 +93,21 @@ true if the kill is successful, and false otherwise. #### `child.pid` A `Integer | undefined` representing the process identifier (PID) of the child process. -If the child process fails to spawn due to errors, then the value is `undefined`. When +Until the child process has spawned successfully, the value is `undefined`. When the child process exits, then the value is `undefined` after the `exit` event is emitted. +```js +const child = utilityProcess.fork(path.join(__dirname, 'test.js')) + +child.on('spawn', () => { + console.log(child.pid) // Integer +}) + +child.on('exit', () => { + console.log(child.pid) // undefined +}) +``` + #### `child.stdout` A `NodeJS.ReadableStream | null` that represents the child process's stdout. @@ -123,12 +135,26 @@ When the child process exits, then the value is `null` after the `exit` event is Emitted once the child process has spawned successfully. +#### Event: 'error' _Experimental_ + +Returns: + +* `type` string - Type of error. One of the following values: + * `FatalError` +* `location` string - Source location from where the error originated. +* `report` string - [`Node.js diagnostic report`][]. + +Emitted when the child process needs to terminate due to non continuable error from V8. + +No matter if you listen to the `error` event, the `exit` event will be emitted after the +child process terminates. + #### Event: 'exit' Returns: * `code` number - Contains the exit code for -the process obtained from waitpid on posix, or GetExitCodeProcess on windows. +the process obtained from waitpid on POSIX, or GetExitCodeProcess on Windows. Emitted after the child process ends. @@ -145,3 +171,4 @@ Emitted when the child process sends a message using [`process.parentPort.postMe [stdio]: https://nodejs.org/dist/latest/docs/api/child_process.html#optionsstdio [event-emitter]: https://nodejs.org/api/events.html#events_class_eventemitter [`MessagePortMain`]: latest/api/message-port-main.md +[`Node.js diagnostic report`]: https://nodejs.org/docs/latest/api/report.html#diagnostic-report diff --git a/docs/latest/api/view.md b/docs/latest/api/view.md index 3c52f3d..09d7511 100644 --- a/docs/latest/api/view.md +++ b/docs/latest/api/view.md @@ -103,6 +103,12 @@ Examples of valid `color` values: **Note:** Hex format with alpha takes `AARRGGBB` or `ARGB`, _not_ `RRGGBBAA` or `RGB`. +#### `view.setBorderRadius(radius)` + +* `radius` Integer - Border radius size in pixels. + +**Note:** The area cutout of the view's border still captures clicks. + #### `view.setVisible(visible)` * `visible` boolean - If false, the view will be hidden from display. diff --git a/docs/latest/api/web-contents.md b/docs/latest/api/web-contents.md index 5867280..6f8b9d5 100644 --- a/docs/latest/api/web-contents.md +++ b/docs/latest/api/web-contents.md @@ -249,8 +249,9 @@ Returns: * `isSameDocument` boolean - This event does not fire for same document navigations using window.history api and reference fragment navigations. This property is always set to `false` for this event. * `isMainFrame` boolean - True if the navigation is taking place in a main frame. - * `frame` WebFrameMain - The frame to be navigated. - * `initiator` WebFrameMain (optional) - The frame which initiated the + * `frame` WebFrameMain | null - The frame to be navigated. + May be `null` if accessed after the frame has either navigated or been destroyed. + * `initiator` WebFrameMain | null (optional) - The frame which initiated the navigation, which can be a parent frame (e.g. via `window.open` with a frame's name), or null if the navigation was not initiated by a frame. This can also be null if the initiating frame was deleted before the event was @@ -282,8 +283,9 @@ Returns: * `isSameDocument` boolean - This event does not fire for same document navigations using window.history api and reference fragment navigations. This property is always set to `false` for this event. * `isMainFrame` boolean - True if the navigation is taking place in a main frame. - * `frame` WebFrameMain - The frame to be navigated. - * `initiator` WebFrameMain (optional) - The frame which initiated the + * `frame` WebFrameMain | null - The frame to be navigated. + May be `null` if accessed after the frame has either navigated or been destroyed. + * `initiator` WebFrameMain | null (optional) - The frame which initiated the navigation, which can be a parent frame (e.g. via `window.open` with a frame's name), or null if the navigation was not initiated by a frame. This can also be null if the initiating frame was deleted before the event was @@ -313,8 +315,9 @@ Returns: document. Examples of same document navigations are reference fragment navigations, pushState/replaceState, and same page history navigation. * `isMainFrame` boolean - True if the navigation is taking place in a main frame. - * `frame` WebFrameMain - The frame to be navigated. - * `initiator` WebFrameMain (optional) - The frame which initiated the + * `frame` WebFrameMain | null - The frame to be navigated. + May be `null` if accessed after the frame has either navigated or been destroyed. + * `initiator` WebFrameMain | null (optional) - The frame which initiated the navigation, which can be a parent frame (e.g. via `window.open` with a frame's name), or null if the navigation was not initiated by a frame. This can also be null if the initiating frame was deleted before the event was @@ -337,8 +340,9 @@ Returns: document. Examples of same document navigations are reference fragment navigations, pushState/replaceState, and same page history navigation. * `isMainFrame` boolean - True if the navigation is taking place in a main frame. - * `frame` WebFrameMain - The frame to be navigated. - * `initiator` WebFrameMain (optional) - The frame which initiated the + * `frame` WebFrameMain | null - The frame to be navigated. + May be `null` if accessed after the frame has either navigated or been destroyed. + * `initiator` WebFrameMain | null (optional) - The frame which initiated the navigation, which can be a parent frame (e.g. via `window.open` with a frame's name), or null if the navigation was not initiated by a frame. This can also be null if the initiating frame was deleted before the event was @@ -368,8 +372,9 @@ Returns: document. Examples of same document navigations are reference fragment navigations, pushState/replaceState, and same page history navigation. * `isMainFrame` boolean - True if the navigation is taking place in a main frame. - * `frame` WebFrameMain - The frame to be navigated. - * `initiator` WebFrameMain (optional) - The frame which initiated the + * `frame` WebFrameMain | null - The frame to be navigated. + May be `null` if accessed after the frame has either navigated or been destroyed. + * `initiator` WebFrameMain | null (optional) - The frame which initiated the navigation, which can be a parent frame (e.g. via `window.open` with a frame's name), or null if the navigation was not initiated by a frame. This can also be null if the initiating frame was deleted before the event was @@ -750,7 +755,8 @@ Returns: * `params` Object * `x` Integer - x coordinate. * `y` Integer - y coordinate. - * `frame` WebFrameMain - Frame from which the context menu was invoked. + * `frame` WebFrameMain | null - Frame from which the context menu was invoked. + May be `null` if accessed after the frame has either navigated or been destroyed. * `linkURL` string - URL of the link that encloses the node the context menu was invoked on. * `linkText` string - Text associated with the link. May be an empty @@ -876,12 +882,12 @@ app.whenReady().then(() => { Returns: -* `event` Event +* `details` Event\<\> + * `texture` [OffscreenSharedTexture](latest/api/structures/offscreen-shared-texture.md) (optional) _Experimental_ - The GPU shared texture of the frame, when `webPreferences.offscreen.useSharedTexture` is `true`. * `dirtyRect` [Rectangle](latest/api/structures/rectangle.md) * `image` [NativeImage](latest/api/native-image.md) - The image data of the whole frame. -Emitted when a new frame is generated. Only the dirty area is passed in the -buffer. +Emitted when a new frame is generated. Only the dirty area is passed in the buffer. ```js const { BrowserWindow } = require('electron') @@ -893,6 +899,33 @@ win.webContents.on('paint', (event, dirty, image) => { win.loadURL('https://github.com') ``` +When using shared texture (set `webPreferences.offscreen.useSharedTexture` to `true`) feature, you can pass the texture handle to external rendering pipeline without the overhead of +copying data between CPU and GPU memory, with Chromium's hardware acceleration support. This feature is helpful for high-performance rendering scenarios. + +Only a limited number of textures can exist at the same time, so it's important that you call `texture.release()` as soon as you're done with the texture. +By managing the texture lifecycle by yourself, you can safely pass the `texture.textureInfo` to other processes through IPC. + +```js +const { BrowserWindow } = require('electron') + +const win = new BrowserWindow({ webPreferences: { offscreen: { useSharedTexture: true } } }) +win.webContents.on('paint', async (e, dirty, image) => { + if (e.texture) { + // By managing lifecycle yourself, you can handle the event in async handler or pass the `e.texture.textureInfo` + // to other processes (not `e.texture`, the `e.texture.release` function is not passable through IPC). + await new Promise(resolve => setTimeout(resolve, 50)) + + // You can send the native texture handle to native code for importing into your rendering pipeline. + // For example: https://github.com/electron/electron/tree/main/spec/fixtures/native-addon/osr-gpu + // importTextureHandle(dirty, e.texture.textureInfo) + + // You must call `e.texture.release()` as soon as possible, before the underlying frame pool is drained. + e.texture.release() + } +}) +win.loadURL('https://github.com') +``` + #### Event: 'devtools-reload-page' Emitted when the devtools window instructs the webContents to reload @@ -990,7 +1023,8 @@ Returns: * `event` Event * `details` Object - * `frame` WebFrameMain + * `frame` WebFrameMain | null - The created frame. + May be `null` if accessed after the frame has either navigated or been destroyed. Emitted when the [mainFrame](latest/api/web-contents.md#contentsmainframe-readonly), an `