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

Merge pull request #7884 from electron/optional-things

Browse source 
Update docs to correctly identify props and params that are optional
This commit is contained in:
Zeke Sikelianos 2016-11-11 09:47:31 -08:00 • committed by GitHub
commit 80a7835cdf
18 changed files with 181 additions and 243 deletions
Download patch file Download diff file Expand all files Collapse all files

69
docs/api/app.md
View file

@ -519,22 +519,7 @@ The API uses the Windows Registry and LSCopyDefaultHandlerForURLScheme internall
Adds `tasks` to the [Tasks][tasks] category of the JumpList on Windows.
`tasks` is an array of `Task` objects in the following format:
`Task` Object:
* `program` String - Path of the program to execute, usually you should
specify `process.execPath` which opens the current program.
* `arguments` String - The command line arguments when `program` is
executed.
* `title` String - The string to be displayed in a JumpList.
* `description` String - Description of this task.
* `iconPath` String - The absolute path to an icon to be displayed in a
JumpList, which can be an arbitrary resource file that contains an icon. You
can usually specify `process.execPath` to show the icon of the program.
* `iconIndex` Integer - The icon index in the icon file. If an icon file
consists of two or more icons, set this value to identify the icon. If an
icon file consists of one icon, this value is 0.
`tasks` is an array of [`Task`](structures/task.md) objects.
Returns `Boolean` - Whether the call succeeded.
@ -575,23 +560,6 @@ following strings:
If `categories` is `null` the previously set custom Jump List (if any) will be
replaced by the standard Jump List for the app (managed by Windows).
`JumpListCategory` objects should have the following properties:
* `type` String - One of the following:
* `tasks` - Items in this category will be placed into the standard `Tasks`
category. There can be only one such category, and it will always be
displayed at the bottom of the Jump List.
* `frequent` - Displays a list of files frequently opened by the app, the
name of the category and its items are set by Windows.
* `recent` - Displays a list of files recently opened by the app, the name
of the category and its items are set by Windows. Items may be added to
this category indirectly using `app.addRecentDocument(path)`.
* `custom` - Displays tasks or file links, `name` must be set by the app.
* `name` String - Must be set if `type` is `custom`, otherwise it should be
omitted.
* `items` Array - Array of `JumpListItem` objects if `type` is `tasks` or
`custom`, otherwise it should be omitted.
**Note:** If a `JumpListCategory` object has neither the `type` nor the `name`
property set then its `type` is assumed to be `tasks`. If the `name` property
is set but the `type` property is omitted then the `type` is assumed to be
@ -604,35 +572,6 @@ re-add a removed item to a custom category earlier than that will result in the
entire custom category being omitted from the Jump List. The list of removed
items can be obtained using `app.getJumpListSettings()`.
`JumpListItem` objects should have the following properties:
* `type` String - One of the following:
* `task` - A task will launch an app with specific arguments.
* `separator` - Can be used to separate items in the standard `Tasks`
category.
* `file` - A file link will open a file using the app that created the
Jump List, for this to work the app must be registered as a handler for
the file type (though it doesn't have to be the default handler).
* `path` String - Path of the file to open, should only be set if `type` is
`file`.
* `program` String - Path of the program to execute, usually you should
specify `process.execPath` which opens the current program. Should only be
set if `type` is `task`.
* `args` String - The command line arguments when `program` is executed. Should
only be set if `type` is `task`.
* `title` String - The text to be displayed for the item in the Jump List.
Should only be set if `type` is `task`.
* `description` String - Description of the task (displayed in a tooltip).
Should only be set if `type` is `task`.
* `iconPath` String - The absolute path to an icon to be displayed in a
Jump List, which can be an arbitrary resource file that contains an icon
(e.g. `.ico`, `.exe`, `.dll`). You can usually specify `process.execPath` to
show the program icon.
* `iconIndex` Integer - The index of the icon in the resource file. If a
resource file contains multiple icons this value can be used to specify the
zero-based index of the icon that should be displayed for this task. If a
resource file contains only one icon, this property should be set to zero.
Here's a very simple example of creating a custom Jump List:
```javascript
@ -758,7 +697,7 @@ multiple instances of the application to once again run side by side.
* `type` String - Uniquely identifies the activity. Maps to
[`NSUserActivity.activityType`][activity-type].
* `userInfo` Object - App-specific state to store for use by another device.
* `webpageURL` String - The webpage to load in a browser if no suitable app is
* `webpageURL` String (optional) - The webpage to load in a browser if no suitable app is
installed on the resuming device. The scheme must be `http` or `https`.
Creates an `NSUserActivity` and sets it as the current activity. The activity
@ -837,9 +776,9 @@ Returns `Object`:
### `app.setLoginItemSettings(settings)` _macOS_ _Windows_
* `settings` Object
* `openAtLogin` Boolean - `true` to open the app at login, `false` to remove
* `openAtLogin` Boolean (optional) - `true` to open the app at login, `false` to remove
the app as a login item. Defaults to `false`.
* `openAsHidden` Boolean - `true` to open the app as hidden. Defaults to
* `openAsHidden` Boolean (optional) - `true` to open the app as hidden. Defaults to
`false`. The user can edit this setting from the System Preferences so
`app.getLoginItemStatus().wasOpenedAsHidden` should be checked when the app
is opened to know the current value. This setting is only supported on

2
docs/api/auto-updater.md
View file

@ -103,7 +103,7 @@ The `autoUpdater` object has the following methods:
### `autoUpdater.setFeedURL(url[, requestHeaders])`
* `url` String
* `requestHeaders` Object _macOS_ - HTTP request headers.
* `requestHeaders` Object _macOS_ (optional) - HTTP request headers.
Sets the `url` and initialize the auto updater.

156
docs/api/browser-window.md
View file

@ -116,78 +116,78 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
### `new BrowserWindow([options])`
* `options` Object
* `width` Integer - Window's width in pixels. Default is `800`.
* `height` Integer - Window's height in pixels. Default is `600`.
* `x` Integer (**required** if y is used) - Window's left offset from screen.
* `options` Object (optional)
* `width` Integer (optional) - Window's width in pixels. Default is `800`.
* `height` Integer (optional) - Window's height in pixels. Default is `600`.
* `x` Integer (optional) (**required** if y is used) - Window's left offset from screen.
Default is to center the window.
* `y` Integer (**required** if x is used) - Window's top offset from screen.
* `y` Integer (optional) (**required** if x is used) - Window's top offset from screen.
Default is to center the window.
* `useContentSize` Boolean - The `width` and `height` would be used as web
* `useContentSize` Boolean (optional) - The `width` and `height` would be used as web
page's size, which means the actual window's size will include window
frame's size and be slightly larger. Default is `false`.
* `center` Boolean - Show window in the center of the screen.
* `minWidth` Integer - Window's minimum width. Default is `0`.
* `minHeight` Integer - Window's minimum height. Default is `0`.
* `maxWidth` Integer - Window's maximum width. Default is no limit.
* `maxHeight` Integer - Window's maximum height. Default is no limit.
* `resizable` Boolean - Whether window is resizable. Default is `true`.
* `movable` Boolean - Whether window is movable. This is not implemented
* `center` Boolean (optional) - Show window in the center of the screen.
* `minWidth` Integer (optional) - Window's minimum width. Default is `0`.
* `minHeight` Integer (optional) - Window's minimum height. Default is `0`.
* `maxWidth` Integer (optional) - Window's maximum width. Default is no limit.
* `maxHeight` Integer (optional) - Window's maximum height. Default is no limit.
* `resizable` Boolean (optional) - Whether window is resizable. Default is `true`.
* `movable` Boolean (optional) - Whether window is movable. This is not implemented
on Linux. Default is `true`.
* `minimizable` Boolean - Whether window is minimizable. This is not
* `minimizable` Boolean (optional) - Whether window is minimizable. This is not
implemented on Linux. Default is `true`.
* `maximizable` Boolean - Whether window is maximizable. This is not
* `maximizable` Boolean (optional) - Whether window is maximizable. This is not
implemented on Linux. Default is `true`.
* `closable` Boolean - Whether window is closable. This is not implemented
* `closable` Boolean (optional) - Whether window is closable. This is not implemented
on Linux. Default is `true`.
* `focusable` Boolean - Whether the window can be focused. Default is
* `focusable` Boolean (optional) - Whether the window can be focused. Default is
`true`. On Windows setting `focusable: false` also implies setting
`skipTaskbar: true`. On Linux setting `focusable: false` makes the window
stop interacting with wm, so the window will always stay on top in all
workspaces.
* `alwaysOnTop` Boolean - Whether the window should always stay on top of
* `alwaysOnTop` Boolean (optional) - Whether the window should always stay on top of
other windows. Default is `false`.
* `fullscreen` Boolean - Whether the window should show in fullscreen. When
* `fullscreen` Boolean (optional) - Whether the window should show in fullscreen. When
explicitly set to `false` the fullscreen button will be hidden or disabled
on macOS. Default is `false`.
* `fullscreenable` Boolean - Whether the window can be put into fullscreen
* `fullscreenable` Boolean (optional) - Whether the window can be put into fullscreen
mode. On macOS, also whether the maximize/zoom button should toggle full
screen mode or maximize window. Default is `true`.
* `skipTaskbar` Boolean - Whether to show the window in taskbar. Default is
* `skipTaskbar` Boolean (optional) - Whether to show the window in taskbar. Default is
`false`.
* `kiosk` Boolean - The kiosk mode. Default is `false`.
* `title` String - Default window title. Default is `"Electron"`.
* `icon` [NativeImage](native-image.md) - The window icon. On Windows it is
* `kiosk` Boolean (optional) - The kiosk mode. Default is `false`.
* `title` String (optional) - Default window title. Default is `"Electron"`.
* `icon` ([NativeImage](native-image.md) | String) (optional) - The window icon. On Windows it is
recommended to use `ICO` icons to get best visual effects, you can also
leave it undefined so the executable's icon will be used.
* `show` Boolean - Whether window should be shown when created. Default is
* `show` Boolean (optional) - Whether window should be shown when created. Default is
`true`.
* `frame` Boolean - Specify `false` to create a
* `frame` Boolean (optional) - Specify `false` to create a
[Frameless Window](frameless-window.md). Default is `true`.
* `parent` BrowserWindow - Specify parent window. Default is `null`.
* `modal` Boolean - Whether this is a modal window. This only works when the
* `parent` BrowserWindow (optional) - Specify parent window. Default is `null`.
* `modal` Boolean (optional) - Whether this is a modal window. This only works when the
window is a child window. Default is `false`.
* `acceptFirstMouse` Boolean - Whether the web view accepts a single
* `acceptFirstMouse` Boolean (optional) - Whether the web view accepts a single
mouse-down event that simultaneously activates the window. Default is
`false`.
* `disableAutoHideCursor` Boolean - Whether to hide cursor when typing.
* `disableAutoHideCursor` Boolean (optional) - Whether to hide cursor when typing.
Default is `false`.
* `autoHideMenuBar` Boolean - Auto hide the menu bar unless the `Alt`
* `autoHideMenuBar` Boolean (optional) - Auto hide the menu bar unless the `Alt`
key is pressed. Default is `false`.
* `enableLargerThanScreen` Boolean - Enable the window to be resized larger
* `enableLargerThanScreen` Boolean (optional) - Enable the window to be resized larger
than screen. Default is `false`.
* `backgroundColor` String - Window's background color as Hexadecimal value,
* `backgroundColor` String (optional) - Window's background color as Hexadecimal value,
like `#66CD00` or `#FFF` or `#80FFFFFF` (alpha is supported). Default is
`#FFF` (white).
* `hasShadow` Boolean - Whether window should have a shadow. This is only
* `hasShadow` Boolean (optional) - Whether window should have a shadow. This is only
implemented on macOS. Default is `true`.
* `darkTheme` Boolean - Forces using dark theme for the window, only works on
* `darkTheme` Boolean (optional) - Forces using dark theme for the window, only works on
some GTK+3 desktop environments. Default is `false`.
* `transparent` Boolean - Makes the window [transparent](frameless-window.md).
* `transparent` Boolean (optional) - Makes the window [transparent](frameless-window.md).
Default is `false`.
* `type` String - The type of window, default is normal window. See more about
* `type` String (optional) - The type of window, default is normal window. See more about
this below.
* `titleBarStyle` String - The style of window title bar. Default is `default`. Possible values are:
* `titleBarStyle` String (optional) - The style of window title bar. Default is `default`. Possible values are:
* `default` - Results in the standard gray opaque Mac title
bar.
* `hidden` - Results in a hidden title bar and a full size content window, yet
@ -195,79 +195,79 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
the top left.
* `hidden-inset` - Results in a hidden title bar with an alternative look
where the traffic light buttons are slightly more inset from the window edge.
* `thickFrame` Boolean - Use `WS_THICKFRAME` style for frameless windows on
* `thickFrame` Boolean (optional) - Use `WS_THICKFRAME` style for frameless windows on
Windows, which adds standard window frame. Setting it to `false` will remove
window shadow and window animations. Default is `true`.
* `vibrancy` String - Add a type of vibrancy effect to the window, only on
macOS. Can be `appearance-based`, `light`, `dark`, `titlebar`, `selection`,
`menu`, `popover`, `sidebar`, `medium-light` or `ultra-dark`.
* `webPreferences` Object - Settings of web page's features.
* `devTools` Boolean - Whether to enable DevTools. If it is set to `false`, can not use `BrowserWindow.webContents.openDevTools()` to open DevTools. Default is `true`.
* `nodeIntegration` Boolean - Whether node integration is enabled. Default
* `webPreferences` Object (optional) - Settings of web page's features.
* `devTools` Boolean (optional) - Whether to enable DevTools. If it is set to `false`, can not use `BrowserWindow.webContents.openDevTools()` to open DevTools. Default is `true`.
* `nodeIntegration` Boolean (optional) - Whether node integration is enabled. Default
is `true`.
* `preload` String - Specifies a script that will be loaded before other
* `preload` String (optional) - Specifies a script that will be loaded before other
scripts run in the page. This script will always have access to node APIs
no matter whether node integration is turned on or off. The value should
be the absolute file path to the script.
When node integration is turned off, the preload script can reintroduce
Node global symbols back to the global scope. See example
[here](process.md#event-loaded).
* `session` [Session](session.md#class-session) - Sets the session used by the
* `session` [Session](session.md#class-session) (optional) - Sets the session used by the
page. Instead of passing the Session object directly, you can also choose to
use the `partition` option instead, which accepts a partition string. When
both `session` and `partition` are provided, `session` will be preferred.
Default is the default session.
* `partition` String - Sets the session used by the page according to the
* `partition` String (optional) - Sets the session used by the page according to the
session's partition string. If `partition` starts with `persist:`, the page
will use a persistent session available to all pages in the app with the
same `partition`. If there is no `persist:` prefix, the page will use an
in-memory session. By assigning the same `partition`, multiple pages can share
the same session. Default is the default session.
* `zoomFactor` Number - The default zoom factor of the page, `3.0` represents
* `zoomFactor` Number (optional) - The default zoom factor of the page, `3.0` represents
`300%`. Default is `1.0`.
* `javascript` Boolean - Enables JavaScript support. Default is `true`.
* `webSecurity` Boolean - When `false`, it will disable the
* `javascript` Boolean (optional) - Enables JavaScript support. Default is `true`.
* `webSecurity` Boolean (optional) - When `false`, it will disable the
same-origin policy (usually using testing websites by people), and set
`allowDisplayingInsecureContent` and `allowRunningInsecureContent` to
`true` if these two options are not set by user. Default is `true`.
* `allowDisplayingInsecureContent` Boolean - Allow an https page to display
* `allowDisplayingInsecureContent` Boolean (optional) - Allow an https page to display
content like images from http URLs. Default is `false`.
* `allowRunningInsecureContent` Boolean - Allow an https page to run
* `allowRunningInsecureContent` Boolean (optional) - Allow an https page to run
JavaScript, CSS or plugins from http URLs. Default is `false`.
* `images` Boolean - Enables image support. Default is `true`.
* `textAreasAreResizable` Boolean - Make TextArea elements resizable. Default
* `images` Boolean (optional) - Enables image support. Default is `true`.
* `textAreasAreResizable` Boolean (optional) - Make TextArea elements resizable. Default
is `true`.
* `webgl` Boolean - Enables WebGL support. Default is `true`.
* `webaudio` Boolean - Enables WebAudio support. Default is `true`.
* `plugins` Boolean - Whether plugins should be enabled. Default is `false`.
* `experimentalFeatures` Boolean - Enables Chromium's experimental features.
* `webgl` Boolean (optional) - Enables WebGL support. Default is `true`.
* `webaudio` Boolean (optional) - Enables WebAudio support. Default is `true`.
* `plugins` Boolean (optional) - Whether plugins should be enabled. Default is `false`.
* `experimentalFeatures` Boolean (optional) - Enables Chromium's experimental features.
Default is `false`.
* `experimentalCanvasFeatures` Boolean - Enables Chromium's experimental
* `experimentalCanvasFeatures` Boolean (optional) - Enables Chromium's experimental
canvas features. Default is `false`.
* `scrollBounce` Boolean - Enables scroll bounce (rubber banding) effect on
* `scrollBounce` Boolean (optional) - Enables scroll bounce (rubber banding) effect on
macOS. Default is `false`.
* `blinkFeatures` String - A list of feature strings separated by `,`, like
* `blinkFeatures` String (optional) - A list of feature strings separated by `,`, like
`CSSVariables,KeyboardEventKey` to enable. The full list of supported feature
strings can be found in the [RuntimeEnabledFeatures.in][blink-feature-string]
file.
* `disableBlinkFeatures` String - A list of feature strings separated by `,`,
* `disableBlinkFeatures` String (optional) - A list of feature strings separated by `,`,
like `CSSVariables,KeyboardEventKey` to disable. The full list of supported
feature strings can be found in the
[RuntimeEnabledFeatures.in][blink-feature-string] file.
* `defaultFontFamily` Object - Sets the default font for the font-family.
* `standard` String - Defaults to `Times New Roman`.
* `serif` String - Defaults to `Times New Roman`.
* `sansSerif` String - Defaults to `Arial`.
* `monospace` String - Defaults to `Courier New`.
* `defaultFontSize` Integer - Defaults to `16`.
* `defaultMonospaceFontSize` Integer - Defaults to `13`.
* `minimumFontSize` Integer - Defaults to `0`.
* `defaultEncoding` String - Defaults to `ISO-8859-1`.
* `backgroundThrottling` Boolean - Whether to throttle animations and timers
* `defaultFontFamily` Object (optional) - Sets the default font for the font-family.
* `standard` String (optional) - Defaults to `Times New Roman`.
* `serif` String (optional) - Defaults to `Times New Roman`.
* `sansSerif` String (optional) - Defaults to `Arial`.
* `monospace` String (optional) - Defaults to `Courier New`.
* `defaultFontSize` Integer (optional) - Defaults to `16`.
* `defaultMonospaceFontSize` Integer (optional) - Defaults to `13`.
* `minimumFontSize` Integer (optional) - Defaults to `0`.
* `defaultEncoding` String (optional) - Defaults to `ISO-8859-1`.
* `backgroundThrottling` Boolean (optional) - Whether to throttle animations and timers
when the page becomes background. Defaults to `true`.
* `offscreen` Boolean - Whether to enable offscreen rendering for the browser
* `offscreen` Boolean (optional) - Whether to enable offscreen rendering for the browser
window. Defaults to `false`.
* `sandbox` Boolean - Whether to enable Chromium OS-level sandbox.
* `sandbox` Boolean (optional) - Whether to enable Chromium OS-level sandbox.
When setting minimum or maximum window size with `minWidth`/`maxWidth`/
`minHeight`/`maxHeight`, it only constrains the users. It won't prevent you from
@ -948,7 +948,7 @@ bar will become gray when set to `true`.
#### `win.isDocumentEdited()` _macOS_
Whether `Boolean` - Whether the window's document has been edited.
Returns `Boolean` - Whether the window's document has been edited.
#### `win.focusOnWebView()`
@ -964,11 +964,11 @@ Same as `webContents.capturePage([rect, ]callback)`.
#### `win.loadURL(url[, options])`
* `url` URL
* `url` String
* `options` Object (optional)
* `httpReferrer` String - A HTTP Referrer url.
* `userAgent` String - A user agent originating the request.
* `extraHeaders` String - Extra headers separated by "\n"
* `httpReferrer` String (optional) - A HTTP Referrer url.
* `userAgent` String (optional) - A user agent originating the request.
* `extraHeaders` String (optional) - Extra headers separated by "\n"
Same as `webContents.loadURL(url[, options])`.
@ -1004,7 +1004,7 @@ menu bar.
* `progress` Double
* `options` Object (optional)
* `mode` String _Windows_ - Mode for the progress bar (`none`, `normal`, `indeterminate`, `error`, or `paused`)
* `mode` String _Windows_ - Mode for the progress bar. Can be `none`, `normal`, `indeterminate`, `error`, or `paused`.
Sets progress value in progress bar. Valid range is [0, 1.0].

10
docs/api/clipboard.md
View file

@ -155,11 +155,11 @@ Returns `String` - Reads `data` from the clipboard.
### `clipboard.write(data[, type])`
* `data` Object
* `text` String
* `html` String
* `image` [NativeImage](native-image.md)
* `rtf` String
* `bookmark` String - The title of the url at `text`.
* `text` String (optional)
* `html` String (optional)
* `image` [NativeImage](native-image.md) (optional)
* `rtf` String (optional)
* `bookmark` String (optional) - The title of the url at `text`.
* `type` String (optional)
```javascript

18
docs/api/crash-reporter.md
View file

@ -37,13 +37,13 @@ The `crash-reporter` module has the following methods:
### `crashReporter.start(options)`
* `options` Object
* `companyName` String
* `companyName` String (optional)
* `submitURL` String - URL that crash reports will be sent to as POST.
* `productName` String (optional) - Defaults to `app.getName()`.
* `autoSubmit` Boolean - Send the crash report without user interaction.
* `autoSubmit` Boolean (optional) - Send the crash report without user interaction.
Default is `true`.
* `ignoreSystemCrashHandler` Boolean - Default is `false`.
* `extra` Object - An object you can define that will be sent along with the
* `ignoreSystemCrashHandler` Boolean (optional) - Default is `false`.
* `extra` Object (optional) - An object you can define that will be sent along with the
report. Only string properties are sent correctly, Nested objects are not
supported.
@ -58,20 +58,14 @@ crash reports.
### `crashReporter.getLastCrashReport()`
Returns `Object`:
* `date` String
* `ID` Integer
Returns [`CrashReport`](structures/crash-report.md):
Returns the date and ID of the last crash report. If no crash reports have been
sent or the crash reporter has not been started, `null` is returned.
### `crashReporter.getUploadedReports()`
Returns `Object[]`:
* `date` String
* `ID` Integer
Returns [`CrashReport[]`](structures/crash-report.md):
Returns all uploaded crash reports. Each report contains the date and uploaded
ID.

47
docs/api/dialog.md
View file

@ -27,19 +27,19 @@ The `dialog` module has the following methods:
* `browserWindow` BrowserWindow (optional)
* `options` Object
* `title` String
* `defaultPath` String
* `buttonLabel` String - Custom label for the confirmation button, when
* `title` String (optional)
* `defaultPath` String (optional)
* `buttonLabel` String (optional) - Custom label for the confirmation button, when
left empty the default label will be used.
* `filters` String[]
* `properties` String[] - Contains which features the dialog should use, can
* `filters` [FileFilter[]](structrs/file-filter.md) (optional)
* `properties` String[] (optional) - Contains which features the dialog should use, can
contain `openFile`, `openDirectory`, `multiSelections`, `createDirectory`
and `showHiddenFiles`.
* `callback` Function (optional)
* `filePaths` String[] - An array of file paths chosen by the user
On success this method returns an array of file paths chosen by the user,
otherwise it returns `undefined`.
Returns `String[]`, an array of file paths chosen by the user,
if the callback is provided it returns `undefined`.
The `filters` specifies an array of file types that can be displayed or
selected when you want to limit the user to a specific type. For example:
@ -71,16 +71,16 @@ shown.
* `browserWindow` BrowserWindow (optional)
* `options` Object
* `title` String
* `defaultPath` String
* `buttonLabel` String - Custom label for the confirmation button, when
* `title` String (optional)
* `defaultPath` String (optional)
* `buttonLabel` String (optional) - Custom label for the confirmation button, when
left empty the default label will be used.
* `filters` String[]
* `filters` [FileFilter[]](structrs/file-filter.md) (optional)
* `callback` Function (optional)
* `filename` String
On success this method returns the path of the file chosen by the user,
otherwise it returns `undefined`.
Returns `String`, the path of the file chosen by the user,
if a callback is provided it returns `undefined`.
The `filters` specifies an array of file types that can be displayed, see
`dialog.showOpenDialog` for an example.
@ -92,30 +92,33 @@ will be passed via `callback(filename)`
* `browserWindow` BrowserWindow (optional)
* `options` Object
* `type` String - Can be `"none"`, `"info"`, `"error"`, `"question"` or
* `type` String (optional) - Can be `"none"`, `"info"`, `"error"`, `"question"` or
`"warning"`. On Windows, "question" displays the same icon as "info", unless
you set an icon using the "icon" option.
* `buttons` String[] - Array of texts for buttons. On Windows, an empty array
* `buttons` String[] (optional) - Array of texts for buttons. On Windows, an empty array
will result in one button labeled "OK".
* `defaultId` Integer - Index of the button in the buttons array which will
* `defaultId` Integer (optional) - Index of the button in the buttons array which will
be selected by default when the message box opens.
* `title` String - Title of the message box, some platforms will not show it.
* `title` String (optional) - 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
* `detail` String (optional) - Extra information of the message.
* `icon` [NativeImage](native-image.md) (optional)
* `cancelId` Integer (optional) - 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 macOS 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 will try to figure out which one of
* `noLink` Boolean (optional) - 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
the style of modern Windows apps. If you don't like this behavior, you can
set `noLink` to `true`.
* `callback` Function
* `callback` Function (optional)
* `response` Number - The index of the button that was clicked
Returns `Integer`, the index of the clicked button, if a callback is provided
it returns undefined.
Shows a message box, it will block the process until the message box is closed.
It returns the index of the clicked button.

49
docs/api/download-item.md
View file

@ -37,9 +37,11 @@ win.webContents.session.on('will-download', (event, item, webContents) => {
})
```
## Events
## Class: DownloadItem
### Event: 'updated'
### Instance Events
#### Event: 'updated'
Returns:
@ -53,7 +55,7 @@ The `state` can be one of following:
* `progressing` - The download is in-progress.
* `interrupted` - The download has interrupted and can be resumed.
### Event: 'done'
#### Event: 'done'
Returns:
@ -70,11 +72,11 @@ The `state` can be one of following:
* `cancelled` - The download has been cancelled.
* `interrupted` - The download has interrupted and can not resume.
## Methods
### Instance Methods
The `downloadItem` object has the following methods:
### `downloadItem.setSavePath(path)`
#### `downloadItem.setSavePath(path)`
* `path` String - Set the save file path of the download item.
@ -82,45 +84,45 @@ The API is only available in session's `will-download` callback function.
If user doesn't set the save path via the API, Electron will use the original
routine to determine the save path(Usually prompts a save dialog).
### `downloadItem.getSavePath()`
#### `downloadItem.getSavePath()`
Returns `String` - The save path of the download item. This will be either the path
set via `downloadItem.setSavePath(path)` or the path selected from the shown
save dialog.
### `downloadItem.pause()`
#### `downloadItem.pause()`
Pauses the download.
### `downloadItem.isPaused()`
#### `downloadItem.isPaused()`
Returns `Boolean` - Whether the download is paused.
### `downloadItem.resume()`
#### `downloadItem.resume()`
Resumes the download that has been paused.
### `downloadItem.canResume()`
#### `downloadItem.canResume()`
Resumes `Boolean` - Whether the download can resume.
### `downloadItem.cancel()`
#### `downloadItem.cancel()`
Cancels the download operation.
### `downloadItem.getURL()`
#### `downloadItem.getURL()`
Returns `String` - The origin url where the item is downloaded from.
### `downloadItem.getMimeType()`
#### `downloadItem.getMimeType()`
Returns `String` - The files mime type.
### `downloadItem.hasUserGesture()`
#### `downloadItem.hasUserGesture()`
Returns `Boolean` - Whether the download has user gesture.
### `downloadItem.getFilename()`
#### `downloadItem.getFilename()`
Returns `String` - The file name of the download item.
@ -128,28 +130,21 @@ Returns `String` - The file name of the download item.
disk. If user changes the file name in a prompted download saving dialog, the
actual name of saved file will be different.
### `downloadItem.getTotalBytes()`
#### `downloadItem.getTotalBytes()`
Returns `Integer` - The total size in bytes of the download item.
If the size is unknown, it returns 0.
### `downloadItem.getReceivedBytes()`
#### `downloadItem.getReceivedBytes()`
Returns `Integer` - The received bytes of the download item.
### `downloadItem.getContentDisposition()`
#### `downloadItem.getContentDisposition()`
Returns `String` - The Content-Disposition field from the response
header.
### `downloadItem.getState()`
#### `downloadItem.getState()`
Returns `String` - The current state.
Possible values are:
* `progressing` - The download is in-progress.
* `completed` - The download completed successfully.
* `cancelled` - The download has been cancelled.
* `interrupted` - The download has interrupted.
Returns `String` - The current state. Can be `progressing`, `completed`, `cancelled` or `interrupted`.

12
docs/api/ipc-renderer.md
View file

@ -14,7 +14,7 @@ See [ipcMain](ipc-main.md) for code examples.
## Methods
The `ipcRenderer` module has the following method to listen for events:
The `ipcRenderer` module has the following method to listen for events and send messages:
### `ipcRenderer.on(channel, listener)`
@ -46,14 +46,10 @@ Removes the specified `listener` from the listener array for the specified
Removes all listeners, or those of the specified `channel`.
## Sending Messages
The `ipcRenderer` module has the following methods for sending messages:
### `ipcRenderer.send(channel[, arg1][, arg2][, ...])`
* `channel` String
* `arg` (optional)
* `...args` any[]
Send a message to the main process asynchronously via `channel`, you can also
send arbitrary arguments. Arguments will be serialized in JSON internally and
@ -64,7 +60,7 @@ The main process handles it by listening for `channel` with `ipcMain` module.
### `ipcRenderer.sendSync(channel[, arg1][, arg2][, ...])`
* `channel` String
* `arg` (optional)
* `...args` any[]
Send a message to the main process synchronously via `channel`, you can also
send arbitrary arguments. Arguments will be serialized in JSON internally and
@ -79,7 +75,7 @@ unless you know what you are doing you should never use it.
### `ipcRenderer.sendToHost(channel[, arg1][, arg2][, ...])`
* `channel` String
* `arg` (optional)
* `...args` any[]
Like `ipcRenderer.send` but the event will be sent to the `<webview>` element in
the host page instead of the main process.

26
docs/api/menu-item.md
View file

@ -13,31 +13,31 @@ Create a new `MenuItem` with the following method:
### `new MenuItem(options)`
* `options` Object
* `click` Function - Will be called with
* `click` Function - (optional) Will be called with
`click(menuItem, browserWindow, event)` when the menu item is clicked.
* `menuItem` MenuItem
* `browserWindow` BrowserWindow
* `event` Event
* `role` String - Define the action of the menu item, when specified the
* `role` String - (optional) Define the action of the menu item, when specified the
`click` property will be ignored.
* `type` String - Can be `normal`, `separator`, `submenu`, `checkbox` or
* `type` String - (optional) Can be `normal`, `separator`, `submenu`, `checkbox` or
`radio`.
* `label` String
* `sublabel` String
* `accelerator` [Accelerator](accelerator.md)
* `icon` [NativeImage](native-image.md)
* `enabled` Boolean - If false, the menu item will be greyed out and
* `label` String - (optional)
* `sublabel` String - (optional)
* `accelerator` [Accelerator](accelerator.md) - (optional)
* `icon` ([NativeImage](native-image.md) | String) - (optional)
* `enabled` Boolean - (optional) If false, the menu item will be greyed out and
unclickable.
* `visible` Boolean - If false, the menu item will be entirely hidden.
* `checked` Boolean - Should only be specified for `checkbox` or `radio` type
* `visible` Boolean - (optional) If false, the menu item will be entirely hidden.
* `checked` Boolean - (optional) Should only be specified for `checkbox` or `radio` type
menu items.
* `submenu` Menu - Should be specified for `submenu` type menu items. If
* `submenu` MenuItemConstructorOptions[] - (optional) Should be specified for `submenu` type menu items. If
`submenu` is specified, the `type: 'submenu'` can be omitted. If the value
is not a `Menu` then it will be automatically converted to one using
`Menu.buildFromTemplate`.
* `id` String - Unique within a single menu. If defined then it can be used
* `id` String - (optional) Unique within a single menu. If defined then it can be used
as a reference to this item by the position attribute.
* `position` String - This field allows fine-grained definition of the
* `position` String - (optional) This field allows fine-grained definition of the
specific location within a given menu.
It is best to specify `role` for any menu item that matches a standard role,

6
docs/api/menu.md
View file

@ -238,7 +238,7 @@ will be set as each window's top menu.
#### `Menu.getApplicationMenu()`
Returns the application menu (an instance of `Menu`), if set, or `null`, if not set.
Returns `Menu` - The application menu, if set, or `null`, if not set.
#### `Menu.sendActionToFirstResponder(action)` _macOS_
@ -253,7 +253,9 @@ for more information on macOS' native actions.
#### `Menu.buildFromTemplate(template)`
* `template` MenuItem[]
* `template` MenuItemConstructorOptions[]
Returns `Menu`
Generally, the `template` is just an array of `options` for constructing a
[MenuItem](menu-item.md). The usage can be referenced above.

2
docs/api/remote.md
View file

@ -140,7 +140,7 @@ The `remote` module has the following methods:
* `module` String
Returns `Object` - The object returned by `require(module)` in the main process.
Returns `any` - The object returned by `require(module)` in the main process.
### `remote.getCurrentWindow()`

4
docs/api/structures/crash-report.md Normal file
View file

@ -0,0 +1,4 @@
# CrashReport Object
* `date` String
* `ID` Integer

4
docs/api/structures/file-filter.md Normal file
View file

@ -0,0 +1,4 @@
# FileFilter Object
* `name` String
* `extensions` String[]

4
docs/api/structures/jump-list-category.md
View file

@ -10,9 +10,9 @@
of the category and its items are set by Windows. Items may be added to
this category indirectly using `app.addRecentDocument(path)`.
* `custom` - Displays tasks or file links, `name` must be set by the app.
* `name` String - Must be set if `type` is `custom`, otherwise it should be
* `name` String - (optional) Must be set if `type` is `custom`, otherwise it should be
omitted.
* `items` JumpListItem[] - Array of [`JumpListItem`](jump-list-item.md) objects if `type` is `tasks` or
* `items` JumpListItem[] - (optional) Array of [`JumpListItem`](jump-list-item.md) objects if `type` is `tasks` or
`custom`, otherwise it should be omitted.
**Note:** If a `JumpListCategory` object has neither the `type` nor the `name`

10
docs/api/structures/jump-list-item.md
View file

@ -7,16 +7,16 @@
* `file` - A file link will open a file using the app that created the
Jump List, for this to work the app must be registered as a handler for
the file type (though it doesn't have to be the default handler).
* `path` String - Path of the file to open, should only be set if `type` is
* `path` String - (optional) Path of the file to open, should only be set if `type` is
`file`.
* `program` String - Path of the program to execute, usually you should
* `program` String - (optional) Path of the program to execute, usually you should
specify `process.execPath` which opens the current program. Should only be
set if `type` is `task`.
* `args` String - The command line arguments when `program` is executed. Should
* `args` String - (optional) The command line arguments when `program` is executed. Should
only be set if `type` is `task`.
* `title` String - The text to be displayed for the item in the Jump List.
* `title` String - (optional) The text to be displayed for the item in the Jump List.
Should only be set if `type` is `task`.
* `description` String - Description of the task (displayed in a tooltip).
* `description` String - (optional) Description of the task (displayed in a tooltip).
Should only be set if `type` is `task`.
* `iconPath` String - The absolute path to an icon to be displayed in a
Jump List, which can be an arbitrary resource file that contains an icon

2
docs/api/tray.md
View file

@ -57,7 +57,7 @@ rely on the `click` event and always attach a context menu to the tray icon.
### `new Tray(image)`
* `image` [NativeImage](native-image.md)
* `image` ([NativeImage](native-image.md) | String)
Creates a new tray icon associated with the `image`.

1
docs/api/web-contents.md
View file

@ -952,6 +952,7 @@ Opens the developer tools for the service worker context.
#### `contents.send(channel[, arg1][, arg2][, ...])`
* `channel` String
* `...args` any[]
Send an asynchronous message to renderer process via `channel`, you can also
send arbitrary arguments. Arguments will be serialized in JSON internally and

2
package.json
View file

@ -5,7 +5,7 @@
"asar": "^0.11.0",
"browserify": "^13.1.0",
"electabul": "~0.0.4",
"electron-docs-linter": "^1.13.2",
"electron-docs-linter": "^1.14.1",
"request": "*",
"standard": "^8.4.0",
"standard-markdown": "^2.1.1"