docs: expand dialog window to `BaseWindow` (#43334)

docs: expand dialog window to BaseWindow

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<Object>` - 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[]&#32;(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<Object>` - 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<Object>` - 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<void>` - 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

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
 

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', () => {