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

Merge pull request #6467 from electron/enforce-new-docs-styleguide

Browse source 
Update documentation guidelines for Classes
This commit is contained in:
Cheng Zhao 2016-07-13 16:41:13 +09:00 • committed by GitHub
commit 1faa567d09
4 changed files with 194 additions and 188 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -181,12 +181,12 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
this below. this below.
When setting minimum or maximum window size with `minWidth`/`maxWidth`/ When setting minimum or maximum window size with `minWidth`/`maxWidth`/
`minHeight`/`maxHeight`, it only constrains the users, it won't prevent you from `minHeight`/`maxHeight`, it only constrains the users. It won't prevent you from
passing a size that does not follow size constraints to `setBounds`/`setSize` or passing a size that does not follow size constraints to `setBounds`/`setSize` or
to the constructor of `BrowserWindow`. to the constructor of `BrowserWindow`.
The possible values and behaviors of `type` option are platform dependent, The possible values and behaviors of the `type` option are platform dependent.
supported values are: Possible values are:
* On Linux, possible types are `desktop`, `dock`, `toolbar`, `splash`, * On Linux, possible types are `desktop`, `dock`, `toolbar`, `splash`,
`notification`. `notification`.
@ -210,7 +210,7 @@ Possible values are:
* `hidden-inset` results in a hidden title bar with an alternative look * `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. where the traffic light buttons are slightly more inset from the window edge.
The `webPreferences` option is an object that can have following properties: The `webPreferences` option is an object that can have the following properties:
* `nodeIntegration` Boolean - Whether node integration is enabled. Default * `nodeIntegration` Boolean - Whether node integration is enabled. Default
is `true`. is `true`.
@ -224,24 +224,24 @@ The `webPreferences` option is an object that can have following properties:
* `session` [Session](session.md#class-session) - Sets the session used by the * `session` [Session](session.md#class-session) - Sets the session used by the
page. Instead of passing the Session object directly, you can also choose to page. Instead of passing the Session object directly, you can also choose to
use the `partition` option instead, which accepts a partition string. When use the `partition` option instead, which accepts a partition string. When
both `session` and `partition` are provided, `session` would be preferred. both `session` and `partition` are provided, `session` will be preferred.
Default is the default session. Default is the default session.
* `partition` String - Sets the session used by the page according to the * `partition` String - Sets the session used by the page according to the
session's partition string. If `partition` starts with `persist:`, the page 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 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 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 in-memory session. By assigning the same `partition`, multiple pages can share
the same session. Default is the default session. the same session. Default is the default session.
* `zoomFactor` Number - The default zoom factor of the page, `3.0` represents * `zoomFactor` Number - The default zoom factor of the page, `3.0` represents
`300%`. Default is `1.0`. `300%`. Default is `1.0`.
* `javascript` Boolean - Enables JavaScript support. Default is `true`. * `javascript` Boolean - Enables JavaScript support. Default is `true`.
* `webSecurity` Boolean - When setting `false`, it will disable the * `webSecurity` Boolean - When `false`, it will disable the
same-origin policy (Usually using testing websites by people), and set same-origin policy (usually using testing websites by people), and set
`allowDisplayingInsecureContent` and `allowRunningInsecureContent` to `allowDisplayingInsecureContent` and `allowRunningInsecureContent` to
`true` if these two options are not set by user. Default is `true`. `true` if these two options are not set by user. Default is `true`.
* `allowDisplayingInsecureContent` Boolean - Allow an https page to display * `allowDisplayingInsecureContent` Boolean - Allow an https page to display
content like images from http URLs. Default is `false`. content like images from http URLs. Default is `false`.
* `allowRunningInsecureContent` Boolean - Allow a https page to run * `allowRunningInsecureContent` Boolean - Allow an https page to run
JavaScript, CSS or plugins from http URLs. Default is `false`. JavaScript, CSS or plugins from http URLs. Default is `false`.
* `images` Boolean - Enables image support. Default is `true`. * `images` Boolean - Enables image support. Default is `true`.
* `textAreasAreResizable` Boolean - Make TextArea elements resizable. Default * `textAreasAreResizable` Boolean - Make TextArea elements resizable. Default
@ -277,23 +277,23 @@ The `webPreferences` option is an object that can have following properties:
* `backgroundThrottling` Boolean - Whether to throttle animations and timers * `backgroundThrottling` Boolean - Whether to throttle animations and timers
when the page becomes background. Defaults to `true`. when the page becomes background. Defaults to `true`.
## Events ### Instance Events
The `BrowserWindow` object emits the following events: Objects created with `new BrowserWindow` emit the following events:
**Note:** Some events are only available on specific operating systems and are **Note:** Some events are only available on specific operating systems and are
labeled as such. labeled as such.
### Event: 'page-title-updated' #### Event: 'page-title-updated'
Returns: Returns:
* `event` Event * `event` Event
Emitted when the document changed its title, calling `event.preventDefault()` Emitted when the document changed its title, calling `event.preventDefault()`
would prevent the native window's title to change. will prevent the native window's title from changing.
### Event: 'close' #### Event: 'close'
Returns: Returns:
@ -320,87 +320,87 @@ window.onbeforeunload = (e) => {
}; };
``` ```
### Event: 'closed' #### Event: 'closed'
Emitted when the window is closed. After you have received this event you should Emitted when the window is closed. After you have received this event you should
remove the reference to the window and avoid using it anymore. remove the reference to the window and avoid using it any more.
### Event: 'unresponsive' #### Event: 'unresponsive'
Emitted when the web page becomes unresponsive. Emitted when the web page becomes unresponsive.
### Event: 'responsive' #### Event: 'responsive'
Emitted when the unresponsive web page becomes responsive again. Emitted when the unresponsive web page becomes responsive again.
### Event: 'blur' #### Event: 'blur'
Emitted when the window loses focus. Emitted when the window loses focus.
### Event: 'focus' #### Event: 'focus'
Emitted when the window gains focus. Emitted when the window gains focus.
### Event: 'show' #### Event: 'show'
Emitted when the window is shown. Emitted when the window is shown.
### Event: 'hide' #### Event: 'hide'
Emitted when the window is hidden. Emitted when the window is hidden.
### Event: 'ready-to-show' #### Event: 'ready-to-show'
Emitted when the web page has been rendered and window can be displayed without Emitted when the web page has been rendered and window can be displayed without
visual flash. a visual flash.
### Event: 'maximize' #### Event: 'maximize'
Emitted when window is maximized. Emitted when window is maximized.
### Event: 'unmaximize' #### Event: 'unmaximize'
Emitted when the window exits from maximized state. Emitted when the window exits from a maximized state.
### Event: 'minimize' #### Event: 'minimize'
Emitted when the window is minimized. Emitted when the window is minimized.
### Event: 'restore' #### Event: 'restore'
Emitted when the window is restored from minimized state. Emitted when the window is restored from a minimized state.
### Event: 'resize' #### Event: 'resize'
Emitted when the window is getting resized. Emitted when the window is being resized.
### Event: 'move' #### Event: 'move'
Emitted when the window is getting moved to a new position. Emitted when the window is being moved to a new position.
__Note__: On macOS this event is just an alias of `moved`. __Note__: On macOS this event is just an alias of `moved`.
### Event: 'moved' _macOS_ #### Event: 'moved' _macOS_
Emitted once when the window is moved to a new position. Emitted once when the window is moved to a new position.
### Event: 'enter-full-screen' #### Event: 'enter-full-screen'
Emitted when the window enters full screen state. Emitted when the window enters a full-screen state.
### Event: 'leave-full-screen' #### Event: 'leave-full-screen'
Emitted when the window leaves full screen state. Emitted when the window leaves a full-screen state.
### Event: 'enter-html-full-screen' #### Event: 'enter-html-full-screen'
Emitted when the window enters full screen state triggered by html api. Emitted when the window enters a full-screen state triggered by HTML API.
### Event: 'leave-html-full-screen' #### Event: 'leave-html-full-screen'
Emitted when the window leaves full screen state triggered by html api. Emitted when the window leaves a full-screen state triggered by HTML API.
### Event: 'app-command' _Windows_ #### Event: 'app-command' _Windows_
Returns: Returns:
@ -411,8 +411,8 @@ Emitted when an [App Command](https://msdn.microsoft.com/en-us/library/windows/d
is invoked. These are typically related to keyboard media keys or browser is invoked. These are typically related to keyboard media keys or browser
commands, as well as the "Back" button built into some mice on Windows. commands, as well as the "Back" button built into some mice on Windows.
Commands are lowercased with underscores replaced with hyphens and the Commands are lowercased, underscores are replaced with hyphens, and the
`APPCOMMAND_` prefix stripped off. `APPCOMMAND_` prefix is stripped off.
e.g. `APPCOMMAND_BROWSER_BACKWARD` is emitted as `browser-backward`. e.g. `APPCOMMAND_BROWSER_BACKWARD` is emitted as `browser-backward`.
```javascript ```javascript
@ -424,15 +424,15 @@ someWindow.on('app-command', (e, cmd) => {
}); });
``` ```
### Event: 'scroll-touch-begin' _macOS_ #### Event: 'scroll-touch-begin' _macOS_
Emitted when scroll wheel event phase has begun. Emitted when scroll wheel event phase has begun.
### Event: 'scroll-touch-end' _macOS_ #### Event: 'scroll-touch-end' _macOS_
Emitted when scroll wheel event phase has ended. Emitted when scroll wheel event phase has ended.
### Event: 'swipe' _macOS_ #### Event: 'swipe' _macOS_
Returns: Returns:
@ -441,31 +441,31 @@ Returns:
Emitted on 3-finger swipe. Possible directions are `up`, `right`, `down`, `left`. Emitted on 3-finger swipe. Possible directions are `up`, `right`, `down`, `left`.
## Methods ### Static Methods
The `BrowserWindow` object has the following methods: The `BrowserWindow` class has the following static methods:
### `BrowserWindow.getAllWindows()` #### `BrowserWindow.getAllWindows()`
Returns an array of all opened browser windows. Returns an array of all opened browser windows.
### `BrowserWindow.getFocusedWindow()` #### `BrowserWindow.getFocusedWindow()`
Returns the window that is focused in this application, otherwise returns `null`. Returns the window that is focused in this application, otherwise returns `null`.
### `BrowserWindow.fromWebContents(webContents)` #### `BrowserWindow.fromWebContents(webContents)`
* `webContents` [WebContents](web-contents.md) * `webContents` [WebContents](web-contents.md)
Find a window according to the `webContents` it owns. Find a window according to the `webContents` it owns.
### `BrowserWindow.fromId(id)` #### `BrowserWindow.fromId(id)`
* `id` Integer * `id` Integer
Find a window according to its ID. Find a window according to its ID.
### `BrowserWindow.addDevToolsExtension(path)` #### `BrowserWindow.addDevToolsExtension(path)`
* `path` String * `path` String
@ -476,21 +476,21 @@ API is not for programming use. If you try to add an extension that has already
been loaded, this method will not return and instead log a warning to the been loaded, this method will not return and instead log a warning to the
console. console.
Method will also not return if the extension's manifest is missing or incomplete. The method will also not return if the extension's manifest is missing or incomplete.
**Note:** This API cannot be called before the `ready` event of the `app` module **Note:** This API cannot be called before the `ready` event of the `app` module
is emitted. is emitted.
### `BrowserWindow.removeDevToolsExtension(name)` #### `BrowserWindow.removeDevToolsExtension(name)`
* `name` String * `name` String
Remove the DevTools extension whose name is `name`. Remove a DevTools extension by name.
**Note:** This API cannot be called before the `ready` event of the `app` module **Note:** This API cannot be called before the `ready` event of the `app` module
is emitted. is emitted.
### `BrowserWindow.getDevToolsExtensions()` #### `BrowserWindow.getDevToolsExtensions()`
Returns an Object where the keys are the extension names and each value is Returns an Object where the keys are the extension names and each value is
an Object containing `name` and `version` properties. an Object containing `name` and `version` properties.
@ -504,7 +504,7 @@ let installed = BrowserWindow.getDevToolsExtensions().hasOwnProperty('devtron')
**Note:** This API cannot be called before the `ready` event of the `app` module **Note:** This API cannot be called before the `ready` event of the `app` module
is emitted. is emitted.
## Instance Properties ### Instance Properties
Objects created with `new BrowserWindow` have the following properties: Objects created with `new BrowserWindow` have the following properties:
@ -513,114 +513,114 @@ Objects created with `new BrowserWindow` have the following properties:
let win = new BrowserWindow({width: 800, height: 600}); let win = new BrowserWindow({width: 800, height: 600});
``` ```
### `win.webContents` #### `win.webContents`
The `WebContents` object this window owns, all web page related events and The `WebContents` object this window owns. All web page related events and
operations will be done via it. operations will be done via it.
See the [`webContents` documentation](web-contents.md) for its methods and See the [`webContents` documentation](web-contents.md) for its methods and
events. events.
### `win.id` #### `win.id`
The unique ID of this window. The unique ID of the window.
## Instance Methods ### Instance Methods
Objects created with `new BrowserWindow` have the following instance methods: Objects created with `new BrowserWindow` have the following instance methods:
**Note:** Some methods are only available on specific operating systems and are **Note:** Some methods are only available on specific operating systems and are
labeled as such. labeled as such.
### `win.destroy()` #### `win.destroy()`
Force closing the window, the `unload` and `beforeunload` event won't be emitted Force closing the window, the `unload` and `beforeunload` event won't be emitted
for the web page, and `close` event will also not be emitted for the web page, and `close` event will also not be emitted
for this window, but it guarantees the `closed` event will be emitted. for this window, but it guarantees the `closed` event will be emitted.
### `win.close()` #### `win.close()`
Try to close the window, this has the same effect with user manually clicking Try to close the window. This has the same effect as a user manually clicking
the close button of the window. The web page may cancel the close though, see the close button of the window. The web page may cancel the close though. See
the [close event](#event-close). the [close event](#event-close).
### `win.focus()` #### `win.focus()`
Focuses on the window. Focuses on the window.
### `win.blur()` #### `win.blur()`
Removes focus from the window. Removes focus from the window.
### `win.isFocused()` #### `win.isFocused()`
Returns a boolean, whether the window is focused. Returns a boolean, whether the window is focused.
### `win.show()` #### `win.show()`
Shows and gives focus to the window. Shows and gives focus to the window.
### `win.showInactive()` #### `win.showInactive()`
Shows the window but doesn't focus on it. Shows the window but doesn't focus on it.
### `win.hide()` #### `win.hide()`
Hides the window. Hides the window.
### `win.isVisible()` #### `win.isVisible()`
Returns a boolean, whether the window is visible to the user. Returns a boolean, whether the window is visible to the user.
### `win.isModal()` #### `win.isModal()`
Returns whether current window is a modal window. Returns a boolean, whether current window is a modal window.
### `win.maximize()` #### `win.maximize()`
Maximizes the window. Maximizes the window.
### `win.unmaximize()` #### `win.unmaximize()`
Unmaximizes the window. Unmaximizes the window.
### `win.isMaximized()` #### `win.isMaximized()`
Returns a boolean, whether the window is maximized. Returns a boolean, whether the window is maximized.
### `win.minimize()` #### `win.minimize()`
Minimizes the window. On some platforms the minimized window will be shown in Minimizes the window. On some platforms the minimized window will be shown in
the Dock. the Dock.
### `win.restore()` #### `win.restore()`
Restores the window from minimized state to its previous state. Restores the window from minimized state to its previous state.
### `win.isMinimized()` #### `win.isMinimized()`
Returns a boolean, whether the window is minimized. Returns a boolean, whether the window is minimized.
### `win.setFullScreen(flag)` #### `win.setFullScreen(flag)`
* `flag` Boolean * `flag` Boolean
Sets whether the window should be in fullscreen mode. Sets whether the window should be in fullscreen mode.
### `win.isFullScreen()` #### `win.isFullScreen()`
Returns a boolean, whether the window is in fullscreen mode. Returns a boolean, whether the window is in fullscreen mode.
### `win.setAspectRatio(aspectRatio[, extraSize])` _macOS_ #### `win.setAspectRatio(aspectRatio[, extraSize])` _macOS_
* `aspectRatio` The aspect ratio we want to maintain for some portion of the * `aspectRatio` The aspect ratio to maintain for some portion of the
content view. content view.
* `extraSize` Object (optional) - The extra size not to be included while * `extraSize` Object (optional) - The extra size not to be included while
maintaining the aspect ratio. maintaining the aspect ratio.
* `width` Integer * `width` Integer
* `height` Integer * `height` Integer
This will have a window maintain an aspect ratio. The extra size allows a This will make a window maintain an aspect ratio. The extra size allows a
developer to have space, specified in pixels, not included within the aspect developer to have space, specified in pixels, not included within the aspect
ratio calculations. This API already takes into account the difference between a ratio calculations. This API already takes into account the difference between a
window's size and its content size. window's size and its content size.
@ -634,7 +634,7 @@ the player itself we would call this function with arguments of 16/9 and
are within the content view--only that they exist. Just sum any extra width and are within the content view--only that they exist. Just sum any extra width and
height areas you have within the overall content view. height areas you have within the overall content view.
### `win.setBounds(options[, animate])` #### `win.setBounds(options[, animate])`
* `options` Object * `options` Object
* `x` Integer * `x` Integer
@ -645,11 +645,11 @@ height areas you have within the overall content view.
Resizes and moves the window to `width`, `height`, `x`, `y`. Resizes and moves the window to `width`, `height`, `x`, `y`.
### `win.getBounds()` #### `win.getBounds()`
Returns an object that contains window's width, height, x and y values. Returns an object that contains window's width, height, x and y values.
### `win.setSize(width, height[, animate])` #### `win.setSize(width, height[, animate])`
* `width` Integer * `width` Integer
* `height` Integer * `height` Integer
@ -657,11 +657,11 @@ Returns an object that contains window's width, height, x and y values.
Resizes the window to `width` and `height`. Resizes the window to `width` and `height`.
### `win.getSize()` #### `win.getSize()`
Returns an array that contains window's width and height. Returns an array that contains window's width and height.
### `win.setContentSize(width, height[, animate])` #### `win.setContentSize(width, height[, animate])`
* `width` Integer * `width` Integer
* `height` Integer * `height` Integer
@ -669,101 +669,101 @@ Returns an array that contains window's width and height.
Resizes the window's client area (e.g. the web page) to `width` and `height`. Resizes the window's client area (e.g. the web page) to `width` and `height`.
### `win.getContentSize()` #### `win.getContentSize()`
Returns an array that contains window's client area's width and height. Returns an array that contains window's client area's width and height.
### `win.setMinimumSize(width, height)` #### `win.setMinimumSize(width, height)`
* `width` Integer * `width` Integer
* `height` Integer * `height` Integer
Sets the minimum size of window to `width` and `height`. Sets the minimum size of window to `width` and `height`.
### `win.getMinimumSize()` #### `win.getMinimumSize()`
Returns an array that contains window's minimum width and height. Returns an array that contains window's minimum width and height.
### `win.setMaximumSize(width, height)` #### `win.setMaximumSize(width, height)`
* `width` Integer * `width` Integer
* `height` Integer * `height` Integer
Sets the maximum size of window to `width` and `height`. Sets the maximum size of window to `width` and `height`.
### `win.getMaximumSize()` #### `win.getMaximumSize()`
Returns an array that contains window's maximum width and height. Returns an array that contains window's maximum width and height.
### `win.setResizable(resizable)` #### `win.setResizable(resizable)`
* `resizable` Boolean * `resizable` Boolean
Sets whether the window can be manually resized by user. Sets whether the window can be manually resized by user.
### `win.isResizable()` #### `win.isResizable()`
Returns whether the window can be manually resized by user. Returns whether the window can be manually resized by user.
### `win.setMovable(movable)` _macOS_ _Windows_ #### `win.setMovable(movable)` _macOS_ _Windows_
* `movable` Boolean * `movable` Boolean
Sets whether the window can be moved by user. On Linux does nothing. Sets whether the window can be moved by user. On Linux does nothing.
### `win.isMovable()` _macOS_ _Windows_ #### `win.isMovable()` _macOS_ _Windows_
Returns whether the window can be moved by user. On Linux always returns Returns whether the window can be moved by user. On Linux always returns
`true`. `true`.
### `win.setMinimizable(minimizable)` _macOS_ _Windows_ #### `win.setMinimizable(minimizable)` _macOS_ _Windows_
* `minimizable` Boolean * `minimizable` Boolean
Sets whether the window can be manually minimized by user. On Linux does Sets whether the window can be manually minimized by user. On Linux does
nothing. nothing.
### `win.isMinimizable()` _macOS_ _Windows_ #### `win.isMinimizable()` _macOS_ _Windows_
Returns whether the window can be manually minimized by user. On Linux always Returns whether the window can be manually minimized by user. On Linux always
returns `true`. returns `true`.
### `win.setMaximizable(maximizable)` _macOS_ _Windows_ #### `win.setMaximizable(maximizable)` _macOS_ _Windows_
* `maximizable` Boolean * `maximizable` Boolean
Sets whether the window can be manually maximized by user. On Linux does Sets whether the window can be manually maximized by user. On Linux does
nothing. nothing.
### `win.isMaximizable()` _macOS_ _Windows_ #### `win.isMaximizable()` _macOS_ _Windows_
Returns whether the window can be manually maximized by user. On Linux always Returns whether the window can be manually maximized by user. On Linux always
returns `true`. returns `true`.
### `win.setFullScreenable(fullscreenable)` #### `win.setFullScreenable(fullscreenable)`
* `fullscreenable` Boolean * `fullscreenable` Boolean
Sets whether the maximize/zoom window button toggles fullscreen mode or Sets whether the maximize/zoom window button toggles fullscreen mode or
maximizes the window. maximizes the window.
### `win.isFullScreenable()` #### `win.isFullScreenable()`
Returns whether the maximize/zoom window button toggles fullscreen mode or Returns whether the maximize/zoom window button toggles fullscreen mode or
maximizes the window. maximizes the window.
### `win.setClosable(closable)` _macOS_ _Windows_ #### `win.setClosable(closable)` _macOS_ _Windows_
* `closable` Boolean * `closable` Boolean
Sets whether the window can be manually closed by user. On Linux does nothing. Sets whether the window can be manually closed by user. On Linux does nothing.
### `win.isClosable()` _macOS_ _Windows_ #### `win.isClosable()` _macOS_ _Windows_
Returns whether the window can be manually closed by user. On Linux always Returns whether the window can be manually closed by user. On Linux always
returns `true`. returns `true`.
### `win.setAlwaysOnTop(flag)` #### `win.setAlwaysOnTop(flag)`
* `flag` Boolean * `flag` Boolean
@ -771,15 +771,15 @@ Sets whether the window should show always on top of other windows. After
setting this, the window is still a normal window, not a toolbox window which setting this, the window is still a normal window, not a toolbox window which
can not be focused on. can not be focused on.
### `win.isAlwaysOnTop()` #### `win.isAlwaysOnTop()`
Returns whether the window is always on top of other windows. Returns whether the window is always on top of other windows.
### `win.center()` #### `win.center()`
Moves window to the center of the screen. Moves window to the center of the screen.
### `win.setPosition(x, y[, animate])` #### `win.setPosition(x, y[, animate])`
* `x` Integer * `x` Integer
* `y` Integer * `y` Integer
@ -787,24 +787,24 @@ Moves window to the center of the screen.
Moves window to `x` and `y`. Moves window to `x` and `y`.
### `win.getPosition()` #### `win.getPosition()`
Returns an array that contains window's current position. Returns an array that contains window's current position.
### `win.setTitle(title)` #### `win.setTitle(title)`
* `title` String * `title` String
Changes the title of native window to `title`. Changes the title of native window to `title`.
### `win.getTitle()` #### `win.getTitle()`
Returns the title of the native window. Returns the title of the native window.
**Note:** The title of web page can be different from the title of the native **Note:** The title of web page can be different from the title of the native
window. window.
### `win.setSheetOffset(offsetY[, offsetX])` _macOS_ #### `win.setSheetOffset(offsetY[, offsetX])` _macOS_
Changes the attachment point for sheets on macOS. By default, sheets are Changes the attachment point for sheets on macOS. By default, sheets are
attached just below the window frame, but you may want to display them beneath attached just below the window frame, but you may want to display them beneath
@ -815,36 +815,36 @@ let toolbarRect = document.getElementById('toolbar').getBoundingClientRect();
win.setSheetOffset(toolbarRect.height); win.setSheetOffset(toolbarRect.height);
``` ```
### `win.flashFrame(flag)` #### `win.flashFrame(flag)`
* `flag` Boolean * `flag` Boolean
Starts or stops flashing the window to attract user's attention. Starts or stops flashing the window to attract user's attention.
### `win.setSkipTaskbar(skip)` #### `win.setSkipTaskbar(skip)`
* `skip` Boolean * `skip` Boolean
Makes the window not show in the taskbar. Makes the window not show in the taskbar.
### `win.setKiosk(flag)` #### `win.setKiosk(flag)`
* `flag` Boolean * `flag` Boolean
Enters or leaves the kiosk mode. Enters or leaves the kiosk mode.
### `win.isKiosk()` #### `win.isKiosk()`
Returns whether the window is in kiosk mode. Returns whether the window is in kiosk mode.
### `win.getNativeWindowHandle()` #### `win.getNativeWindowHandle()`
Returns the platform-specific handle of the window as `Buffer`. Returns the platform-specific handle of the window as `Buffer`.
The native type of the handle is `HWND` on Windows, `NSView*` on macOS, and The native type of the handle is `HWND` on Windows, `NSView*` on macOS, and
`Window` (`unsigned long`) on Linux. `Window` (`unsigned long`) on Linux.
### `win.hookWindowMessage(message, callback)` _Windows_ #### `win.hookWindowMessage(message, callback)` _Windows_
* `message` Integer * `message` Integer
* `callback` Function * `callback` Function
@ -852,68 +852,68 @@ The native type of the handle is `HWND` on Windows, `NSView*` on macOS, and
Hooks a windows message. The `callback` is called when Hooks a windows message. The `callback` is called when
the message is received in the WndProc. the message is received in the WndProc.
### `win.isWindowMessageHooked(message)` _Windows_ #### `win.isWindowMessageHooked(message)` _Windows_
* `message` Integer * `message` Integer
Returns `true` or `false` depending on whether the message is hooked. Returns `true` or `false` depending on whether the message is hooked.
### `win.unhookWindowMessage(message)` _Windows_ #### `win.unhookWindowMessage(message)` _Windows_
* `message` Integer * `message` Integer
Unhook the window message. Unhook the window message.
### `win.unhookAllWindowMessages()` _Windows_ #### `win.unhookAllWindowMessages()` _Windows_
Unhooks all of the window messages. Unhooks all of the window messages.
### `win.setRepresentedFilename(filename)` _macOS_ #### `win.setRepresentedFilename(filename)` _macOS_
* `filename` String * `filename` String
Sets the pathname of the file the window represents, and the icon of the file Sets the pathname of the file the window represents, and the icon of the file
will show in window's title bar. will show in window's title bar.
### `win.getRepresentedFilename()` _macOS_ #### `win.getRepresentedFilename()` _macOS_
Returns the pathname of the file the window represents. Returns the pathname of the file the window represents.
### `win.setDocumentEdited(edited)` _macOS_ #### `win.setDocumentEdited(edited)` _macOS_
* `edited` Boolean * `edited` Boolean
Specifies whether the window’s document has been edited, and the icon in title Specifies whether the window’s document has been edited, and the icon in title
bar will become gray when set to `true`. bar will become gray when set to `true`.
### `win.isDocumentEdited()` _macOS_ #### `win.isDocumentEdited()` _macOS_
Whether the window's document has been edited. Whether the window's document has been edited.
### `win.focusOnWebView()` #### `win.focusOnWebView()`
### `win.blurWebView()` #### `win.blurWebView()`
### `win.capturePage([rect, ]callback)` #### `win.capturePage([rect, ]callback)`
Same as `webContents.capturePage([rect, ]callback)`. Same as `webContents.capturePage([rect, ]callback)`.
### `win.loadURL(url[, options])` #### `win.loadURL(url[, options])`
Same as `webContents.loadURL(url[, options])`. Same as `webContents.loadURL(url[, options])`.
### `win.reload()` #### `win.reload()`
Same as `webContents.reload`. Same as `webContents.reload`.
### `win.setMenu(menu)` _Linux_ _Windows_ #### `win.setMenu(menu)` _Linux_ _Windows_
* `menu` Menu * `menu` Menu
Sets the `menu` as the window's menu bar, setting it to `null` will remove the Sets the `menu` as the window's menu bar, setting it to `null` will remove the
menu bar. menu bar.
### `win.setProgressBar(progress)` #### `win.setProgressBar(progress)`
* `progress` Double * `progress` Double
@ -926,7 +926,7 @@ On Linux platform, only supports Unity desktop environment, you need to specify
the `*.desktop` file name to `desktopName` field in `package.json`. By default, the `*.desktop` file name to `desktopName` field in `package.json`. By default,
it will assume `app.getName().desktop`. it will assume `app.getName().desktop`.
### `win.setOverlayIcon(overlay, description)` _Windows 7+_ #### `win.setOverlayIcon(overlay, description)` _Windows 7+_
* `overlay` [NativeImage](native-image.md) - the icon to display on the bottom * `overlay` [NativeImage](native-image.md) - the icon to display on the bottom
right corner of the taskbar icon. If this parameter is `null`, the overlay is right corner of the taskbar icon. If this parameter is `null`, the overlay is
@ -937,19 +937,19 @@ screen readers
Sets a 16 x 16 pixel overlay onto the current taskbar icon, usually used to Sets a 16 x 16 pixel overlay onto the current taskbar icon, usually used to
convey some sort of application status or to passively notify the user. convey some sort of application status or to passively notify the user.
### `win.setHasShadow(hasShadow)` _macOS_ #### `win.setHasShadow(hasShadow)` _macOS_
* `hasShadow` Boolean * `hasShadow` Boolean
Sets whether the window should have a shadow. On Windows and Linux does Sets whether the window should have a shadow. On Windows and Linux does
nothing. nothing.
### `win.hasShadow()` _macOS_ #### `win.hasShadow()` _macOS_
Returns whether the window has a shadow. On Windows and Linux always returns Returns whether the window has a shadow. On Windows and Linux always returns
`true`. `true`.
### `win.setThumbarButtons(buttons)` _Windows 7+_ #### `win.setThumbarButtons(buttons)` _Windows 7+_
* `buttons` Array * `buttons` Array
@ -985,17 +985,17 @@ The `flags` is an array that can include following `String`s:
button state is drawn. This value is intended for instances where the button button state is drawn. This value is intended for instances where the button
is used in a notification. is used in a notification.
### `win.showDefinitionForSelection()` _macOS_ #### `win.showDefinitionForSelection()` _macOS_
Same as `webContents.showDefinitionForSelection()`. Same as `webContents.showDefinitionForSelection()`.
### `win.setIcon(icon)` _Windows_ _Linux_ #### `win.setIcon(icon)` _Windows_ _Linux_
* `icon` [NativeImage](native-image.md) * `icon` [NativeImage](native-image.md)
Changes window icon. Changes window icon.
### `win.setAutoHideMenuBar(hide)` #### `win.setAutoHideMenuBar(hide)`
* `hide` Boolean * `hide` Boolean
@ -1005,22 +1005,22 @@ menu bar will only show when users press the single `Alt` key.
If the menu bar is already visible, calling `setAutoHideMenuBar(true)` won't If the menu bar is already visible, calling `setAutoHideMenuBar(true)` won't
hide it immediately. hide it immediately.
### `win.isMenuBarAutoHide()` #### `win.isMenuBarAutoHide()`
Returns whether menu bar automatically hides itself. Returns whether menu bar automatically hides itself.
### `win.setMenuBarVisibility(visible)` #### `win.setMenuBarVisibility(visible)`
* `visible` Boolean * `visible` Boolean
Sets whether the menu bar should be visible. If the menu bar is auto-hide, users Sets whether the menu bar should be visible. If the menu bar is auto-hide, users
can still bring up the menu bar by pressing the single `Alt` key. can still bring up the menu bar by pressing the single `Alt` key.
### `win.isMenuBarVisible()` #### `win.isMenuBarVisible()`
Returns whether the menu bar is visible. Returns whether the menu bar is visible.
### `win.setVisibleOnAllWorkspaces(visible)` #### `win.setVisibleOnAllWorkspaces(visible)`
* `visible` Boolean * `visible` Boolean
@ -1028,13 +1028,13 @@ Sets whether the window should be visible on all workspaces.
**Note:** This API does nothing on Windows. **Note:** This API does nothing on Windows.
### `win.isVisibleOnAllWorkspaces()` #### `win.isVisibleOnAllWorkspaces()`
Returns whether the window is visible on all workspaces. Returns whether the window is visible on all workspaces.
**Note:** This API always returns false on Windows. **Note:** This API always returns false on Windows.
### `win.setIgnoreMouseEvents(ignore)` #### `win.setIgnoreMouseEvents(ignore)`
* `ignore` Boolean * `ignore` Boolean
@ -1044,14 +1044,14 @@ All mouse events happened in this window will be passed to the window below
this window, but if this window has focus, it will still receive keyboard this window, but if this window has focus, it will still receive keyboard
events. events.
### `win.setContentProtection(enable)` _macOS_ _Windows_ #### `win.setContentProtection(enable)` _macOS_ _Windows_
Prevents the window contents from being captured by other apps. Prevents the window contents from being captured by other apps.
On macOS it sets the NSWindow's sharingType to NSWindowSharingNone. On macOS it sets the NSWindow's sharingType to NSWindowSharingNone.
On Windows it calls SetWindowDisplayAffinity with WDA_MONITOR. On Windows it calls SetWindowDisplayAffinity with WDA_MONITOR.
### `win.setFocusable(focusable)` _Windows_ #### `win.setFocusable(focusable)` _Windows_
* `focusable` Boolean * `focusable` Boolean
@ -1059,17 +1059,17 @@ Changes whether the window can be focused.
[blink-feature-string]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.in [blink-feature-string]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.in
### `win.setParentWindow(parent)` _Linux_ _macOS_ #### `win.setParentWindow(parent)` _Linux_ _macOS_
* `parent` BrowserWindow * `parent` BrowserWindow
Sets `parent` as current window's parent window, passing `null` will turn Sets `parent` as current window's parent window, passing `null` will turn
current window into a top-level window. current window into a top-level window.
### `win.getParentWindow()` #### `win.getParentWindow()`
Returns the parent window. Returns the parent window.
### `win.getChildWindows()` #### `win.getChildWindows()`
Returns all child windows. Returns all child windows.

39
docs/api/menu.md
View file

@ -183,11 +183,11 @@ Menu.setApplicationMenu(menu);
Creates a new menu. Creates a new menu.
## Methods ### Static Methods
The `menu` class has the following methods: The `menu` class has the following static methods:
### `Menu.setApplicationMenu(menu)` #### `Menu.setApplicationMenu(menu)`
* `menu` Menu * `menu` Menu
@ -196,11 +196,11 @@ will be set as each window's top menu.
**Note:** This API has to be called after the `ready` event of `app` module. **Note:** This API has to be called after the `ready` event of `app` module.
### `Menu.getApplicationMenu()` #### `Menu.getApplicationMenu()`
Returns the application menu (an instance of `Menu`), if set, or `null`, if not set. Returns the application menu (an instance of `Menu`), if set, or `null`, if not set.
### `Menu.sendActionToFirstResponder(action)` _macOS_ #### `Menu.sendActionToFirstResponder(action)` _macOS_
* `action` String * `action` String
@ -211,7 +211,7 @@ emulating default Cocoa menu behaviors, usually you would just use the
See the [macOS Cocoa Event Handling Guide](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/EventOverview/EventArchitecture/EventArchitecture.html#//apple_ref/doc/uid/10000060i-CH3-SW7) See the [macOS Cocoa Event Handling Guide](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/EventOverview/EventArchitecture/EventArchitecture.html#//apple_ref/doc/uid/10000060i-CH3-SW7)
for more information on macOS' native actions. for more information on macOS' native actions.
### `Menu.buildFromTemplate(template)` #### `Menu.buildFromTemplate(template)`
* `template` Array * `template` Array
@ -221,11 +221,11 @@ Generally, the `template` is just an array of `options` for constructing a
You can also attach other fields to the element of the `template` and they You can also attach other fields to the element of the `template` and they
will become properties of the constructed menu items. will become properties of the constructed menu items.
## Instance Methods ### Instance Methods
The `menu` object has the following instance methods: The `menu` object has the following instance methods:
### `menu.popup([browserWindow, x, y, positioningItem])` #### `menu.popup([browserWindow, x, y, positioningItem])`
* `browserWindow` BrowserWindow (optional) - Default is `null`. * `browserWindow` BrowserWindow (optional) - Default is `null`.
* `x` Number (optional) - Default is -1. * `x` Number (optional) - Default is -1.
@ -238,35 +238,35 @@ Pops up this menu as a context menu in the `browserWindow`. You can optionally
provide a `x, y` coordinate to place the menu at, otherwise it will be placed provide a `x, y` coordinate to place the menu at, otherwise it will be placed
at the current mouse cursor position. at the current mouse cursor position.
### `menu.append(menuItem)` #### `menu.append(menuItem)`
* `menuItem` MenuItem * `menuItem` MenuItem
Appends the `menuItem` to the menu. Appends the `menuItem` to the menu.
### `menu.insert(pos, menuItem)` #### `menu.insert(pos, menuItem)`
* `pos` Integer * `pos` Integer
* `menuItem` MenuItem * `menuItem` MenuItem
Inserts the `menuItem` to the `pos` position of the menu. Inserts the `menuItem` to the `pos` position of the menu.
## Instance Properties ### Instance Properties
`menu` objects also have the following properties: `menu` objects also have the following properties:
### `menu.items` #### `menu.items`
Get an array containing the menu's items. Get an array containing the menu's items.
## Notes on macOS Application Menu ## Notes on macOS Application Menu
macOS has a completely different style of application menu from Windows and macOS has a completely different style of application menu from Windows and
Linux, here are some notes on making your app's menu more native-like. Linux. Here are some notes on making your app's menu more native-like.
### Standard Menus ### Standard Menus
On macOS there are many system defined standard menus, like the `Services` and On macOS there are many system-defined standard menus, like the `Services` and
`Windows` menus. To make your menu a standard menu, you should set your menu's `Windows` menus. To make your menu a standard menu, you should set your menu's
`role` to one of following and Electron will recognize them and make them `role` to one of following and Electron will recognize them and make them
become standard menus: become standard menus:
@ -283,15 +283,16 @@ action, you should set the `role` attribute of the menu item.
### Main Menu's Name ### Main Menu's Name
On macOS the label of application menu's first item is always your app's name, On macOS the label of the application menu's first item is always your app's
no matter what label you set. To change it you have to change your app's name name, no matter what label you set. To change it, modify your app bundle's
by modifying your app bundle's `Info.plist` file. See [About Information `Info.plist` file. See
Property List Files][AboutInformationPropertyListFiles] for more information. [About Information Property List Files][AboutInformationPropertyListFiles]
for more information.
## Setting Menu for Specific Browser Window (*Linux* *Windows*) ## Setting Menu for Specific Browser Window (*Linux* *Windows*)
The [`setMenu` method][setMenu] of browser windows can set the menu of certain The [`setMenu` method][setMenu] of browser windows can set the menu of certain
browser window. browser windows.
## Menu Item Position ## Menu Item Position

18
docs/api/window-open.md
View file

@ -41,33 +41,37 @@ origin preference.
The `BrowserWindowProxy` object is returned from `window.open` and provides The `BrowserWindowProxy` object is returned from `window.open` and provides
limited functionality with the child window. limited functionality with the child window.
### `BrowserWindowProxy.blur()` ### Instance Methods
The `BrowserWindowProxy` object has the following instance methods:
#### `BrowserWindowProxy.blur()`
Removes focus from the child window. Removes focus from the child window.
### `BrowserWindowProxy.close()` #### `BrowserWindowProxy.close()`
Forcefully closes the child window without calling its unload event. Forcefully closes the child window without calling its unload event.
### `BrowserWindowProxy.closed` #### `BrowserWindowProxy.closed`
Set to true after the child window gets closed. Set to true after the child window gets closed.
### `BrowserWindowProxy.eval(code)` #### `BrowserWindowProxy.eval(code)`
* `code` String * `code` String
Evaluates the code in the child window. Evaluates the code in the child window.
### `BrowserWindowProxy.focus()` #### `BrowserWindowProxy.focus()`
Focuses the child window (brings the window to front). Focuses the child window (brings the window to front).
### `BrowserWindowProxy.print()` #### `BrowserWindowProxy.print()`
Invokes the print dialog on the child window. Invokes the print dialog on the child window.
### `BrowserWindowProxy.postMessage(message, targetOrigin)` #### `BrowserWindowProxy.postMessage(message, targetOrigin)`
* `message` String * `message` String
* `targetOrigin` String * `targetOrigin` String

9
docs/styleguide.md
View file

@ -96,10 +96,11 @@ Using `autoUpdater` as an example:
* API classes or classes that are part of modules must be listed under a * API classes or classes that are part of modules must be listed under a
`## Class: TheClassName` chapter. `## Class: TheClassName` chapter.
* One page can have multiple classes. * One page can have multiple classes.
* The constructors must be listed with `###`-level titles. * Constructors must be listed with `###`-level titles.
* The methods must be listed under an `### Instance Methods` chapter. * [Static Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/static) must be listed under a `### Static Methods` chapter.
* The events must be listed under an `### Instance Events` chapter. * [Instance Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#Prototype_methods) must be listed under an `### Instance Methods` chapter.
* The properties must be listed under an `### Instance Properties` chapter. * Instance Events must be listed under an `### Instance Events` chapter.
* Instance Properties must be listed under an `### Instance Properties` chapter.
Using the `Session` and `Cookies` classes as an example: Using the `Session` and `Cookies` classes as an example: