From 1a9b4b4671069c92ca50c5ebcfaf7e309a9d5e33 Mon Sep 17 00:00:00 2001 From: Samuel Attard Date: Sun, 30 Oct 2016 21:46:20 +1100 Subject: [PATCH 1/8] First few docs made optional --- docs/api/app.md | 69 +---------------- docs/api/auto-updater.md | 2 +- docs/api/browser-window.md | 152 ++++++++++++++++++------------------- docs/api/clipboard.md | 10 +-- docs/api/crash-reporter.md | 8 +- docs/api/dialog.md | 30 ++++---- 6 files changed, 105 insertions(+), 166 deletions(-) diff --git a/docs/api/app.md b/docs/api/app.md index 634f60cde0e0..52c3738fb8ec 100644 --- a/docs/api/app.md +++ b/docs/api/app.md @@ -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 diff --git a/docs/api/auto-updater.md b/docs/api/auto-updater.md index 9db876eb9c9a..89f7145e3795 100644 --- a/docs/api/auto-updater.md +++ b/docs/api/auto-updater.md @@ -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. diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md index 25c4823bb8bd..321482e0e9b2 100644 --- a/docs/api/browser-window.md +++ b/docs/api/browser-window.md @@ -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]. diff --git a/docs/api/clipboard.md b/docs/api/clipboard.md index f6e72b82c7ef..400f03f3b5a7 100644 --- a/docs/api/clipboard.md +++ b/docs/api/clipboard.md @@ -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 diff --git a/docs/api/crash-reporter.md b/docs/api/crash-reporter.md index b23f8b070b72..32d27b8d8aed 100644 --- a/docs/api/crash-reporter.md +++ b/docs/api/crash-reporter.md @@ -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. diff --git a/docs/api/dialog.md b/docs/api/dialog.md index 5094c714c38c..24b3f7390216 100644 --- a/docs/api/dialog.md +++ b/docs/api/dialog.md @@ -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 From 63ebc417788d529c5975b62b26b43e7585d65ce8 Mon Sep 17 00:00:00 2001 From: Samuel Attard Date: Sat, 5 Nov 2016 19:42:45 +1100 Subject: [PATCH 2/8] More docs updates --- docs/api/browser-window.md | 6 +++--- docs/api/dialog.md | 21 ++++++++++-------- docs/api/ipc-renderer.md | 12 ++++------- docs/api/menu-item.md | 26 +++++++++++------------ docs/api/structures/file-filter.md | 4 ++++ docs/api/structures/jump-list-category.md | 4 ++-- docs/api/structures/jump-list-item.md | 10 ++++----- docs/api/web-contents.md | 1 + 8 files changed, 44 insertions(+), 40 deletions(-) create mode 100644 docs/api/structures/file-filter.md diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md index 321482e0e9b2..d49ae9e1a0a4 100644 --- a/docs/api/browser-window.md +++ b/docs/api/browser-window.md @@ -157,7 +157,7 @@ It creates a new `BrowserWindow` with native properties as set by the `options`. `false`. * `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 + * `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 (optional) - Whether window should be shown when created. Default is @@ -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,7 +964,7 @@ Same as `webContents.capturePage([rect, ]callback)`. #### `win.loadURL(url[, options])` -* `url` URL +* `url` String * `options` Object (optional) * `httpReferrer` String (optional) - A HTTP Referrer url. * `userAgent` String (optional) - A user agent originating the request. diff --git a/docs/api/dialog.md b/docs/api/dialog.md index 24b3f7390216..bfe838082627 100644 --- a/docs/api/dialog.md +++ b/docs/api/dialog.md @@ -27,19 +27,19 @@ The `dialog` module has the following methods: * `browserWindow` BrowserWindow (optional) * `options` Object - * `title` String + * `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[] (optional) + * `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 + * `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[] (optional) + * `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. @@ -113,9 +113,12 @@ will be passed via `callback(filename)` 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. diff --git a/docs/api/ipc-renderer.md b/docs/api/ipc-renderer.md index b40baf856d5a..db150d489c65 100644 --- a/docs/api/ipc-renderer.md +++ b/docs/api/ipc-renderer.md @@ -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 `` element in the host page instead of the main process. diff --git a/docs/api/menu-item.md b/docs/api/menu-item.md index 812a50f30167..c92df1760df0 100644 --- a/docs/api/menu-item.md +++ b/docs/api/menu-item.md @@ -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` Menu - (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, diff --git a/docs/api/structures/file-filter.md b/docs/api/structures/file-filter.md new file mode 100644 index 000000000000..014350a60f86 --- /dev/null +++ b/docs/api/structures/file-filter.md @@ -0,0 +1,4 @@ +# FileFilter Object + +* `name` String +* `extensions` String[] diff --git a/docs/api/structures/jump-list-category.md b/docs/api/structures/jump-list-category.md index 71bf0e49b5f3..6ff328eea650 100644 --- a/docs/api/structures/jump-list-category.md +++ b/docs/api/structures/jump-list-category.md @@ -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` diff --git a/docs/api/structures/jump-list-item.md b/docs/api/structures/jump-list-item.md index a58293a4ca94..0eb6f56d8f06 100644 --- a/docs/api/structures/jump-list-item.md +++ b/docs/api/structures/jump-list-item.md @@ -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 diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index 55db42e4928d..249188eac8bd 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -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 From 11f8923c4341f6da81122dbf628dadc42a2e80fa Mon Sep 17 00:00:00 2001 From: Samuel Attard Date: Mon, 7 Nov 2016 17:43:55 +1100 Subject: [PATCH 3/8] Fix tray and menu docs --- docs/api/menu-item.md | 2 +- docs/api/menu.md | 6 ++++-- docs/api/tray.md | 2 +- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/api/menu-item.md b/docs/api/menu-item.md index c92df1760df0..90d57478b151 100644 --- a/docs/api/menu-item.md +++ b/docs/api/menu-item.md @@ -31,7 +31,7 @@ Create a new `MenuItem` with the following method: * `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 - (optional) 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`. diff --git a/docs/api/menu.md b/docs/api/menu.md index d5446f46cecd..3d9861876ea8 100644 --- a/docs/api/menu.md +++ b/docs/api/menu.md @@ -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 (an instance of `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. diff --git a/docs/api/tray.md b/docs/api/tray.md index 6353c470df8c..660d703c4abe 100644 --- a/docs/api/tray.md +++ b/docs/api/tray.md @@ -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`. From c1af62a3b3c9131636deae0443b74ff15678a92b Mon Sep 17 00:00:00 2001 From: Samuel Attard Date: Tue, 8 Nov 2016 15:54:34 +1100 Subject: [PATCH 4/8] Move crash-report object to it's own struct --- docs/api/crash-reporter.md | 10 ++-------- docs/api/structures/crash-report.md | 4 ++++ 2 files changed, 6 insertions(+), 8 deletions(-) create mode 100644 docs/api/structures/crash-report.md diff --git a/docs/api/crash-reporter.md b/docs/api/crash-reporter.md index 32d27b8d8aed..171a0997f141 100644 --- a/docs/api/crash-reporter.md +++ b/docs/api/crash-reporter.md @@ -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. diff --git a/docs/api/structures/crash-report.md b/docs/api/structures/crash-report.md new file mode 100644 index 000000000000..b26d4adeca70 --- /dev/null +++ b/docs/api/structures/crash-report.md @@ -0,0 +1,4 @@ +# CrashReport Object + +* `date` String +* `ID` Integer \ No newline at end of file From aeefee7348cfcee3631a59df699eef87460eeffd Mon Sep 17 00:00:00 2001 From: Samuel Attard Date: Tue, 8 Nov 2016 16:31:36 +1100 Subject: [PATCH 5/8] Fix the download-item doc so it correctly resembles a class --- docs/api/download-item.md | 49 ++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 27 deletions(-) diff --git a/docs/api/download-item.md b/docs/api/download-item.md index 08939c344532..4887966e6c5d 100644 --- a/docs/api/download-item.md +++ b/docs/api/download-item.md @@ -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`. From 494afec01d207a97514001f06d5fcdbb721be8c9 Mon Sep 17 00:00:00 2001 From: Samuel Attard Date: Tue, 8 Nov 2016 16:32:40 +1100 Subject: [PATCH 6/8] remote require could resolve to strings/numbers not just objects --- docs/api/remote.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/remote.md b/docs/api/remote.md index bff7f8ab77eb..c82337f34e16 100644 --- a/docs/api/remote.md +++ b/docs/api/remote.md @@ -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()` From 174e51507dd183d66dff57bcc8575c59de86c534 Mon Sep 17 00:00:00 2001 From: Samuel Attard Date: Fri, 11 Nov 2016 16:37:19 +1100 Subject: [PATCH 7/8] Update menu.md --- docs/api/menu.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/menu.md b/docs/api/menu.md index 3d9861876ea8..37085fcd3990 100644 --- a/docs/api/menu.md +++ b/docs/api/menu.md @@ -238,7 +238,7 @@ will be set as each window's top menu. #### `Menu.getApplicationMenu()` -Returns `Menu` 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_ From 50be8b65d1fa267869624d046e4cf34faeb421a8 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Fri, 11 Nov 2016 09:20:57 -0800 Subject: [PATCH 8/8] update docs linter --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index e4527d2df8ed..379227c4b8aa 100644 --- a/package.json +++ b/package.json @@ -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"