diff --git a/docs/api/dialog.md b/docs/api/dialog.md index 084e6bae0c4a..d00540e62df9 100644 --- a/docs/api/dialog.md +++ b/docs/api/dialog.md @@ -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. diff --git a/docs/api/file-object.md b/docs/api/file-object.md index 36154cdd6a1f..01d49c39155f 100644 --- a/docs/api/file-object.md +++ b/docs/api/file-object.md @@ -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
diff --git a/docs/api/frameless-window.md b/docs/api/frameless-window.md index 498a65b225db..8d5c578914c7 100644 --- a/docs/api/frameless-window.md +++ b/docs/api/frameless-window.md @@ -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.