First few docs made optional

This commit is contained in:
Samuel Attard 2016-10-30 21:46:20 +11:00 committed by Zeke Sikelianos
parent 8a29604f1e
commit 1a9b4b4671
6 changed files with 105 additions and 166 deletions

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

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.

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) (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
@ -966,9 +966,9 @@ Same as `webContents.capturePage([rect, ]callback)`.
* `url` URL
* `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].

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

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.

View file

@ -28,11 +28,11 @@ 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
* `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` String[] (optional)
* `properties` String[] (optional) - Contains which features the dialog should use, can
contain `openFile`, `openDirectory`, `multiSelections`, `createDirectory`
and `showHiddenFiles`.
* `callback` Function (optional)
@ -72,10 +72,10 @@ shown.
* `browserWindow` BrowserWindow (optional)
* `options` Object
* `title` String
* `defaultPath` String
* `buttonLabel` String - Custom label for the confirmation button, when
* `defaultPath` String (optional)
* `buttonLabel` String (optional) - Custom label for the confirmation button, when
left empty the default label will be used.
* `filters` String[]
* `filters` String[] (optional)
* `callback` Function (optional)
* `filename` String
@ -92,23 +92,23 @@ 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