Merge pull request #2602 from atom/jl-std-docs-3
Standardize Docs: dialog, file-object, frameless-window
This commit is contained in:
Jessica Lord
commit
26f7f2ab21
3 changed files with 74 additions and 66 deletions
|
|
@ -1,12 +1,13 @@
|
|||
# dialog
|
||||
|
||||
The `dialog` module provides APIs to show native system dialogs, so web
|
||||
applications can deliver the same user experience as native applications.
|
||||
The `dialog` module provides APIs to show native system dialogs, such as opening
|
||||
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:
|
||||
|
||||
```javascript
|
||||
var win = ...; // window in which to show the dialog
|
||||
var win = ...; // BrowserWindow in which to show the dialog
|
||||
var dialog = require('dialog');
|
||||
console.log(dialog.showOpenDialog({ properties: [ 'openFile', 'openDirectory', 'multiSelections' ]}));
|
||||
```
|
||||
|
|
@ -15,23 +16,27 @@ console.log(dialog.showOpenDialog({ properties: [ 'openFile', 'openDirectory', '
|
|||
have to do is provide a `BrowserWindow` reference in the `browserWindow`
|
||||
parameter.
|
||||
|
||||
## dialog.showOpenDialog([browserWindow], [options], [callback])
|
||||
## Methods
|
||||
|
||||
* `browserWindow` BrowserWindow
|
||||
* `options` Object
|
||||
The `dialog` module has the following methods:
|
||||
|
||||
### `dialog.showOpenDialog([browserWindow][, options][, callback])`
|
||||
|
||||
* `browserWindow` BrowserWindow (optional)
|
||||
* `options` Object (optional)
|
||||
* `title` String
|
||||
* `defaultPath` String
|
||||
* `filters` Array
|
||||
* `properties` Array - Contains which features the dialog should use, can
|
||||
contain `openFile`, `openDirectory`, `multiSelections` and
|
||||
`createDirectory`
|
||||
* `callback` Function
|
||||
* `callback` Function (optional)
|
||||
|
||||
On success, returns an array of file paths chosen by the user, otherwise
|
||||
returns `undefined`.
|
||||
On success this method returns an array of file paths chosen by the user,
|
||||
otherwise it returns `undefined`.
|
||||
|
||||
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
|
||||
{
|
||||
|
|
@ -44,28 +49,28 @@ selected, an example is:
|
|||
}
|
||||
```
|
||||
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).
|
||||
|
||||
If a `callback` is passed, the API call would be asynchronous and the result
|
||||
would be passed via `callback(filenames)`
|
||||
If a `callback` is passed, the API call will be asynchronous and the result
|
||||
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
|
||||
`['openFile', 'openDirectory']` on these platforms, a directory selector will be
|
||||
shown.
|
||||
|
||||
## dialog.showSaveDialog([browserWindow], [options], [callback])
|
||||
### `dialog.showSaveDialog([browserWindow][, options][, callback])`
|
||||
|
||||
* `browserWindow` BrowserWindow
|
||||
* `options` Object
|
||||
* `browserWindow` BrowserWindow (optional)
|
||||
* `options` Object (optional)
|
||||
* `title` String
|
||||
* `defaultPath` String
|
||||
* `filters` Array
|
||||
* `callback` Function
|
||||
* `callback` Function (optional)
|
||||
|
||||
On success, returns the path of the file chosen by the user, otherwise returns
|
||||
`undefined`.
|
||||
On success this method returns the path of the file chosen by the user,
|
||||
otherwise it returns `undefined`.
|
||||
|
||||
The `filters` specifies an array of file types that can be displayed, see
|
||||
`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
|
||||
will be passed via `callback(filename)`
|
||||
|
||||
## dialog.showMessageBox([browserWindow], options, [callback])
|
||||
### `dialog.showMessageBox([browserWindow][, options][, callback])`
|
||||
|
||||
* `browserWindow` BrowserWindow
|
||||
* `options` Object
|
||||
* `browserWindow` BrowserWindow (optional)
|
||||
* `options` Object (optional)
|
||||
* `type` String - Can be `"none"`, `"info"`, `"error"`, `"question"` or
|
||||
`"warning"`. On Windows, "question" displays the same icon as "info", unless
|
||||
if you set an icon using the "icon" option
|
||||
* `buttons` Array - Array of texts for buttons
|
||||
* `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
|
||||
you set an icon using the "icon" option.
|
||||
* `buttons` Array - Array of texts for buttons.
|
||||
* `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.
|
||||
* `icon` [NativeImage](native-image.md)
|
||||
* `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
|
||||
used as `cancelId`, not matter whether it is already specified
|
||||
* `noLink` Boolean - On Windows Electron would try to figure out which ones of
|
||||
used as `cancelId`, not matter whether it is already specified.
|
||||
* `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
|
||||
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
|
||||
specify `noLink` to `true`
|
||||
set `noLink` to `true`.
|
||||
* `callback` Function
|
||||
|
||||
Shows a message box, it will block until the message box is closed. It returns
|
||||
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.
|
||||
|
||||
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
|
||||
is usually used to report errors in early stage of startup.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
# `File` object
|
||||
|
||||
The DOM's File interface provides abstraction around native files, in order to
|
||||
let users work on native files directly with HTML5 file API, Electron has
|
||||
added a `path` attribute to `File` interface which exposes the file's real path
|
||||
on filesystem.
|
||||
The DOM's File interface provides abstraction around native files in order to
|
||||
let users work on native files directly with the HTML5 file API. Electron has
|
||||
added a `path` attribute to the `File` interface which exposes the file's real
|
||||
path on filesystem.
|
||||
|
||||
Example on getting real path of a dragged file:
|
||||
Example on getting a real path from a dragged-onto-the-app file:
|
||||
|
||||
```html
|
||||
<div id="holder">
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
# Frameless window
|
||||
# Frameless Window
|
||||
|
||||
A frameless window is a window that has no chrome.
|
||||
A frameless window is a window that has no [chrome](https://developer.mozilla.org/en-US/docs/Glossary/Chrome), the parts of the window, like toolbars, that are not a part of the webp page. These are options on the [`BrowserWindow`](browser-window.md) class.
|
||||
|
||||
## Create a frameless window
|
||||
|
||||
To create a frameless window, you only need to specify `frame` to `false` in
|
||||
To create a frameless window, you need to set `frame` to `false` in
|
||||
[BrowserWindow](browser-window.md)'s `options`:
|
||||
|
||||
|
||||
|
|
@ -24,19 +24,22 @@ var win = new BrowserWindow({ transparent: true, frame: false });
|
|||
|
||||
### Limitations
|
||||
|
||||
* You can not click through the transparent area, we are going to introduce an
|
||||
* You can not click through the transparent area. We are going to introduce an
|
||||
API to set window shape to solve this, but currently blocked at an
|
||||
[upstream bug](https://code.google.com/p/chromium/issues/detail?id=387234).
|
||||
* Transparent window is not resizable, setting `resizable` to `true` may make
|
||||
transparent window stop working on some platforms.
|
||||
* Transparent windows are not resizable. Setting `resizable` to `true` may make
|
||||
a transparent window stop working on some platforms.
|
||||
* The `blur` filter only applies to the web page, so there is no way to apply
|
||||
blur effect to the content below the window.
|
||||
* On Windows transparent window will not work when DWM is disabled.
|
||||
blur effect to the content below the window (i.e. other applications open on
|
||||
the user's system).
|
||||
* On Windows operation shystems, transparent windows will not work when DWM is
|
||||
disabled.
|
||||
* On Linux users have to put `--enable-transparent-visuals --disable-gpu` in
|
||||
command line to disable GPU and allow ARGB to make transparent window, this is
|
||||
caused by an upstream bug that [alpha channel doesn't work on some NVidia
|
||||
drivers](https://code.google.com/p/chromium/issues/detail?id=369209) on Linux.
|
||||
* On Mac the native window shadow will not show for transparent window.
|
||||
the command line to disable GPU and allow ARGB to make transparent window,
|
||||
this is caused by an upstream bug that [alpha channel doesn't work on some
|
||||
NVidia drivers](https://code.google.com/p/chromium/issues/detail?id=369209) on
|
||||
Linux.
|
||||
* On Mac the native window shadow will not be shown on a transparent window.
|
||||
|
||||
## Draggable region
|
||||
|
||||
|
|
@ -44,7 +47,7 @@ By default, the frameless window is non-draggable. Apps need to specify
|
|||
`-webkit-app-region: drag` in CSS to tell Electron which regions are draggable
|
||||
(like the OS's standard titlebar), and apps can also use
|
||||
`-webkit-app-region: no-drag` to exclude the non-draggable area from the
|
||||
draggable region. Note that only rectangular shape is currently supported.
|
||||
draggable region. Note that only rectangular shapes are currently supported.
|
||||
|
||||
To make the whole window draggable, you can add `-webkit-app-region: drag` as
|
||||
`body`'s style:
|
||||
|
|
@ -64,15 +67,15 @@ button {
|
|||
}
|
||||
```
|
||||
|
||||
If you're only using a custom titlebar, you also need to make buttons in
|
||||
titlebar non-draggable.
|
||||
If you're setting just a custom titlebar as draggable, you also need to make all
|
||||
buttons in titlebar non-draggable.
|
||||
|
||||
## Text selection
|
||||
|
||||
One thing on frameless window is that the dragging behaviour may conflict with
|
||||
selecting text, for example, when you drag the titlebar, you may accidentally
|
||||
select the text on titlebar. To prevent this, you need to disable text
|
||||
selection on dragging area like this:
|
||||
In a frameless window the dragging behaviour may conflict with selecting text.
|
||||
For example, when you drag the titlebar you may accidentally select the text on
|
||||
the titlebar. To prevent this, you need to disable text selection within a
|
||||
draggable area like this:
|
||||
|
||||
```css
|
||||
.titlebar {
|
||||
|
|
@ -83,7 +86,7 @@ selection on dragging area like this:
|
|||
|
||||
## Context menu
|
||||
|
||||
On some platforms, the draggable area would be treated as non-client frame, so
|
||||
when you right click on it a system menu would be popuped. To make context menu
|
||||
behave correctly on all platforms, you should never custom context menu on
|
||||
On some platforms, the draggable area will be treated as a non-client frame, so
|
||||
when you right click on it a system menu will pop up. To make the context menu
|
||||
behave correctly on all platforms you should never use a custom context menu on
|
||||
draggable areas.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue