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

Standardize dialog

Browse source
This commit is contained in:
Jessica Lord 2015-08-25 05:46:06 -07:00
parent a1ef09a243
commit 81ed608b9c
1 changed files with 42 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

79
docs/api/dialog.md
View file

@ -1,7 +1,8 @@
# dialog # dialog
The `dialog` module provides APIs to show native system dialogs, so web The `dialog` module provides APIs to show native system dialogs, such as opening
applications can deliver the same user experience as native applications. files or alerting, so web applications can deliver the same user experience as
native applications.
An example of showing a dialog to select multiple files and directories: An example of showing a dialog to select multiple files and directories:
@ -15,23 +16,27 @@ console.log(dialog.showOpenDialog({ properties: [ 'openFile', 'openDirectory', '
have to do is provide a `BrowserWindow` reference in the `browserWindow` have to do is provide a `BrowserWindow` reference in the `browserWindow`
parameter. parameter.
## dialog.showOpenDialog([browserWindow], [options], [callback]) ## Methods
* `browserWindow` BrowserWindow The `dialog` module has the following methods:
* `options` Object
### `dialog.showOpenDialog([browserWindow][, options][, callback])`
* `browserWindow` BrowserWindow (optional)
* `options` Object (optional)
* `title` String * `title` String
* `defaultPath` String * `defaultPath` String
* `filters` Array * `filters` Array
* `properties` Array - Contains which features the dialog should use, can * `properties` Array - Contains which features the dialog should use, can
contain `openFile`, `openDirectory`, `multiSelections` and contain `openFile`, `openDirectory`, `multiSelections` and
`createDirectory` `createDirectory`
* `callback` Function * `callback` Function (optional)
On success, returns an array of file paths chosen by the user, otherwise On success this method returns an array of file paths chosen by the user,
returns `undefined`. otherwise it returns `undefined`.
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, an example is: selected when you want to limit the user to a specific type. For example:
```javascript ```javascript
{ {
@ -44,28 +49,28 @@ selected, an example is:
} }
``` ```
The `extensions` array should contain extensions without wildcards or dots (e.g. The `extensions` array should contain extensions without wildcards or dots (e.g.
`'png'` is good, `'.png'` and `'*.png'` are bad). To show all files, use the `'png'` is good but `'.png'` and `'*.png'` are bad). To show all files, use the
`'*'` wildcard (no other wildcard is supported). `'*'` wildcard (no other wildcard is supported).
If a `callback` is passed, the API call would be asynchronous and the result If a `callback` is passed, the API call will be asynchronous and the result
would be passed via `callback(filenames)` wil be passed via `callback(filenames)`
**Note:** On Windows and Linux, an open dialog can not be both a file selector **Note:** On Windows and Linux, an open dialog can not be both a file selector
and a directory selector, so if you set `properties` to 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.
## dialog.showSaveDialog([browserWindow], [options], [callback]) ### `dialog.showSaveDialog([browserWindow][, options][, callback])`
* `browserWindow` BrowserWindow * `browserWindow` BrowserWindow (optional)
* `options` Object * `options` Object (optional)
* `title` String * `title` String
* `defaultPath` String * `defaultPath` String
* `filters` Array * `filters` Array
* `callback` Function * `callback` Function (optional)
On success, returns the path of the file chosen by the user, otherwise returns On success this method returns the path of the file chosen by the user,
`undefined`. otherwise it returns `undefined`.
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.
@ -73,39 +78,39 @@ The `filters` specifies an array of file types that can be displayed, see
If a `callback` is passed, the API call will be asynchronous and the result If a `callback` is passed, the API call will be asynchronous and the result
will be passed via `callback(filename)` will be passed via `callback(filename)`
## dialog.showMessageBox([browserWindow], options, [callback]) ### `dialog.showMessageBox([browserWindow][, options][, callback])`
* `browserWindow` BrowserWindow * `browserWindow` BrowserWindow (optional)
* `options` Object * `options` Object (optional)
* `type` String - Can be `"none"`, `"info"`, `"error"`, `"question"` or * `type` String - Can be `"none"`, `"info"`, `"error"`, `"question"` or
`"warning"`. On Windows, "question" displays the same icon as "info", unless `"warning"`. On Windows, "question" displays the same icon as "info", unless
if you set an icon using the "icon" option you set an icon using the "icon" option.
* `buttons` Array - Array of texts for buttons * `buttons` Array - Array of texts for buttons.
* `title` String - Title of the message box, some platforms will not show it * `title` String - Title of the message box, some platforms will not show it.
* `message` String - Content of the message box * `message` String - Content of the message box.
* `detail` String - Extra information of the message * `detail` String - Extra information of the message.
* `icon` [NativeImage](native-image.md) * `icon` [NativeImage](native-image.md)
* `cancelId` Integer - The value will be returned when user cancels the dialog * `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 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 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 buttons. On OS X and Windows the index of "Cancel" button will always be
used as `cancelId`, not matter whether it is already specified used as `cancelId`, not matter whether it is already specified.
* `noLink` Boolean - On Windows Electron would try to figure out which ones of * `noLink` Boolean - On Windows Electron will try to figure out which one of
the `buttons` are common buttons (like "Cancel" or "Yes"), and show the the `buttons` are common buttons (like "Cancel" or "Yes"), and show the
others as command links in the dialog, this can make the dialog appear in others as command links in the dialog. This can make the dialog appear in
the style of modern Windows apps. If you don't like this behavior, you can the style of modern Windows apps. If you don't like this behavior, you can
specify `noLink` to `true` set `noLink` to `true`.
* `callback` Function * `callback` Function
Shows a message box, it will block until the message box is closed. It returns Shows a message box, it will block the process until the message box is closed.
the index of the clicked button. It returns the index of the clicked button.
If a `callback` is passed, the API call will be asynchronous and the result If a `callback` is passed, the API call will be asynchronous and the result
will be passed via `callback(response)` will be passed via `callback(response)`.
## dialog.showErrorBox(title, content) ### `dialog.showErrorBox(title, content)`
Runs a modal dialog that shows an error message. Displays a modal dialog that shows an error message.
This API can be called safely before the `ready` event of `app` module emits, it This API can be called safely before the `ready` event the `app` module emits,
is usually used to report errors in early stage of startup. it is usually used to report errors in early stage of startup.