mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

docs: expand dialog window to BaseWindow (#43334)

Browse source 
docs: expand dialog window to BaseWindow
This commit is contained in:
Shelley Vohr 2024-08-16 16:49:10 +02:00 committed by GitHub
parent b497700e36
commit d7689bb9b5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 44 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
docs/api/dialog.md
View file

@ -15,9 +15,9 @@ console.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections']
The `dialog` module has the following methods: 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 * `options` Object
* `title` string (optional) * `title` string (optional)
* `defaultPath` 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`. 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 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: 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 `['openFile', 'openDirectory']` on these platforms, a directory selector will be
shown. shown.
```js @ts-type={mainWindow:Electron.BrowserWindow} ```js @ts-type={mainWindow:Electron.BaseWindow}
dialog.showOpenDialogSync(mainWindow, { dialog.showOpenDialogSync(mainWindow, {
properties: ['openFile', 'openDirectory'] 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 * `options` Object
* `title` string (optional) * `title` string (optional)
* `defaultPath` 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. * `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).) * `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 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: 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 `['openFile', 'openDirectory']` on these platforms, a directory selector will be
shown. shown.
```js @ts-type={mainWindow:Electron.BrowserWindow} ```js @ts-type={mainWindow:Electron.BaseWindow}
dialog.showOpenDialog(mainWindow, { dialog.showOpenDialog(mainWindow, {
properties: ['openFile', 'openDirectory'] properties: ['openFile', 'openDirectory']
}).then(result => { }).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 * `options` Object
* `title` string (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments. * `title` string (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments.
* `defaultPath` string (optional) - Absolute directory path, absolute file * `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. 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 The `filters` specifies an array of file types that can be displayed, see
`dialog.showOpenDialog` for an example. `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 * `options` Object
* `title` string (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments. * `title` string (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments.
* `defaultPath` string (optional) - Absolute directory path, absolute file * `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. * `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).) * `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 The `filters` specifies an array of file types that can be displayed, see
`dialog.showOpenDialog` for an example. `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 **Note:** On macOS, using the asynchronous version is recommended to avoid issues when
expanding and collapsing the dialog. 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 * `options` Object
* `message` string - Content of the message box. * `message` string - Content of the message box.
* `type` string (optional) - Can be `none`, `info`, `error`, `question` or * `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. Shows a message box, it will block the process until the message box is closed.
It returns the index of the clicked button. It returns the index of the clicked button.
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.
If `browserWindow` is not shown dialog will not be attached to it. In such case it will be displayed as an independent window. 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 * `options` Object
* `message` string - Content of the message box. * `message` string - Content of the message box.
* `type` string (optional) - Can be `none`, `info`, `error`, `question` or * `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. 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)` ### `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, before the app `ready`event on Linux, the message will be emitted to stderr,
and no GUI dialog will appear. 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 * `options` Object
* `certificate` [Certificate](structures/certificate.md) - The certificate to trust/import. * `certificate` [Certificate](structures/certificate.md) - The certificate to trust/import.
* `message` string - The message to display to the user. * `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 On macOS, this displays a modal dialog that shows a message and certificate
information, and gives the user the option of trusting/importing the 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. attached to the parent window, making it modal.
On Windows the options are more limited, due to the Win32 APIs used: 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 * The `message` argument is not used, as the OS provides its own confirmation
dialog. 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. this confirmation dialog modal.
## Bookmarks array ## Bookmarks array
@ -362,10 +362,10 @@ On Windows the options are more limited, due to the Win32 APIs used:
## Sheets ## Sheets
On macOS, dialogs are presented as sheets attached to a window if you provide 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. 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. the offset from the window frame where sheets are attached.
[AbortSignal]: https://nodejs.org/api/globals.html#globals_class_abortsignal [AbortSignal]: https://nodejs.org/api/globals.html#globals_class_abortsignal

2
docs/breaking-changes.md
View file

@ -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. 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, 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 ### API Changed: Callback-based versions of promisified APIs

17
spec/api-dialog-spec.ts
View file

@ -1,5 +1,5 @@
import { expect } from 'chai'; import { expect } from 'chai';
import { dialog, BrowserWindow } from 'electron/main'; import { dialog, BaseWindow, BrowserWindow } from 'electron/main';
import { closeAllWindows } from './lib/window-helpers'; import { closeAllWindows } from './lib/window-helpers';
import { ifit } from './lib/spec-helpers'; import { ifit } from './lib/spec-helpers';
import { setTimeout } from 'node:timers/promises'; import { setTimeout } from 'node:timers/promises';
@ -16,6 +16,11 @@ describe('dialog module', () => {
const w = new BrowserWindow(); const w = new BrowserWindow();
dialog.showOpenDialog(w, { title: 'i am title' }); dialog.showOpenDialog(w, { title: 'i am title' });
}).to.not.throw(); }).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', () => { it('throws errors when the options are invalid', () => {
@ -52,6 +57,11 @@ describe('dialog module', () => {
const w = new BrowserWindow(); const w = new BrowserWindow();
dialog.showSaveDialog(w, { title: 'i am title' }); dialog.showSaveDialog(w, { title: 'i am title' });
}).to.not.throw(); }).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', () => { it('throws errors when the options are invalid', () => {
@ -93,6 +103,11 @@ describe('dialog module', () => {
const w = new BrowserWindow(); const w = new BrowserWindow();
dialog.showMessageBox(w, { message: 'i am message' }); dialog.showMessageBox(w, { message: 'i am message' });
}).to.not.throw(); }).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', () => { it('throws errors when the options are invalid', () => {