From d7689bb9b5c062dd7c3a024e340ebff75bd63668 Mon Sep 17 00:00:00 2001 From: Shelley Vohr Date: Fri, 16 Aug 2024 16:49:10 +0200 Subject: [PATCH] docs: expand dialog window to `BaseWindow` (#43334) docs: expand dialog window to BaseWindow --- docs/api/dialog.md | 54 ++++++++++++++++++++-------------------- docs/breaking-changes.md | 2 +- spec/api-dialog-spec.ts | 17 ++++++++++++- 3 files changed, 44 insertions(+), 29 deletions(-) diff --git a/docs/api/dialog.md b/docs/api/dialog.md index bb731cd2367d..78cb384a77c3 100644 --- a/docs/api/dialog.md +++ b/docs/api/dialog.md @@ -15,9 +15,9 @@ console.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] The `dialog` module has the following methods: -### `dialog.showOpenDialogSync([browserWindow, ]options)` +### `dialog.showOpenDialogSync([window, ]options)` -* `browserWindow` [BrowserWindow](browser-window.md) (optional) +* `window` [BaseWindow](base-window.md) (optional) * `options` Object * `title` string (optional) * `defaultPath` string (optional) @@ -47,7 +47,7 @@ The `dialog` module has the following methods: Returns `string[] | undefined`, the file paths chosen by the user; if the dialog is cancelled it returns `undefined`. -The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal. +The `window` argument allows the dialog to attach itself to a parent window, making it modal. The `filters` specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. For example: @@ -72,15 +72,15 @@ and a directory selector, so if you set `properties` to `['openFile', 'openDirectory']` on these platforms, a directory selector will be shown. -```js @ts-type={mainWindow:Electron.BrowserWindow} +```js @ts-type={mainWindow:Electron.BaseWindow} dialog.showOpenDialogSync(mainWindow, { properties: ['openFile', 'openDirectory'] }) ``` -### `dialog.showOpenDialog([browserWindow, ]options)` +### `dialog.showOpenDialog([window, ]options)` -* `browserWindow` [BrowserWindow](browser-window.md) (optional) +* `window` [BaseWindow](base-window.md) (optional) * `options` Object * `title` string (optional) * `defaultPath` string (optional) @@ -114,7 +114,7 @@ Returns `Promise` - Resolve with an object containing the following: * `filePaths` string[] - An array of file paths chosen by the user. If the dialog is cancelled this will be an empty array. * `bookmarks` string[] (optional) _macOS_ _mas_ - An array matching the `filePaths` array of base64 encoded strings which contains security scoped bookmark data. `securityScopedBookmarks` must be enabled for this to be populated. (For return values, see [table here](#bookmarks-array).) -The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal. +The `window` argument allows the dialog to attach itself to a parent window, making it modal. The `filters` specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. For example: @@ -139,7 +139,7 @@ and a directory selector, so if you set `properties` to `['openFile', 'openDirectory']` on these platforms, a directory selector will be shown. -```js @ts-type={mainWindow:Electron.BrowserWindow} +```js @ts-type={mainWindow:Electron.BaseWindow} dialog.showOpenDialog(mainWindow, { properties: ['openFile', 'openDirectory'] }).then(result => { @@ -150,9 +150,9 @@ dialog.showOpenDialog(mainWindow, { }) ``` -### `dialog.showSaveDialogSync([browserWindow, ]options)` +### `dialog.showSaveDialogSync([window, ]options)` -* `browserWindow` [BrowserWindow](browser-window.md) (optional) +* `window` [BaseWindow](base-window.md) (optional) * `options` Object * `title` string (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments. * `defaultPath` string (optional) - Absolute directory path, absolute file @@ -176,14 +176,14 @@ dialog.showOpenDialog(mainWindow, { Returns `string`, the path of the file chosen by the user; if the dialog is cancelled it returns an empty string. -The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal. +The `window` argument allows the dialog to attach itself to a parent window, making it modal. The `filters` specifies an array of file types that can be displayed, see `dialog.showOpenDialog` for an example. -### `dialog.showSaveDialog([browserWindow, ]options)` +### `dialog.showSaveDialog([window, ]options)` -* `browserWindow` [BrowserWindow](browser-window.md) (optional) +* `window` [BaseWindow](base-window.md) (optional) * `options` Object * `title` string (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments. * `defaultPath` string (optional) - Absolute directory path, absolute file @@ -210,7 +210,7 @@ Returns `Promise` - Resolve with an object containing the following: * `filePath` string - If the dialog is canceled, this will be an empty string. * `bookmark` string (optional) _macOS_ _mas_ - Base64 encoded string which contains the security scoped bookmark data for the saved file. `securityScopedBookmarks` must be enabled for this to be present. (For return values, see [table here](#bookmarks-array).) -The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal. +The `window` argument allows the dialog to attach itself to a parent window, making it modal. The `filters` specifies an array of file types that can be displayed, see `dialog.showOpenDialog` for an example. @@ -218,9 +218,9 @@ The `filters` specifies an array of file types that can be displayed, see **Note:** On macOS, using the asynchronous version is recommended to avoid issues when expanding and collapsing the dialog. -### `dialog.showMessageBoxSync([browserWindow, ]options)` +### `dialog.showMessageBoxSync([wndow, ]options)` -* `browserWindow` [BrowserWindow](browser-window.md) (optional) +* `window` [BaseWindow](base-window.md) (optional) * `options` Object * `message` string - Content of the message box. * `type` string (optional) - Can be `none`, `info`, `error`, `question` or @@ -258,12 +258,12 @@ Returns `Integer` - the index of the clicked button. Shows a message box, it will block the process until the message box is closed. It returns the index of the clicked button. -The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal. -If `browserWindow` is not shown dialog will not be attached to it. In such case it will be displayed as an independent window. +The `window` argument allows the dialog to attach itself to a parent window, making it modal. +If `window` is not shown dialog will not be attached to it. In such case it will be displayed as an independent window. -### `dialog.showMessageBox([browserWindow, ]options)` +### `dialog.showMessageBox([window, ]options)` -* `browserWindow` [BrowserWindow](browser-window.md) (optional) +* `window` [BaseWindow](base-window.md) (optional) * `options` Object * `message` string - Content of the message box. * `type` string (optional) - Can be `none`, `info`, `error`, `question` or @@ -313,7 +313,7 @@ Returns `Promise` - resolves with a promise containing the following pro Shows a message box. -The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal. +The `window` argument allows the dialog to attach itself to a parent window, making it modal. ### `dialog.showErrorBox(title, content)` @@ -327,9 +327,9 @@ it is usually used to report errors in early stage of startup. If called before the app `ready`event on Linux, the message will be emitted to stderr, and no GUI dialog will appear. -### `dialog.showCertificateTrustDialog([browserWindow, ]options)` _macOS_ _Windows_ +### `dialog.showCertificateTrustDialog([window, ]options)` _macOS_ _Windows_ -* `browserWindow` [BrowserWindow](browser-window.md) (optional) +* `window` [BaseWindow](base-window.md) (optional) * `options` Object * `certificate` [Certificate](structures/certificate.md) - The certificate to trust/import. * `message` string - The message to display to the user. @@ -338,14 +338,14 @@ Returns `Promise` - resolves when the certificate trust dialog is shown. On macOS, this displays a modal dialog that shows a message and certificate information, and gives the user the option of trusting/importing the -certificate. If you provide a `browserWindow` argument the dialog will be +certificate. If you provide a `window` argument the dialog will be attached to the parent window, making it modal. On Windows the options are more limited, due to the Win32 APIs used: * The `message` argument is not used, as the OS provides its own confirmation dialog. -* The `browserWindow` argument is ignored since it is not possible to make +* The `window` argument is ignored since it is not possible to make this confirmation dialog modal. ## Bookmarks array @@ -362,10 +362,10 @@ On Windows the options are more limited, due to the Win32 APIs used: ## Sheets On macOS, dialogs are presented as sheets attached to a window if you provide -a [`BrowserWindow`](browser-window.md) reference in the `browserWindow` parameter, or modals if no +a [`BaseWindow`](base-window.md) reference in the `window` parameter, or modals if no window is provided. -You can call `BrowserWindow.getCurrentWindow().setSheetOffset(offset)` to change +You can call `BaseWindow.getCurrentWindow().setSheetOffset(offset)` to change the offset from the window frame where sheets are attached. [AbortSignal]: https://nodejs.org/api/globals.html#globals_class_abortsignal diff --git a/docs/breaking-changes.md b/docs/breaking-changes.md index 58a39a99e53e..ea6e7149de8d 100644 --- a/docs/breaking-changes.md +++ b/docs/breaking-changes.md @@ -1827,7 +1827,7 @@ In Electron 7, this now returns a `FileList` with a `File` object for: Note that `webkitdirectory` no longer exposes the path to the selected folder. If you require the path to the selected folder rather than the folder contents, -see the `dialog.showOpenDialog` API ([link](api/dialog.md#dialogshowopendialogbrowserwindow-options)). +see the `dialog.showOpenDialog` API ([link](api/dialog.md#dialogshowopendialogwindow-options)). ### API Changed: Callback-based versions of promisified APIs diff --git a/spec/api-dialog-spec.ts b/spec/api-dialog-spec.ts index fa9b538c522a..a375c8716473 100644 --- a/spec/api-dialog-spec.ts +++ b/spec/api-dialog-spec.ts @@ -1,5 +1,5 @@ import { expect } from 'chai'; -import { dialog, BrowserWindow } from 'electron/main'; +import { dialog, BaseWindow, BrowserWindow } from 'electron/main'; import { closeAllWindows } from './lib/window-helpers'; import { ifit } from './lib/spec-helpers'; import { setTimeout } from 'node:timers/promises'; @@ -16,6 +16,11 @@ describe('dialog module', () => { const w = new BrowserWindow(); dialog.showOpenDialog(w, { title: 'i am title' }); }).to.not.throw(); + + expect(() => { + const w = new BaseWindow(); + dialog.showOpenDialog(w, { title: 'i am title' }); + }).to.not.throw(); }); it('throws errors when the options are invalid', () => { @@ -52,6 +57,11 @@ describe('dialog module', () => { const w = new BrowserWindow(); dialog.showSaveDialog(w, { title: 'i am title' }); }).to.not.throw(); + + expect(() => { + const w = new BaseWindow(); + dialog.showSaveDialog(w, { title: 'i am title' }); + }).to.not.throw(); }); it('throws errors when the options are invalid', () => { @@ -93,6 +103,11 @@ describe('dialog module', () => { const w = new BrowserWindow(); dialog.showMessageBox(w, { message: 'i am message' }); }).to.not.throw(); + + expect(() => { + const w = new BaseWindow(); + dialog.showMessageBox(w, { message: 'i am message' }); + }).to.not.throw(); }); it('throws errors when the options are invalid', () => {