electron/docs/api/web-contents.md

2048 lines
68 KiB
Markdown
Raw Normal View History

2015-08-20 13:17:53 +00:00
# webContents
2016-04-22 17:30:49 +00:00
> Render and control web pages.
2016-11-23 19:20:56 +00:00
Process: [Main](../glossary.md#main-process)
2016-11-03 17:26:00 +00:00
`webContents` is an [EventEmitter][event-emitter].
2015-08-24 22:41:02 +00:00
It is responsible for rendering and controlling a web page and is a property of
the [`BrowserWindow`](browser-window.md) object. An example of accessing the
`webContents` object:
2015-08-20 13:17:53 +00:00
```javascript
2018-09-13 16:10:51 +00:00
const { BrowserWindow } = require('electron')
2015-08-20 13:17:53 +00:00
2020-07-09 17:18:49 +00:00
const win = new BrowserWindow({ width: 800, height: 1500 })
win.loadURL('http://github.com')
2015-08-20 13:17:53 +00:00
2020-07-09 17:18:49 +00:00
const contents = win.webContents
console.log(contents)
2015-08-20 13:17:53 +00:00
```
## Methods
2015-08-20 13:17:53 +00:00
2016-07-15 00:54:18 +00:00
These methods can be accessed from the `webContents` module:
2015-08-20 13:17:53 +00:00
2016-08-16 21:50:21 +00:00
```javascript
2018-09-13 16:10:51 +00:00
const { webContents } = require('electron')
console.log(webContents)
2016-07-15 00:54:18 +00:00
```
### `webContents.getAllWebContents()`
2015-08-20 13:17:53 +00:00
Returns `WebContents[]` - An array of all `WebContents` instances. This will contain web contents
2016-08-22 21:11:03 +00:00
for all windows, webviews, opened devtools, and devtools extension background pages.
### `webContents.getFocusedWebContents()`
Returns `WebContents` - The web contents that is focused in this application, otherwise
returns `null`.
2016-08-31 03:25:04 +00:00
### `webContents.fromId(id)`
* `id` Integer
Returns `WebContents` | undefined - A WebContents instance with the given ID, or
`undefined` if there is no WebContents associated with the given ID.
2016-08-31 03:25:04 +00:00
### `webContents.fromDevToolsTargetId(targetId)`
* `targetId` string - The Chrome DevTools Protocol [TargetID](https://chromedevtools.github.io/devtools-protocol/tot/Target/#type-TargetID) associated with the WebContents instance.
Returns `WebContents` | undefined - A WebContents instance with the given TargetID, or
`undefined` if there is no WebContents associated with the given TargetID.
When communicating with the [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/),
it can be useful to lookup a WebContents instance based on its assigned TargetID.
```js
async function lookupTargetId (browserWindow) {
const wc = browserWindow.webContents
await wc.debugger.attach('1.3')
const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')
const { targetId } = targetInfo
const targetWebContents = await webContents.fromDevToolsTargetId(targetId)
}
```
## Class: WebContents
2016-08-22 21:11:03 +00:00
> Render and control the contents of a BrowserWindow instance.
Process: [Main](../glossary.md#main-process)<br />
_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
### Instance Events
#### Event: 'did-finish-load'
2015-08-20 13:17:53 +00:00
Emitted when the navigation is done, i.e. the spinner of the tab has stopped
spinning, and the `onload` event was dispatched.
#### Event: 'did-fail-load'
2015-08-20 13:17:53 +00:00
Returns:
* `event` Event
* `errorCode` Integer
* `errorDescription` string
* `validatedURL` string
* `isMainFrame` boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
2015-08-20 13:17:53 +00:00
This event is like `did-finish-load` but emitted when the load failed.
The full list of error codes and their meaning is available [here](https://source.chromium.org/chromium/chromium/src/+/master:net/base/net_error_list.h).
2015-08-20 13:17:53 +00:00
#### Event: 'did-fail-provisional-load'
Returns:
* `event` Event
* `errorCode` Integer
* `errorDescription` string
* `validatedURL` string
* `isMainFrame` boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
This event is like `did-fail-load` but emitted when the load was cancelled
(e.g. `window.stop()` was invoked).
#### Event: 'did-frame-finish-load'
2015-08-20 13:17:53 +00:00
Returns:
* `event` Event
* `isMainFrame` boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
2015-08-20 13:17:53 +00:00
Emitted when a frame has done navigation.
#### Event: 'did-start-loading'
2015-08-20 13:17:53 +00:00
Corresponds to the points in time when the spinner of the tab started spinning.
#### Event: 'did-stop-loading'
2015-08-20 13:17:53 +00:00
Corresponds to the points in time when the spinner of the tab stopped spinning.
#### Event: 'dom-ready'
2015-08-20 13:17:53 +00:00
Returns:
* `event` Event
Emitted when the document in the top-level frame is loaded.
2015-08-20 13:17:53 +00:00
#### Event: 'page-title-updated'
Returns:
* `event` Event
* `title` string
* `explicitSet` boolean
Fired when page title is set during navigation. `explicitSet` is false when
title is synthesized from file url.
#### Event: 'page-favicon-updated'
2015-08-20 13:17:53 +00:00
Returns:
* `event` Event
* `favicons` string[] - Array of URLs.
2015-08-20 13:17:53 +00:00
Emitted when page receives favicon urls.
#### Event: 'new-window' _Deprecated_
2015-08-20 13:17:53 +00:00
Returns:
* `event` NewWindowWebContentsEvent
* `url` string
* `frameName` string
* `disposition` string - Can be `default`, `foreground-tab`, `background-tab`,
`new-window`, `save-to-disk` and `other`.
* `options` BrowserWindowConstructorOptions - The options which will be used for creating the new
2017-11-28 17:15:15 +00:00
[`BrowserWindow`](browser-window.md).
* `additionalFeatures` string[] - The non-standard features (features not handled
by Chromium or Electron) given to `window.open()`. Deprecated, and will now
always be the empty array `[]`.
* `referrer` [Referrer](structures/referrer.md) - The referrer that will be
passed to the new window. May or may not result in the `Referer` header being
sent, depending on the referrer policy.
* `postBody` [PostBody](structures/post-body.md) (optional) - The post data that
will be sent to the new window, along with the appropriate headers that will
be set. If no post data is to be sent, the value will be `null`. Only defined
when the window is being created by a form that set `target=_blank`.
2015-08-20 13:17:53 +00:00
2020-11-19 07:06:32 +00:00
Deprecated in favor of [`webContents.setWindowOpenHandler`](web-contents.md#contentssetwindowopenhandlerhandler).
2015-08-20 13:17:53 +00:00
Emitted when the page requests to open a new window for a `url`. It could be
requested by `window.open` or an external link like `<a target='_blank'>`.
By default a new `BrowserWindow` will be created for the `url`.
Calling `event.preventDefault()` will prevent Electron from automatically creating a
2017-11-28 17:15:15 +00:00
new [`BrowserWindow`](browser-window.md). If you call `event.preventDefault()` and manually create a new
[`BrowserWindow`](browser-window.md) then you must set `event.newGuest` to reference the new [`BrowserWindow`](browser-window.md)
instance, failing to do so may result in unexpected behavior. For example:
```javascript
myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures, referrer, postBody) => {
event.preventDefault()
const win = new BrowserWindow({
webContents: options.webContents, // use existing webContents if provided
show: false
})
win.once('ready-to-show', () => win.show())
if (!options.webContents) {
const loadOptions = {
httpReferrer: referrer
}
if (postBody != null) {
const { data, contentType, boundary } = postBody
loadOptions.postData = postBody.data
loadOptions.extraHeaders = `content-type: ${contentType}; boundary=${boundary}`
}
win.loadURL(url, loadOptions) // existing webContents will be navigated automatically
}
event.newGuest = win
})
```
2015-08-20 13:17:53 +00:00
#### Event: 'did-create-window'
Returns:
2020-11-25 02:52:46 +00:00
* `window` BrowserWindow
* `details` Object
* `url` string - URL for the created window.
* `frameName` string - Name given to the created window in the
2020-11-25 02:52:46 +00:00
`window.open()` call.
* `options` BrowserWindowConstructorOptions - The options used to create the
BrowserWindow. They are merged in increasing precedence: parsed options
from the `features` string from `window.open()`, security-related
webPreferences inherited from the parent, and options given by
2020-11-25 02:52:46 +00:00
[`webContents.setWindowOpenHandler`](web-contents.md#contentssetwindowopenhandlerhandler).
Unrecognized options are not filtered out.
* `referrer` [Referrer](structures/referrer.md) - The referrer that will be
passed to the new window. May or may not result in the `Referer` header
being sent, depending on the referrer policy.
* `postBody` [PostBody](structures/post-body.md) (optional) - The post data
that will be sent to the new window, along with the appropriate headers
that will be set. If no post data is to be sent, the value will be `null`.
Only defined when the window is being created by a form that set
`target=_blank`.
* `disposition` string - Can be `default`, `foreground-tab`,
2020-11-25 02:52:46 +00:00
`background-tab`, `new-window`, `save-to-disk` and `other`.
Emitted _after_ successful creation of a window via `window.open` in the renderer.
Not emitted if the creation of the window is canceled from
2020-11-19 07:06:32 +00:00
[`webContents.setWindowOpenHandler`](web-contents.md#contentssetwindowopenhandlerhandler).
See [`window.open()`](window-open.md) for more details and how to use this in conjunction with `webContents.setWindowOpenHandler`.
#### Event: 'will-navigate'
2015-08-20 13:17:53 +00:00
Returns:
* `event` Event
* `url` string
2015-08-20 13:17:53 +00:00
Emitted when a user or the page wants to start navigation. It can happen when
the `window.location` object is changed or a user clicks a link in the page.
2015-08-20 13:17:53 +00:00
2015-08-24 22:41:02 +00:00
This event will not emit when the navigation is started programmatically with
2015-11-13 08:03:40 +00:00
APIs like `webContents.loadURL` and `webContents.back`.
2015-08-20 13:17:53 +00:00
It is also not emitted for in-page navigations, such as clicking anchor links
or updating the `window.location.hash`. Use `did-navigate-in-page` event for
this purpose.
Calling `event.preventDefault()` will prevent the navigation.
2015-08-20 13:17:53 +00:00
#### Event: 'did-start-navigation'
Returns:
* `event` Event
* `url` string
* `isInPlace` boolean
* `isMainFrame` boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
2020-10-09 10:56:07 +00:00
Emitted when any frame (including main) starts navigating. `isInPlace` will be
`true` for in-page navigations.
#### Event: 'will-redirect'
Returns:
* `event` Event
* `url` string
* `isInPlace` boolean
* `isMainFrame` boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
Emitted as a server side redirect occurs during navigation. For example a 302
redirect.
This event will be emitted after `did-start-navigation` and always before the
`did-redirect-navigation` event for the same navigation.
Calling `event.preventDefault()` will prevent the navigation (not just the
redirect).
#### Event: 'did-redirect-navigation'
Returns:
* `event` Event
* `url` string
* `isInPlace` boolean
* `isMainFrame` boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
Emitted after a server side redirect occurs during navigation. For example a 302
redirect.
This event cannot be prevented, if you want to prevent redirects you should
checkout out the `will-redirect` event above.
#### Event: 'did-navigate'
Returns:
* `event` Event
* `url` string
* `httpResponseCode` Integer - -1 for non HTTP navigations
* `httpStatusText` string - empty for non HTTP navigations
Emitted when a main frame navigation is done.
This event is not emitted for in-page navigations, such as clicking anchor links
or updating the `window.location.hash`. Use `did-navigate-in-page` event for
this purpose.
#### Event: 'did-frame-navigate'
Returns:
* `event` Event
* `url` string
* `httpResponseCode` Integer - -1 for non HTTP navigations
* `httpStatusText` string - empty for non HTTP navigations,
* `isMainFrame` boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
Emitted when any frame navigation is done.
This event is not emitted for in-page navigations, such as clicking anchor links
or updating the `window.location.hash`. Use `did-navigate-in-page` event for
this purpose.
#### Event: 'did-navigate-in-page'
Returns:
* `event` Event
* `url` string
* `isMainFrame` boolean
* `frameProcessId` Integer
* `frameRoutingId` Integer
Emitted when an in-page navigation happened in any frame.
When in-page navigation happens, the page URL changes but does not cause
navigation outside of the page. Examples of this occurring are when anchor links
are clicked or when the DOM `hashchange` event is triggered.
2017-04-28 00:28:48 +00:00
#### Event: 'will-prevent-unload'
Returns:
* `event` Event
Emitted when a `beforeunload` event handler is attempting to cancel a page unload.
Calling `event.preventDefault()` will ignore the `beforeunload` event handler
and allow the page to be unloaded.
```javascript
2018-09-13 16:10:51 +00:00
const { BrowserWindow, dialog } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
2017-04-28 00:28:48 +00:00
win.webContents.on('will-prevent-unload', (event) => {
const choice = dialog.showMessageBoxSync(win, {
2017-04-28 00:28:48 +00:00
type: 'question',
buttons: ['Leave', 'Stay'],
title: 'Do you want to leave this site?',
message: 'Changes you made may not be saved.',
defaultId: 0,
cancelId: 1
})
const leave = (choice === 0)
2017-04-28 00:28:48 +00:00
if (leave) {
event.preventDefault()
}
})
```
**Note:** This will be emitted for `BrowserViews` but will _not_ be respected - this is because we have chosen not to tie the `BrowserView` lifecycle to its owning BrowserWindow should one exist per the [specification](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event).
#### Event: 'crashed' _Deprecated_
2015-08-20 13:17:53 +00:00
Returns:
* `event` Event
* `killed` boolean
Emitted when the renderer process crashes or is killed.
2015-08-20 13:17:53 +00:00
**Deprecated:** This event is superceded by the `render-process-gone` event
which contains more information about why the render process disappeared. It
isn't always because it crashed. The `killed` boolean can be replaced by
checking `reason === 'killed'` when you switch to that event.
#### Event: 'render-process-gone'
Returns:
* `event` Event
* `details` Object
* `reason` string - The reason the render process is gone. Possible values:
* `clean-exit` - Process exited with an exit code of zero
* `abnormal-exit` - Process exited with a non-zero exit code
* `killed` - Process was sent a SIGTERM or otherwise killed externally
* `crashed` - Process crashed
* `oom` - Process ran out of memory
* `launch-failed` - Process never successfully launched
* `integrity-failure` - Windows code integrity checks failed
* `exitCode` Integer - The exit code of the process, unless `reason` is
`launch-failed`, in which case `exitCode` will be a platform-specific
launch failure error code.
Emitted when the renderer process unexpectedly disappears. This is normally
because it was crashed or killed.
2018-05-02 16:19:52 +00:00
#### Event: 'unresponsive'
Emitted when the web page becomes unresponsive.
#### Event: 'responsive'
Emitted when the unresponsive web page becomes responsive again.
#### Event: 'plugin-crashed'
2015-08-20 13:17:53 +00:00
Returns:
* `event` Event
* `name` string
* `version` string
2015-08-20 13:17:53 +00:00
Emitted when a plugin process has crashed.
#### Event: 'destroyed'
2015-08-20 13:17:53 +00:00
Emitted when `webContents` is destroyed.
#### Event: 'before-input-event'
Returns:
* `event` Event
2017-11-28 17:15:15 +00:00
* `input` Object - Input properties.
* `type` string - Either `keyUp` or `keyDown`.
* `key` string - Equivalent to [KeyboardEvent.key][keyboardevent].
* `code` string - Equivalent to [KeyboardEvent.code][keyboardevent].
* `isAutoRepeat` boolean - Equivalent to [KeyboardEvent.repeat][keyboardevent].
* `isComposing` boolean - Equivalent to [KeyboardEvent.isComposing][keyboardevent].
* `shift` boolean - Equivalent to [KeyboardEvent.shiftKey][keyboardevent].
* `control` boolean - Equivalent to [KeyboardEvent.controlKey][keyboardevent].
* `alt` boolean - Equivalent to [KeyboardEvent.altKey][keyboardevent].
* `meta` boolean - Equivalent to [KeyboardEvent.metaKey][keyboardevent].
* `location` number - Equivalent to [KeyboardEvent.location][keyboardevent].
* `modifiers` string[] - See [InputEvent.modifiers](structures/input-event.md).
Emitted before dispatching the `keydown` and `keyup` events in the page.
Calling `event.preventDefault` will prevent the page `keydown`/`keyup` events
and the menu shortcuts.
To only prevent the menu shortcuts, use
[`setIgnoreMenuShortcuts`](#contentssetignoremenushortcutsignore):
```javascript
2018-09-13 16:10:51 +00:00
const { BrowserWindow } = require('electron')
2020-07-09 17:18:49 +00:00
const win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('before-input-event', (event, input) => {
// For example, only enable application menu keyboard shortcuts when
// Ctrl/Cmd are down.
win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)
})
```
#### Event: 'enter-html-full-screen'
Emitted when the window enters a full-screen state triggered by HTML API.
#### Event: 'leave-html-full-screen'
Emitted when the window leaves a full-screen state triggered by HTML API.
#### Event: 'zoom-changed'
Returns:
* `event` Event
* `zoomDirection` string - Can be `in` or `out`.
Emitted when the user is requesting to change the zoom level using the mouse wheel.
#### Event: 'devtools-opened'
Emitted when DevTools is opened.
#### Event: 'devtools-closed'
Emitted when DevTools is closed.
#### Event: 'devtools-focused'
Emitted when DevTools is focused / opened.
#### Event: 'certificate-error'
2015-11-18 03:35:26 +00:00
Returns:
* `event` Event
* `url` string
* `error` string - The error code.
* `certificate` [Certificate](structures/certificate.md)
2015-11-18 03:35:26 +00:00
* `callback` Function
* `isTrusted` boolean - Indicates whether the certificate can be considered trusted.
* `isMainFrame` boolean
2015-11-18 03:35:26 +00:00
Emitted when failed to verify the `certificate` for `url`.
The usage is the same with [the `certificate-error` event of
`app`](app.md#event-certificate-error).
#### Event: 'select-client-certificate'
2015-11-18 03:35:26 +00:00
Returns:
* `event` Event
* `url` URL
2016-10-12 16:12:02 +00:00
* `certificateList` [Certificate[]](structures/certificate.md)
2015-11-18 03:35:26 +00:00
* `callback` Function
2017-11-28 17:15:15 +00:00
* `certificate` [Certificate](structures/certificate.md) - Must be a certificate from the given list.
2015-11-18 03:35:26 +00:00
Emitted when a client certificate is requested.
The usage is the same with [the `select-client-certificate` event of
`app`](app.md#event-select-client-certificate).
#### Event: 'login'
2015-10-28 13:14:00 +00:00
Returns:
* `event` Event
* `authenticationResponseDetails` Object
2015-10-28 13:14:00 +00:00
* `url` URL
* `authInfo` Object
* `isProxy` boolean
* `scheme` string
* `host` string
2015-10-28 13:14:00 +00:00
* `port` Integer
* `realm` string
2015-10-28 13:14:00 +00:00
* `callback` Function
* `username` string (optional)
* `password` string (optional)
2015-10-28 13:14:00 +00:00
Emitted when `webContents` wants to do basic auth.
The usage is the same with [the `login` event of `app`](app.md#event-login).
#### Event: 'found-in-page'
2015-12-17 17:27:56 +00:00
Returns:
* `event` Event
* `result` Object
* `requestId` Integer
* `activeMatchOrdinal` Integer - Position of the active match.
* `matches` Integer - Number of Matches.
* `selectionArea` Rectangle - Coordinates of first match region.
* `finalUpdate` boolean
2015-12-17 17:27:56 +00:00
Emitted when a result is available for
[`webContents.findInPage`] request.
2015-12-17 17:27:56 +00:00
#### Event: 'media-started-playing'
Emitted when media starts playing.
#### Event: 'media-paused'
Emitted when media is paused or done playing.
#### Event: 'did-change-theme-color'
Returns:
* `event` Event
* `color` (string | null) - Theme color is in format of '#rrggbb'. It is `null` when no theme color is set.
Emitted when a page's theme color changes. This is usually due to encountering
a meta tag:
```html
<meta name='theme-color' content='#ff0000'>
```
#### Event: 'update-target-url'
2016-06-07 06:56:19 +00:00
Returns:
* `event` Event
* `url` string
2016-06-07 06:56:19 +00:00
Emitted when mouse moves over a link or the keyboard moves the focus to a link.
#### Event: 'cursor-changed'
Returns:
* `event` Event
* `type` string
2017-11-28 17:15:15 +00:00
* `image` [NativeImage](native-image.md) (optional)
* `scale` Float (optional) - scaling factor for the custom cursor.
* `size` [Size](structures/size.md) (optional) - the size of the `image`.
* `hotspot` [Point](structures/point.md) (optional) - coordinates of the custom cursor's hotspot.
Emitted when the cursor's type changes. The `type` parameter can be `default`,
`crosshair`, `pointer`, `text`, `wait`, `help`, `e-resize`, `n-resize`,
`ne-resize`, `nw-resize`, `s-resize`, `se-resize`, `sw-resize`, `w-resize`,
`ns-resize`, `ew-resize`, `nesw-resize`, `nwse-resize`, `col-resize`,
`row-resize`, `m-panning`, `e-panning`, `n-panning`, `ne-panning`, `nw-panning`,
`s-panning`, `se-panning`, `sw-panning`, `w-panning`, `move`, `vertical-text`,
`cell`, `context-menu`, `alias`, `progress`, `nodrop`, `copy`, `none`,
2017-11-28 17:15:15 +00:00
`not-allowed`, `zoom-in`, `zoom-out`, `grab`, `grabbing` or `custom`.
If the `type` parameter is `custom`, the `image` parameter will hold the custom
2017-11-28 17:15:15 +00:00
cursor image in a [`NativeImage`](native-image.md), and `scale`, `size` and `hotspot` will hold
2016-08-01 00:14:45 +00:00
additional information about the custom cursor.
#### Event: 'context-menu'
2016-05-03 12:48:16 +00:00
Returns:
* `event` Event
* `params` Object
2017-11-28 17:15:15 +00:00
* `x` Integer - x coordinate.
* `y` Integer - y coordinate.
* `frame` WebFrameMain - Frame from which the context menu was invoked.
* `linkURL` string - URL of the link that encloses the node the context menu
was invoked on.
* `linkText` string - Text associated with the link. May be an empty
string if the contents of the link are an image.
* `pageURL` string - URL of the top level page that the context menu was
invoked on.
* `frameURL` string - URL of the subframe that the context menu was invoked
on.
* `srcURL` string - Source URL for the element that the context menu
was invoked on. Elements with source URLs are images, audio and video.
* `mediaType` string - Type of the node the context menu was invoked on. Can
be `none`, `image`, `audio`, `video`, `canvas`, `file` or `plugin`.
* `hasImageContents` boolean - Whether the context menu was invoked on an image
which has non-empty contents.
* `isEditable` boolean - Whether the context is editable.
* `selectionText` string - Text of the selection that the context menu was
invoked on.
* `titleText` string - Title text of the selection that the context menu was
invoked on.
* `altText` string - Alt text of the selection that the context menu was
invoked on.
* `suggestedFilename` string - Suggested filename to be used when saving file through 'Save
Link As' option of context menu.
* `selectionRect` [Rectangle](structures/rectangle.md) - Rect representing the coordinates in the document space of the selection.
* `selectionStartOffset` number - Start position of the selection text.
* `referrerPolicy` [Referrer](structures/referrer.md) - The referrer policy of the frame on which the menu is invoked.
* `misspelledWord` string - The misspelled word under the cursor, if any.
* `dictionarySuggestions` string[] - An array of suggested words to show the
user to replace the `misspelledWord`. Only available if there is a misspelled
word and spellchecker is enabled.
* `frameCharset` string - The character encoding of the frame on which the
menu was invoked.
* `inputFieldType` string - If the context menu was invoked on an input
field, the type of that field. Possible values are `none`, `plainText`,
`password`, `other`.
* `spellcheckEnabled` boolean - If the context is editable, whether or not spellchecking is enabled.
* `menuSourceType` string - Input source that invoked the context menu.
Can be `none`, `mouse`, `keyboard`, `touch`, `touchMenu`, `longPress`, `longTap`, `touchHandle`, `stylus`, `adjustSelection`, or `adjustSelectionReset`.
* `mediaFlags` Object - The flags for the media element the context menu was
invoked on.
* `inError` boolean - Whether the media element has crashed.
* `isPaused` boolean - Whether the media element is paused.
* `isMuted` boolean - Whether the media element is muted.
* `hasAudio` boolean - Whether the media element has audio.
* `isLooping` boolean - Whether the media element is looping.
* `isControlsVisible` boolean - Whether the media element's controls are
2016-10-26 05:18:55 +00:00
visible.
* `canToggleControls` boolean - Whether the media element's controls are
2016-10-26 05:18:55 +00:00
toggleable.
* `canPrint` boolean - Whether the media element can be printed.
* `canSave` boolean - Whether or not the media element can be downloaded.
* `canShowPictureInPicture` boolean - Whether the media element can show picture-in-picture.
* `isShowingPictureInPicture` boolean - Whether the media element is currently showing picture-in-picture.
* `canRotate` boolean - Whether the media element can be rotated.
* `canLoop` boolean - Whether the media element can be looped.
* `editFlags` Object - These flags indicate whether the renderer believes it
is able to perform the corresponding action.
* `canUndo` boolean - Whether the renderer believes it can undo.
* `canRedo` boolean - Whether the renderer believes it can redo.
* `canCut` boolean - Whether the renderer believes it can cut.
* `canCopy` boolean - Whether the renderer believes it can copy.
* `canPaste` boolean - Whether the renderer believes it can paste.
* `canDelete` boolean - Whether the renderer believes it can delete.
* `canSelectAll` boolean - Whether the renderer believes it can select all.
* `canEditRichly` boolean - Whether the renderer believes it can edit text richly.
2016-05-03 12:48:16 +00:00
Emitted when there is a new context menu that needs to be handled.
#### Event: 'select-bluetooth-device'
2016-05-31 08:07:45 +00:00
Returns:
* `event` Event
2016-10-13 03:38:06 +00:00
* `devices` [BluetoothDevice[]](structures/bluetooth-device.md)
2016-05-31 08:07:45 +00:00
* `callback` Function
* `deviceId` string
2016-05-31 08:07:45 +00:00
Emitted when bluetooth device needs to be selected on call to
2016-06-01 06:09:14 +00:00
`navigator.bluetooth.requestDevice`. To use `navigator.bluetooth` api
2017-11-29 10:58:24 +00:00
`webBluetooth` should be enabled. If `event.preventDefault` is not called,
2016-06-01 06:09:14 +00:00
first available device will be selected. `callback` should be called with
`deviceId` to be selected, passing empty string to `callback` will
cancel the request.
2016-06-02 16:38:21 +00:00
```javascript
2018-09-13 16:10:51 +00:00
const { app, BrowserWindow } = require('electron')
let win = null
app.commandLine.appendSwitch('enable-experimental-web-platform-features')
2016-06-01 06:09:14 +00:00
app.whenReady().then(() => {
2018-09-13 16:10:51 +00:00
win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {
2016-06-01 06:09:14 +00:00
event.preventDefault()
2020-07-09 17:18:49 +00:00
const result = deviceList.find((device) => {
2016-06-01 06:09:14 +00:00
return device.deviceName === 'test'
})
if (!result) {
callback('')
} else {
callback(result.deviceId)
}
})
})
```
2016-05-31 08:07:45 +00:00
2016-07-30 22:22:34 +00:00
#### Event: 'paint'
Returns:
* `event` Event
2016-10-08 02:09:31 +00:00
* `dirtyRect` [Rectangle](structures/rectangle.md)
2016-08-05 09:08:36 +00:00
* `image` [NativeImage](native-image.md) - The image data of the whole frame.
2016-07-30 22:22:34 +00:00
Emitted when a new frame is generated. Only the dirty area is passed in the
buffer.
```javascript
2018-09-13 16:10:51 +00:00
const { BrowserWindow } = require('electron')
2020-07-09 17:18:49 +00:00
const win = new BrowserWindow({ webPreferences: { offscreen: true } })
win.webContents.on('paint', (event, dirty, image) => {
2016-08-05 09:08:36 +00:00
// updateBitmap(dirty, image.getBitmap())
2016-08-03 01:15:38 +00:00
})
win.loadURL('http://github.com')
2016-07-30 22:22:34 +00:00
```
2016-11-23 00:51:44 +00:00
#### Event: 'devtools-reload-page'
Emitted when the devtools window instructs the webContents to reload
2017-02-03 20:58:04 +00:00
#### Event: 'will-attach-webview'
Returns:
* `event` Event
* `webPreferences` WebPreferences - The web preferences that will be used by the guest
2017-02-03 20:58:04 +00:00
page. This object can be modified to adjust the preferences for the guest
page.
* `params` Record<string, string> - The other `<webview>` parameters such as the `src` URL.
2017-02-03 21:58:07 +00:00
This object can be modified to adjust the parameters of the guest page.
2017-02-03 20:58:04 +00:00
2017-02-03 21:58:07 +00:00
Emitted when a `<webview>`'s web contents is being attached to this web
contents. Calling `event.preventDefault()` will destroy the guest page.
2017-02-03 20:58:04 +00:00
This event can be used to configure `webPreferences` for the `webContents`
of a `<webview>` before it's loaded, and provides the ability to set settings
that can't be set via `<webview>` attributes.
**Note:** The specified `preload` script option will appear as `preloadURL`
(not `preload`) in the `webPreferences` object emitted with this event.
2017-10-06 16:31:41 +00:00
#### Event: 'did-attach-webview'
Returns:
* `event` Event
* `webContents` WebContents - The guest web contents that is used by the
`<webview>`.
Emitted when a `<webview>` has been attached to this web contents.
2017-11-08 17:37:56 +00:00
#### Event: 'console-message'
2017-11-08 17:35:01 +00:00
Returns:
* `event` Event
* `level` Integer - The log level, from 0 to 3. In order it matches `verbose`, `info`, `warning` and `error`.
* `message` string - The actual console message
* `line` Integer - The line number of the source that triggered this console message
* `sourceId` string
2017-11-08 17:35:01 +00:00
Emitted when the associated window logs a console message.
2017-11-08 17:35:01 +00:00
#### Event: 'preload-error'
Returns:
* `event` Event
* `preloadPath` string
* `error` Error
Emitted when the preload script `preloadPath` throws an unhandled exception `error`.
#### Event: 'ipc-message'
Returns:
* `event` Event
* `channel` string
* `...args` any[]
Emitted when the renderer process sends an asynchronous message via `ipcRenderer.send()`.
#### Event: 'ipc-message-sync'
Returns:
* `event` Event
* `channel` string
* `...args` any[]
Emitted when the renderer process sends a synchronous message via `ipcRenderer.sendSync()`.
#### Event: 'preferred-size-changed'
Returns:
* `event` Event
* `preferredSize` [Size](structures/size.md) - The minimum size needed to
contain the layout of the document—without requiring scrolling.
Emitted when the `WebContents` preferred size has changed.
This event will only be emitted when `enablePreferredSizeMode` is set to `true`
in `webPreferences`.
#### Event: 'frame-created'
Returns:
* `event` Event
* `details` Object
* `frame` WebFrameMain
Emitted when the [mainFrame](web-contents.md#contentsmainframe-readonly), an `<iframe>`, or a nested `<iframe>` is loaded within the page.
### Instance Methods
2015-08-20 13:17:53 +00:00
#### `contents.loadURL(url[, options])`
2015-08-20 13:17:53 +00:00
* `url` string
* `options` Object (optional)
* `httpReferrer` (string | [Referrer](structures/referrer.md)) (optional) - An HTTP Referrer url.
* `userAgent` string (optional) - A user agent originating the request.
* `extraHeaders` string (optional) - Extra headers separated by "\n".
* `postData` ([UploadRawData](structures/upload-raw-data.md) | [UploadFile](structures/upload-file.md))[] (optional)
* `baseURLForDataURL` string (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified `url` is a data url and needs to load other files.
2015-08-20 13:17:53 +00:00
Returns `Promise<void>` - the promise will resolve when the page has finished loading
(see [`did-finish-load`](web-contents.md#event-did-finish-load)), and rejects
if the page fails to load (see
[`did-fail-load`](web-contents.md#event-did-fail-load)). A noop rejection handler is already attached, which avoids unhandled rejection errors.
2016-08-19 05:20:55 +00:00
Loads the `url` in the window. The `url` must contain the protocol prefix,
2015-11-14 06:39:18 +00:00
e.g. the `http://` or `file://`. If the load should bypass http cache then
use the `pragma` header to achieve it.
```javascript
2018-09-13 16:10:51 +00:00
const { webContents } = require('electron')
const options = { extraHeaders: 'pragma: no-cache\n' }
webContents.loadURL('https://github.com', options)
2015-11-14 06:39:18 +00:00
```
2015-08-20 13:17:53 +00:00
#### `contents.loadFile(filePath[, options])`
* `filePath` string
* `options` Object (optional)
* `query` Record<string, string> (optional) - Passed to `url.format()`.
* `search` string (optional) - Passed to `url.format()`.
* `hash` string (optional) - Passed to `url.format()`.
Returns `Promise<void>` - the promise will resolve when the page has finished loading
(see [`did-finish-load`](web-contents.md#event-did-finish-load)), and rejects
if the page fails to load (see [`did-fail-load`](web-contents.md#event-did-fail-load)).
Loads the given file in the window, `filePath` should be a path to
an HTML file relative to the root of your application. For instance
an app structure like this:
2018-01-22 17:41:46 +00:00
```sh
| root
| - package.json
| - src
| - main.js
| - index.html
```
Would require code like this
```js
win.loadFile('src/index.html')
```
#### `contents.downloadURL(url)`
2015-12-02 21:49:42 +00:00
* `url` string
2015-12-02 21:49:42 +00:00
Initiates a download of the resource at `url` without navigating. The
`will-download` event of `session` will be triggered.
#### `contents.getURL()`
2015-08-20 13:17:53 +00:00
Returns `string` - The URL of the current web page.
2015-08-20 13:17:53 +00:00
```javascript
2018-09-13 16:10:51 +00:00
const { BrowserWindow } = require('electron')
2020-07-09 17:18:49 +00:00
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('http://github.com').then(() => {
const currentURL = win.webContents.getURL()
console.log(currentURL)
})
2015-08-20 13:17:53 +00:00
```
#### `contents.getTitle()`
2015-08-20 13:17:53 +00:00
Returns `string` - The title of the current web page.
2015-08-20 13:17:53 +00:00
#### `contents.isDestroyed()`
Returns `boolean` - Whether the web page is destroyed.
2017-06-15 17:19:27 +00:00
#### `contents.focus()`
Focuses the web page.
#### `contents.isFocused()`
2016-07-13 21:20:33 +00:00
Returns `boolean` - Whether the web page is focused.
2016-07-13 21:20:33 +00:00
#### `contents.isLoading()`
2015-08-20 13:17:53 +00:00
Returns `boolean` - Whether web page is still loading resources.
2015-08-20 13:17:53 +00:00
#### `contents.isLoadingMainFrame()`
Returns `boolean` - Whether the main frame (and not just iframes or frames within it) is
still loading.
#### `contents.isWaitingForResponse()`
2015-08-20 13:17:53 +00:00
Returns `boolean` - Whether the web page is waiting for a first-response from the main
2015-08-24 22:41:02 +00:00
resource of the page.
2015-08-20 13:17:53 +00:00
#### `contents.stop()`
2015-08-20 13:17:53 +00:00
Stops any pending navigation.
#### `contents.reload()`
2015-08-20 13:17:53 +00:00
2015-08-20 17:03:53 +00:00
Reloads the current web page.
2015-08-20 13:17:53 +00:00
#### `contents.reloadIgnoringCache()`
2015-08-20 13:17:53 +00:00
Reloads current page and ignores cache.
#### `contents.canGoBack()`
2015-08-20 13:17:53 +00:00
Returns `boolean` - Whether the browser can go back to previous web page.
2015-08-20 13:17:53 +00:00
#### `contents.canGoForward()`
2015-08-20 13:17:53 +00:00
Returns `boolean` - Whether the browser can go forward to next web page.
2015-08-20 13:17:53 +00:00
#### `contents.canGoToOffset(offset)`
2015-08-20 13:17:53 +00:00
* `offset` Integer
Returns `boolean` - Whether the web page can go to `offset`.
2015-08-20 13:17:53 +00:00
#### `contents.clearHistory()`
2015-08-20 13:17:53 +00:00
Clears the navigation history.
#### `contents.goBack()`
2015-08-20 13:17:53 +00:00
2015-08-20 17:03:53 +00:00
Makes the browser go back a web page.
2015-08-20 13:17:53 +00:00
#### `contents.goForward()`
2015-08-20 13:17:53 +00:00
2015-08-20 17:03:53 +00:00
Makes the browser go forward a web page.
2015-08-20 13:17:53 +00:00
#### `contents.goToIndex(index)`
2015-08-20 13:17:53 +00:00
* `index` Integer
2015-08-20 17:03:53 +00:00
Navigates browser to the specified absolute web page index.
2015-08-20 13:17:53 +00:00
#### `contents.goToOffset(offset)`
2015-08-20 13:17:53 +00:00
* `offset` Integer
Navigates to the specified offset from the "current entry".
#### `contents.isCrashed()`
2015-08-20 13:17:53 +00:00
Returns `boolean` - Whether the renderer process has crashed.
2015-08-20 13:17:53 +00:00
#### `contents.forcefullyCrashRenderer()`
Forcefully terminates the renderer process that is currently hosting this
`webContents`. This will cause the `render-process-gone` event to be emitted
with the `reason=killed || reason=crashed`. Please note that some webContents share renderer
processes and therefore calling this method may also crash the host process
for other webContents as well.
Calling `reload()` immediately after calling this
method will force the reload to occur in a new process. This should be used
when this process is unstable or unusable, for instance in order to recover
from the `unresponsive` event.
```js
contents.on('unresponsive', async () => {
const { response } = await dialog.showMessageBox({
message: 'App X has become unresponsive',
title: 'Do you want to try forcefully reloading the app?',
buttons: ['OK', 'Cancel'],
cancelId: 1
})
if (response === 0) {
contents.forcefullyCrashRenderer()
contents.reload()
}
})
```
#### `contents.setUserAgent(userAgent)`
2015-08-20 13:17:53 +00:00
* `userAgent` string
2015-08-20 13:17:53 +00:00
Overrides the user agent for this web page.
2015-08-20 13:17:53 +00:00
#### `contents.getUserAgent()`
2015-08-20 13:17:53 +00:00
Returns `string` - The user agent for this web page.
2015-08-20 13:17:53 +00:00
#### `contents.insertCSS(css[, options])`
2015-08-20 13:17:53 +00:00
* `css` string
* `options` Object (optional)
* `cssOrigin` string (optional) - Can be either 'user' or 'author'; Specifying 'user' enables you to prevent websites from overriding the CSS you insert. Default is 'author'.
2015-08-20 13:17:53 +00:00
Returns `Promise<string>` - A promise that resolves with a key for the inserted CSS that can later be used to remove the CSS via `contents.removeInsertedCSS(key)`.
2019-06-17 15:39:36 +00:00
Injects CSS into the current web page and returns a unique key for the inserted
stylesheet.
2015-08-20 13:17:53 +00:00
```js
contents.on('did-finish-load', () => {
contents.insertCSS('html, body { background-color: #f00; }')
})
```
2019-06-17 15:39:36 +00:00
#### `contents.removeInsertedCSS(key)`
* `key` string
2019-06-17 15:39:36 +00:00
Returns `Promise<void>` - Resolves if the removal was successful.
Removes the inserted CSS from the current web page. The stylesheet is identified
by its key, which is returned from `contents.insertCSS(css)`.
```js
contents.on('did-finish-load', async () => {
2019-06-17 15:39:36 +00:00
const key = await contents.insertCSS('html, body { background-color: #f00; }')
contents.removeInsertedCSS(key)
})
```
#### `contents.executeJavaScript(code[, userGesture])`
* `code` string
* `userGesture` boolean (optional) - Default is `false`.
Returns `Promise<any>` - A promise that resolves with the result of the executed code
or is rejected if the result of the code is a rejected promise.
Evaluates `code` in page.
In the browser window some HTML APIs like `requestFullScreen` can only be
invoked by a gesture from the user. Setting `userGesture` to `true` will remove
this limitation.
Code execution will be suspended until web page stop loading.
```js
contents.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1").then(resp => resp.json())', true)
.then((result) => {
console.log(result) // Will be the JSON object from the fetch call
})
```
#### `contents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])`
* `worldId` Integer - The ID of the world to run the javascript in, `0` is the default world, `999` is the world used by Electron's `contextIsolation` feature. You can provide any integer here.
* `scripts` [WebSource[]](structures/web-source.md)
* `userGesture` boolean (optional) - Default is `false`.
Returns `Promise<any>` - A promise that resolves with the result of the executed code
or is rejected if the result of the code is a rejected promise.
Works like `executeJavaScript` but evaluates `scripts` in an isolated context.
#### `contents.setIgnoreMenuShortcuts(ignore)`
* `ignore` boolean
Ignore application menu shortcuts while this web contents is focused.
#### `contents.setWindowOpenHandler(handler)`
* `handler` Function<{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}>
* `details` Object
* `url` string - The _resolved_ version of the URL passed to `window.open()`. e.g. opening a window with `window.open('foo')` will yield something like `https://the-origin/the/current/path/foo`.
* `frameName` string - Name of the window provided in `window.open()`
* `features` string - Comma separated list of window features provided to `window.open()`.
* `disposition` string - Can be `default`, `foreground-tab`, `background-tab`,
`new-window`, `save-to-disk` or `other`.
* `referrer` [Referrer](structures/referrer.md) - The referrer that will be
passed to the new window. May or may not result in the `Referer` header being
sent, depending on the referrer policy.
* `postBody` [PostBody](structures/post-body.md) (optional) - The post data that
will be sent to the new window, along with the appropriate headers that will
be set. If no post data is to be sent, the value will be `null`. Only defined
when the window is being created by a form that set `target=_blank`.
Returns `{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}` - `deny` cancels the creation of the new
window. `allow` will allow the new window to be created. Specifying `overrideBrowserWindowOptions` allows customization of the created window.
Returning an unrecognized value such as a null, undefined, or an object
without a recognized 'action' value will result in a console error and have
the same effect as returning `{action: 'deny'}`.
Called before creating a window a new window is requested by the renderer, e.g.
by `window.open()`, a link with `target="_blank"`, shift+clicking on a link, or
submitting a form with `<form target="_blank">`. See
[`window.open()`](window-open.md) for more details and how to use this in
conjunction with `did-create-window`.
#### `contents.setAudioMuted(muted)`
2015-08-20 13:17:53 +00:00
* `muted` boolean
2015-08-20 13:17:53 +00:00
2015-08-20 17:03:53 +00:00
Mute the audio on the current web page.
2015-08-20 13:17:53 +00:00
#### `contents.isAudioMuted()`
2015-08-20 13:17:53 +00:00
Returns `boolean` - Whether this page has been muted.
2015-08-20 13:17:53 +00:00
#### `contents.isCurrentlyAudible()`
Returns `boolean` - Whether audio is currently playing.
#### `contents.setZoomFactor(factor)`
* `factor` Double - Zoom factor; default is 1.0.
Changes the zoom factor to the specified factor. Zoom factor is
zoom percent divided by 100, so 300% = 3.0.
The factor must be greater than 0.0.
#### `contents.getZoomFactor()`
Returns `number` - the current zoom factor.
#### `contents.setZoomLevel(level)`
* `level` number - Zoom level.
Changes the zoom level to the specified level. The original size is 0 and each
increment above or below represents zooming 20% larger or smaller to default
2018-02-10 04:20:45 +00:00
limits of 300% and 50% of original size, respectively. The formula for this is
`scale := 1.2 ^ level`.
> **NOTE**: The zoom policy at the Chromium level is same-origin, meaning that the
> zoom level for a specific domain propagates across all instances of windows with
> the same domain. Differentiating the window URLs will make zoom work per-window.
#### `contents.getZoomLevel()`
2016-08-02 05:44:06 +00:00
Returns `number` - the current zoom level.
#### `contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)`
* `minimumLevel` number
* `maximumLevel` number
Returns `Promise<void>`
Sets the maximum and minimum pinch-to-zoom level.
> **NOTE**: Visual zoom is disabled by default in Electron. To re-enable it, call:
>
> ```js
> contents.setVisualZoomLevelLimits(1, 3)
> ```
#### `contents.undo()`
2015-08-20 13:17:53 +00:00
Executes the editing command `undo` in web page.
2015-08-20 13:17:53 +00:00
#### `contents.redo()`
2015-08-20 13:17:53 +00:00
Executes the editing command `redo` in web page.
2015-08-20 13:17:53 +00:00
#### `contents.cut()`
2015-08-20 13:17:53 +00:00
Executes the editing command `cut` in web page.
2015-08-20 13:17:53 +00:00
#### `contents.copy()`
2015-08-20 13:17:53 +00:00
Executes the editing command `copy` in web page.
2015-08-20 13:17:53 +00:00
2016-08-25 21:42:53 +00:00
#### `contents.copyImageAt(x, y)`
2016-07-26 19:08:05 +00:00
* `x` Integer
* `y` Integer
Copy the image at the given position to the clipboard.
#### `contents.paste()`
2015-08-20 13:17:53 +00:00
Executes the editing command `paste` in web page.
2015-08-20 13:17:53 +00:00
#### `contents.pasteAndMatchStyle()`
2015-08-20 13:17:53 +00:00
Executes the editing command `pasteAndMatchStyle` in web page.
2015-08-20 13:17:53 +00:00
#### `contents.delete()`
2015-08-20 13:17:53 +00:00
Executes the editing command `delete` in web page.
2015-08-20 13:17:53 +00:00
#### `contents.selectAll()`
2015-08-20 13:17:53 +00:00
Executes the editing command `selectAll` in web page.
2015-08-20 13:17:53 +00:00
#### `contents.unselect()`
2015-08-20 13:17:53 +00:00
Executes the editing command `unselect` in web page.
2015-08-20 13:17:53 +00:00
#### `contents.replace(text)`
2015-08-20 13:17:53 +00:00
* `text` string
2015-08-20 13:17:53 +00:00
Executes the editing command `replace` in web page.
2015-08-20 13:17:53 +00:00
#### `contents.replaceMisspelling(text)`
2015-08-20 13:17:53 +00:00
* `text` string
2015-08-20 13:17:53 +00:00
Executes the editing command `replaceMisspelling` in web page.
2015-08-20 13:17:53 +00:00
#### `contents.insertText(text)`
2016-01-13 03:55:49 +00:00
* `text` string
2016-01-13 03:55:49 +00:00
Returns `Promise<void>`
2016-01-13 03:55:49 +00:00
Inserts `text` to the focused element.
#### `contents.findInPage(text[, options])`
2015-12-17 17:27:56 +00:00
* `text` string - Content to be searched, must not be empty.
2016-02-16 03:54:41 +00:00
* `options` Object (optional)
* `forward` boolean (optional) - Whether to search forward or backward, defaults to `true`.
* `findNext` boolean (optional) - Whether to begin a new text finding session with this request. Should be `true` for initial requests, and `false` for follow-up requests. Defaults to `false`.
* `matchCase` boolean (optional) - Whether search should be case-sensitive,
2015-12-17 23:10:42 +00:00
defaults to `false`.
2015-12-17 17:27:56 +00:00
Returns `Integer` - The request id used for the request.
Starts a request to find all matches for the `text` in the web page. The result of the request
can be obtained by subscribing to [`found-in-page`](web-contents.md#event-found-in-page) event.
2015-12-17 17:27:56 +00:00
#### `contents.stopFindInPage(action)`
2015-12-17 17:27:56 +00:00
* `action` string - Specifies the action to take place when ending
[`webContents.findInPage`] request.
* `clearSelection` - Clear the selection.
* `keepSelection` - Translate the selection into a normal selection.
2015-12-17 23:10:42 +00:00
* `activateSelection` - Focus and click the selection node.
2015-12-17 17:27:56 +00:00
2015-12-17 23:10:42 +00:00
Stops any `findInPage` request for the `webContents` with the provided `action`.
2015-12-17 17:27:56 +00:00
```javascript
2018-09-13 16:10:51 +00:00
const { webContents } = require('electron')
webContents.on('found-in-page', (event, result) => {
if (result.finalUpdate) webContents.stopFindInPage('clearSelection')
})
2015-12-17 17:27:56 +00:00
const requestId = webContents.findInPage('api')
console.log(requestId)
2015-12-17 23:10:42 +00:00
```
2015-12-17 17:27:56 +00:00
#### `contents.capturePage([rect])`
* `rect` [Rectangle](structures/rectangle.md) (optional) - The area of the page to be captured.
2019-04-16 23:03:17 +00:00
Returns `Promise<NativeImage>` - Resolves with a [NativeImage](native-image.md)
Captures a snapshot of the page within `rect`. Omitting `rect` will capture the whole visible page.
#### `contents.isBeingCaptured()`
Returns `boolean` - Whether this page is being captured. It returns true when the capturer count
is large then 0.
chore: bump chromium to 92.0.4475.0 (master) (#28462) * chore: bump chromium in DEPS to 91.0.4464.0 * chore: rebuild chromium/dcheck.patch with import-patches -3 Mechanical only; no code changes * chore: remove content_browser_main_loop.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2725153 The function being patched (BrowserMainLoop::MainMessageLoopRun()) no longer exists. NB: if removing this introduces regressions the likely fix will be to add a similar patch for ShellBrowserMainParts::WillRunMainMessageLoop() which has similar code and was added at the same time this was removed. * chore: rebuild chromium/put_back_deleted_colors_for_autofill.patch with import-patches -3 Mechanical only; no code changes * chore: rebuild chromium/disable_color_correct_rendering.patch with import-patches -3 Mechanical only; no code changes * chore: rebuild chromium/eat_allow_disabling_blink_scheduler_throttling_per_renderview.patch with patch Mechanical only; no code changes * chore: rebuild chromium/gpu_notify_when_dxdiag_request_fails.patch with import-patches -3 Mechanical only; no code changes * chore: rebuild chromium/ui_gtk_public_header.patch manually no code changes * chore: rebuild chromium/web_contents.patch with import-patches -3 Mechanical only; no code changes * chore: remove v8/skip_global_registration_of_shared_arraybuffer_backing_stores.patch Refs: https://chromium-review.googlesource.com/c/v8/v8/+/2763874 This patch has been merged upstream * chore: export patches * chore: update add_trustedauthclient_to_urlloaderfactory.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2757969 Sync with removal of render_frame_id_ * chore: sync chromium/put_back_deleted_colors_for_autofill.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2785841 SkColorFromColorId() no longer takes theme, scheme args * chore: sync chromium/put_back_deleted_colors_for_autofill.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2772143 Change new calls to GetDarkSchemeColor to fit our patched call signature * chore: update add_trustedauthclient_to_urlloaderfactory.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2757969 Sync with removal of render_frame_id_ in our mojom * chore: update chromium/frame_host_manager.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2740008 UrlInfo ctor now takes UrlInfo::OriginIsolationRequest instead of a bool * chore: update chromium/revert_remove_contentrendererclient_shouldfork.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2755314 Upstream has removed `history_list_length_` which we were comparing to 0 to calculate our `is_initial_navigation` bool when calling ShouldFork(). ShouldFork() is ours and none of the code paths actually use that param, so this commit removes it altogether. * chore: update permissions_to_register Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2789074 Replace all uses of APIPermission::ID enum with Mojo type * refactor: update return type of PreMainMessageLoopRun() Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2725153 Used to return void; now returns an int errorcode. Note: 2725153 also has some nice doc updates about Browser's "stages" * refactor: sync ElectronBrowserMainParts to MainParts changes Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2725153 RunMainMessageLoopParts has been replaced with WillRunMainMessageLoop so `BrowserMainLoop::result_code_` is no longer available to us for our exit_code_ pointer. This variable held a dual role: (1) of course, hold the exit code, but also (2) was a nullptr before the message loop was ready, indicating to anyone calling SetExitCode() that we were still in startup and could just exit() without any extra steps. exit_code_ still fulfills these two roles but is now a base::Optional. * chore: update ElectronBrowserMainParts::PreDefaultMainMessageLoopRun Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2725153 BrowserMainParts::BrowsePreDefaultMainMesssageLoopRun() has been removed; move that work to the new WillRunMainMessageLoop(). * refactor: stop using CallbackList; it has been removed. Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2785973 * refactor: update use of threadpools. Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2773408 The upstream code is still in flux (e.g. reverts and re-lands) but the tl;dr for this commit is (1) include thread_pool.h if you're using it and (2) don't instantiate pools directly. * refactor: remove routing_id from CreateLoaderAndStart Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2762858 NB: One logic branch in ProxyingURLLoaderFactory::CreateLoaderAndStart calls std::make_unique<InProgressRequest>, which needs a routing_id. This PR uses the member field `routing_id_` since there's no longer one being passed into CreateLoaderAndStart. * refactor: sync to upstream ParittionOptions churn Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2771318 PartitionOptions' enums have changed. * refactor: update Manifest::Location usage Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2771320 tldr: s/Manifest::FOO/ManifestLocation::kFoo/ * chore: bump chromium in DEPS to 91.0.4465.0 * update patches * refactor: update extensions::Manifest to upstream Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2771320 - extensions::Manifest::COMPONENT + extensions::mojom::ManifestLocation::kExternalComponent * refactor: sync with upstream UrlInfo ctor changes Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2740008 UrlInfo ctor now takes UrlInfo::OriginIsolationRequest instead of a bool * chore: update invocation of convert_protocol_to_json.py Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2792623 python3 is being used in parts of the upstream build, but the copy of convert_protocol_to_json.py invoked in v8/third_party/inspector_protocol is not python3-friendly. Node has a py2+3-friendly version of it in its tools directory, so call it instead. * chore: use extensions::mojom::APIPermissionID Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2791122 tldr: - extensions::APIPermission::kFoo + extensions::mojom::APIPermissionID::kFoo * chore: Remove support for TLS1.0/1.1 in SSLVersionMin policy Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2765737 Remove TLS v1.0 & 1.1 from our SSLProtocolVersionFromString() function. This is the same change made upstream at https://chromium-review.googlesource.com/c/chromium/src/+/2765737/8/chrome/browser/ssl/ssl_config_service_manager_pref.cc * fixup! chore: update ElectronBrowserMainParts::PreDefaultMainMessageLoopRun * chore: Use IDType for permission change subscriptions. Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2791431 tldr: {Subscribe,Unsubscribe}PermissionStatusChange's tag type used to be an int; now it's the new SubscriptionId type (which is an IdType64). * chore: sync PowerMonitor code to upstream refactor Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2752635 tldr: PowerMonitor has been split into PowerStateObserver, PowerSuspendObserver, and PowerThermalObserver to reduce number of tasks posted to consumers who only need notifications for one of those things instead of all of them. * chore: use PartitionOptions's new Cookies field Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2771318 * Revert "refactor: remove routing_id from CreateLoaderAndStart" This reverts commit 8c9773b87a3c84f9073a47089eb2b6889d745245. 8c9773b was only a partial fix; reverting to start & try again. * update patches * chore: bump chromium in DEPS to 91.0.4466.0 * chore: update chromium/accelerator.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2795472 tldr: sync patch with upstream renamed variable & macro names. * chore: update chromium/gtk_visibility.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2796200 tldr: no code changes; just updating the diff to apply cleanly. note: ooh upstream Wayland hacking! * chore: update chromium/picture-in-picture.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2710023 tldr: no code changes; just updating the diff to apply cleanly. * chore: update chromium/worker_feat_add_hook_to_notify_script_ready.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2775573 tldr: no code changes; just updating the diff to apply cleanly. * chore: export_all_patches * chore: update chromium/feat_add_set_theme_source_to_allow_apps_to.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2796511 tldr: NotifyObservers has been renamed to NotifyOnNativeThemeUpdated, so update the invocation in our patch. * chore: update ElectronBrowserClient w/upstream API Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2797454 tldr: GetDevToolsManagerDelegate() was returning an owned raw pointer. Replaced it with CreateDevToolsManagerDelegate() which uses unique_ptr<>. * chore: handle new content::PermissionType::FILE_HANDLING in toV8() Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2762201 `file-handling` string confirmed in https://chromium-review.googlesource.com/c/chromium/src/+/2762201/18/chrome/browser/ui/webui/settings/site_settings_helper.cc * refactor: remove routing_id from CreateLoaderAndStart pt 1 Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2762858 Part 1: the easiest ones * 2796724: Support Python3 https://chromium-review.googlesource.com/c/infra/luci/python-adb/+/2796724 * chore: bump chromium in DEPS to 91.0.4468.0 * 2668974: WebShare: Implement SharingServicePicker https://chromium-review.googlesource.com/c/chromium/src/+/2668974 * 2802766: Apply modernize-make-unique to media/ https://chromium-review.googlesource.com/c/chromium/src/+/2802766 * 2802823: Apply modernize-make-unique to gpu/ https://chromium-review.googlesource.com/c/chromium/src/+/2802823 * 2803041: Apply modernize-make-unique to remaining files https://chromium-review.googlesource.com/c/chromium/src/+/2803041 * 2798873: Convert GtkKeyBindingsHandler build checks to runtime checks https://chromium-review.googlesource.com/c/chromium/src/+/2798873 * 2733595: [ch-r] Parse ACCEPT_CH H2/3 frame and restart with new headers if needed https://chromium-review.googlesource.com/c/chromium/src/+/2733595 * chore: update patch indices * 2795107: Remove unused PermissionRequest IDs. https://chromium-review.googlesource.com/c/chromium/src/+/2795107 * chore: bump chromium in DEPS to 91.0.4469.0 * chore: fixup patch indices * chore: bump chromium in DEPS to 91.0.4469.5 * PiP 1.5: Add microphone, camera, and hang up buttons to the PiP window https://chromium-review.googlesource.com/c/chromium/src/+/2710023 * fixup! refactor: remove routing_id from CreateLoaderAndStart * refactor: use URLLoaderNetworkServiceObserver for auth requests from SimpleURLLoader * fixup! chore: fixup patch indices * 2724817: Expand scope of wasm-eval to all URLs https://chromium-review.googlesource.com/c/chromium/src/+/2724817 * Fixup patch after rebase * chore: bump chromium in DEPS to 91.0.4472.0 * 2797341: [ozone/x11] Enabled the global shortcut listener. https://chromium-review.googlesource.com/c/chromium/src/+/2797341 * 2805553: Reland Add GTK ColorMixers to ColorPipeline P1 https://chromium-review.googlesource.com/c/chromium/src/+/2805553 * 2804366: PiP 1.5: Label back to tab button with origin and center it https://chromium-review.googlesource.com/c/chromium/src/+/2804366 * 2784730: Fix crash on AX mode change in NativeViewHost without a Widget https://chromium-review.googlesource.com/c/chromium/src/+/2784730 * chore: update patch indices * 2810174: Add PdfAnnotationsEnabled policy. https://chromium-review.googlesource.com/c/chromium/src/+/2810174 * 2807829: Allow capturers to indicate if they want a WakeLock or not. https://chromium-review.googlesource.com/c/chromium/src/+/2807829 * chore: bump chromium in DEPS to 92.0.4473.0 * chore: bump chromium in DEPS to 92.0.4474.0 * chore: bump chromium in DEPS to 92.0.4475.0 * chore: update patches * chore: updates patches * chore: update is_media_key patch to handle new ozone impl Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2797341 * fix: ExecuteJavascript requests now need to be flagged as non-bf-aware Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2787195 * chore: icon_util_x11 is now icon_util_linux Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2791362 * build: update sysroots Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2628496 * build: fix missing symbols on linux build * use_ozone and use_x11 are not exclusive * new button view to build for pip Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2797341 Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2804366 * chore: fix broken gtk_util color patch * chore: remove patch conflict * build: update linux manifests * chore: build bttlb on all platforms for pip * chore: add thread_pool include for views delegate win * chore: fix lint * chore: add node patches for V8 changes * build: add missing base include on windows * fix: update frame host manager patch for new state transitions Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2714464 * chore: update windows zip manifests * chore: update mac zip manifests * chore: fix patch linting * refactor: implement missing URLLoaderNetworkServiceObserver methods It is against The Mojo Rules to leave hanging callbacks. These always have to be called. Refs: https://github.com/electron/electron/commit/186528aab9f8e29d658f07d220bb7f627980edda * spec: fix locale test on local linux * fix: pass the exit code correctly in new PreMainMessageLoopRun Refs: https://github.com/electron/electron/commit/2622e91c4493ceb032e2f80cb484885bb8f97475 * fix: ensure we early-exit when request_handler_ is not provided Refs: https://github.com/electron/electron/commit/93077afbfb6db248a0c0cc447d7ad2c9ccfda1d5 * fix: strongly set result_code in the BrowserMainLoop * fix: invalid usage of non-targetted PostTask You must always either use a host threadpool or specify a target thread. In this case we did neither after this refactor. Refs: https://github.com/electron/electron/pull/28462/commits/4e33ee0ad35a710bd34641cb0376bdee6aea2d1f * chore: fix gn check * chore: remove stray .rej files in patch * chore: add mojo error code to url loader failure * build: ensure CI is truthy in arm test env * fix: handle windowCaptureMacV2 being enabled when fetching media source id Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2709931 Co-authored-by: Charles Kerr <charles@charleskerr.com> Co-authored-by: Shelley Vohr <shelley.vohr@gmail.com> Co-authored-by: deepak1556 <hop2deep@gmail.com> Co-authored-by: Samuel Attard <samuel.r.attard@gmail.com> Co-authored-by: Samuel Attard <sattard@slack-corp.com>
2021-04-15 17:44:35 +00:00
#### `contents.incrementCapturerCount([size, stayHidden, stayAwake])`
* `size` [Size](structures/size.md) (optional) - The preferred size for the capturer.
* `stayHidden` boolean (optional) - Keep the page hidden instead of visible.
* `stayAwake` boolean (optional) - Keep the system awake instead of allowing it to sleep.
Increase the capturer count by one. The page is considered visible when its browser window is
hidden and the capturer count is non-zero. If you would like the page to stay hidden, you should ensure that `stayHidden` is set to true.
This also affects the Page Visibility API.
chore: bump chromium to 92.0.4475.0 (master) (#28462) * chore: bump chromium in DEPS to 91.0.4464.0 * chore: rebuild chromium/dcheck.patch with import-patches -3 Mechanical only; no code changes * chore: remove content_browser_main_loop.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2725153 The function being patched (BrowserMainLoop::MainMessageLoopRun()) no longer exists. NB: if removing this introduces regressions the likely fix will be to add a similar patch for ShellBrowserMainParts::WillRunMainMessageLoop() which has similar code and was added at the same time this was removed. * chore: rebuild chromium/put_back_deleted_colors_for_autofill.patch with import-patches -3 Mechanical only; no code changes * chore: rebuild chromium/disable_color_correct_rendering.patch with import-patches -3 Mechanical only; no code changes * chore: rebuild chromium/eat_allow_disabling_blink_scheduler_throttling_per_renderview.patch with patch Mechanical only; no code changes * chore: rebuild chromium/gpu_notify_when_dxdiag_request_fails.patch with import-patches -3 Mechanical only; no code changes * chore: rebuild chromium/ui_gtk_public_header.patch manually no code changes * chore: rebuild chromium/web_contents.patch with import-patches -3 Mechanical only; no code changes * chore: remove v8/skip_global_registration_of_shared_arraybuffer_backing_stores.patch Refs: https://chromium-review.googlesource.com/c/v8/v8/+/2763874 This patch has been merged upstream * chore: export patches * chore: update add_trustedauthclient_to_urlloaderfactory.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2757969 Sync with removal of render_frame_id_ * chore: sync chromium/put_back_deleted_colors_for_autofill.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2785841 SkColorFromColorId() no longer takes theme, scheme args * chore: sync chromium/put_back_deleted_colors_for_autofill.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2772143 Change new calls to GetDarkSchemeColor to fit our patched call signature * chore: update add_trustedauthclient_to_urlloaderfactory.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2757969 Sync with removal of render_frame_id_ in our mojom * chore: update chromium/frame_host_manager.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2740008 UrlInfo ctor now takes UrlInfo::OriginIsolationRequest instead of a bool * chore: update chromium/revert_remove_contentrendererclient_shouldfork.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2755314 Upstream has removed `history_list_length_` which we were comparing to 0 to calculate our `is_initial_navigation` bool when calling ShouldFork(). ShouldFork() is ours and none of the code paths actually use that param, so this commit removes it altogether. * chore: update permissions_to_register Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2789074 Replace all uses of APIPermission::ID enum with Mojo type * refactor: update return type of PreMainMessageLoopRun() Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2725153 Used to return void; now returns an int errorcode. Note: 2725153 also has some nice doc updates about Browser's "stages" * refactor: sync ElectronBrowserMainParts to MainParts changes Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2725153 RunMainMessageLoopParts has been replaced with WillRunMainMessageLoop so `BrowserMainLoop::result_code_` is no longer available to us for our exit_code_ pointer. This variable held a dual role: (1) of course, hold the exit code, but also (2) was a nullptr before the message loop was ready, indicating to anyone calling SetExitCode() that we were still in startup and could just exit() without any extra steps. exit_code_ still fulfills these two roles but is now a base::Optional. * chore: update ElectronBrowserMainParts::PreDefaultMainMessageLoopRun Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2725153 BrowserMainParts::BrowsePreDefaultMainMesssageLoopRun() has been removed; move that work to the new WillRunMainMessageLoop(). * refactor: stop using CallbackList; it has been removed. Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2785973 * refactor: update use of threadpools. Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2773408 The upstream code is still in flux (e.g. reverts and re-lands) but the tl;dr for this commit is (1) include thread_pool.h if you're using it and (2) don't instantiate pools directly. * refactor: remove routing_id from CreateLoaderAndStart Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2762858 NB: One logic branch in ProxyingURLLoaderFactory::CreateLoaderAndStart calls std::make_unique<InProgressRequest>, which needs a routing_id. This PR uses the member field `routing_id_` since there's no longer one being passed into CreateLoaderAndStart. * refactor: sync to upstream ParittionOptions churn Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2771318 PartitionOptions' enums have changed. * refactor: update Manifest::Location usage Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2771320 tldr: s/Manifest::FOO/ManifestLocation::kFoo/ * chore: bump chromium in DEPS to 91.0.4465.0 * update patches * refactor: update extensions::Manifest to upstream Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2771320 - extensions::Manifest::COMPONENT + extensions::mojom::ManifestLocation::kExternalComponent * refactor: sync with upstream UrlInfo ctor changes Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2740008 UrlInfo ctor now takes UrlInfo::OriginIsolationRequest instead of a bool * chore: update invocation of convert_protocol_to_json.py Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2792623 python3 is being used in parts of the upstream build, but the copy of convert_protocol_to_json.py invoked in v8/third_party/inspector_protocol is not python3-friendly. Node has a py2+3-friendly version of it in its tools directory, so call it instead. * chore: use extensions::mojom::APIPermissionID Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2791122 tldr: - extensions::APIPermission::kFoo + extensions::mojom::APIPermissionID::kFoo * chore: Remove support for TLS1.0/1.1 in SSLVersionMin policy Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2765737 Remove TLS v1.0 & 1.1 from our SSLProtocolVersionFromString() function. This is the same change made upstream at https://chromium-review.googlesource.com/c/chromium/src/+/2765737/8/chrome/browser/ssl/ssl_config_service_manager_pref.cc * fixup! chore: update ElectronBrowserMainParts::PreDefaultMainMessageLoopRun * chore: Use IDType for permission change subscriptions. Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2791431 tldr: {Subscribe,Unsubscribe}PermissionStatusChange's tag type used to be an int; now it's the new SubscriptionId type (which is an IdType64). * chore: sync PowerMonitor code to upstream refactor Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2752635 tldr: PowerMonitor has been split into PowerStateObserver, PowerSuspendObserver, and PowerThermalObserver to reduce number of tasks posted to consumers who only need notifications for one of those things instead of all of them. * chore: use PartitionOptions's new Cookies field Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2771318 * Revert "refactor: remove routing_id from CreateLoaderAndStart" This reverts commit 8c9773b87a3c84f9073a47089eb2b6889d745245. 8c9773b was only a partial fix; reverting to start & try again. * update patches * chore: bump chromium in DEPS to 91.0.4466.0 * chore: update chromium/accelerator.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2795472 tldr: sync patch with upstream renamed variable & macro names. * chore: update chromium/gtk_visibility.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2796200 tldr: no code changes; just updating the diff to apply cleanly. note: ooh upstream Wayland hacking! * chore: update chromium/picture-in-picture.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2710023 tldr: no code changes; just updating the diff to apply cleanly. * chore: update chromium/worker_feat_add_hook_to_notify_script_ready.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2775573 tldr: no code changes; just updating the diff to apply cleanly. * chore: export_all_patches * chore: update chromium/feat_add_set_theme_source_to_allow_apps_to.patch Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2796511 tldr: NotifyObservers has been renamed to NotifyOnNativeThemeUpdated, so update the invocation in our patch. * chore: update ElectronBrowserClient w/upstream API Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2797454 tldr: GetDevToolsManagerDelegate() was returning an owned raw pointer. Replaced it with CreateDevToolsManagerDelegate() which uses unique_ptr<>. * chore: handle new content::PermissionType::FILE_HANDLING in toV8() Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2762201 `file-handling` string confirmed in https://chromium-review.googlesource.com/c/chromium/src/+/2762201/18/chrome/browser/ui/webui/settings/site_settings_helper.cc * refactor: remove routing_id from CreateLoaderAndStart pt 1 Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2762858 Part 1: the easiest ones * 2796724: Support Python3 https://chromium-review.googlesource.com/c/infra/luci/python-adb/+/2796724 * chore: bump chromium in DEPS to 91.0.4468.0 * 2668974: WebShare: Implement SharingServicePicker https://chromium-review.googlesource.com/c/chromium/src/+/2668974 * 2802766: Apply modernize-make-unique to media/ https://chromium-review.googlesource.com/c/chromium/src/+/2802766 * 2802823: Apply modernize-make-unique to gpu/ https://chromium-review.googlesource.com/c/chromium/src/+/2802823 * 2803041: Apply modernize-make-unique to remaining files https://chromium-review.googlesource.com/c/chromium/src/+/2803041 * 2798873: Convert GtkKeyBindingsHandler build checks to runtime checks https://chromium-review.googlesource.com/c/chromium/src/+/2798873 * 2733595: [ch-r] Parse ACCEPT_CH H2/3 frame and restart with new headers if needed https://chromium-review.googlesource.com/c/chromium/src/+/2733595 * chore: update patch indices * 2795107: Remove unused PermissionRequest IDs. https://chromium-review.googlesource.com/c/chromium/src/+/2795107 * chore: bump chromium in DEPS to 91.0.4469.0 * chore: fixup patch indices * chore: bump chromium in DEPS to 91.0.4469.5 * PiP 1.5: Add microphone, camera, and hang up buttons to the PiP window https://chromium-review.googlesource.com/c/chromium/src/+/2710023 * fixup! refactor: remove routing_id from CreateLoaderAndStart * refactor: use URLLoaderNetworkServiceObserver for auth requests from SimpleURLLoader * fixup! chore: fixup patch indices * 2724817: Expand scope of wasm-eval to all URLs https://chromium-review.googlesource.com/c/chromium/src/+/2724817 * Fixup patch after rebase * chore: bump chromium in DEPS to 91.0.4472.0 * 2797341: [ozone/x11] Enabled the global shortcut listener. https://chromium-review.googlesource.com/c/chromium/src/+/2797341 * 2805553: Reland Add GTK ColorMixers to ColorPipeline P1 https://chromium-review.googlesource.com/c/chromium/src/+/2805553 * 2804366: PiP 1.5: Label back to tab button with origin and center it https://chromium-review.googlesource.com/c/chromium/src/+/2804366 * 2784730: Fix crash on AX mode change in NativeViewHost without a Widget https://chromium-review.googlesource.com/c/chromium/src/+/2784730 * chore: update patch indices * 2810174: Add PdfAnnotationsEnabled policy. https://chromium-review.googlesource.com/c/chromium/src/+/2810174 * 2807829: Allow capturers to indicate if they want a WakeLock or not. https://chromium-review.googlesource.com/c/chromium/src/+/2807829 * chore: bump chromium in DEPS to 92.0.4473.0 * chore: bump chromium in DEPS to 92.0.4474.0 * chore: bump chromium in DEPS to 92.0.4475.0 * chore: update patches * chore: updates patches * chore: update is_media_key patch to handle new ozone impl Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2797341 * fix: ExecuteJavascript requests now need to be flagged as non-bf-aware Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2787195 * chore: icon_util_x11 is now icon_util_linux Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2791362 * build: update sysroots Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2628496 * build: fix missing symbols on linux build * use_ozone and use_x11 are not exclusive * new button view to build for pip Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2797341 Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2804366 * chore: fix broken gtk_util color patch * chore: remove patch conflict * build: update linux manifests * chore: build bttlb on all platforms for pip * chore: add thread_pool include for views delegate win * chore: fix lint * chore: add node patches for V8 changes * build: add missing base include on windows * fix: update frame host manager patch for new state transitions Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2714464 * chore: update windows zip manifests * chore: update mac zip manifests * chore: fix patch linting * refactor: implement missing URLLoaderNetworkServiceObserver methods It is against The Mojo Rules to leave hanging callbacks. These always have to be called. Refs: https://github.com/electron/electron/commit/186528aab9f8e29d658f07d220bb7f627980edda * spec: fix locale test on local linux * fix: pass the exit code correctly in new PreMainMessageLoopRun Refs: https://github.com/electron/electron/commit/2622e91c4493ceb032e2f80cb484885bb8f97475 * fix: ensure we early-exit when request_handler_ is not provided Refs: https://github.com/electron/electron/commit/93077afbfb6db248a0c0cc447d7ad2c9ccfda1d5 * fix: strongly set result_code in the BrowserMainLoop * fix: invalid usage of non-targetted PostTask You must always either use a host threadpool or specify a target thread. In this case we did neither after this refactor. Refs: https://github.com/electron/electron/pull/28462/commits/4e33ee0ad35a710bd34641cb0376bdee6aea2d1f * chore: fix gn check * chore: remove stray .rej files in patch * chore: add mojo error code to url loader failure * build: ensure CI is truthy in arm test env * fix: handle windowCaptureMacV2 being enabled when fetching media source id Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2709931 Co-authored-by: Charles Kerr <charles@charleskerr.com> Co-authored-by: Shelley Vohr <shelley.vohr@gmail.com> Co-authored-by: deepak1556 <hop2deep@gmail.com> Co-authored-by: Samuel Attard <samuel.r.attard@gmail.com> Co-authored-by: Samuel Attard <sattard@slack-corp.com>
2021-04-15 17:44:35 +00:00
#### `contents.decrementCapturerCount([stayHidden, stayAwake])`
* `stayHidden` boolean (optional) - Keep the page in hidden state instead of visible.
* `stayAwake` boolean (optional) - Keep the system awake instead of allowing it to sleep.
Decrease the capturer count by one. The page will be set to hidden or occluded state when its
browser window is hidden or occluded and the capturer count reaches zero. If you want to
decrease the hidden capturer count instead you should set `stayHidden` to true.
#### `contents.getPrinters()` _Deprecated_
2017-05-18 17:50:08 +00:00
Get the system printer list.
2017-05-18 17:14:55 +00:00
Returns [`PrinterInfo[]`](structures/printer-info.md)
**Deprecated:** Should use the new [`contents.getPrintersAsync`](web-contents.md#contentsgetprintersasync) API.
#### `contents.getPrintersAsync()`
Get the system printer list.
Returns `Promise<PrinterInfo[]>` - Resolves with a [`PrinterInfo[]`](structures/printer-info.md)
#### `contents.print([options], [callback])`
2015-08-20 13:17:53 +00:00
* `options` Object (optional)
* `silent` boolean (optional) - Don't ask user for print settings. Default is `false`.
* `printBackground` boolean (optional) - Prints the background color and image of
the web page. Default is `false`.
* `deviceName` string (optional) - Set the printer device name to use. Must be the system-defined name and not the 'friendly' name, e.g 'Brother_QL_820NWB' and not 'Brother QL-820NWB'.
* `color` boolean (optional) - Set whether the printed web page will be in color or grayscale. Default is `true`.
* `margins` Object (optional)
* `marginType` string (optional) - Can be `default`, `none`, `printableArea`, or `custom`. If `custom` is chosen, you will also need to specify `top`, `bottom`, `left`, and `right`.
* `top` number (optional) - The top margin of the printed web page, in pixels.
* `bottom` number (optional) - The bottom margin of the printed web page, in pixels.
* `left` number (optional) - The left margin of the printed web page, in pixels.
* `right` number (optional) - The right margin of the printed web page, in pixels.
* `landscape` boolean (optional) - Whether the web page should be printed in landscape mode. Default is `false`.
* `scaleFactor` number (optional) - The scale factor of the web page.
* `pagesPerSheet` number (optional) - The number of pages to print per page sheet.
* `collate` boolean (optional) - Whether the web page should be collated.
* `copies` number (optional) - The number of copies of the web page to print.
* `pageRanges` Object[] (optional) - The page range to print. On macOS, only one range is honored.
* `from` number - Index of the first page to print (0-based).
* `to` number - Index of the last page to print (inclusive) (0-based).
* `duplexMode` string (optional) - Set the duplex mode of the printed web page. Can be `simplex`, `shortEdge`, or `longEdge`.
* `dpi` Record<string, number> (optional)
* `horizontal` number (optional) - The horizontal dpi.
* `vertical` number (optional) - The vertical dpi.
* `header` string (optional) - string to be printed as page header.
* `footer` string (optional) - string to be printed as page footer.
* `pageSize` string | Size (optional) - Specify page size of the printed document. Can be `A3`,
`A4`, `A5`, `Legal`, `Letter`, `Tabloid` or an Object containing `height`.
* `callback` Function (optional)
* `success` boolean - Indicates success of the print call.
* `failureReason` string - Error description called back if the print fails.
2015-08-20 13:17:53 +00:00
When a custom `pageSize` is passed, Chromium attempts to validate platform specific minimum values for `width_microns` and `height_microns`. Width and height must both be minimum 353 microns but may be higher on some operating systems.
Prints window's web page. When `silent` is set to `true`, Electron will pick
the system's default printer if `deviceName` is empty and the default settings for printing.
2015-08-20 13:17:53 +00:00
Use `page-break-before: always;` CSS style to force to print to a new page.
Example usage:
```js
const options = {
silent: true,
deviceName: 'My-Printer',
pageRanges: [{
from: 0,
to: 1
}]
}
win.webContents.print(options, (success, errorType) => {
if (!success) console.log(errorType)
})
```
#### `contents.printToPDF(options)`
* `options` Object
* `headerFooter` Record<string, string> (optional) - the header and footer for the PDF.
* `title` string - The title for the PDF header.
* `url` string - the url for the PDF footer.
* `landscape` boolean (optional) - `true` for landscape, `false` for portrait.
* `marginsType` Integer (optional) - Specifies the type of margins to use. Uses 0 for
default margin, 1 for no margin, and 2 for minimum margin.
* `scaleFactor` number (optional) - The scale factor of the web page. Can range from 0 to 100.
* `pageRanges` Record<string, number> (optional) - The page range to print.
* `from` number - Index of the first page to print (0-based).
* `to` number - Index of the last page to print (inclusive) (0-based).
* `pageSize` string | Size (optional) - Specify page size of the generated PDF. Can be `A3`,
`A4`, `A5`, `Legal`, `Letter`, `Tabloid` or an Object containing `height` and `width` in microns.
* `printBackground` boolean (optional) - Whether to print CSS backgrounds.
* `printSelectionOnly` boolean (optional) - Whether to print selection only.
2019-04-16 23:03:17 +00:00
Returns `Promise<Buffer>` - Resolves with the generated PDF data.
Prints window's web page as PDF with Chromium's preview printing custom
settings.
The `landscape` will be ignored if `@page` CSS at-rule is used in the web page.
2015-08-20 17:03:53 +00:00
By default, an empty `options` will be regarded as:
2016-08-16 21:50:21 +00:00
```javascript
2015-08-20 17:03:53 +00:00
{
marginsType: 0,
printBackground: false,
printSelectionOnly: false,
landscape: false,
pageSize: 'A4',
scaleFactor: 100
2015-08-20 17:03:53 +00:00
}
```
2015-08-20 13:17:53 +00:00
2020-11-19 04:58:47 +00:00
Use `page-break-before: always;` CSS style to force to print to a new page.
An example of `webContents.printToPDF`:
2015-08-20 13:17:53 +00:00
```javascript
2018-09-13 16:10:51 +00:00
const { BrowserWindow } = require('electron')
const fs = require('fs')
chore: bump chromium to 6d130075d378a64187360ba4e7820 (master) (#24256) * chore: bump chromium in DEPS to 7fb9778894d73378bff51087ce869ea5aa6e5d5d * chore: bump chromium in DEPS to 83da426e53d423f0530fc23433b6d2c4d0548442 * update patches * remove chromeos-only TtsControllerDelegate Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2255314 * SharedUserScriptMaster -> SharedUserScriptManager Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2258357 * avoid deprecated DISALLOW_COPY_AND_ASSIGN https://groups.google.com/a/chromium.org/forum/#!msg/cxx/qwH2hxaEjac/TUKq6eqfCwAJ * chore: bump chromium in DEPS to b2eaf9ff4e6b03267bf279583ea20ceb2b25e9d0 * update patches * rename GetHighContrastColorScheme -> GetPlatformHighContrastColorScheme Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2250224 * remove vulkan info collection Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2252818 * add max_xcode_version build var Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2264867 * add missing headers * chore: bump chromium in DEPS to cded18ca1138f7e8efc904f077ddcca34f0135cf * update patches * add empty floc blocklist to BrowserProcessImpl Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2240873 * chore: bump chromium in DEPS to f06602226cd80bf677b2ce013a94a2fb7f6ac58d * chore: bump chromium in DEPS to 747aa4bfc74fc6cf7f08ee72624cd69ae41ae28d * chore: bump chromium in DEPS to 31c0105e50fcc4e94de33e5c8602c755ace4a32b * chore: update patches * Reland "[base] Stop including check.h, notreached.h, etc. in logging.h" https://chromium-review.googlesource.com/c/chromium/src/+/2264297 * X11 and Ozone: make sure gfx::AcceleratedWidget to be uint32_t https://chromium-review.googlesource.com/c/chromium/src/+/2260554 * Move zygote from //services/service_manager back to //content https://chromium-review.googlesource.com/c/chromium/src/+/2252466 * chore: update v8 patches * [XProto] Remove usage of Shape extension https://chromium-review.googlesource.com/c/chromium/src/+/2262113 * fixup! add empty floc blocklist to BrowserProcessImpl * Require macOS 10.15.1 sdk https://chromium-review.googlesource.com/c/chromium/src/+/2238504 * Use newer Xcode version 11.5.0 * update src cache * chore: bump chromium in DEPS to 60a9883e35db3f6f91916f0878e88e1849c17b11 * chore: update patches * Reland "Reland "New toolchain for Windows 10 19041 SDK"" https://chromium-review.googlesource.com/c/chromium/src/+/2255527 * update patches * Convert raw NonClientFrameViews to unique_ptrs https://chromium-review.googlesource.com/c/chromium/src/+/2240417 * [printing] Move PrintHostMsg_DidPreviewDocument_Params to print.mojom https://chromium-review.googlesource.com/c/chromium/src/+/2257035 * chore: bump chromium in DEPS to 12c233c2a85bfa28fb279f390121ba681e52a71b * chore: update patches * Removing oppressive language for the directory chrome/browser/apps https://chromium-review.googlesource.com/c/chromium/src/+/2269822 * Inclusion: rename SpellcheckLanguageBlacklistPolicyHandler https://chromium-review.googlesource.com/c/chromium/src/+/2267646 * Clean up duplicate WebContents "is fullscreen" functions https://chromium-review.googlesource.com/c/chromium/src/+/2275148 * Adds icon loading service with sandbox for Windows. https://chromium-review.googlesource.com/c/chromium/src/+/1987273 * No more Vulkan info collection for UMA on Windows https://chromium-review.googlesource.com/c/chromium/src/+/2252818 * fix lint * chore: update buildflag conditions * chore: bump chromium in DEPS to a837d4c4230ace4f10b2768728f4044b7995dfa5 * update hunspell files * chore: update patches * Make content::FileSelectListener a RefCounted https://chromium-review.googlesource.com/c/chromium/src/+/2275338 * fix build failures on MAS * update patches * fixup! Reland "[base] Stop including check.h, notreached.h, etc. in logging.h" * fix build on windows * Check for GDI exhaustion if window creation fails https://chromium-review.googlesource.com/c/chromium/src/+/2244124 * chore: bump chromium in DEPS to 2c9b2a73be4ef9ec22d8b6da8e174cb80753f125 * chore: update patches * Network Service: Move DeleteCookiePredicate into public folder https://chromium-review.googlesource.com/c/chromium/src/+/2264186 * chore: bump chromium in DEPS to fa2606299bcc02c362528d26b5dcf8c8a0db0735 * chore: bump chromium in DEPS to d9c235d1227204dbae3708daae851573a3566b94 * chore: bump chromium in DEPS to 2f82c284243c035f49a747fd1ead6c44b4b31093 * chore: update patches * Move creating the LayerTreeSettings into blink. https://chromium-review.googlesource.com/c/chromium/src/+/2267720 * chore: bump chromium in DEPS to 914112f1d9af9e4974059dc403da62699a55550f * update patches * chore: bump chromium in DEPS to e0bc1ffae6393fc543a2da94c88167df75859b36 * refactor: match upstream print preview handling (#24452) * update patches * chore: bump chromium in DEPS to 0881423156abe084164b51ab58ce93a8bd380524 * update patches * update patches * give a type to pendingPromise * chore: bump chromium in DEPS to 11a8c1534b16d130075d378a64187360ba4e7820 * update patches * 2272609: Move //services/service_manager/sandbox to //sandbox/policy. https://chromium-review.googlesource.com/c/chromium/src/+/2272609 * update patches * fixup! 2272609: Move //services/service_manager/sandbox to //sandbox/policy. * fixup! 2272609: Move //services/service_manager/sandbox to //sandbox/policy. * 2264511: Cookies: Update SetCanonicalCookie to return CookieAccessResult https://chromium-review.googlesource.com/c/chromium/src/+/2264511 * chore: fix setAlwaysOnTop test The window must be visible for state to be updated properly. * Revert "Migrate modules/desktop_capture and modules/video_capture to webrtc::Mutex." https://webrtc-review.googlesource.com/c/src/+/179080 * update patches Co-authored-by: Andy Locascio <andy@slack-corp.com> Co-authored-by: deepak1556 <hop2deep@gmail.com> Co-authored-by: Samuel Attard <samuel.r.attard@gmail.com> Co-authored-by: John Kleinschmidt <jkleinsc@github.com> Co-authored-by: Electron Bot <anonymous@electronjs.org> Co-authored-by: Shelley Vohr <shelley.vohr@gmail.com> Co-authored-by: Jeremy Rose <nornagon@nornagon.net> Co-authored-by: Samuel Attard <marshallofsound@electronjs.org>
2020-07-14 01:13:34 +00:00
const path = require('path')
const os = require('os')
2015-08-20 13:17:53 +00:00
2020-07-09 17:18:49 +00:00
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('http://github.com')
2015-08-20 13:17:53 +00:00
win.webContents.on('did-finish-load', () => {
2015-08-20 13:17:53 +00:00
// Use default printing options
const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')
win.webContents.printToPDF({}).then(data => {
chore: bump chromium to 6d130075d378a64187360ba4e7820 (master) (#24256) * chore: bump chromium in DEPS to 7fb9778894d73378bff51087ce869ea5aa6e5d5d * chore: bump chromium in DEPS to 83da426e53d423f0530fc23433b6d2c4d0548442 * update patches * remove chromeos-only TtsControllerDelegate Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2255314 * SharedUserScriptMaster -> SharedUserScriptManager Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2258357 * avoid deprecated DISALLOW_COPY_AND_ASSIGN https://groups.google.com/a/chromium.org/forum/#!msg/cxx/qwH2hxaEjac/TUKq6eqfCwAJ * chore: bump chromium in DEPS to b2eaf9ff4e6b03267bf279583ea20ceb2b25e9d0 * update patches * rename GetHighContrastColorScheme -> GetPlatformHighContrastColorScheme Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2250224 * remove vulkan info collection Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2252818 * add max_xcode_version build var Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2264867 * add missing headers * chore: bump chromium in DEPS to cded18ca1138f7e8efc904f077ddcca34f0135cf * update patches * add empty floc blocklist to BrowserProcessImpl Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2240873 * chore: bump chromium in DEPS to f06602226cd80bf677b2ce013a94a2fb7f6ac58d * chore: bump chromium in DEPS to 747aa4bfc74fc6cf7f08ee72624cd69ae41ae28d * chore: bump chromium in DEPS to 31c0105e50fcc4e94de33e5c8602c755ace4a32b * chore: update patches * Reland "[base] Stop including check.h, notreached.h, etc. in logging.h" https://chromium-review.googlesource.com/c/chromium/src/+/2264297 * X11 and Ozone: make sure gfx::AcceleratedWidget to be uint32_t https://chromium-review.googlesource.com/c/chromium/src/+/2260554 * Move zygote from //services/service_manager back to //content https://chromium-review.googlesource.com/c/chromium/src/+/2252466 * chore: update v8 patches * [XProto] Remove usage of Shape extension https://chromium-review.googlesource.com/c/chromium/src/+/2262113 * fixup! add empty floc blocklist to BrowserProcessImpl * Require macOS 10.15.1 sdk https://chromium-review.googlesource.com/c/chromium/src/+/2238504 * Use newer Xcode version 11.5.0 * update src cache * chore: bump chromium in DEPS to 60a9883e35db3f6f91916f0878e88e1849c17b11 * chore: update patches * Reland "Reland "New toolchain for Windows 10 19041 SDK"" https://chromium-review.googlesource.com/c/chromium/src/+/2255527 * update patches * Convert raw NonClientFrameViews to unique_ptrs https://chromium-review.googlesource.com/c/chromium/src/+/2240417 * [printing] Move PrintHostMsg_DidPreviewDocument_Params to print.mojom https://chromium-review.googlesource.com/c/chromium/src/+/2257035 * chore: bump chromium in DEPS to 12c233c2a85bfa28fb279f390121ba681e52a71b * chore: update patches * Removing oppressive language for the directory chrome/browser/apps https://chromium-review.googlesource.com/c/chromium/src/+/2269822 * Inclusion: rename SpellcheckLanguageBlacklistPolicyHandler https://chromium-review.googlesource.com/c/chromium/src/+/2267646 * Clean up duplicate WebContents "is fullscreen" functions https://chromium-review.googlesource.com/c/chromium/src/+/2275148 * Adds icon loading service with sandbox for Windows. https://chromium-review.googlesource.com/c/chromium/src/+/1987273 * No more Vulkan info collection for UMA on Windows https://chromium-review.googlesource.com/c/chromium/src/+/2252818 * fix lint * chore: update buildflag conditions * chore: bump chromium in DEPS to a837d4c4230ace4f10b2768728f4044b7995dfa5 * update hunspell files * chore: update patches * Make content::FileSelectListener a RefCounted https://chromium-review.googlesource.com/c/chromium/src/+/2275338 * fix build failures on MAS * update patches * fixup! Reland "[base] Stop including check.h, notreached.h, etc. in logging.h" * fix build on windows * Check for GDI exhaustion if window creation fails https://chromium-review.googlesource.com/c/chromium/src/+/2244124 * chore: bump chromium in DEPS to 2c9b2a73be4ef9ec22d8b6da8e174cb80753f125 * chore: update patches * Network Service: Move DeleteCookiePredicate into public folder https://chromium-review.googlesource.com/c/chromium/src/+/2264186 * chore: bump chromium in DEPS to fa2606299bcc02c362528d26b5dcf8c8a0db0735 * chore: bump chromium in DEPS to d9c235d1227204dbae3708daae851573a3566b94 * chore: bump chromium in DEPS to 2f82c284243c035f49a747fd1ead6c44b4b31093 * chore: update patches * Move creating the LayerTreeSettings into blink. https://chromium-review.googlesource.com/c/chromium/src/+/2267720 * chore: bump chromium in DEPS to 914112f1d9af9e4974059dc403da62699a55550f * update patches * chore: bump chromium in DEPS to e0bc1ffae6393fc543a2da94c88167df75859b36 * refactor: match upstream print preview handling (#24452) * update patches * chore: bump chromium in DEPS to 0881423156abe084164b51ab58ce93a8bd380524 * update patches * update patches * give a type to pendingPromise * chore: bump chromium in DEPS to 11a8c1534b16d130075d378a64187360ba4e7820 * update patches * 2272609: Move //services/service_manager/sandbox to //sandbox/policy. https://chromium-review.googlesource.com/c/chromium/src/+/2272609 * update patches * fixup! 2272609: Move //services/service_manager/sandbox to //sandbox/policy. * fixup! 2272609: Move //services/service_manager/sandbox to //sandbox/policy. * 2264511: Cookies: Update SetCanonicalCookie to return CookieAccessResult https://chromium-review.googlesource.com/c/chromium/src/+/2264511 * chore: fix setAlwaysOnTop test The window must be visible for state to be updated properly. * Revert "Migrate modules/desktop_capture and modules/video_capture to webrtc::Mutex." https://webrtc-review.googlesource.com/c/src/+/179080 * update patches Co-authored-by: Andy Locascio <andy@slack-corp.com> Co-authored-by: deepak1556 <hop2deep@gmail.com> Co-authored-by: Samuel Attard <samuel.r.attard@gmail.com> Co-authored-by: John Kleinschmidt <jkleinsc@github.com> Co-authored-by: Electron Bot <anonymous@electronjs.org> Co-authored-by: Shelley Vohr <shelley.vohr@gmail.com> Co-authored-by: Jeremy Rose <nornagon@nornagon.net> Co-authored-by: Samuel Attard <marshallofsound@electronjs.org>
2020-07-14 01:13:34 +00:00
fs.writeFile(pdfPath, data, (error) => {
if (error) throw error
chore: bump chromium to 6d130075d378a64187360ba4e7820 (master) (#24256) * chore: bump chromium in DEPS to 7fb9778894d73378bff51087ce869ea5aa6e5d5d * chore: bump chromium in DEPS to 83da426e53d423f0530fc23433b6d2c4d0548442 * update patches * remove chromeos-only TtsControllerDelegate Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2255314 * SharedUserScriptMaster -> SharedUserScriptManager Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2258357 * avoid deprecated DISALLOW_COPY_AND_ASSIGN https://groups.google.com/a/chromium.org/forum/#!msg/cxx/qwH2hxaEjac/TUKq6eqfCwAJ * chore: bump chromium in DEPS to b2eaf9ff4e6b03267bf279583ea20ceb2b25e9d0 * update patches * rename GetHighContrastColorScheme -> GetPlatformHighContrastColorScheme Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2250224 * remove vulkan info collection Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2252818 * add max_xcode_version build var Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2264867 * add missing headers * chore: bump chromium in DEPS to cded18ca1138f7e8efc904f077ddcca34f0135cf * update patches * add empty floc blocklist to BrowserProcessImpl Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2240873 * chore: bump chromium in DEPS to f06602226cd80bf677b2ce013a94a2fb7f6ac58d * chore: bump chromium in DEPS to 747aa4bfc74fc6cf7f08ee72624cd69ae41ae28d * chore: bump chromium in DEPS to 31c0105e50fcc4e94de33e5c8602c755ace4a32b * chore: update patches * Reland "[base] Stop including check.h, notreached.h, etc. in logging.h" https://chromium-review.googlesource.com/c/chromium/src/+/2264297 * X11 and Ozone: make sure gfx::AcceleratedWidget to be uint32_t https://chromium-review.googlesource.com/c/chromium/src/+/2260554 * Move zygote from //services/service_manager back to //content https://chromium-review.googlesource.com/c/chromium/src/+/2252466 * chore: update v8 patches * [XProto] Remove usage of Shape extension https://chromium-review.googlesource.com/c/chromium/src/+/2262113 * fixup! add empty floc blocklist to BrowserProcessImpl * Require macOS 10.15.1 sdk https://chromium-review.googlesource.com/c/chromium/src/+/2238504 * Use newer Xcode version 11.5.0 * update src cache * chore: bump chromium in DEPS to 60a9883e35db3f6f91916f0878e88e1849c17b11 * chore: update patches * Reland "Reland "New toolchain for Windows 10 19041 SDK"" https://chromium-review.googlesource.com/c/chromium/src/+/2255527 * update patches * Convert raw NonClientFrameViews to unique_ptrs https://chromium-review.googlesource.com/c/chromium/src/+/2240417 * [printing] Move PrintHostMsg_DidPreviewDocument_Params to print.mojom https://chromium-review.googlesource.com/c/chromium/src/+/2257035 * chore: bump chromium in DEPS to 12c233c2a85bfa28fb279f390121ba681e52a71b * chore: update patches * Removing oppressive language for the directory chrome/browser/apps https://chromium-review.googlesource.com/c/chromium/src/+/2269822 * Inclusion: rename SpellcheckLanguageBlacklistPolicyHandler https://chromium-review.googlesource.com/c/chromium/src/+/2267646 * Clean up duplicate WebContents "is fullscreen" functions https://chromium-review.googlesource.com/c/chromium/src/+/2275148 * Adds icon loading service with sandbox for Windows. https://chromium-review.googlesource.com/c/chromium/src/+/1987273 * No more Vulkan info collection for UMA on Windows https://chromium-review.googlesource.com/c/chromium/src/+/2252818 * fix lint * chore: update buildflag conditions * chore: bump chromium in DEPS to a837d4c4230ace4f10b2768728f4044b7995dfa5 * update hunspell files * chore: update patches * Make content::FileSelectListener a RefCounted https://chromium-review.googlesource.com/c/chromium/src/+/2275338 * fix build failures on MAS * update patches * fixup! Reland "[base] Stop including check.h, notreached.h, etc. in logging.h" * fix build on windows * Check for GDI exhaustion if window creation fails https://chromium-review.googlesource.com/c/chromium/src/+/2244124 * chore: bump chromium in DEPS to 2c9b2a73be4ef9ec22d8b6da8e174cb80753f125 * chore: update patches * Network Service: Move DeleteCookiePredicate into public folder https://chromium-review.googlesource.com/c/chromium/src/+/2264186 * chore: bump chromium in DEPS to fa2606299bcc02c362528d26b5dcf8c8a0db0735 * chore: bump chromium in DEPS to d9c235d1227204dbae3708daae851573a3566b94 * chore: bump chromium in DEPS to 2f82c284243c035f49a747fd1ead6c44b4b31093 * chore: update patches * Move creating the LayerTreeSettings into blink. https://chromium-review.googlesource.com/c/chromium/src/+/2267720 * chore: bump chromium in DEPS to 914112f1d9af9e4974059dc403da62699a55550f * update patches * chore: bump chromium in DEPS to e0bc1ffae6393fc543a2da94c88167df75859b36 * refactor: match upstream print preview handling (#24452) * update patches * chore: bump chromium in DEPS to 0881423156abe084164b51ab58ce93a8bd380524 * update patches * update patches * give a type to pendingPromise * chore: bump chromium in DEPS to 11a8c1534b16d130075d378a64187360ba4e7820 * update patches * 2272609: Move //services/service_manager/sandbox to //sandbox/policy. https://chromium-review.googlesource.com/c/chromium/src/+/2272609 * update patches * fixup! 2272609: Move //services/service_manager/sandbox to //sandbox/policy. * fixup! 2272609: Move //services/service_manager/sandbox to //sandbox/policy. * 2264511: Cookies: Update SetCanonicalCookie to return CookieAccessResult https://chromium-review.googlesource.com/c/chromium/src/+/2264511 * chore: fix setAlwaysOnTop test The window must be visible for state to be updated properly. * Revert "Migrate modules/desktop_capture and modules/video_capture to webrtc::Mutex." https://webrtc-review.googlesource.com/c/src/+/179080 * update patches Co-authored-by: Andy Locascio <andy@slack-corp.com> Co-authored-by: deepak1556 <hop2deep@gmail.com> Co-authored-by: Samuel Attard <samuel.r.attard@gmail.com> Co-authored-by: John Kleinschmidt <jkleinsc@github.com> Co-authored-by: Electron Bot <anonymous@electronjs.org> Co-authored-by: Shelley Vohr <shelley.vohr@gmail.com> Co-authored-by: Jeremy Rose <nornagon@nornagon.net> Co-authored-by: Samuel Attard <marshallofsound@electronjs.org>
2020-07-14 01:13:34 +00:00
console.log(`Wrote PDF successfully to ${pdfPath}`)
})
}).catch(error => {
chore: bump chromium to 6d130075d378a64187360ba4e7820 (master) (#24256) * chore: bump chromium in DEPS to 7fb9778894d73378bff51087ce869ea5aa6e5d5d * chore: bump chromium in DEPS to 83da426e53d423f0530fc23433b6d2c4d0548442 * update patches * remove chromeos-only TtsControllerDelegate Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2255314 * SharedUserScriptMaster -> SharedUserScriptManager Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2258357 * avoid deprecated DISALLOW_COPY_AND_ASSIGN https://groups.google.com/a/chromium.org/forum/#!msg/cxx/qwH2hxaEjac/TUKq6eqfCwAJ * chore: bump chromium in DEPS to b2eaf9ff4e6b03267bf279583ea20ceb2b25e9d0 * update patches * rename GetHighContrastColorScheme -> GetPlatformHighContrastColorScheme Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2250224 * remove vulkan info collection Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2252818 * add max_xcode_version build var Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2264867 * add missing headers * chore: bump chromium in DEPS to cded18ca1138f7e8efc904f077ddcca34f0135cf * update patches * add empty floc blocklist to BrowserProcessImpl Refs: https://chromium-review.googlesource.com/c/chromium/src/+/2240873 * chore: bump chromium in DEPS to f06602226cd80bf677b2ce013a94a2fb7f6ac58d * chore: bump chromium in DEPS to 747aa4bfc74fc6cf7f08ee72624cd69ae41ae28d * chore: bump chromium in DEPS to 31c0105e50fcc4e94de33e5c8602c755ace4a32b * chore: update patches * Reland "[base] Stop including check.h, notreached.h, etc. in logging.h" https://chromium-review.googlesource.com/c/chromium/src/+/2264297 * X11 and Ozone: make sure gfx::AcceleratedWidget to be uint32_t https://chromium-review.googlesource.com/c/chromium/src/+/2260554 * Move zygote from //services/service_manager back to //content https://chromium-review.googlesource.com/c/chromium/src/+/2252466 * chore: update v8 patches * [XProto] Remove usage of Shape extension https://chromium-review.googlesource.com/c/chromium/src/+/2262113 * fixup! add empty floc blocklist to BrowserProcessImpl * Require macOS 10.15.1 sdk https://chromium-review.googlesource.com/c/chromium/src/+/2238504 * Use newer Xcode version 11.5.0 * update src cache * chore: bump chromium in DEPS to 60a9883e35db3f6f91916f0878e88e1849c17b11 * chore: update patches * Reland "Reland "New toolchain for Windows 10 19041 SDK"" https://chromium-review.googlesource.com/c/chromium/src/+/2255527 * update patches * Convert raw NonClientFrameViews to unique_ptrs https://chromium-review.googlesource.com/c/chromium/src/+/2240417 * [printing] Move PrintHostMsg_DidPreviewDocument_Params to print.mojom https://chromium-review.googlesource.com/c/chromium/src/+/2257035 * chore: bump chromium in DEPS to 12c233c2a85bfa28fb279f390121ba681e52a71b * chore: update patches * Removing oppressive language for the directory chrome/browser/apps https://chromium-review.googlesource.com/c/chromium/src/+/2269822 * Inclusion: rename SpellcheckLanguageBlacklistPolicyHandler https://chromium-review.googlesource.com/c/chromium/src/+/2267646 * Clean up duplicate WebContents "is fullscreen" functions https://chromium-review.googlesource.com/c/chromium/src/+/2275148 * Adds icon loading service with sandbox for Windows. https://chromium-review.googlesource.com/c/chromium/src/+/1987273 * No more Vulkan info collection for UMA on Windows https://chromium-review.googlesource.com/c/chromium/src/+/2252818 * fix lint * chore: update buildflag conditions * chore: bump chromium in DEPS to a837d4c4230ace4f10b2768728f4044b7995dfa5 * update hunspell files * chore: update patches * Make content::FileSelectListener a RefCounted https://chromium-review.googlesource.com/c/chromium/src/+/2275338 * fix build failures on MAS * update patches * fixup! Reland "[base] Stop including check.h, notreached.h, etc. in logging.h" * fix build on windows * Check for GDI exhaustion if window creation fails https://chromium-review.googlesource.com/c/chromium/src/+/2244124 * chore: bump chromium in DEPS to 2c9b2a73be4ef9ec22d8b6da8e174cb80753f125 * chore: update patches * Network Service: Move DeleteCookiePredicate into public folder https://chromium-review.googlesource.com/c/chromium/src/+/2264186 * chore: bump chromium in DEPS to fa2606299bcc02c362528d26b5dcf8c8a0db0735 * chore: bump chromium in DEPS to d9c235d1227204dbae3708daae851573a3566b94 * chore: bump chromium in DEPS to 2f82c284243c035f49a747fd1ead6c44b4b31093 * chore: update patches * Move creating the LayerTreeSettings into blink. https://chromium-review.googlesource.com/c/chromium/src/+/2267720 * chore: bump chromium in DEPS to 914112f1d9af9e4974059dc403da62699a55550f * update patches * chore: bump chromium in DEPS to e0bc1ffae6393fc543a2da94c88167df75859b36 * refactor: match upstream print preview handling (#24452) * update patches * chore: bump chromium in DEPS to 0881423156abe084164b51ab58ce93a8bd380524 * update patches * update patches * give a type to pendingPromise * chore: bump chromium in DEPS to 11a8c1534b16d130075d378a64187360ba4e7820 * update patches * 2272609: Move //services/service_manager/sandbox to //sandbox/policy. https://chromium-review.googlesource.com/c/chromium/src/+/2272609 * update patches * fixup! 2272609: Move //services/service_manager/sandbox to //sandbox/policy. * fixup! 2272609: Move //services/service_manager/sandbox to //sandbox/policy. * 2264511: Cookies: Update SetCanonicalCookie to return CookieAccessResult https://chromium-review.googlesource.com/c/chromium/src/+/2264511 * chore: fix setAlwaysOnTop test The window must be visible for state to be updated properly. * Revert "Migrate modules/desktop_capture and modules/video_capture to webrtc::Mutex." https://webrtc-review.googlesource.com/c/src/+/179080 * update patches Co-authored-by: Andy Locascio <andy@slack-corp.com> Co-authored-by: deepak1556 <hop2deep@gmail.com> Co-authored-by: Samuel Attard <samuel.r.attard@gmail.com> Co-authored-by: John Kleinschmidt <jkleinsc@github.com> Co-authored-by: Electron Bot <anonymous@electronjs.org> Co-authored-by: Shelley Vohr <shelley.vohr@gmail.com> Co-authored-by: Jeremy Rose <nornagon@nornagon.net> Co-authored-by: Samuel Attard <marshallofsound@electronjs.org>
2020-07-14 01:13:34 +00:00
console.log(`Failed to write PDF to ${pdfPath}: `, error)
})
})
2015-08-20 13:17:53 +00:00
```
#### `contents.addWorkSpace(path)`
2015-08-20 13:17:53 +00:00
* `path` string
2015-08-20 13:17:53 +00:00
Adds the specified path to DevTools workspace. Must be used after DevTools
creation:
```javascript
2018-09-13 16:10:51 +00:00
const { BrowserWindow } = require('electron')
2020-07-09 17:18:49 +00:00
const win = new BrowserWindow()
2016-05-10 17:38:42 +00:00
win.webContents.on('devtools-opened', () => {
win.webContents.addWorkSpace(__dirname)
})
```
2015-08-20 13:17:53 +00:00
#### `contents.removeWorkSpace(path)`
2015-08-20 13:17:53 +00:00
* `path` string
2015-08-20 13:17:53 +00:00
2015-09-09 21:11:06 +00:00
Removes the specified path from DevTools workspace.
2015-08-20 13:17:53 +00:00
2017-11-30 11:25:57 +00:00
#### `contents.setDevToolsWebContents(devToolsWebContents)`
* `devToolsWebContents` WebContents
Uses the `devToolsWebContents` as the target `WebContents` to show devtools.
The `devToolsWebContents` must not have done any navigation, and it should not
be used for other purposes after the call.
By default Electron manages the devtools by creating an internal `WebContents`
with native view, which developers have very limited control of. With the
`setDevToolsWebContents` method, developers can use any `WebContents` to show
the devtools in it, including `BrowserWindow`, `BrowserView` and `<webview>`
tag.
2018-02-13 05:18:27 +00:00
Note that closing the devtools does not destroy the `devToolsWebContents`, it
is caller's responsibility to destroy `devToolsWebContents`.
2017-11-30 11:25:57 +00:00
An example of showing devtools in a `<webview>` tag:
```html
<html>
<head>
<style type="text/css">
* { margin: 0; }
#browser { height: 70%; }
#devtools { height: 30%; }
</style>
</head>
<body>
<webview id="browser" src="https://github.com"></webview>
<webview id="devtools" src="about:blank"></webview>
2017-11-30 11:25:57 +00:00
<script>
const { ipcRenderer } = require('electron')
const emittedOnce = (element, eventName) => new Promise(resolve => {
element.addEventListener(eventName, event => resolve(event), { once: true })
})
2017-11-30 11:25:57 +00:00
const browserView = document.getElementById('browser')
const devtoolsView = document.getElementById('devtools')
const browserReady = emittedOnce(browserView, 'dom-ready')
const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')
Promise.all([browserReady, devtoolsReady]).then(() => {
const targetId = browserView.getWebContentsId()
const devtoolsId = devtoolsView.getWebContentsId()
ipcRenderer.send('open-devtools', targetId, devtoolsId)
2017-11-30 11:25:57 +00:00
})
</script>
</body>
</html>
```
```js
// Main process
const { ipcMain, webContents } = require('electron')
ipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {
const target = webContents.fromId(targetContentsId)
const devtools = webContents.fromId(devtoolsContentsId)
target.setDevToolsWebContents(devtools)
target.openDevTools()
})
```
2017-11-30 11:25:57 +00:00
An example of showing devtools in a `BrowserWindow`:
```js
2018-09-13 16:10:51 +00:00
const { app, BrowserWindow } = require('electron')
2017-11-30 11:25:57 +00:00
let win = null
let devtools = null
app.whenReady().then(() => {
2017-11-30 11:25:57 +00:00
win = new BrowserWindow()
2017-12-01 03:04:50 +00:00
devtools = new BrowserWindow()
2017-11-30 11:25:57 +00:00
win.loadURL('https://github.com')
win.webContents.setDevToolsWebContents(devtools.webContents)
2018-09-13 16:10:51 +00:00
win.webContents.openDevTools({ mode: 'detach' })
2017-11-30 11:25:57 +00:00
})
```
#### `contents.openDevTools([options])`
* `options` Object (optional)
* `mode` string - Opens the devtools with specified dock state, can be
`right`, `bottom`, `undocked`, `detach`. Defaults to last used dock state.
In `undocked` mode it's possible to dock back. In `detach` mode it's not.
* `activate` boolean (optional) - Whether to bring the opened devtools window
to the foreground. The default is `true`.
2016-01-04 02:46:30 +00:00
Opens the devtools.
When `contents` is a `<webview>` tag, the `mode` would be `detach` by default,
explicitly passing an empty `mode` can force using last used dock state.
#### `contents.closeDevTools()`
2016-01-04 02:46:30 +00:00
Closes the devtools.
#### `contents.isDevToolsOpened()`
Returns `boolean` - Whether the devtools is opened.
2016-01-04 02:46:30 +00:00
#### `contents.isDevToolsFocused()`
2016-01-04 02:46:30 +00:00
Returns `boolean` - Whether the devtools view is focused .
#### `contents.toggleDevTools()`
Toggles the developer tools.
#### `contents.inspectElement(x, y)`
* `x` Integer
* `y` Integer
Starts inspecting element at position (`x`, `y`).
#### `contents.inspectSharedWorker()`
Opens the developer tools for the shared worker context.
#### `contents.inspectSharedWorkerById(workerId)`
* `workerId` string
Inspects the shared worker based on its ID.
#### `contents.getAllSharedWorkers()`
Returns [`SharedWorkerInfo[]`](structures/shared-worker-info.md) - Information about all Shared Workers.
#### `contents.inspectServiceWorker()`
Opens the developer tools for the service worker context.
#### `contents.send(channel, ...args)`
2015-08-20 13:17:53 +00:00
* `channel` string
2016-11-05 08:42:45 +00:00
* `...args` any[]
2015-08-20 13:17:53 +00:00
refactor: use v8 serialization for ipc (#20214) * refactor: use v8 serialization for ipc * cloning process.env doesn't work * serialize host objects by enumerating key/values * new serialization can handle NaN, Infinity, and undefined correctly * can't allocate v8 objects during GC * backport microtasks fix * fix compile * fix node_stream_loader reentrancy * update subframe spec to expect undefined instead of null * write undefined instead of crashing when serializing host objects * fix webview spec * fix download spec * buffers are transformed into uint8arrays * can't serialize promises * fix chrome.i18n.getMessage * fix devtools tests * fix zoom test * fix debug build * fix lint * update ipcRenderer tests * fix printToPDF test * update patch * remove accidentally re-added remote-side spec * wip * don't attempt to serialize host objects * jump through different hoops to set options.webContents sometimes * whoops * fix lint * clean up error-handling logic * fix memory leak * fix lint * convert host objects using old base::Value serialization * fix lint more * fall back to base::Value-based serialization * remove commented-out code * add docs to breaking-changes.md * Update breaking-changes.md * update ipcRenderer and WebContents docs * lint * use named values for format tag * save a memcpy for ~30% speedup * get rid of calls to ShallowClone * extra debugging for paranoia * d'oh, use the correct named tags * apparently msstl doesn't like this DCHECK * funny story about that DCHECK * disable remote-related functions when enable_remote_module = false * nits * use EnableIf to disable remote methods in mojom * fix include * review comments
2019-10-09 17:59:08 +00:00
Send an asynchronous message to the renderer process via `channel`, along with
arguments. Arguments will be serialized with the [Structured Clone
Algorithm][SCA], just like [`postMessage`][], so prototype chains will not be
included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will
throw an exception.
> **NOTE**: Sending non-standard JavaScript types such as DOM objects or
> special Electron objects will throw an exception.
2016-02-16 03:34:39 +00:00
The renderer process can handle the message by listening to `channel` with the
[`ipcRenderer`](ipc-renderer.md) module.
2015-08-20 13:17:53 +00:00
An example of sending messages from the main process to the renderer process:
```javascript
2015-09-04 20:44:40 +00:00
// In the main process.
2018-09-13 16:10:51 +00:00
const { app, BrowserWindow } = require('electron')
let win = null
app.whenReady().then(() => {
2018-09-13 16:10:51 +00:00
win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL(`file://${__dirname}/index.html`)
2016-05-10 17:38:42 +00:00
win.webContents.on('did-finish-load', () => {
win.webContents.send('ping', 'whoooooooh!')
})
})
2015-08-20 13:17:53 +00:00
```
```html
<!-- index.html -->
<html>
<body>
<script>
require('electron').ipcRenderer.on('ping', (event, message) => {
2017-11-29 10:58:24 +00:00
console.log(message) // Prints 'whoooooooh!'
})
2015-08-20 13:17:53 +00:00
</script>
</body>
</html>
```
#### `contents.sendToFrame(frameId, channel, ...args)`
* `frameId` Integer | [number, number] - the ID of the frame to send to, or a
pair of `[processId, frameId]` if the frame is in a different process to the
main frame.
* `channel` string
* `...args` any[]
Send an asynchronous message to a specific frame in a renderer process via
refactor: use v8 serialization for ipc (#20214) * refactor: use v8 serialization for ipc * cloning process.env doesn't work * serialize host objects by enumerating key/values * new serialization can handle NaN, Infinity, and undefined correctly * can't allocate v8 objects during GC * backport microtasks fix * fix compile * fix node_stream_loader reentrancy * update subframe spec to expect undefined instead of null * write undefined instead of crashing when serializing host objects * fix webview spec * fix download spec * buffers are transformed into uint8arrays * can't serialize promises * fix chrome.i18n.getMessage * fix devtools tests * fix zoom test * fix debug build * fix lint * update ipcRenderer tests * fix printToPDF test * update patch * remove accidentally re-added remote-side spec * wip * don't attempt to serialize host objects * jump through different hoops to set options.webContents sometimes * whoops * fix lint * clean up error-handling logic * fix memory leak * fix lint * convert host objects using old base::Value serialization * fix lint more * fall back to base::Value-based serialization * remove commented-out code * add docs to breaking-changes.md * Update breaking-changes.md * update ipcRenderer and WebContents docs * lint * use named values for format tag * save a memcpy for ~30% speedup * get rid of calls to ShallowClone * extra debugging for paranoia * d'oh, use the correct named tags * apparently msstl doesn't like this DCHECK * funny story about that DCHECK * disable remote-related functions when enable_remote_module = false * nits * use EnableIf to disable remote methods in mojom * fix include * review comments
2019-10-09 17:59:08 +00:00
`channel`, along with arguments. Arguments will be serialized with the
[Structured Clone Algorithm][SCA], just like [`postMessage`][], so prototype
chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or
WeakSets will throw an exception.
> **NOTE:** Sending non-standard JavaScript types such as DOM objects or
> special Electron objects will throw an exception.
The renderer process can handle the message by listening to `channel` with the
[`ipcRenderer`](ipc-renderer.md) module.
If you want to get the `frameId` of a given renderer context you should use
the `webFrame.routingId` value. E.g.
```js
// In a renderer process
console.log('My frameId is:', require('electron').webFrame.routingId)
```
You can also read `frameId` from all incoming IPC messages in the main process.
```js
// In the main process
ipcMain.on('ping', (event) => {
console.info('Message came from frameId:', event.frameId)
})
```
#### `contents.postMessage(channel, message, [transfer])`
* `channel` string
* `message` any
* `transfer` MessagePortMain[] (optional)
Send a message to the renderer process, optionally transferring ownership of
zero or more [`MessagePortMain`][] objects.
The transferred `MessagePortMain` objects will be available in the renderer
process by accessing the `ports` property of the emitted event. When they
arrive in the renderer, they will be native DOM `MessagePort` objects.
For example:
```js
// Main process
const { port1, port2 } = new MessageChannelMain()
webContents.postMessage('port', { message: 'hello' }, [port1])
// Renderer process
ipcRenderer.on('port', (e, msg) => {
const [port] = e.ports
// ...
})
```
#### `contents.enableDeviceEmulation(parameters)`
2015-08-31 09:19:19 +00:00
2016-08-25 17:52:19 +00:00
* `parameters` Object
* `screenPosition` string - Specify the screen type to emulate
(default: `desktop`):
* `desktop` - Desktop screen type.
* `mobile` - Mobile screen type.
* `screenSize` [Size](structures/size.md) - Set the emulated screen size (screenPosition == mobile).
* `viewPosition` [Point](structures/point.md) - Position the view on the screen
2018-09-13 16:10:51 +00:00
(screenPosition == mobile) (default: `{ x: 0, y: 0 }`).
2016-08-25 17:52:19 +00:00
* `deviceScaleFactor` Integer - Set the device scale factor (if zero defaults to
original device scale factor) (default: `0`).
* `viewSize` [Size](structures/size.md) - Set the emulated view size (empty means no override)
2016-08-25 17:52:19 +00:00
* `scale` Float - Scale of emulated view inside available space (not in fit to
view mode) (default: `1`).
2015-08-31 09:19:19 +00:00
Enable device emulation with the given parameters.
#### `contents.disableDeviceEmulation()`
2015-08-31 09:19:19 +00:00
Disable device emulation enabled by `webContents.enableDeviceEmulation`.
2015-09-18 09:44:11 +00:00
#### `contents.sendInputEvent(inputEvent)`
2015-09-18 09:44:11 +00:00
* `inputEvent` [MouseInputEvent](structures/mouse-input-event.md) | [MouseWheelInputEvent](structures/mouse-wheel-input-event.md) | [KeyboardInputEvent](structures/keyboard-input-event.md)
2015-09-18 09:44:11 +00:00
Sends an input `event` to the page.
**Note:** The [`BrowserWindow`](browser-window.md) containing the contents needs to be focused for
2017-06-05 17:03:25 +00:00
`sendInputEvent()` to work.
2015-09-18 09:44:11 +00:00
#### `contents.beginFrameSubscription([onlyDirty ,]callback)`
* `onlyDirty` boolean (optional) - Defaults to `false`.
* `callback` Function
* `image` [NativeImage](native-image.md)
2016-10-13 06:30:57 +00:00
* `dirtyRect` [Rectangle](structures/rectangle.md)
Begin subscribing for presentation events and captured frames, the `callback`
will be called with `callback(image, dirtyRect)` when there is a presentation
event.
The `image` is an instance of [NativeImage](native-image.md) that stores the
captured frame.
The `dirtyRect` is an object with `x, y, width, height` properties that
describes which part of the page was repainted. If `onlyDirty` is set to
`true`, `image` will only contain the repainted area. `onlyDirty` defaults to
`false`.
#### `contents.endFrameSubscription()`
End subscribing for frame presentation events.
#### `contents.startDrag(item)`
2016-07-03 06:10:59 +00:00
2016-10-13 03:38:06 +00:00
* `item` Object
* `file` string - The path to the file being dragged.
* `files` string[] (optional) - The paths to the files being dragged. (`files` will override `file` field)
* `icon` [NativeImage](native-image.md) | string - The image must be
non-empty on macOS.
2016-07-03 06:10:59 +00:00
Sets the `item` as dragging item for current drag-drop operation, `file` is the
absolute path of the file to be dragged, and `icon` is the image showing under
the cursor when dragging.
#### `contents.savePage(fullPath, saveType)`
2015-10-14 04:41:31 +00:00
* `fullPath` string - The full file path.
* `saveType` string - Specify the save type.
2015-10-14 04:41:31 +00:00
* `HTMLOnly` - Save only the HTML of the page.
* `HTMLComplete` - Save complete-html page.
* `MHTML` - Save complete-html page as MHTML.
Returns `Promise<void>` - resolves if the page is saved.
2015-10-14 04:41:31 +00:00
```javascript
2018-09-13 16:10:51 +00:00
const { BrowserWindow } = require('electron')
2020-07-09 17:18:49 +00:00
const win = new BrowserWindow()
win.loadURL('https://github.com')
2015-10-14 04:41:31 +00:00
win.webContents.on('did-finish-load', async () => {
win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {
console.log('Page was saved successfully.')
}).catch(err => {
console.log(err)
})
})
2015-10-14 04:41:31 +00:00
```
#### `contents.showDefinitionForSelection()` _macOS_
Shows pop-up dictionary that searches the selected word on the page.
2016-07-31 15:10:53 +00:00
#### `contents.isOffscreen()`
Returns `boolean` - Indicates whether *offscreen rendering* is enabled.
2016-07-31 15:10:53 +00:00
2016-07-30 22:22:34 +00:00
#### `contents.startPainting()`
If *offscreen rendering* is enabled and not painting, start painting.
#### `contents.stopPainting()`
If *offscreen rendering* is enabled and painting, stop painting.
#### `contents.isPainting()`
Returns `boolean` - If *offscreen rendering* is enabled returns whether it is currently painting.
2016-07-30 22:22:34 +00:00
#### `contents.setFrameRate(fps)`
2016-08-25 21:43:06 +00:00
* `fps` Integer
2016-07-30 22:22:34 +00:00
If *offscreen rendering* is enabled sets the frame rate to the specified number.
Only values between 1 and 240 are accepted.
2016-07-30 22:22:34 +00:00
#### `contents.getFrameRate()`
Returns `Integer` - If *offscreen rendering* is enabled returns the current frame rate.
2016-07-30 22:22:34 +00:00
2016-09-01 22:18:16 +00:00
#### `contents.invalidate()`
Schedules a full repaint of the window this web contents is in.
2016-09-01 22:18:16 +00:00
If *offscreen rendering* is enabled invalidates the frame and generates a new
one through the `'paint'` event.
#### `contents.getWebRTCIPHandlingPolicy()`
Returns `string` - Returns the WebRTC IP Handling Policy.
#### `contents.setWebRTCIPHandlingPolicy(policy)`
* `policy` string - Specify the WebRTC IP Handling Policy.
2017-11-29 10:58:24 +00:00
* `default` - Exposes user's public and local IPs. This is the default
behavior. When this policy is used, WebRTC has the right to enumerate all
2017-03-09 14:54:09 +00:00
interfaces and bind them to discover public interfaces.
* `default_public_interface_only` - Exposes user's public IP, but does not
2017-11-29 10:58:24 +00:00
expose user's local IP. When this policy is used, WebRTC should only use the
2017-03-09 14:54:09 +00:00
default route used by http. This doesn't expose any local addresses.
* `default_public_and_private_interfaces` - Exposes user's public and local
2017-11-29 10:58:24 +00:00
IPs. When this policy is used, WebRTC should only use the default route used
2017-03-09 14:54:09 +00:00
by http. This also exposes the associated default private address. Default
route is the route chosen by the OS on a multi-homed endpoint.
2017-11-29 10:58:24 +00:00
* `disable_non_proxied_udp` - Does not expose public or local IPs. When this
2017-03-09 14:54:09 +00:00
policy is used, WebRTC should only use TCP to contact peers or servers unless
the proxy server supports UDP.
Setting the WebRTC IP handling policy allows you to control which IPs are
exposed via WebRTC. See [BrowserLeaks](https://browserleaks.com/webrtc) for
2017-03-09 14:54:09 +00:00
more details.
#### `contents.getMediaSourceId(requestWebContents)`
* `requestWebContents` WebContents - Web contents that the id will be registered to.
Returns `string` - The identifier of a WebContents stream. This identifier can be used
with `navigator.mediaDevices.getUserMedia` using a `chromeMediaSource` of `tab`.
The identifier is restricted to the web contents that it is registered to and is only valid for 10 seconds.
2017-05-15 18:02:20 +00:00
#### `contents.getOSProcessId()`
Returns `Integer` - The operating system `pid` of the associated renderer
process.
#### `contents.getProcessId()`
2018-07-20 17:58:19 +00:00
Returns `Integer` - The Chromium internal `pid` of the associated renderer. Can
be compared to the `frameProcessId` passed by frame specific navigation events
(e.g. `did-frame-navigate`)
2017-05-15 18:02:20 +00:00
#### `contents.takeHeapSnapshot(filePath)`
* `filePath` string - Path to the output file.
Returns `Promise<void>` - Indicates whether the snapshot has been created successfully.
Takes a V8 heap snapshot and saves it to `filePath`.
#### `contents.getBackgroundThrottling()`
Returns `boolean` - whether or not this WebContents will throttle animations and timers
when the page becomes backgrounded. This also affects the Page Visibility API.
#### `contents.setBackgroundThrottling(allowed)`
* `allowed` boolean
Controls whether or not this WebContents will throttle animations and timers
when the page becomes backgrounded. This also affects the Page Visibility API.
#### `contents.getType()`
Returns `string` - the type of the webContent. Can be `backgroundPage`, `window`, `browserView`, `remote`, `webview` or `offscreen`.
#### `contents.setImageAnimationPolicy(policy)`
* `policy` string - Can be `animate`, `animateOnce` or `noAnimation`.
Sets the image animation policy for this webContents. The policy only affects
_new_ images, existing images that are currently being animated are unaffected.
This is a known limitation in Chromium, you can force image animation to be
recalculated with `img.src = img.src` which will result in no network traffic
but will update the animation policy.
This corresponds to the [animationPolicy][] accessibility feature in Chromium.
[animationPolicy]: https://developer.chrome.com/docs/extensions/reference/accessibilityFeatures/#property-animationPolicy
### Instance Properties
#### `contents.audioMuted`
A `boolean` property that determines whether this page is muted.
#### `contents.userAgent`
A `string` property that determines the user agent for this web page.
#### `contents.zoomLevel`
A `number` property that determines the zoom level for this web contents.
The original size is 0 and each increment above or below represents zooming 20% larger or smaller to default limits of 300% and 50% of original size, respectively. The formula for this is `scale := 1.2 ^ level`.
#### `contents.zoomFactor`
A `number` property that determines the zoom factor for this web contents.
The zoom factor is the zoom percent divided by 100, so 300% = 3.0.
#### `contents.frameRate`
An `Integer` property that sets the frame rate of the web contents to the specified number.
Only values between 1 and 240 are accepted.
Only applicable if *offscreen rendering* is enabled.
#### `contents.id` _Readonly_
2016-05-17 12:56:47 +00:00
A `Integer` representing the unique ID of this WebContents. Each ID is unique among all `WebContents` instances of the entire Electron application.
2016-05-17 12:56:47 +00:00
#### `contents.session` _Readonly_
2017-07-24 08:29:03 +00:00
A [`Session`](session.md) used by this webContents.
#### `contents.hostWebContents` _Readonly_
2016-11-10 20:25:26 +00:00
A [`WebContents`](web-contents.md) instance that might own this `WebContents`.
#### `contents.devToolsWebContents` _Readonly_
A `WebContents | null` property that represents the of DevTools `WebContents` associated with a given `WebContents`.
**Note:** Users should never store this object because it may become `null`
when the DevTools has been closed.
2016-01-21 18:22:23 +00:00
#### `contents.debugger` _Readonly_
A [`Debugger`](debugger.md) instance for this webContents.
2016-12-13 23:58:03 +00:00
#### `contents.backgroundThrottling`
A `boolean` property that determines whether or not this WebContents will throttle animations and timers
when the page becomes backgrounded. This also affects the Page Visibility API.
#### `contents.mainFrame` _Readonly_
A [`WebFrameMain`](web-frame-main.md) property that represents the top frame of the page's frame hierarchy.
[keyboardevent]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent
[event-emitter]: https://nodejs.org/api/events.html#events_class_eventemitter
[SCA]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
[`postMessage`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage