electron/docs/api/dialog.md

132 lines
5 KiB
Markdown
Raw Normal View History

2013-09-09 07:35:57 +00:00
# dialog
2013-08-14 22:43:35 +00:00
Display native system dialogs for opening and saving files, alerting, etc.
2013-08-14 22:43:35 +00:00
An example of showing a dialog to select multiple files and directories:
```javascript
2015-08-26 23:41:25 +00:00
var win = ...; // BrowserWindow in which to show the dialog
const dialog = require('electron').dialog;
2013-08-14 22:43:35 +00:00
console.log(dialog.showOpenDialog({ properties: [ 'openFile', 'openDirectory', 'multiSelections' ]}));
```
The Dialog is opened from Electron's main thread. If you want to use the dialog
object from a renderer process, remember to access it using the remote:
```javascript
const dialog = require('electron').remote.dialog;
```
2015-08-25 12:46:06 +00:00
## Methods
2013-08-14 22:43:35 +00:00
2015-08-25 12:46:06 +00:00
The `dialog` module has the following methods:
### `dialog.showOpenDialog([browserWindow, ]options[, callback])`
2015-08-25 12:46:06 +00:00
* `browserWindow` BrowserWindow (optional)
* `options` Object
2013-08-14 22:43:35 +00:00
* `title` String
2014-03-13 06:09:30 +00:00
* `defaultPath` String
2014-08-06 07:00:31 +00:00
* `filters` Array
* `properties` Array - Contains which features the dialog should use, can
contain `openFile`, `openDirectory`, `multiSelections` and
`createDirectory`
2015-08-25 12:46:06 +00:00
* `callback` Function (optional)
2013-08-14 22:43:35 +00:00
2015-08-25 12:46:06 +00:00
On success this method returns an array of file paths chosen by the user,
otherwise it returns `undefined`.
2013-08-14 22:43:35 +00:00
2014-08-06 07:00:31 +00:00
The `filters` specifies an array of file types that can be displayed or
2015-08-25 12:46:06 +00:00
selected when you want to limit the user to a specific type. For example:
2014-08-06 07:00:31 +00:00
```javascript
{
filters: [
{ name: 'Images', extensions: ['jpg', 'png', 'gif'] },
{ name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },
{ name: 'Custom File Type', extensions: ['as'] },
{ name: 'All Files', extensions: ['*'] }
]
2014-08-06 07:00:31 +00:00
}
```
2015-09-02 01:19:18 +00:00
The `extensions` array should contain extensions without wildcards or dots (e.g.
2015-08-25 12:46:06 +00:00
`'png'` is good but `'.png'` and `'*.png'` are bad). To show all files, use the
`'*'` wildcard (no other wildcard is supported).
2014-08-06 07:00:31 +00:00
2015-08-25 12:46:06 +00:00
If a `callback` is passed, the API call will be asynchronous and the result
2015-09-02 01:19:18 +00:00
will be passed via `callback(filenames)`
2014-03-13 06:09:30 +00:00
2015-08-26 23:41:25 +00:00
**Note:** On Windows and Linux an open dialog can not be both a file selector
2015-06-07 19:32:54 +00:00
and a directory selector, so if you set `properties` to
`['openFile', 'openDirectory']` on these platforms, a directory selector will be
shown.
2013-08-14 22:43:35 +00:00
### `dialog.showSaveDialog([browserWindow, ]options[, callback])`
2013-08-14 22:43:35 +00:00
2015-08-25 12:46:06 +00:00
* `browserWindow` BrowserWindow (optional)
* `options` Object
2013-08-14 22:43:35 +00:00
* `title` String
* `defaultPath` String
2014-08-06 07:00:31 +00:00
* `filters` Array
2015-08-25 12:46:06 +00:00
* `callback` Function (optional)
2013-08-14 22:43:35 +00:00
2015-08-25 12:46:06 +00:00
On success this method returns the path of the file chosen by the user,
otherwise it returns `undefined`.
2013-08-14 22:43:35 +00:00
2014-08-06 07:00:31 +00:00
The `filters` specifies an array of file types that can be displayed, see
`dialog.showOpenDialog` for an example.
2015-06-07 19:32:54 +00:00
If a `callback` is passed, the API call will be asynchronous and the result
will be passed via `callback(filename)`
2013-08-14 22:43:35 +00:00
### `dialog.showMessageBox([browserWindow, ]options[, callback])`
2013-08-14 22:43:35 +00:00
2015-08-25 12:46:06 +00:00
* `browserWindow` BrowserWindow (optional)
* `options` Object
* `type` String - Can be `"none"`, `"info"`, `"error"`, `"question"` or
`"warning"`. On Windows, "question" displays the same icon as "info", unless
2015-08-25 12:46:06 +00:00
you set an icon using the "icon" option.
* `buttons` Array - Array of texts for buttons.
2016-01-11 03:15:40 +00:00
* `defaultId` Integer - Index of the button in the buttons array which will
be selected by default when the message box opens.
2015-08-25 12:46:06 +00:00
* `title` String - Title of the message box, some platforms will not show it.
* `message` String - Content of the message box.
* `detail` String - Extra information of the message.
2015-02-12 05:52:28 +00:00
* `icon` [NativeImage](native-image.md)
2015-07-07 10:51:49 +00:00
* `cancelId` Integer - The value will be returned when user cancels the dialog
instead of clicking the buttons of the dialog. By default it is the index
of the buttons that have "cancel" or "no" as label, or 0 if there is no such
buttons. On OS X and Windows the index of "Cancel" button will always be
2015-08-25 12:46:06 +00:00
used as `cancelId`, not matter whether it is already specified.
* `noLink` Boolean - On Windows Electron will try to figure out which one of
2015-07-23 09:20:43 +00:00
the `buttons` are common buttons (like "Cancel" or "Yes"), and show the
2015-08-25 12:46:06 +00:00
others as command links in the dialog. This can make the dialog appear in
2015-07-23 09:20:43 +00:00
the style of modern Windows apps. If you don't like this behavior, you can
2015-08-25 12:46:06 +00:00
set `noLink` to `true`.
2014-03-13 06:09:30 +00:00
* `callback` Function
2013-08-14 22:43:35 +00:00
2015-08-25 12:46:06 +00:00
Shows a message box, it will block the process until the message box is closed.
It returns the index of the clicked button.
2013-08-14 22:43:35 +00:00
2015-06-07 19:32:54 +00:00
If a `callback` is passed, the API call will be asynchronous and the result
2015-08-25 12:46:06 +00:00
will be passed via `callback(response)`.
2015-08-25 12:46:06 +00:00
### `dialog.showErrorBox(title, content)`
2015-08-25 12:46:06 +00:00
Displays a modal dialog that shows an error message.
2015-08-25 12:46:06 +00:00
This API can be called safely before the `ready` event the `app` module emits,
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,
2015-10-31 23:04:01 +00:00
and no GUI dialog will appear.
## Sheets
On Mac OS X, dialogs are presented as sheets attached to a window if you provide
a `BrowserWindow` reference in the `browserWindow` parameter, or modals if no
window is provided.
You can call `BrowserWindow.getCurrentWindow().setSheetOffset(offset)` to change
the offset from the window frame where sheets are attached.