diff --git a/docs/latest/.sha b/docs/latest/.sha index c84015347..f6bcede79 100644 --- a/docs/latest/.sha +++ b/docs/latest/.sha @@ -1 +1 @@ -633448a4c19d7c7f8b29a953df14c06d5e6900ee \ No newline at end of file +5147ac2d278f105ec0801c1ef021709979f6d428 \ No newline at end of file diff --git a/docs/latest/api/dialog.md b/docs/latest/api/dialog.md index 299f30468..6c3997b16 100644 --- a/docs/latest/api/dialog.md +++ b/docs/latest/api/dialog.md @@ -33,7 +33,10 @@ added: * `window` [BaseWindow](base-window.md) (optional) * `options` Object * `title` string (optional) - * `defaultPath` string (optional) + * `defaultPath` string (optional) - Absolute directory path, absolute file + path, or file name to use by default. If not provided, the dialog will + default to the user's Downloads folder, or their home directory if Downloads + doesn't exist. * `buttonLabel` string (optional) - Custom label for the confirmation button, when left empty the default label will be used. * `filters` [FileFilter[]](structures/file-filter.md) (optional) @@ -42,7 +45,7 @@ added: * `openFile` - Allow files to be selected. * `openDirectory` - Allow directories to be selected. * `multiSelections` - Allow multiple paths to be selected. - * `showHiddenFiles` _macOS_ _Windows_ _Deprecated_ - Show hidden files in dialog. Deprecated on Linux. + * `showHiddenFiles` _macOS_ _Windows_ - Show hidden files in dialog. * `createDirectory` _macOS_ - Allow creating new directories from dialog. * `promptToCreate` _Windows_ - Prompt for creation if the file path entered in the dialog does not exist. This does not actually create the file at @@ -112,7 +115,10 @@ changes: * `window` [BaseWindow](base-window.md) (optional) * `options` Object * `title` string (optional) - * `defaultPath` string (optional) + * `defaultPath` string (optional) - Absolute directory path, absolute file + path, or file name to use by default. If not provided, the dialog will + default to the user's Downloads folder, or their home directory if Downloads + doesn't exist. * `buttonLabel` string (optional) - Custom label for the confirmation button, when left empty the default label will be used. * `filters` [FileFilter[]](structures/file-filter.md) (optional) @@ -121,7 +127,7 @@ changes: * `openFile` - Allow files to be selected. * `openDirectory` - Allow directories to be selected. * `multiSelections` - Allow multiple paths to be selected. - * `showHiddenFiles` _macOS_ _Windows_ _Deprecated_ - Show hidden files in dialog. Deprecated on Linux. + * `showHiddenFiles` _macOS_ _Windows_ - Show hidden files in dialog. * `createDirectory` _macOS_ - Allow creating new directories from dialog. * `promptToCreate` _Windows_ - Prompt for creation if the file path entered in the dialog does not exist. This does not actually create the file at @@ -199,7 +205,9 @@ added: * `options` Object * `title` string (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments. * `defaultPath` string (optional) - Absolute directory path, absolute file - path, or file name to use by default. + path, or file name to use by default. If not provided, the dialog will + default to the user's Downloads folder, or their home directory if Downloads + doesn't exist. * `buttonLabel` string (optional) - Custom label for the confirmation button, when left empty the default label will be used. * `filters` [FileFilter[]](structures/file-filter.md) (optional) @@ -209,7 +217,7 @@ added: * `showsTagField` boolean (optional) _macOS_ - Show the tags input box, defaults to `true`. * `properties` string[] (optional) - * `showHiddenFiles` _macOS_ _Windows_ _Deprecated_ - Show hidden files in dialog. Deprecated on Linux. + * `showHiddenFiles` _macOS_ _Windows_ - Show hidden files in dialog. * `createDirectory` _macOS_ - Allow creating new directories from dialog. * `treatPackageAsDirectory` _macOS_ - Treat packages, such as `.app` folders, as a directory instead of a file. @@ -237,7 +245,9 @@ changes: * `options` Object * `title` string (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments. * `defaultPath` string (optional) - Absolute directory path, absolute file - path, or file name to use by default. + path, or file name to use by default. If not provided, the dialog will + default to the user's Downloads folder, or their home directory if Downloads + doesn't exist. * `buttonLabel` string (optional) - Custom label for the confirmation button, when left empty the default label will be used. * `filters` [FileFilter[]](structures/file-filter.md) (optional) @@ -246,7 +256,7 @@ changes: displayed in front of the filename text field. * `showsTagField` boolean (optional) _macOS_ - Show the tags input box, defaults to `true`. * `properties` string[] (optional) - * `showHiddenFiles` _macOS_ _Windows_ _Deprecated_ - Show hidden files in dialog. Deprecated on Linux. + * `showHiddenFiles` _macOS_ _Windows_ - Show hidden files in dialog. * `createDirectory` _macOS_ - Allow creating new directories from dialog. * `treatPackageAsDirectory` _macOS_ - Treat packages, such as `.app` folders, as a directory instead of a file. diff --git a/docs/latest/api/dock.md b/docs/latest/api/dock.md index 5774893a0..09df5a2b8 100644 --- a/docs/latest/api/dock.md +++ b/docs/latest/api/dock.md @@ -63,6 +63,9 @@ Returns `string` - The badge string of the dock. Hides the dock icon. +> [!IMPORTANT] +> **Known issue:** Calling `dock.hide()` within one second of a previous call will have no effect. As a workaround, ensure at least one second has elapsed between calls — for example, by deferring with a `setTimeout` of 1100ms or more after a previous call. + #### `dock.show()` _macOS_ Returns `Promise` - Resolves when the dock icon is shown. diff --git a/docs/latest/api/environment-variables.md b/docs/latest/api/environment-variables.md index 9f26858c1..efe8db2ea 100644 --- a/docs/latest/api/environment-variables.md +++ b/docs/latest/api/environment-variables.md @@ -210,13 +210,22 @@ the one downloaded by `npm install`. Usage: export ELECTRON_OVERRIDE_DIST_PATH=/Users/username/projects/electron/out/Testing ``` -### `ELECTRON_SKIP_BINARY_DOWNLOAD` +### `ELECTRON_INSTALL_PLATFORM` -If you want to install your project's dependencies but don't need to use Electron functionality, -you can set the `ELECTRON_SKIP_BINARY_DOWNLOAD` environment variable to prevent the binary from being -downloaded. For instance, this feature can be useful in continuous integration environments when -running unit tests that mock out the `electron` module. +Manually overrides platform used by `electron` package during an install. +This can be useful if you are on one platform (e.g macOS) but want to +download binaries for another platform (e.g Windows or Linux). Usage: ```sh -ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install +ELECTRON_INSTALL_PLATFORM=darwin npm install +``` + +### `ELECTRON_INSTALL_ARCH` + +Manually overrides architecture used by `electron` package during an install. +This can be useful if you are on one arch (e.g `arm64`) but want to download +binaries meant for another arch. Note that this will not work under Rosetta. Usage: + +```sh +ELECTRON_INSTALL_ARCH=arm64 npm install ``` diff --git a/docs/latest/api/menu-item.md b/docs/latest/api/menu-item.md index e60ecc3db..0f0203319 100644 --- a/docs/latest/api/menu-item.md +++ b/docs/latest/api/menu-item.md @@ -38,6 +38,7 @@ See [`Menu`](menu.md) for examples. * `header` - Only available on macOS 14 and up. * `palette` - Only available on macOS 14 and up. * `label` string (optional) + * `accessibilityLabel` string (optional) _macOS_ * `sublabel` string (optional) _macOS_ - Available in macOS >= 14.4 * `toolTip` string (optional) _macOS_ - Hover text for this menu item. * `accelerator` string (optional) - An [Accelerator](../tutorial/keyboard-shortcuts.md#accelerators) string. @@ -90,6 +91,12 @@ A `string` indicating the item's visible label. This property can be dynamically changed. +#### `menuItem.accessibilityLabel` _macOS_ + +A `string` indicating the item's accessibility label (used by assistive technology), if set. + +This property can be dynamically changed. + #### `menuItem.click` A `Function` that is fired when the MenuItem receives a click event. diff --git a/docs/latest/api/native-image.md b/docs/latest/api/native-image.md index 4e588b8a8..8d421aedd 100644 --- a/docs/latest/api/native-image.md +++ b/docs/latest/api/native-image.md @@ -201,10 +201,15 @@ Returns `NativeImage` Creates a new `NativeImage` instance from `dataUrl`, a base 64 encoded [Data URL][data-url] string. -### `nativeImage.createFromNamedImage(imageName[, hslShift])` _macOS_ +### `nativeImage.createFromNamedImage(imageName[, options])` _macOS_ * `imageName` string -* `hslShift` number[] (optional) +* `options` Object | number[] (optional) - If `options` is a number array (_Deprecated_), it is interpreted as `hslShift`. If it is an object, the +following properties can be specified: + * `hslShift` number[] (optional) + * `pointSize` Number (optional) - Defaults to `30.0`. + * `weight` 'ultralight' | 'thin' | 'light' | 'regular' | 'medium' | 'semibold' | 'bold' | 'heavy' | 'black' (optional) - Defaults to `regular`. + * `scale` 'small' | 'medium' | 'large' (optional) - Defaults to `medium`. Returns `NativeImage` @@ -246,6 +251,23 @@ const image = nativeImage.createFromNamedImage('square.and.pencil') where `'square.and.pencil'` is the symbol name from the [SF Symbols app](https://developer.apple.com/sf-symbols/). +### `nativeImage.createMenuSymbol(imageName)` _macOS_ + +* `imageName` string + +Returns `NativeImage` + +Creates a new `NativeImage` instance from an SF Symbol for use in a native [Menu](./menu.md). See [SF Symbols](https://developer.apple.com/sf-symbols/) for a list of possible values. + +```js +const { nativeImage, MenuItem } = require('electron') + +const item = new MenuItem({ + icon: nativeImage.createMenuSymbol('folder.badge.plus'), + label: 'Create Folder' +}) +``` + ## Class: NativeImage > Natively wrap images such as tray, dock, and application icons. @@ -272,8 +294,18 @@ Returns `Buffer` - A [Buffer][buffer] that contains the image's `JPEG` encoded d #### `image.toBitmap([options])` +```YAML history +changes: + - pr-url: https://github.com/electron/electron/pull/48178 + description: "Normalized `NativeImage.toBitmap()` pixel data to sRGB by default." + breaking-changes-header: behavior-changed-nativeimagetobitmap-now-normalizes-color-space +``` + * `options` Object (optional) * `scaleFactor` Number (optional) - Defaults to 1.0. + * `colorSpace` [ColorSpace](structures/color-space.md) (optional) - The target color space + for the output pixel data. Defaults to sRGB. Pass the image's original color space to + preserve the previous behavior, or another color space to get pixel values in that space. Returns `Buffer` - A [Buffer][buffer] that contains a copy of the image's raw bitmap pixel data. @@ -294,8 +326,18 @@ Returns `string` - The [Data URL][data-url] of the image. #### `image.getBitmap([options])` _Deprecated_ +```YAML history +changes: + - pr-url: https://github.com/electron/electron/pull/48178 + description: "Normalized `NativeImage.toBitmap()` pixel data to sRGB by default." + breaking-changes-header: behavior-changed-nativeimagetobitmap-now-normalizes-color-space +``` + * `options` Object (optional) * `scaleFactor` Number (optional) - Defaults to 1.0. + * `colorSpace` [ColorSpace](structures/color-space.md) (optional) - The target color space + for the output pixel data. Defaults to sRGB. Pass the image's original color space to + preserve the previous behavior, or another color space to get pixel values in that space. Legacy alias for `image.toBitmap()`. diff --git a/docs/latest/api/session.md b/docs/latest/api/session.md index ae0b8d707..d7ae57855 100644 --- a/docs/latest/api/session.md +++ b/docs/latest/api/session.md @@ -705,7 +705,7 @@ Clears the session’s HTTP cache. `scheme://host:port`. * `storages` string[] (optional) - The types of storages to clear, can be `cookies`, `filesystem`, `indexdb`, `localstorage`, - `shadercache`, `websql`, `serviceworkers`, `cachestorage`. If not + `shadercache`, `serviceworkers`, `cachestorage`. If not specified, clear all storage types. Returns `Promise` - resolves when the storage data has been cleared. diff --git a/docs/latest/api/structures/base-window-options.md b/docs/latest/api/structures/base-window-options.md index 4d7e96fbe..0b55fab9b 100644 --- a/docs/latest/api/structures/base-window-options.md +++ b/docs/latest/api/structures/base-window-options.md @@ -108,10 +108,11 @@ hide_title: false * `accentColor` boolean | string (optional) _Windows_ - The accent color for the window. By default, follows user preference in System Settings. Set to `false` to explicitly disable, or set the color in Hex, RGB, RGBA, HSL, HSLA or named CSS color format. Alpha values will be ignored. * `trafficLightPosition` [Point](point.md) (optional) _macOS_ - Set a custom position for the traffic light buttons in frameless windows. -* `roundedCorners` boolean (optional) _macOS_ _Windows_ - Whether frameless window +* `roundedCorners` boolean (optional) - Whether a frameless window should have rounded corners. Default is `true`. On Windows versions older than Windows 11 Build 22000 this property has no effect, and frameless windows will - not have rounded corners. + not have rounded corners. On Linux, rounded corners are only drawn when the + desktop environment supports client-side decorations. * `thickFrame` boolean (optional) _Windows_ - Use `WS_THICKFRAME` style for frameless windows on Windows, which adds the standard window frame. Setting it to `false` will remove window shadow and window animations, and disable window diff --git a/docs/latest/api/structures/web-preferences.md b/docs/latest/api/structures/web-preferences.md index b4f9e1d6b..1ca927db3 100644 --- a/docs/latest/api/structures/web-preferences.md +++ b/docs/latest/api/structures/web-preferences.md @@ -101,6 +101,7 @@ hide_title: false The actual output pixel format and color space of the texture should refer to [`OffscreenSharedTexture`](../structures/offscreen-shared-texture.md) object in the `paint` event. * `argb` - The requested output texture format is 8-bit unorm RGBA, with SRGB SDR color space. * `rgbaf16` - The requested output texture format is 16-bit float RGBA, with scRGB HDR color space. + * `nv12` - The requested output texture format is 12bpp with Y plane followed by a 2x2 interleaved UV plane, with REC709 color space. * `deviceScaleFactor` number (optional) _Experimental_ - The device scale factor of the offscreen rendering output. If not set, will use `1` as default. * `contextIsolation` boolean (optional) - Whether to run Electron APIs and the specified `preload` script in a separate JavaScript context. Defaults diff --git a/docs/latest/api/tray.md b/docs/latest/api/tray.md index 26310b6b3..2b5800185 100644 --- a/docs/latest/api/tray.md +++ b/docs/latest/api/tray.md @@ -45,7 +45,7 @@ app.whenReady().then(() => { * Tray icon uses [StatusNotifierItem](https://www.freedesktop.org/wiki/Specifications/StatusNotifierItem/) by default, when it is not available in user's desktop environment the - `GtkStatusIcon` will be used instead. + `GtkStatusIcon` will be used instead. If StatusNotifierItem is available, the first tray icon created will use SNI, while subsequently-created icons will use `GtkStatusIcon`. * The `click` event is emitted when the tray icon receives activation from user, however the StatusNotifierItem spec does not specify which action would cause an activation, for some environments it is left mouse click, but for diff --git a/docs/latest/api/view.md b/docs/latest/api/view.md index a3f5bedfb..cad62e9ff 100644 --- a/docs/latest/api/view.md +++ b/docs/latest/api/view.md @@ -124,6 +124,13 @@ Examples of valid `color` values: > [!NOTE] > The area cutout of the view's border still captures clicks. +#### `view.setBackgroundBlur(blurRadius)` + +* `blurRadius` Integer - The radius of the background blur effect (in pixels). + +> [!NOTE] +> You must set a background color with an alpha channel (e.g. `#80ffffff`) in order for the blur effect to be visible. + #### `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 517d3c62e..860b4bde5 100644 --- a/docs/latest/api/web-contents.md +++ b/docs/latest/api/web-contents.md @@ -1594,6 +1594,20 @@ Centers the current text selection in web page. Copy the image at the given position to the clipboard. +#### `contents.copyVideoFrameAt(x, y)` + +* `x` Integer +* `y` Integer + +When executed on a video media element, copies the frame at (x, y) to the clipboard. + +#### `contents.saveVideoFrameAs(x, y)` + +* `x` Integer +* `y` Integer + +When executed on a video media element, shows a save dialog and saves the frame at (x, y) to disk. + #### `contents.paste()` Executes the editing command `paste` in web page. @@ -2270,6 +2284,20 @@ Returns `Integer` - The Chromium internal `pid` of the associated renderer. Can be compared to the `frameProcessId` passed by frame specific navigation events (e.g. `did-frame-navigate`) +#### `contents.clone()` + +Returns `WebContents` - A cloned WebContents instance. This method creates a copy +of the WebContents with the following attributes: + +* **WebPreferences** - All preferences from the original WebContents are copied +* **SiteInstance** - Uses the same SiteInstance as the original. This means the cloned WebContents will reuse the same render process as the original when loading same-origin pages, and only spawn a new render process for cross-origin navigations. This process allocation behavior is consistent with window.open and tab duplication in Chromium. For more details, see [Chromium's Site Isolation](https://www.chromium.org/developers/design-documents/site-isolation/) design document. +* **Opener relationship** - Inherits the opener (window.opener) relationship +* **Navigation state** - Copies the navigation history and controller state + +The cloned WebContents is an independent instance with its own lifecycle that can be destroyed separately and will not contain any open web pages. + +This API is useful for use cases where you want to create a new WebContents that shares the same render process with the original for same-origin content, while maintaining full lifecycle independence. Additionally, reusing the existing render process can help optimize memory usage and page load speed to a certain extent, as it eliminates the overhead of spawning and initializing a new render process from scratch. + #### `contents.takeHeapSnapshot(filePath)` * `filePath` string - Path to the output file. diff --git a/docs/latest/api/web-frame-main.md b/docs/latest/api/web-frame-main.md index e97631162..16fa150ca 100644 --- a/docs/latest/api/web-frame-main.md +++ b/docs/latest/api/web-frame-main.md @@ -182,6 +182,20 @@ app.on('web-contents-created', (_, webContents) => { }) ``` +#### `frame.copyVideoFrameAt(x, y)` + +* `x` Integer +* `y` Integer + +When executed on a video media element, copies the frame at (x, y) to the clipboard. + +#### `frame.saveVideoFrameAs(x, y)` + +* `x` Integer +* `y` Integer + +When executed on a video media element, shows a save dialog and saves the frame at (x, y) to disk. + ### Instance Properties #### `frame.ipc` _Readonly_ diff --git a/docs/latest/breaking-changes.md b/docs/latest/breaking-changes.md index 1e3489afd..6cde2017b 100644 --- a/docs/latest/breaking-changes.md +++ b/docs/latest/breaking-changes.md @@ -19,6 +19,110 @@ This document uses the following convention to categorize breaking changes: * **Deprecated:** An API was marked as deprecated. The API will continue to function, but will emit a deprecation warning, and will be removed in a future release. * **Removed:** An API or feature was removed, and is no longer supported by Electron. +## Planned Breaking API Changes (44.0) + +### Removed: Windows 32-bit (ia32) and Linux 32-bit ARM (armv7l) support + +Electron no longer publishes prebuilt binaries for 32-bit platforms: Windows x86 +(`win32-ia32`) and Linux ARM (`linux-armv7l`). All related release artifacts +(`chromedriver`, `mksnapshot`, `ffmpeg`, and the Windows x86 `node.lib` on the +Electron headers CDN) are no longer published either. + +Older versions of Electron will continue to support these platforms, but Electron +v44.0.0 and higher will only be published for 64-bit platforms. + +Once the v44 series reaches end of life in January 2027, Electron will no longer +support these platforms completely. + +### Removed: `clipboard` module is no longer available in the renderer process + +The `clipboard` module is no longer exposed to renderer processes. It was +[previously deprecated](#deprecated-clipboard-api-access-from-renderer-processes) +and is now removed in line with +[RFC 0019](https://github.com/electron/rfcs/blob/main/text/0019-clipboard-rearchitecture.md#removing-the-clipboard-api-from-the-renderer) +to close the security risk of granting non-sandboxed renderers direct clipboard access. + +Renderers should use the [`navigator.clipboard` API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API) to safely work with the system clipboard. If more advanced usage is necessary, expose the necessary helpers from a +preload script using the [`contextBridge` API](api/context-bridge.md). +When using `contextBridge` care must be taken to ensure that the [`clipboard API` is not exposed to untrusted content](https://www.electronjs.org/docs/latest/tutorial/security#20-do-not-expose-electron-apis-to-untrusted-web-content). + +## Planned Breaking API Changes (43.0) + +### Behavior Changed: Rounded corners on Linux + +Frameless windows default to rounded corners on Linux if the desktop environment supports client-side decorations. This can be configured using the existing `roundedCorners` option on `BrowserWindow`, +which is now supported on Linux and defaults to `true` on all platforms. + +### Behavior Changed: WCO respects the native title bar layout on Linux + +Frameless windows with Window Controls Overlay (WCO) now adopt the native title bar layout and user settings on Linux. For example, controls will appear on the left side of the frame on RTL systems, and only the close button will be visible by default on GNOME. Depending on the user's desktop environment and configuration, buttons can appear on the left or right side of the frame (or both). To account for all possibilities, use the CSS variables `env(titlebar-area-x, 0px)` and `env(titlebar-area-width, 100%)` to constrain your app's title bar content to a safe area. + +### Behavior Changed: `NativeImage.toBitmap()` now normalizes color space + +`NativeImage.toBitmap()` (and its deprecated alias `NativeImage.getBitmap()`) now normalizes pixel data to sRGB by default. Previously, raw pixel data was returned without color space conversion, which meant pixel values from images with different embedded color profiles (e.g., Display P3 on macOS) could differ for the same visual color. + +To preserve the previous behavior, pass the image's original color space in the `colorSpace` +option. You can also pass `colorSpace` to convert to any other specific color space: + +```js +const image = nativeImage.createFromPath('photo.png') +// New default: normalized to sRGB +const srgbBitmap = image.toBitmap() +// Convert to Display P3 +const p3Bitmap = image.toBitmap({ + colorSpace: { + primaries: 'p3', + transfer: 'srgb', + matrix: 'rgb', + range: 'full' + } +}) +``` + +### Behavior Changed: `chrome.scripting` CSS injection matches more fallback frames + +Extensions using `chrome.scripting.insertCSS()` or `chrome.scripting.removeCSS()` +now follow Chrome's behavior when Electron cannot match a frame's URL directly, +such as with `about:blank` or `data:` frames. If the extension has access to the +page that created the frame, CSS may now be inserted into or removed from those +fallback frames as well. + +Apps or extensions that relied on Electron skipping those frames should narrow their +injection target, frame IDs, or match patterns. + +### Behavior Changed: Dialog methods default to Downloads directory + +The `defaultPath` option for the following methods now defaults to the user's Downloads folder (or their home directory if Downloads doesn't exist) when not explicitly provided: + +* `dialog.showOpenDialog` +* `dialog.showOpenDialogSync` +* `dialog.showSaveDialog` +* `dialog.showSaveDialogSync` + +Previously, when no `defaultPath` was provided, the underlying OS file dialog would determine the initial directory — typically remembering the last directory the user navigated to, or falling back to an OS-specific default. Now, Electron explicitly sets the initial directory to Downloads, which also means the OS will no longer track and restore the last-used directory between dialog invocations. + +To preserve the old behavior, you can track the last-used directory yourself and pass it as `defaultPath`: + +```js +const path = require('node:path') + +let lastUsedPath +const result = await dialog.showOpenDialog({ + defaultPath: lastUsedPath +}) + +if (!result.canceled && result.filePaths.length > 0) { + lastUsedPath = path.dirname(result.filePaths[0]) +} +``` + +### Removed: `showHiddenFiles` in Dialogs on Linux + +The `showHiddenFiles` property is no longer supported on Linux. +It continues to work on macOS and Windows. GTK intends for this feature +to be a user choice rather than an app choice, and has removed the API +to do this programmatically. + ## Planned Breaking API Changes (42.0) ### Behavior Changed: macOS notifications now use `UNNotification` API @@ -86,6 +190,19 @@ When calling `Session.clearStorageData(options)`, the `options.quotas` object is [removed](https://chromium-review.googlesource.com/c/chromium/src/+/7596126) from upstream Chromium. +### Deprecated: Passing only an array `hslShift` to `nativeImage.createFromNamedImage()` + +Passing only an array `hslShift` to `nativeImage.createFromNamedImage()` is deprecated. You should now pass an options object with an `hslShift` property instead: + +```js +// Deprecated +nativeImage.createFromNamedImage(imageName, [0, 1, -1]) +// Replace with +nativeImage.createFromNamedImage(imageName, { + hslShift: [0, 1, -1] +}) +``` + ## Planned Breaking API Changes (41.0) ### Behavior Changed: PDFs no longer create a separate WebContents diff --git a/docs/latest/fiddles/features/window-customization/custom-title-bar/safe-area/index.html b/docs/latest/fiddles/features/window-customization/custom-title-bar/safe-area/index.html new file mode 100644 index 000000000..389fd9e76 --- /dev/null +++ b/docs/latest/fiddles/features/window-customization/custom-title-bar/safe-area/index.html @@ -0,0 +1,14 @@ + + + + + + + + Custom Titlebar App + + + +
Cool titlebar
+ + \ No newline at end of file diff --git a/docs/latest/fiddles/features/window-customization/custom-title-bar/safe-area/main.js b/docs/latest/fiddles/features/window-customization/custom-title-bar/safe-area/main.js new file mode 100644 index 000000000..e389551db --- /dev/null +++ b/docs/latest/fiddles/features/window-customization/custom-title-bar/safe-area/main.js @@ -0,0 +1,16 @@ +const { app, BrowserWindow } = require('electron') + +function createWindow () { + const win = new BrowserWindow({ + // remove the default titlebar + titleBarStyle: 'hidden', + // expose window controls in Windows/Linux + ...(process.platform !== 'darwin' ? { titleBarOverlay: true } : {}) + }) + + win.loadFile('index.html') +} + +app.whenReady().then(() => { + createWindow() +}) diff --git a/docs/latest/fiddles/features/window-customization/custom-title-bar/safe-area/styles.css b/docs/latest/fiddles/features/window-customization/custom-title-bar/safe-area/styles.css new file mode 100644 index 000000000..57bb48e0e --- /dev/null +++ b/docs/latest/fiddles/features/window-customization/custom-title-bar/safe-area/styles.css @@ -0,0 +1,17 @@ +body { + margin: 0; +} +.titlebar { + background: blue; + color: white; + display: flex; + justify-content: center; + align-items: center; + app-region: drag; + + margin-left: env(titlebar-area-x, 0); + width: env(titlebar-area-width, 100%); + height: env(titlebar-area-height, 30px); + box-sizing: border-box; + border: 1px dashed red; +} \ No newline at end of file diff --git a/docs/latest/tutorial/custom-title-bar.md b/docs/latest/tutorial/custom-title-bar.md index 20f3e8494..3efa753bb 100644 --- a/docs/latest/tutorial/custom-title-bar.md +++ b/docs/latest/tutorial/custom-title-bar.md @@ -69,6 +69,15 @@ bar to reposition our app window! For more information around how to manage drag regions defined by your electron application, see the [Custom draggable regions][] section below. +One more step: we should make sure our title bar content doesn't overlap with the native +window controls. Buttons can appear on the right or left side of the frame (or both) depending +on RTL and the user's settings. We can create a safe area using the CSS variables +`env(titlebar-area-x, 0px)` and `env(titlebar-area-width, 100%)`. + +```fiddle docs/latest/fiddles/features/window-customization/custom-title-bar/safe-area + +``` + Congratulations, you've just implemented a basic custom title bar! ## Advanced window customization diff --git a/docs/latest/tutorial/introduction.md b/docs/latest/tutorial/introduction.md index 1e43abd91..765acf8a9 100644 --- a/docs/latest/tutorial/introduction.md +++ b/docs/latest/tutorial/introduction.md @@ -27,10 +27,9 @@ Electron's maintainers. We highly recommend installing it as a learning tool to experiment with Electron's APIs or to prototype features during development. Fiddle also integrates nicely with our documentation. When browsing through examples -in our tutorials, you'll frequently see an "Open in Electron Fiddle" button underneath -a code block. If you have Fiddle installed, this button will open a -`fiddle.electronjs.org` link that will automatically load the example into Fiddle, -no copy-pasting required. +in our tutorials, you'll frequently see an "Open in Fiddle" button above a code +block. If you have Fiddle installed, this button will open a `fiddle.electronjs.org` +link that will automatically load the example into Fiddle, no copy-pasting required. ```fiddle docs/latest/fiddles/quick-start ``` diff --git a/docs/latest/tutorial/launch-app-from-url-in-another-app.md b/docs/latest/tutorial/launch-app-from-url-in-another-app.md index 754b05366..433a2a16b 100644 --- a/docs/latest/tutorial/launch-app-from-url-in-another-app.md +++ b/docs/latest/tutorial/launch-app-from-url-in-another-app.md @@ -87,6 +87,13 @@ if (!gotTheLock) { // Create mainWindow, load the rest of the app, etc... app.whenReady().then(() => { createWindow() + // Check for deep link on cold start + if (process.argv.length >= 2) { + const lastArg = process.argv[process.argv.length - 1] + if (lastArg.startsWith('electron-fiddle://')) { + dialog.showErrorBox('Welcome Back', `You arrived from: ${lastArg}`) + } + } }) } ```