Merge pull request #2602 from atom/jl-std-docs-3

Standardize Docs: dialog, file-object, frameless-window
This commit is contained in:
Jessica Lord 2015-08-28 11:30:18 -07:00
commit 26f7f2ab21
3 changed files with 74 additions and 66 deletions

View file

@ -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.

View file

@ -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">

View file

@ -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.