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

Merge branch 'master' into desktop-capture-api

Browse source
This commit is contained in:
Cheng Zhao 2015-12-08 12:43:44 +08:00
commit 04f7ceab73
464 changed files with 18563 additions and 4629 deletions
Download patch file Download diff file Expand all files Collapse all files

205
docs/api/app.md
View file

@ -6,7 +6,7 @@ The following example shows how to quit the application when the last window is
closed:
```javascript
var app = require('app');
const app = require('electron').app;
app.on('window-all-closed', function() {
app.quit();
});
@ -66,7 +66,7 @@ the `will-quit` and `window-all-closed` events.
Emitted when the application is quitting.
### Event: 'open-file'
### Event: 'open-file' _OS X_
Returns:
@ -82,7 +82,9 @@ handle this case (even before the `ready` event is emitted).
You should call `event.preventDefault()` if you want to handle this event.
### Event: 'open-url'
On Windows, you have to parse `process.argv` to get the filepath.
### Event: 'open-url' _OS X_
Returns:
@ -99,7 +101,7 @@ You should call `event.preventDefault()` if you want to handle this event.
Returns:
* `event` Event
* `hasVisibleWindows` Bool
* `hasVisibleWindows` Boolean
Emitted when the application is activated, which usually happens when clicks on
the applications's dock icon.
@ -131,32 +133,92 @@ Returns:
Emitted when a new [browserWindow](browser-window.md) is created.
### Event: 'select-certificate'
Emitted when a client certificate is requested.
### Event: 'certificate-error'
Returns:
* `event` Event
* `webContents` [WebContents](browser-window.md#class-webcontents)
* `url` String
* `certificateList` [Objects]
* `data` PEM encoded data
* `issuerName` Issuer's Common Name
* `webContents` [WebContents](web-contents.md)
* `url` URL
* `error` String - The error code
* `certificate` Object
* `data` Buffer - PEM encoded data
* `issuerName` String
* `callback` Function
Emitted when failed to verify the `certificate` for `url`, to trust the
certificate you should prevent the default behavior with
`event.preventDefault()` and call `callback(true)`.
```javascript
app.on('select-certificate', function(event, host, url, list, callback) {
event.preventDefault();
callback(list[0]);
})
session.on('certificate-error', function(event, webContents, url, error, certificate, callback) {
if (url == "https://github.com") {
// Verification logic.
event.preventDefault();
callback(true);
} else {
callback(false);
}
});
```
### Event: 'select-client-certificate'
Returns:
* `event` Event
* `webContents` [WebContents](web-contents.md)
* `url` URL
* `certificateList` [Objects]
* `data` Buffer - PEM encoded data
* `issuerName` String - Issuer's Common Name
* `callback` Function
Emitted when a client certificate is requested.
The `url` corresponds to the navigation entry requesting the client certificate
and `callback` needs to be called with an entry filtered from the list. Using
`event.preventDefault()` prevents the application from using the first
certificate from the store.
```javascript
app.on('select-client-certificate', function(event, webContents, url, list, callback) {
event.preventDefault();
callback(list[0]);
})
```
### Event: 'login'
Returns:
* `event` Event
* `webContents` [WebContents](web-contents.md)
* `request` Object
* `method` String
* `url` URL
* `referrer` URL
* `authInfo` Object
* `isProxy` Boolean
* `scheme` String
* `host` String
* `port` Integer
* `realm` String
* `callback` Function
Emitted when `webContents` wants to do basic auth.
The default behavior is to cancel all authentications, to override this you
should prevent the default behavior with `event.preventDefault()` and call
`callback(username, password)` with the credentials.
```javascript
app.on('login', function(event, webContents, request, authInfo, callback) {
event.preventDefault();
callback('username', 'secret');
})
```
### Event: 'gpu-process-crashed'
Emitted when the gpu process crashes.
@ -169,7 +231,7 @@ The `app` object has the following methods:
### `app.quit()`
Try to close all windows. The `before-quit` event will emitted first. If all
Try to close all windows. The `before-quit` event will be emitted first. If all
windows are successfully closed, the `will-quit` event will be emitted and by
default the application will terminate.
@ -177,6 +239,15 @@ This method guarantees that all `beforeunload` and `unload` event handlers are
correctly executed. It is possible that a window cancels the quitting by
returning `false` in the `beforeunload` event handler.
### `app.exit(exitCode)`
* `exitCode` Integer
Exits immediately with `exitCode`.
All windows will be closed immediately without asking user and the `before-quit`
and `will-quit` events will not be emitted.
### `app.getAppPath()`
Returns the current application directory.
@ -197,16 +268,15 @@ You can request the following paths by the name:
* `~/Library/Application Support` on OS X
* `userData` The directory for storing your app's configuration files, which by
default it is the `appData` directory appended with your app's name.
* `cache` Per-user application cache directory, which by default points to:
* `%APPDATA%` on Windows (which doesn't have a universal cache location)
* `$XDG_CACHE_HOME` or `~/.cache` on Linux
* `~/Library/Caches` on OS X
* `userCache` The directory for placing your app's caches, by default it is the
`cache` directory appended with your app's name.
* `temp` Temporary directory.
* `userDesktop` The current user's Desktop directory.
* `exe` The current executable file.
* `module` The `libchromiumcontent` library.
* `desktop` The current user's Desktop directory.
* `documents` Directory for a user's "My Documents".
* `downloads` Directory for a user's downloads.
* `music` Directory for a user's music.
* `pictures` Directory for a user's pictures.
* `videos` Directory for a user's videos.
### `app.setPath(name, path)`
@ -219,7 +289,7 @@ created by this method. On failure an `Error` is thrown.
You can only override paths of a `name` defined in `app.getPath`.
By default, web pages's cookies and caches will be stored under the `userData`
By default, web pages' cookies and caches will be stored under the `userData`
directory. If you want to change this location, you have to override the
`userData` path before the `ready` event of the `app` module is emitted.
@ -243,15 +313,7 @@ preferred over `name` by Electron.
Returns the current application locale.
### `app.resolveProxy(url, callback)`
* `url` URL
* `callback` Function
Resolves the proxy information for `url`. The `callback` will be called with
`callback(proxy)` when the request is performed.
### `app.addRecentDocument(path)`
### `app.addRecentDocument(path)` _OS X_ _Windows_
* `path` String
@ -260,7 +322,7 @@ Adds `path` to the recent documents list.
This list is managed by the OS. On Windows you can visit the list from the task
bar, and on OS X you can visit it from dock menu.
### `app.clearRecentDocuments()`
### `app.clearRecentDocuments()` _OS X_ _Windows_
Clears the recent documents list.
@ -270,7 +332,7 @@ Clears the recent documents list.
Adds `tasks` to the [Tasks][tasks] category of the JumpList on Windows.
`tasks` is an array of `Task` objects in following format:
`tasks` is an array of `Task` objects in the following format:
`Task` Object
* `program` String - Path of the program to execute, usually you should
@ -286,6 +348,76 @@ Adds `tasks` to the [Tasks][tasks] category of the JumpList on Windows.
consists of two or more icons, set this value to identify the icon. If an
icon file consists of one icon, this value is 0.
### `app.allowNTLMCredentialsForAllDomains(allow)`
* `allow` Boolean
Dynamically sets whether to always send credentials for HTTP NTLM or Negotiate
authentication - normally, Electron will only send NTLM/Kerberos credentials for
URLs that fall under "Local Intranet" sites (i.e. are in the same domain as you).
However, this detection often fails when corporate networks are badly configured,
so this lets you co-opt this behavior and enable it for all URLs.
### `app.makeSingleInstance(callback)`
* `callback` Function
This method makes your application a Single Instance Application - instead of
allowing multiple instances of your app to run, this will ensure that only a
single instance of your app is running, and other instances signal this
instance and exit.
`callback` will be called with `callback(argv, workingDirectory)` when a second
instance has been executed. `argv` is an Array of the second instance's command
line arguments, and `workingDirectory` is its current working directory. Usually
applications respond to this by making their primary window focused and
non-minimized.
The `callback` is guaranteed to be executed after the `ready` event of `app`
gets emitted.
This method returns `false` if your process is the primary instance of the
application and your app should continue loading. And returns `true` if your
process has sent its parameters to another instance, and you should immediately
quit.
On OS X the system enforces single instance automatically when users try to open
a second instance of your app in Finder, and the `open-file` and `open-url`
events will be emitted for that. However when users start your app in command
line the system's single instance machanism will be bypassed and you have to
use this method to ensure single instance.
An example of activating the window of primary instance when a second instance
starts:
```js
var myWindow = null;
var shouldQuit = app.makeSingleInstance(function(commandLine, workingDirectory) {
// Someone tried to run a second instance, we should focus our window
if (myWindow) {
if (myWindow.isMinimized()) myWindow.restore();
myWindow.focus();
}
return true;
});
if (shouldQuit) {
app.quit();
return;
}
// Create myWindow, load the rest of the app, etc...
app.on('ready', function() {
});
```
### `app.setAppUserModelId(id)` _Windows_
* `id` String
Changes the [Application User Model ID][app-user-model-id] to `id`.
### `app.commandLine.appendSwitch(switch[, value])`
Append a switch (with optional `value`) to Chromium's command line.
@ -346,3 +478,4 @@ Sets the application's [dock menu][dock-menu].
[dock-menu]:https://developer.apple.com/library/mac/documentation/Carbon/Conceptual/customizing_docktile/concepts/dockconcepts.html#//apple_ref/doc/uid/TP30000986-CH2-TPXREF103
[tasks]:http://msdn.microsoft.com/en-us/library/windows/desktop/dd378460(v=vs.85).aspx#tasks
[app-user-model-id]: https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v=vs.85).aspx

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

@ -1,106 +1,38 @@
# autoUpdater
**This module has only been implemented for OS X.**
This module provides an interface for the `Squirrel` auto-updater framework.
Check out [atom/grunt-electron-installer](https://github.com/atom/grunt-electron-installer)
to build a Windows installer for your app.
## Platform notices
The `auto-updater` module is a simple wrapper around the
[Squirrel.Mac](https://github.com/Squirrel/Squirrel.Mac) framework.
Though `autoUpdater` provides a uniform API for different platforms, there are
still some subtle differences on each platform.
Squirrel.Mac requires that your `.app` folder is signed using the
[codesign](https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/codesign.1.html)
utility for updates to be installed.
### OS X
## Squirrel
On OS X, the `autoUpdater` module is built upon [Squirrel.Mac][squirrel-mac],
meaning you don't need any special setup to make it work. For server-side
requirements, you can read [Server Support][server-support].
Squirrel is an OS X framework focused on making application updates **as safe
and transparent as updates to a website**.
### Windows
Instead of publishing a feed of versions from which your app must select,
Squirrel updates to the version your server tells it to. This allows you to
intelligently update your clients based on the request you give to Squirrel.
On Windows, you have to install your app into a user's machine before you can
use the auto-updater, so it is recommended to use
[grunt-electron-installer][installer] module to generate a Windows installer.
Your request can include authentication details, custom headers or a request
body so that your server has the context it needs in order to supply the most
suitable update.
The installer generated with Squirrel will create a shortcut icon with an
[Application User Model ID][app-user-model-id] in the format of
`com.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE`, examples are
`com.squirrel.slack.Slack` and `com.squirrel.code.Code`. You have to use the
same ID for your app with `app.setAppUserModelId` API, otherwise Windows will
not be able to pin your app properly in task bar.
The update JSON Squirrel requests should be dynamically generated based on
criteria in the request and whether an update is required. Squirrel relies
on server-side support to determine whether an update is required. See
[Server Support](#server-support).
The server-side setup is also different from OS X. You can read the documents of
[Squirrel.Windows][squirrel-windows] to get more details.
Squirrel's installer is designed to be fault tolerant and ensures that any
updates installed are valid.
### Linux
## Update Requests
Squirrel is indifferent to the request the client application provides for
update checking. `Accept: application/json` is added to the request headers
because Squirrel is responsible for parsing the response.
For the requirements imposed on the responses and the body format of an update
response, see [Server Support](#server-support).
Your update request must *at least* include a version identifier so that the
server can determine whether an update for this specific version is required. It
may also include other identifying criteria, such as operating system version or
username, to allow the server to deliver as fine grained an update as you
would like.
How you include the version identifier or other criteria is specific to the
server that you are requesting updates from. A common approach is to use query
parameters, like this:
```javascript
// In the main process
var app = require('app');
var autoUpdater = require('auto-updater');
autoUpdater.setFeedUrl('http://mycompany.com/myapp/latest?version=' + app.getVersion());
```
## Server Support
Your server should determine whether an update is required based on the
[Update Request](#update-requests) your client issues.
If an update is required, your server should respond with a status code of
[200 OK](http://tools.ietf.org/html/rfc2616#section-10.2.1) and include the
[update JSON](#update-json-format) in the body. Squirrel **will** download and
install this update, even if the version of the update is the same as the
currently running version. To save redundantly downloading the same version
multiple times your server must not inform the client to update.
If no update is required your server must respond with a status code of
[204 No Content](http://tools.ietf.org/html/rfc2616#section-10.2.5). Squirrel
will check for an update again at the interval you specify.
## Update JSON Format
When an update is available, Squirrel expects the following schema in response
to the update request provided:
```json
{
"url": "http://mycompany.com/myapp/releases/myrelease",
"name": "My Release Name",
"notes": "Theses are some release notes innit",
"pub_date": "2013-09-18T12:29:53+01:00"
}
```
The only required key is "url"; the others are optional.
Squirrel will request "url" with `Accept: application/zip` and only supports
installing ZIP updates. If future update formats are supported their MIME type
will be added to the `Accept` header so that your server can return the
appropriate format.
`pub_date` (if present) must be formatted according to ISO 8601.
## Update server implementations
[Nuts](https://github.com/GitbookIO/nuts) is an open source implementation of the update server described above, it integrates beautifully with GitHub releases. Nuts manages downloads and updates, it’s compatible with `Squirrel.Mac` and `Squirrel.Windows` so you get cross-platform support out of the box.
There is not built-in support for auto-updater on Linux, so it is recommended to
use the distribution's package manager to update your app.
## Events
@ -110,8 +42,7 @@ The `autoUpdater` object emits the following events:
Returns:
* `event` Event
* `message` String
* `error` Error
Emitted when there is an error while updating.
@ -136,24 +67,35 @@ Returns:
* `releaseNotes` String
* `releaseName` String
* `releaseDate` Date
* `updateUrl` String
* `quitAndUpdate` Function
* `updateURL` String
Emitted when an update has been downloaded. Calling `quitAndUpdate()` will
restart the application and install the update.
Emitted when an update has been downloaded.
On Windows only `releaseName` is available.
## Methods
The `autoUpdater` object has the following methods:
### `autoUpdater.setFeedUrl(url)`
### `autoUpdater.setFeedURL(url)`
* `url` String
Set the `url` and initialize the auto updater. The `url` cannot be changed
Sets the `url` and initialize the auto updater. The `url` cannot be changed
once it is set.
### `autoUpdater.checkForUpdates()`
Ask the server whether there is an update. You must call `setFeedUrl` before
Asks the server whether there is an update. You must call `setFeedURL` before
using this API.
### `autoUpdater.quitAndInstall()`
Restarts the app and installs the update after it has been downloaded. It
should only be called after `update-downloaded` has been emitted.
[squirrel-mac]: https://github.com/Squirrel/Squirrel.Mac
[server-support]: https://github.com/Squirrel/Squirrel.Mac#server-support
[squirrel-windows]: https://github.com/Squirrel/Squirrel.Windows
[installer]: https://github.com/atom/grunt-electron-installer
[app-user-model-id]: https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v=vs.85).aspx

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

@ -4,14 +4,14 @@ The `BrowserWindow` class gives you the ability to create a browser window. For
example:
```javascript
var BrowserWindow = require('browser-window');
const BrowserWindow = require('electron').BrowserWindow;
var win = new BrowserWindow({ width: 800, height: 600, show: false });
win.on('closed', function() {
win = null;
});
win.loadUrl('https://github.com');
win.loadURL('https://github.com');
win.show();
```
@ -24,104 +24,123 @@ You can also create a window without chrome by using
[EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).
It creates a new `BrowserWindow` with native properties as set by the `options`.
Properties `width` and `height` are required.
### `new BrowserWindow(options)`
### `new BrowserWindow([options])`
`options` Object, properties:
`options` Object (optional), properties:
* `width` Integer (**required**) - Window's width.
* `height` Integer (**required**) - Window's height.
* `x` Integer - Window's left offset from screen.
* `y` Integer - Window's top offset from screen.
* `use-content-size` Boolean - The `width` and `height` would be used as web
* `width` Integer - Window's width in pixels. Default is `800`.
* `height` Integer - Window's height in pixels. Default is `600`.
* `x` Integer - Window's left offset from screen. Default is to center the
window.
* `y` Integer - Window's top offset from screen. Default is to center the
window.
* `useContentSize` Boolean - The `width` and `height` would be used as web
page's size, which means the actual window's size will include window
frame's size and be slightly larger.
frame's size and be slightly larger. Default is `false`.
* `center` Boolean - Show window in the center of the screen.
* `min-width` Integer - Window's minimum width.
* `min-height` Integer - Window's minimum height.
* `max-width` Integer - Window's maximum width.
* `max-height` Integer - Window's maximum height.
* `resizable` Boolean - Whether window is resizable.
* `always-on-top` Boolean - Whether the window should always stay on top of
other windows.
* `minWidth` Integer - Window's minimum width. Default is `0`.
* `minHeight` Integer - Window's minimum height. Default is `0`.
* `maxWidth` Integer - Window's maximum width. Default is no limit.
* `maxHeight` Integer - Window's maximum height. Default is no limit.
* `resizable` Boolean - Whether window is resizable. Default is `true`.
* `alwaysOnTop` Boolean - Whether the window should always stay on top of
other windows. Default is `false`.
* `fullscreen` Boolean - Whether the window should show in fullscreen. When
set to `false` the fullscreen button will be hidden or disabled on OS X.
* `skip-taskbar` Boolean - Whether to show the window in taskbar.
* `kiosk` Boolean - The kiosk mode.
* `title` String - Default window title.
Default is `false`.
* `skipTaskbar` Boolean - Whether to show the window in taskbar. Default is
`false`.
* `kiosk` Boolean - The kiosk mode. Default is `false`.
* `title` String - Default window title. Default is `"Electron"`.
* `icon` [NativeImage](native-image.md) - The window icon, when omitted on
Windows the executable's icon would be used as window icon.
* `show` Boolean - Whether window should be shown when created.
* `show` Boolean - Whether window should be shown when created. Default is
`true`.
* `frame` Boolean - Specify `false` to create a
[Frameless Window](frameless-window.md).
* `accept-first-mouse` Boolean - Whether the web view accepts a single
mouse-down event that simultaneously activates the window.
* `disable-auto-hide-cursor` Boolean - Whether to hide cursor when typing.
* `auto-hide-menu-bar` Boolean - Auto hide the menu bar unless the `Alt`
key is pressed.
* `enable-larger-than-screen` Boolean - Enable the window to be resized larger
than screen.
* `dark-theme` Boolean - Forces using dark theme for the window, only works on
some GTK+3 desktop environments.
[Frameless Window](frameless-window.md). Default is `true`.
* `acceptFirstMouse` Boolean - Whether the web view accepts a single
mouse-down event that simultaneously activates the window. Default is `false`.
* `disableAutoHideCursor` Boolean - Whether to hide cursor when typing. Default
is `false`.
* `autoHideMenuBar` Boolean - Auto hide the menu bar unless the `Alt`
key is pressed. Default is `false`.
* `enableLargerThanScreen` Boolean - Enable the window to be resized larger
than screen. Default is `false`.
* `backgroundColor` String - Window's background color as Hexadecimal value,
like `#66CD00` or `#FFF`. This is only implemented on Linux and Windows.
Default is `#000` (black).
* `darkTheme` Boolean - Forces using dark theme for the window, only works on
some GTK+3 desktop environments. Default is `false`.
* `transparent` Boolean - Makes the window [transparent](frameless-window.md).
* `type` String - Specifies the type of the window, possible types are
`desktop`, `dock`, `toolbar`, `splash`, `notification`. This only works on
Linux.
* `standard-window` Boolean - Uses the OS X's standard window instead of the
textured window. Defaults to `true`.
* `title-bar-style` String, OS X - specifies the style of window title bar.
Default is `false`.
* `type` String - Specifies the type of the window, which applies
additional platform-specific properties. By default it's undefined and you'll
get a regular app window. Supported values:
* On Linux, possible types are `desktop`, `dock`, `toolbar`, `splash`,
`notification`.
* On OS X, possible types are `desktop`, `textured`. The `textured` type adds
metal gradient appearance (`NSTexturedBackgroundWindowMask`). The `desktop`
type places the window at the desktop background window level
(`kCGDesktopWindowLevel - 1`). Note that desktop window will not receive
focus, keyboard or mouse events, but you can use `globalShortcut` to receive
input sparingly.
* `titleBarStyle` String, OS X - specifies the style of window title bar.
This option is supported on OS X 10.10 Yosemite and newer. There are three
possible values:
* `default` or not specified results in the standard gray opaque Mac title
* `default` or not specified, results in the standard gray opaque Mac title
bar.
* `hidden` results in a hidden title bar and a full size content window, yet
the title bar still has the standard window controls ("traffic lights") in
the top left.
* `hidden-inset` results in a hidden title bar with an alternative look
where the traffic light buttons are slightly more inset from the window edge.
* `web-preferences` Object - Settings of web page's features, properties:
* `node-integration` Boolean - Whether node integration is enabled. Default
* `webPreferences` Object - Settings of web page's features, properties:
* `nodeIntegration` Boolean - Whether node integration is enabled. Default
is `true`.
* `preload` String - Specifies a script that will be loaded before other
scripts run in the page. This script will always have access to node APIs
no matter whether node integration is turned on for the page, and the path
of `preload` script has to be absolute path.
no matter whether node integration is turned on or off. The value should
be the absolute file path to the script.
When node integration is turned off, the preload script can reintroduce
Node global symbols back to the global scope. See example
[here](process.md#event-loaded).
* `partition` String - Sets the session used by the page. If `partition`
starts with `persist:`, the page will use a persistent session available to
all pages in the app with the same `partition`. if there is no `persist:`
prefix, the page will use an in-memory session. By assigning the same
`partition`, multiple pages can share the same session. If the `partition`
is unset then default session of the app will be used.
* `zoom-factor` Number - The default zoom factor of the page, `3.0` represents
`300%`.
* `javascript` Boolean
* `web-security` Boolean - When setting `false`, it will disable the
* `zoomFactor` Number - The default zoom factor of the page, `3.0` represents
`300%`. Default is `1.0`.
* `javascript` Boolean - Enables JavaScript support. Default is `true`.
* `webSecurity` Boolean - When setting `false`, it will disable the
same-origin policy (Usually using testing websites by people), and set
`allow_displaying_insecure_content` and `allow_running_insecure_content` to
`true` if these two options are not set by user.
* `allow-displaying-insecure-content` Boolean - Allow an https page to display
content like images from http URLs.
* `allow-running-insecure-content` Boolean - Allow a https page to run
JavaScript, CSS or plugins from http URLs.
* `images` Boolean
* `java` Boolean
* `text-areas-are-resizable` Boolean
* `webgl` Boolean
* `webaudio` Boolean
* `plugins` Boolean - Whether plugins should be enabled.
* `experimental-features` Boolean
* `experimental-canvas-features` Boolean
* `subpixel-font-scaling` Boolean
* `overlay-scrollbars` Boolean
* `overlay-fullscreen-video` Boolean
* `shared-worker` Boolean
* `direct-write` Boolean - Whether the DirectWrite font rendering system on
Windows is enabled.
* `page-visibility` Boolean - Page would be forced to be always in visible
`allowDisplayingInsecureContent` and `allowRunningInsecureContent` to
`true` if these two options are not set by user. Default is `true`.
* `allowDisplayingInsecureContent` Boolean - Allow an https page to display
content like images from http URLs. Default is `false`.
* `allowRunningInsecureContent` Boolean - Allow a https page to run
JavaScript, CSS or plugins from http URLs. Default is `false`.
* `images` Boolean - Enables image support. Default is `true`.
* `textAreasAreResizable` Boolean - Make TextArea elements resizable. Default
is `true`.
* `webgl` Boolean - Enables WebGL support. Default is `true`.
* `webaudio` Boolean - Enables WebAudio support. Default is `true`.
* `plugins` Boolean - Whether plugins should be enabled. Default is `false`.
* `experimentalFeatures` Boolean - Enables Chromium's experimental features.
Default is `false`.
* `experimentalCanvasFeatures` Boolean - Enables Chromium's experimental
canvas features. Default is `false`.
* `overlayScrollbars` Boolean - Enables overlay scrollbars. Default is
`false`.
* `sharedWorker` Boolean - Enables Shared Worker support. Default is `false`.
* `directWrite` Boolean - Enables DirectWrite font rendering system on
Windows. Default is `true`.
* `pageVisibility` Boolean - Page would be forced to be always in visible
or hidden state once set, instead of reflecting current window's
visibility. Users can set it to `true` to prevent throttling of DOM
timers.
timers. Default is `false`.
## Events
@ -232,19 +251,7 @@ Emitted when the window enters full screen state triggered by html api.
Emitted when the window leaves full screen state triggered by html api.
### 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: 'app-command':
### Event: 'app-command' _Windows_
Emitted when an [App Command](https://msdn.microsoft.com/en-us/library/windows/desktop/ms646275(v=vs.85).aspx)
is invoked. These are typically related to keyboard media keys or browser
@ -303,11 +310,8 @@ Remove the DevTools extension whose name is `name`.
Objects created with `new BrowserWindow` have the following properties:
```javascript
var BrowserWindow = require('browser-window');
// In this example `win` is our instance
var win = new BrowserWindow({ width: 800, height: 600 });
```
### `win.webContents`
@ -318,16 +322,6 @@ operations will be done via it.
See the [`webContents` documentation](web-contents.md) for its methods and
events.
**Note:** Users should never store this object because it may become `null`
when the renderer process (web page) has crashed.
### `win.devToolsWebContents`
Get the `WebContents` of DevTools for this window.
**Note:** Users should never store this object because it may become `null`
when the DevTools has been closed.
### `win.id`
The unique ID of this window.
@ -338,14 +332,6 @@ Objects created with `new BrowserWindow` have the following instance methods:
**Note:** Some methods are only available on specific operating systems and are labeled as such.
```javascript
var BrowserWindow = require('browser-window');
// In this example `win` is our instance
var win = new BrowserWindow({ width: 800, height: 600 });
```
### `win.destroy()`
Force closing the window, the `unload` and `beforeunload` event won't be emitted
@ -574,6 +560,30 @@ Enters or leaves the kiosk mode.
Returns whether the window is in kiosk mode.
### `win.hookWindowMessage(message, callback)` _Windows_
* `message` Integer
* `callback` Function
Hooks a windows message. The `callback` is called when
the message is received in the WndProc.
### `win.isWindowMessageHooked(message)` _Windows_
* `message` Integer
Returns `true` or `false` depending on whether the message is hooked.
### `win.unhookWindowMessage(message)` _Windows_
* `message` Integer
Unhook the window message.
### `win.unhookAllWindowMessages()` _Windows_
Unhooks all of the window messages.
### `win.setRepresentedFilename(filename)` _OS X_
* `filename` String
@ -592,45 +602,10 @@ Returns the pathname of the file the window represents.
Specifies whether the window’s document has been edited, and the icon in title
bar will become grey when set to `true`.
### `win.IsDocumentEdited()` _OS X_
### `win.isDocumentEdited()` _OS X_
Whether the window's document has been edited.
### `win.openDevTools([options])`
* `options` Object (optional). Properties:
* `detach` Boolean - opens DevTools in a new window
Opens the developer tools.
### `win.closeDevTools()`
Closes the developer tools.
### `win.isDevToolsOpened()`
Returns whether the developer tools are opened.
### `win.toggleDevTools()`
Toggles the developer tools.
### `win.isDevToolsFocused()`
Returns whether the developer tools is focused.
### `win.inspectElement(x, y)`
* `x` Integer
* `y` Integer
Starts inspecting element at position (`x`, `y`).
### `win.inspectServiceWorker()`
Opens the developer tools for the service worker context present in the web
contents.
### `win.focusOnWebView()`
### `win.blurWebView()`
@ -657,9 +632,9 @@ Same as `webContents.print([options])`
Same as `webContents.printToPDF(options, callback)`
### `win.loadUrl(url[, options])`
### `win.loadURL(url[, options])`
Same as `webContents.loadUrl(url[, options])`.
Same as `webContents.loadURL(url[, options])`.
### `win.reload()`

65
docs/api/chrome-command-line-switches.md
View file

@ -1,12 +1,12 @@
# Supported Chrome command line switches
This page lists the command line switches used by the Chrome browser that are also supported by
Electron. You can use [app.commandLine.appendSwitch][append-switch] to append
them in your app's main script before the [ready][ready] event of [app][app]
module is emitted:
This page lists the command line switches used by the Chrome browser that are
also supported by Electron. You can use
[app.commandLine.appendSwitch][append-switch] to append them in your app's main
script before the [ready][ready] event of [app][app] module is emitted:
```javascript
var app = require('app');
const app = require('electron').app;
app.commandLine.appendSwitch('remote-debugging-port', '8315');
app.commandLine.appendSwitch('host-rules', 'MAP * 127.0.0.1');
@ -31,10 +31,37 @@ Disables the disk cache for HTTP requests.
Enables remote debugging over HTTP on the specified `port`.
## --js-flags=`flags`
Specifies the flags passed to JS engine. It has to be passed when starting
Electron if you want to enable the `flags` in the main process.
```bash
$ electron --js-flags="--harmony_proxies --harmony_collections" your-app
```
## --proxy-server=`address:port`
Use a specified proxy server, which overrides the system setting. This switch only
affects HTTP and HTTPS requests.
Use a specified proxy server, which overrides the system setting. This switch
only affects requests with HTTP protocol, including HTTPS and WebSocket
requests. It is also noteworthy that not all proxy servers support HTTPS and
WebSocket requests.
## --proxy-bypass-list=`hosts`
Instructs Electron to bypass the proxy server for the given semi-colon-separated
list of hosts. This flag has an effect only if used in tandem with
`--proxy-server`.
For example:
```javascript
app.commandLine.appendSwitch('proxy-bypass-list', '<local>;*.google.com;*foo.com;1.2.3.4:5678')`
```
Will use the proxy server for all hosts except for local addresses (`localhost`,
`127.0.0.1` etc.), `google.com` subdomains, hosts that contain the suffix
`foo.com` and anything at `1.2.3.4:5678`.
## --proxy-pac-url=`url`
@ -89,15 +116,27 @@ Enables net log events to be saved and writes them to `path`.
## --ssl-version-fallback-min=`version`
Set the minimum SSL/TLS version ("tls1", "tls1.1" or "tls1.2") that TLS
Sets the minimum SSL/TLS version ("tls1", "tls1.1" or "tls1.2") that TLS
fallback will accept.
## --cipher-suite-blacklist=`cipher_suites`
Specify comma-separated list of SSL cipher suites to disable.
## --enable-logging
Prints Chromium's logging into console.
This switch can not be used in `app.commandLine.appendSwitch` since it is parsed
earlier than user's app is loaded, but you can set the `ELECTRON_ENABLE_LOGGING`
environment variable to achieve the same effect.
## --v=`log_level`
Gives the default maximal active V-logging level; 0 is the default. Normally
positive values are used for V-logging levels.
Passing `--v=-1` will disable logging.
This switch only works when `--enable-logging` is also passed.
## --vmodule=`pattern`
@ -109,10 +148,4 @@ Any pattern containing a forward or backward slash will be tested against the
whole pathname and not just the module. E.g. `*/foo/bar/*=2` would change the
logging level for all code in the source files under a `foo/bar` directory.
To disable all chromium related logs and only enable your application logs you
can do:
```javascript
app.commandLine.appendSwitch('v', -1);
app.commandLine.appendSwitch('vmodule', 'console=0');
```
This switch only works when `--enable-logging` is also passed.

5
docs/api/clipboard.md
View file

@ -4,7 +4,7 @@ The `clipboard` module provides methods to perform copy and paste operations.
The following example shows how to write a string to the clipboard:
```javascript
var clipboard = require('clipboard');
const clipboard = require('electron').clipboard;
clipboard.writeText('Example String');
```
@ -12,7 +12,6 @@ On X Window systems, there is also a selection clipboard. To manipulate it
you need to pass `selection` to each method:
```javascript
var clipboard = require('clipboard');
clipboard.writeText('Example String', 'selection');
console.log(clipboard.readText('selection'));
```
@ -82,7 +81,6 @@ Returns an array of supported formats for the clipboard `type`.
Returns whether the clipboard supports the format of specified `data`.
```javascript
var clipboard = require('clipboard');
console.log(clipboard.has('<p>selection</p>'));
```
@ -102,7 +100,6 @@ Reads `data` from the clipboard.
* `type` String (optional)
```javascript
var clipboard = require('clipboard');
clipboard.write({text: 'test', html: "<b>test</b>"});
```
Writes `data` to the clipboard.

9
docs/api/content-tracing.md
View file

@ -6,9 +6,14 @@ so you need to open `chrome://tracing/` in a Chrome browser and load the
generated file to view the result.
```javascript
var contentTracing = require('content-tracing');
const contentTracing = require('electron').contentTracing;
contentTracing.startRecording('*', contentTracing.DEFAULT_OPTIONS, function() {
const options = {
categoryFilter: '*',
traceOptions: 'record-until-full,enable-sampling'
}
contentTracing.startRecording(options, function() {
console.log('Tracing started');
setTimeout(function() {

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

@ -6,12 +6,12 @@ The following is an example of automatically submitting a crash report to a
remote server:
```javascript
var crashReporter = require('crash-reporter');
const crashReporter = require('electron').crashReporter;
crashReporter.start({
productName: 'YourName',
companyName: 'YourCompany',
submitUrl: 'https://your-domain.com/url-to-submit',
submitURL: 'https://your-domain.com/url-to-submit',
autoSubmit: true
});
```
@ -26,7 +26,7 @@ The `crash-reporter` module has the following methods:
* `productName` String, default: Electron.
* `companyName` String, default: GitHub, Inc.
* `submitUrl` String, default: http://54.249.141.255:1127/post.
* `submitURL` String, default: http://54.249.141.255:1127/post.
* URL that crash reports will be sent to as POST.
* `autoSubmit` Boolean, default: `true`.
* Send the crash report without user interaction.
@ -57,13 +57,12 @@ ID.
## crash-reporter Payload
The crash reporter will send the following data to the `submitUrl` as `POST`:
The crash reporter will send the following data to the `submitURL` as `POST`:
* `rept` String - e.g. 'electron-crash-service'.
* `ver` String - The version of Electron.
* `platform` String - e.g. 'win32'.
* `process_type` String - e.g. 'renderer'.
* `ptime` Number
* `guid` String - e.g. '5e1286fc-da97-479e-918b-6bfb0c3d1c72'
* `_version` String - The version in `package.json`.
* `_productName` String - The product name in the `crashReporter` `options`
object.

6
docs/api/dialog.md
View file

@ -8,7 +8,7 @@ An example of showing a dialog to select multiple files and directories:
```javascript
var win = ...; // BrowserWindow in which to show the dialog
var dialog = require('dialog');
const dialog = require('electron').dialog;
console.log(dialog.showOpenDialog({ properties: [ 'openFile', 'openDirectory', 'multiSelections' ]}));
```
@ -114,4 +114,6 @@ will be passed via `callback(response)`.
Displays a modal dialog that shows an error message.
This API can be called safely before the `ready` event the `app` module emits,
it is usually used to report errors in early stage of startup.
it is usually used to report errors in early stage of startup. If called
before the app `ready`event on Linux, the message will be emitted to stderr,
and no GUI dialog will appear.

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

@ -39,7 +39,7 @@ Emits when the `downloadItem` gets updated.
* `interrupted` - An error broke the connection with the file server.
Emits when the download is in a terminal state. This includes a completed
download, a cancelled download(via `downloadItem.cancel()`), and interrputed
download, a cancelled download(via `downloadItem.cancel()`), and interrupted
download that can't be resumed.
## Methods

50
docs/api/environment-variables.md Normal file
View file

@ -0,0 +1,50 @@
# Environment variables
Some behaviors of Electron are controlled by environment variables, because they
are initialized earlier than command line and the app's code.
Examples on POSIX shells:
```bash
$ export ELECTRON_ENABLE_LOGGING=true
$ electron
```
on Windows console:
```powershell
> set ELECTRON_ENABLE_LOGGING=true
> electron
```
## `ELECTRON_RUN_AS_NODE`
Starts the process as a normal Node.js process.
## `ELECTRON_ENABLE_LOGGING`
Prints Chrome's internal logging to console.
## `ELECTRON_ENABLE_STACK_DUMPING`
When Electron crashed, prints the stack trace to console.
This environment variable will not work if `crashReporter` is started.
## `ELECTRON_DEFAULT_ERROR_MODE` _Windows_
Shows Windows's crash dialog when Electron crashed.
This environment variable will not work if `crashReporter` is started.
## `ELECTRON_NO_ATTACH_CONSOLE` _Windows_
Don't attach to current console session.
## `ELECTRON_FORCE_WINDOW_MENU_BAR` _Linux_
Don't use global menu bar on Linux.
## `ELECTRON_HIDE_INTERNAL_MODULES`
Turns off compatibility mode for old built-in modules like `require('ipc')`.

9
docs/api/frameless-window.md
View file

@ -1,6 +1,6 @@
# Frameless Window
A frameless window is a window that has no [chrome](https://developer.mozilla.org/en-US/docs/Glossary/Chrome), the parts of the window, like toolbars, that are not a part of the webp page. These are options on the [`BrowserWindow`](browser-window.md) class.
A frameless window is a window that has no [chrome](https://developer.mozilla.org/en-US/docs/Glossary/Chrome), the parts of the window, like toolbars, that are not a part of the web page. These are options on the [`BrowserWindow`](browser-window.md) class.
## Create a frameless window
@ -9,11 +9,11 @@ To create a frameless window, you need to set `frame` to `false` in
```javascript
var BrowserWindow = require('browser-window');
const BrowserWindow = require('electron').BrowserWindow;
var win = new BrowserWindow({ width: 800, height: 600, frame: false });
```
### Alternatives on Mac
### Alternatives on OS X
On Mac OS X 10.10 Yosemite and newer, there's an alternative way to specify
a chromeless window. Instead of setting `frame` to `false` which disables
@ -23,8 +23,7 @@ the window controls ("traffic lights") for standard window actions.
You can do so by specifying the new `title-bar-style` option:
```javascript
var BrowserWindow = require('browser-window');
var win = new BrowserWindow({ width: 800, height: 600, 'title-bar-style': 'hidden' });
var win = new BrowserWindow({ 'title-bar-style': 'hidden' });
```
## Transparent window

14
docs/api/global-shortcut.md
View file

@ -9,14 +9,15 @@ not have the keyboard focus. You should not use this module until the `ready`
event of the app module is emitted.
```javascript
var app = require('app');
var globalShortcut = require('global-shortcut');
const electron = require('electron');
const app = electron.app;
const globalShortcut = electron.globalShortcut;
app.on('ready', function() {
// Register a 'ctrl+x' shortcut listener.
var ret = globalShortcut.register('ctrl+x', function() {
console.log('ctrl+x is pressed');
})
});
if (!ret) {
console.log('registration failed');
@ -45,7 +46,10 @@ The `global-shortcut` module has the following methods:
* `callback` Function
Registers a global shortcut of `accelerator`. The `callback` is called when
the registered shortcut is pressed by the user.
the registered shortcut is pressed by the user. Returns `true` if the shortcut
`accelerator` was registered, `false` otherwise. For example, the specified
`accelerator` has already been registered by another caller or other native
applications.
### `globalShortcut.isRegistered(accelerator)`
@ -62,4 +66,4 @@ Unregisters the global shortcut of `accelerator`.
### `globalShortcut.unregisterAll()`
Unregisters all the global shortcuts.
Unregisters all of the global shortcuts.

76
docs/api/ipc-main-process.md
View file

@ -1,76 +0,0 @@
# ipc (main process)
The `ipc` module, when used in the main process, handles asynchronous and
synchronous messages sent from a renderer process (web page). Messages sent from
a renderer will be emitted to this module.
## Sending Messages
It is also possible to send messages from the main process to the renderer
process, see [WebContents.send](web-contents.md#webcontentssendchannel-args)
for more information.
- When sending a message, the event name is the `channel`.
- To reply a synchronous message, you need to set `event.returnValue`.
- To send an asynchronous back to the sender, you can use
`event.sender.send(...)`.
An example of sending and handling messages between the render and main
processes:
```javascript
// In main process.
var ipc = require('ipc');
ipc.on('asynchronous-message', function(event, arg) {
console.log(arg); // prints "ping"
event.sender.send('asynchronous-reply', 'pong');
});
ipc.on('synchronous-message', function(event, arg) {
console.log(arg); // prints "ping"
event.returnValue = 'pong';
});
```
```javascript
// In renderer process (web page).
var ipc = require('ipc');
console.log(ipc.sendSync('synchronous-message', 'ping')); // prints "pong"
ipc.on('asynchronous-reply', function(arg) {
console.log(arg); // prints "pong"
});
ipc.send('asynchronous-message', 'ping');
```
## Listening for Messages
The `ipc` module has the following method to listen for events:
### `ipc.on(channel, callback)`
* `channel` String - The event name.
* `callback` Function
When the event occurs the `callback` is called with an `event` object and a
message, `arg`.
## IPC Events
The `event` object passed to the `callback` has the following methods:
### `Event.returnValue`
Set this to the value to be returned in a synchronous message.
### `Event.sender`
Returns the `WebContents` that sent the message.
### `Event.sender.send(channel[, arg1][, arg2][, ...])`
* `channel` String - The event name.
* `arg` (optional)
This sends an asynchronous message back to the render process. Optionally, there
can be one or a series of arguments, `arg`, which can have any type.

71
docs/api/ipc-main.md Normal file
View file

@ -0,0 +1,71 @@
# ipcMain
The `ipcMain` module, when used in the main process, handles asynchronous and
synchronous messages sent from a renderer process (web page). Messages sent from
a renderer will be emitted to this module.
## Sending Messages
It is also possible to send messages from the main process to the renderer
process, see [webContents.send][webcontents-send] for more information.
* When sending a message, the event name is the `channel`.
* To reply a synchronous message, you need to set `event.returnValue`.
* To send an asynchronous back to the sender, you can use
`event.sender.send(...)`.
An example of sending and handling messages between the render and main
processes:
```javascript
// In main process.
const ipcMain = require('electron').ipcMain;
ipcMain.on('asynchronous-message', function(event, arg) {
console.log(arg); // prints "ping"
event.sender.send('asynchronous-reply', 'pong');
});
ipcMain.on('synchronous-message', function(event, arg) {
console.log(arg); // prints "ping"
event.returnValue = 'pong';
});
```
```javascript
// In renderer process (web page).
const ipcRenderer = require('electron').ipcRenderer;
console.log(ipcRenderer.sendSync('synchronous-message', 'ping')); // prints "pong"
ipcRenderer.on('asynchronous-reply', function(event, arg) {
console.log(arg); // prints "pong"
});
ipcRenderer.send('asynchronous-message', 'ping');
```
## Listening for Messages
The `ipcMain` module has the following method to listen for events:
### `ipcMain.on(channel, callback)`
* `channel` String - The event name.
* `callback` Function
When the event occurs the `callback` is called with an `event` object and a
message, `arg`.
## IPC Event
The `event` object passed to the `callback` has the following methods:
### `event.returnValue`
Set this to the value to be returned in a synchronous message.
### `event.sender`
Returns the `webContents` that sent the message, you can call
`event.sender.send` to reply to the asynchronous message, see
[webContents.send][webcontents-send] for more information.
[webcontents-send]: web-contents.md#webcontentssendchannel-args

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

@ -1,52 +1,54 @@
# ipc (renderer)
# ipcRenderer
The `ipc` module provides a few methods so you can send synchronous and
The `ipcRenderer` module provides a few methods so you can send synchronous and
asynchronous messages from the render process (web page) to the main process.
You can also receive replies from the main process.
**Note:** If you want to make use of modules in the main process from the renderer
process, you might consider using the [remote](remote.md) module.
See [ipcMain](ipc-main.md) for code examples.
See [ipc (main process)](ipc-main-process.md) for code examples.
## Listening for Messages
## Methods
The `ipcRenderer` module has the following method to listen for events:
The `ipc` module has the following methods for sending messages:
### `ipcRenderer.on(channel, callback)`
**Note:** When using these methods to send a `message` you must also listen
for it in the main process with [`ipc (main process)`](ipc-main-process.md).
* `channel` String - The event name.
* `callback` Function
### `ipc.send(channel[, arg1][, arg2][, ...])`
When the event occurs the `callback` is called with an `event` object and
arbitrary arguments.
## Sending Messages
The `ipcRenderer` module has the following methods for sending messages:
### `ipcRenderer.send(channel[, arg1][, arg2][, ...])`
* `channel` String - The event name.
* `arg` (optional)
Send an event to the main process asynchronously via a `channel`. Optionally,
there can be a message: one or a series of arguments, `arg`, which can have any
type. The main process handles it by listening for the `channel` event with
`ipc`.
Send an event to the main process asynchronously via a `channel`, you can also
send arbitrary arguments. The main process handles it by listening for the
`channel` event with `ipcMain`.
### `ipc.sendSync(channel[, arg1][, arg2][, ...])`
### `ipcRenderer.sendSync(channel[, arg1][, arg2][, ...])`
* `channel` String - The event name.
* `arg` (optional)
Send an event to the main process synchronously via a `channel`. Optionally,
there can be a message: one or a series of arguments, `arg`, which can have any
type. The main process handles it by listening for the `channel` event with
`ipc`.
Send an event to the main process synchronously via a `channel`, you can also
send arbitrary arguments.
The main process handles it by listening for the `channel` event with `ipc` and
replies by setting the `event.returnValue`.
The main process handles it by listening for the `channel` event with
`ipcMain` and replies by setting `event.returnValue`.
**Note:** Sending a synchronous message will block the whole renderer process so
using this method is not recommended.
__Note:__ Sending a synchronous message will block the whole renderer process,
unless you know what you are doing you should never use it.
### `ipc.sendToHost(channel[, arg1][, arg2][, ...])`
### `ipcRenderer.sendToHost(channel[, arg1][, arg2][, ...])`
* `channel` String - The event name.
* `arg` (optional)
Like `ipc.send` but the event will be sent to the host page in a `<webview>`
instead of the main process. Optionally, there can be a message: one or a series
of arguments, `arg`, which can have any type.
Like `ipcRenderer.send` but the event will be sent to the `<webview>` element in
the host page instead of the main process.

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

@ -1,6 +1,6 @@
# MenuItem
The `menu-item` module allows you to add items to an application or content
The `menu-item` module allows you to add items to an application or context
[`menu`](menu.md).
See [`menu`](menu.md) for examples.

16
docs/api/menu.md
View file

@ -16,9 +16,9 @@ the user right clicks the page:
```html
<!-- index.html -->
<script>
var remote = require('remote');
var Menu = remote.require('menu');
var MenuItem = remote.require('menu-item');
const remote = require('electron').remote;
const Menu = remote.Menu;
const MenuItem = remote.MenuItem;
var menu = new Menu();
menu.append(new MenuItem({ label: 'MenuItem1', click: function() { console.log('item 1 clicked'); } }));
@ -136,14 +136,14 @@ var template = [
submenu: [
{
label: 'Learn More',
click: function() { require('shell').openExternal('http://electron.atom.io') }
click: function() { require('electron').shell.openExternal('http://electron.atom.io') }
},
]
},
];
if (process.platform == 'darwin') {
var name = require('app').getName();
var name = require('electron').app.getName();
template.unshift({
label: name,
submenu: [
@ -225,7 +225,7 @@ will be set as each window's top menu.
Sends the `action` to the first responder of application. This is used for
emulating default Cocoa menu behaviors, usually you would just use the
`selector` property of `MenuItem`.
`role` property of `MenuItem`.
### `Menu.buildFromTemplate(template)`
@ -237,9 +237,9 @@ Generally, the `template` is just an array of `options` for constructing a
You can also attach other fields to the element of the `template` and they
will become properties of the constructed menu items.
### `Menu.popup(browserWindow[, x, y])`
### `Menu.popup([browserWindow, x, y])`
* `browserWindow` BrowserWindow
* `browserWindow` BrowserWindow (optional)
* `x` Number (optional)
* `y` Number (**required** if `x` is used)

35
docs/api/native-image.md
View file

@ -1,7 +1,7 @@
# NativeImage
# nativeImage
In Electron, for the APIs that take images, you can pass either file paths or
`NativeImage` instances. An empty image will be used when `null` is passed.
`nativeImage` instances. An empty image will be used when `null` is passed.
For example, when creating a tray or setting a window's icon, you can pass an
image file path as a `String`:
@ -11,10 +11,9 @@ var appIcon = new Tray('/Users/somebody/images/icon.png');
var window = new BrowserWindow({icon: '/Users/somebody/images/window.png'});
```
Or read the image from the clipboard which returns a `NativeImage`:
Or read the image from the clipboard which returns a `nativeImage`:
```javascript
var clipboard = require('clipboard');
var image = clipboard.readImage();
var appIcon = new Tray(image);
```
@ -84,40 +83,40 @@ To mark an image as a template image, its filename should end with the word
## Methods
The `NativeImage` class has the following methods:
The `nativeImage` class has the following methods:
### `NativeImage.createEmpty()`
### `nativeImage.createEmpty()`
Creates an empty `NativeImage` instance.
Creates an empty `nativeImage` instance.
### `NativeImage.createFromPath(path)`
### `nativeImage.createFromPath(path)`
* `path` String
Creates a new `NativeImage` instance from a file located at `path`.
Creates a new `nativeImage` instance from a file located at `path`.
### `NativeImage.createFromBuffer(buffer[, scaleFactor])`
### `nativeImage.createFromBuffer(buffer[, scaleFactor])`
* `buffer` [Buffer][buffer]
* `scaleFactor` Double (optional)
Creates a new `NativeImage` instance from `buffer`. The default `scaleFactor` is
Creates a new `nativeImage` instance from `buffer`. The default `scaleFactor` is
1.0.
### `NativeImage.createFromDataUrl(dataUrl)`
### `nativeImage.createFromDataURL(dataURL)`
* `dataUrl` String
* `dataURL` String
Creates a new `NativeImage` instance from `dataUrl`.
Creates a new `nativeImage` instance from `dataURL`.
## Instance Methods
The following methods are available on instances of `nativeImage`:
```javascript
var NativeImage = require('native-image');
const nativeImage = require('electron').nativeImage;
var image = NativeImage.createFromPath('/Users/somebody/images/icon.png');
var image = nativeImage.createFromPath('/Users/somebody/images/icon.png');
```
### `image.toPng()`
@ -130,7 +129,7 @@ Returns a [Buffer][buffer] that contains the image's `PNG` encoded data.
Returns a [Buffer][buffer] that contains the image's `JPEG` encoded data.
### `image.toDataUrl()`
### `image.toDataURL()`
Returns the data URL of the image.
@ -142,7 +141,7 @@ Returns a boolean whether the image is empty.
Returns the size of the image.
[buffer]: https://iojs.org/api/buffer.html#buffer_class_buffer
[buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer
### `image.setTemplateImage(option)`

6
docs/api/power-monitor.md
View file

@ -1,4 +1,4 @@
# power-monitor
# powerMonitor
The `power-monitor` module is used to monitor power state changes. You can
only use it in the main process. You should not use this module until the `ready`
@ -7,10 +7,8 @@ event of the `app` module is emitted.
For example:
```javascript
var app = require('app');
app.on('ready', function() {
require('power-monitor').on('suspend', function() {
require('electron').powerMonitor.on('suspend', function() {
console.log('The system is going to sleep');
});
});

4
docs/api/power-save-blocker.md
View file

@ -1,13 +1,13 @@
# powerSaveBlocker
The `power-save-blocker` module is used to block the system from entering
The `powerSaveBlocker` module is used to block the system from entering
low-power (sleep) mode and thus allowing the app to keep the system and screen
active.
For example:
```javascript
var powerSaveBlocker = require('power-save-blocker');
const powerSaveBlocker = require('electron').powerSaveBlocker;
var id = powerSaveBlocker.start('prevent-display-sleep');
console.log(powerSaveBlocker.isStarted(id));

35
docs/api/process.md
View file

@ -8,16 +8,45 @@ upstream node:
* `process.versions['electron']` String - Version of Electron.
* `process.versions['chrome']` String - Version of Chromium.
* `process.resourcesPath` String - Path to JavaScript source code.
* `process.mas` Boolean - For Mac App Store build, this value is `true`, for
other builds it is `undefined`.
# Methods
## Events
### Event: 'loaded'
Emitted when Electron has loaded its internal initialization script and is
beginning to load the web page or the main script.
It can be used by the preload script to add removed Node global symbols back to
the global scope when node integration is turned off:
```js
// preload.js
var _setImmediate = setImmediate;
var _clearImmediate = clearImmediate;
process.once('loaded', function() {
global.setImmediate = _setImmediate;
global.clearImmediate = _clearImmediate;
});
```
## Properties
### `process.noAsar`
Setting this to `true` can disable the support for `asar` archives in Node's
built-in modules.
## Methods
The `process` object has the following method:
### `process.hang`
### `process.hang()`
Causes the main thread of the current process hang.
## process.setFdLimit(maxDescriptors) _OS X_ _Linux_
### `process.setFdLimit(maxDescriptors)` _OS X_ _Linux_
* `maxDescriptors` Integer

15
docs/api/protocol.md
View file

@ -7,11 +7,12 @@ An example of implementing a protocol that has the same effect as the
`file://` protocol:
```javascript
var app = require('app');
var path = require('path');
const electron = require('electron');
const app = electron.app;
const path = require('path');
app.on('ready', function() {
var protocol = require('protocol');
var protocol = electron.protocol;
protocol.registerFileProtocol('atom', function(request, callback) {
var url = request.url.substr(7);
callback({path: path.normalize(__dirname + '/' + url)});
@ -102,7 +103,7 @@ Registers a protocol of `scheme` that will send a `String` as a response. The
Registers a protocol of `scheme` that will send an HTTP request as a response.
The `callback` should be called with an object that has the `url`, `method`,
`referer`, and `session` properties.
`referrer`, and `session` properties.
By default the HTTP request will reuse the current session. If you want the
request to have a different session you should set `session` to `null`.
@ -140,7 +141,7 @@ which sends a file as a response.
Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
which sends a `String` as a response.
## `protocol.interceptBufferProtocol(scheme, handler[, completion])`
### `protocol.interceptBufferProtocol(scheme, handler[, completion])`
* `scheme` String
* `handler` Function
@ -149,7 +150,7 @@ which sends a `String` as a response.
Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
which sends a `Buffer` as a response.
## `protocol.interceptHttpProtocol(scheme, handler[, completion])`
### `protocol.interceptHttpProtocol(scheme, handler[, completion])`
* `scheme` String
* `handler` Function
@ -158,7 +159,7 @@ which sends a `Buffer` as a response.
Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
which sends a new HTTP request as a response.
## `protocol.uninterceptProtocol(scheme[, completion])`
### `protocol.uninterceptProtocol(scheme[, completion])`
* `scheme` String
* `completion` Function

34
docs/api/remote.md
View file

@ -3,21 +3,20 @@
The `remote` module provides a simple way to do inter-process communication
(IPC) between the renderer process (web page) and the main process.
In Electron, only GUI-unrelated modules are available in the renderer process.
Without the `remote` module, users who want to call a main process API in
the renderer process will have to explicitly send inter-process messages
to the main process. With the `remote` module, you can invoke methods of the
main process object without explicitly sending inter-process messages, similar
to Java's [RMI](http://en.wikipedia.org/wiki/Java_remote_method_invocation).
An example of creating a browser window from a renderer process:
In Electron, GUI-related modules (such as `dialog`, `menu` etc.) are only
available in the main process, not in the renderer process. In order to use them
from the renderer process, the `ipc` module is necessary to send inter-process
messages to the main process. With the `remote` module, you can invoke methods
of the main process object without explicitly sending inter-process messages,
similar to Java's [RMI][rmi]. An example of creating a browser window from a
renderer process:
```javascript
var remote = require('remote');
var BrowserWindow = remote.require('browser-window');
const remote = require('electron').remote;
const BrowserWindow = remote.BrowserWindow;
var win = new BrowserWindow({ width: 800, height: 600 });
win.loadUrl('https://github.com');
win.loadURL('https://github.com');
```
**Note:** for the reverse (access the renderer process from the main process),
@ -101,8 +100,6 @@ For example, the following code seems innocent at first glance. It installs a
callback for the `close` event on a remote object:
```javascript
var remote = require('remote');
remote.getCurrentWindow().on('close', function() {
// blabla...
});
@ -121,6 +118,15 @@ passed to the main process. This involves cleaning up event handlers, or
ensuring the main process is explicitly told to deference callbacks that came
from a renderer process that is exiting.
## Accessing built-in modules in the main process
The built-in modules in the main process are added as getters in the `remote`
module, so you can use them directly like the `electron` module.
```javascript
const app = remote.app;
```
## Methods
The `remote` module has the following methods:
@ -151,3 +157,5 @@ process.
Returns the `process` object in the main process. This is the same as
`remote.getGlobal('process')` but is cached.
[rmi]: http://en.wikipedia.org/wiki/Java_remote_method_invocation

29
docs/api/screen.md
View file

@ -6,21 +6,21 @@ position, etc. You should not use this module until the `ready` event of the
`screen` is an [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).
**Note:** In the renderer / DevTools, `window.screen` is a reserved
DOM property, so writing `var screen = require('screen')` will not work. In our
examples below, we use `atomScreen` as the variable name instead.
**Note:** In the renderer / DevTools, `window.screen` is a reserved DOM
property, so writing `var screen = require('electron').screen` will not work.
In our examples below, we use `electronScreen` as the variable name instead.
An example of creating a window that fills the whole screen:
```javascript
var app = require('app');
var BrowserWindow = require('browser-window');
const electron = require('electron');
const app = electron.app;
const BrowserWindow = electron.BrowserWindow;
var mainWindow;
app.on('ready', function() {
var atomScreen = require('screen');
var size = atomScreen.getPrimaryDisplay().workAreaSize;
var electronScreen = electron.screen;
var size = electronScreen.getPrimaryDisplay().workAreaSize;
mainWindow = new BrowserWindow({ width: size.width, height: size.height });
});
```
@ -28,17 +28,18 @@ app.on('ready', function() {
Another example of creating a window in the external display:
```javascript
var app = require('app');
var BrowserWindow = require('browser-window');
const electron = require('electron');
const app = electron.app;
const BrowserWindow = electron.BrowserWindow;
var mainWindow;
app.on('ready', function() {
var atomScreen = require('screen');
var displays = atomScreen.getAllDisplays();
var electronScreen = electron.screen;
var displays = electronScreen.getAllDisplays();
var externalDisplay = null;
for (var i in displays) {
if (displays[i].bounds.x > 0 || displays[i].bounds.y > 0) {
if (displays[i].bounds.x != 0 || displays[i].bounds.y != 0) {
externalDisplay = displays[i];
break;
}
@ -47,7 +48,7 @@ app.on('ready', function() {
if (externalDisplay) {
mainWindow = new BrowserWindow({
x: externalDisplay.bounds.x + 50,
y: externalDisplay.bounds.y + 50,
y: externalDisplay.bounds.y + 50
});
}
});

143
docs/api/session.md
View file

@ -1,27 +1,64 @@
# session
The `session` object is a property of [`webContents`](web-contents.md) which is
a property of [`BrowserWindow`](browser-window.md). You can access it through an
instance of `BrowserWindow`. For example:
The `session` module can be used to create new `Session` objects.
You can also access the `session` of existing pages by using the `session`
property of [`webContents`](web-contents.md) which is a property of
[`BrowserWindow`](browser-window.md).
```javascript
var BrowserWindow = require('browser-window');
const BrowserWindow = require('electron').BrowserWindow;
var win = new BrowserWindow({ width: 800, height: 600 });
win.loadUrl("http://github.com");
win.loadURL("http://github.com");
var session = win.webContents.session
var ses = win.webContents.session
```
## Events
## Methods
### Event: 'will-download'
The `session` module has the following methods:
### session.fromPartition(partition)
* `partition` String
Returns a new `Session` instance from `partition` string.
If `partition` starts with `persist:`, the page will use a persistent session
available to all pages in the app with the same `partition`. if there is no
`persist:` prefix, the page will use an in-memory session. If the `partition` is
empty then default session of the app will be returned.
## Properties
The `session` module has the following properties:
### session.defaultSession
Returns the default session object of the app.
## Class: Session
You can create a `Session` object in the `session` module:
```javascript
const session = require('electron').session;
var ses = session.fromPartition('persist:name');
```
### Instance Events
The following events are available on instances of `Session`:
#### Event: 'will-download'
* `event` Event
* `item` [DownloadItem](download-item.md)
* `webContents` [WebContents](web-contents.md)
Fired when Electron is about to download `item` in `webContents`.
Emitted when Electron is about to download `item` in `webContents`.
Calling `event.preventDefault()` will cancel the download.
@ -34,20 +71,20 @@ session.on('will-download', function(event, item, webContents) {
});
```
## Methods
### Instance Methods
The `session` object has the following methods:
The following methods are available on instances of `Session`:
### `session.cookies`
#### `ses.cookies`
The `cookies` gives you ability to query and modify cookies. For example:
```javascript
var BrowserWindow = require('browser-window');
const BrowserWindow = require('electron').BrowserWindow;
var win = new BrowserWindow({ width: 800, height: 600 });
win.loadUrl('https://github.com');
win.loadURL('https://github.com');
win.webContents.on('did-finish-load', function() {
// Query all cookies.
@ -74,7 +111,7 @@ win.webContents.on('did-finish-load', function() {
});
```
### `session.cookies.get(details, callback)`
#### `ses.cookies.get(details, callback)`
`details` Object, properties:
@ -102,7 +139,7 @@ win.webContents.on('did-finish-load', function() {
the number of seconds since the UNIX epoch. Not provided for session
cookies.
### `session.cookies.set(details, callback)`
#### `ses.cookies.set(details, callback)`
`details` Object, properties:
@ -121,23 +158,23 @@ win.webContents.on('did-finish-load', function() {
* `callback` Function - function(error)
* `error` Error
### `session.cookies.remove(details, callback)`
#### `ses.cookies.remove(details, callback)`
* `details` Object, proprties:
* `details` Object
* `url` String - The URL associated with the cookie
* `name` String - The name of cookie to remove
* `callback` Function - function(error)
* `error` Error
### `session.clearCache(callback)`
#### `ses.clearCache(callback)`
* `callback` Function - Called when operation is done
Clears the session’s HTTP cache.
### `session.clearStorageData([options, ]callback)`
#### `ses.clearStorageData([options, ]callback)`
* `options` Object (optional), proprties:
* `options` Object (optional)
* `origin` String - Should follow `window.location.origin`’s representation
`scheme://host:port`.
* `storages` Array - The types of storages to clear, can contain:
@ -149,12 +186,14 @@ Clears the session’s HTTP cache.
Clears the data of web storages.
### `session.setProxy(config, callback)`
#### `ses.setProxy(config, callback)`
* `config` String
* `callback` Function - Called when operation is done.
Parses the `config` indicating which proxies to use for the session.
If `config` is a PAC url, it is used directly otherwise
`config` is parsed based on the following rules indicating which
proxies to use for the session.
```
config = scheme-proxies[";"<scheme-proxies>]
@ -185,9 +224,65 @@ proxy-uri = [<proxy-scheme>"://"]<proxy-host>[":"<proxy-port>]
URLs.
```
### `session.setDownloadPath(path)`
### `ses.resolveProxy(url, callback)`
* `url` URL
* `callback` Function
Resolves the proxy information for `url`. The `callback` will be called with
`callback(proxy)` when the request is performed.
#### `ses.setDownloadPath(path)`
* `path` String - The download location
Sets download saving directory. By default, the download directory will be the
`Downloads` under the respective app folder.
#### `ses.enableNetworkEmulation(options)`
* `options` Object
* `offline` Boolean - Whether to emulate network outage.
* `latency` Double - RTT in ms
* `downloadThroughput` Double - Download rate in Bps
* `uploadThroughput` Double - Upload rate in Bps
Emulates network with the given configuration for the `session`.
```javascript
// To emulate a GPRS connection with 50kbps throughput and 500 ms latency.
window.webContents.session.enableNetworkEmulation({
latency: 500,
downloadThroughput: 6400,
uploadThroughput: 6400
});
// To emulate a network outage.
window.webContents.session.enableNetworkEmulation({offline: true});
```
#### `ses.disableNetworkEmulation()`
Disables any network emulation already active for the `session`. Resets to
the original network configuration.
#### `ses.setCertificateVerifyProc(proc)`
* `proc` Function
Sets the certificate verify proc for `session`, the `proc` will be called with
`proc(hostname, certificate, callback)` whenever a server certificate
verification is requested. Calling `callback(true)` accepts the certificate,
calling `callback(false)` rejects it.
Calling `setCertificateVerifyProc(null)` will revert back to default certificate
verify proc.
```javascript
myWindow.webContents.session.setCertificateVerifyProc(function(hostname, cert, callback) {
if (hostname == 'github.com')
callback(true);
else
callback(false);
});
```

2
docs/api/shell.md
View file

@ -5,7 +5,7 @@ The `shell` module provides functions related to desktop integration.
An example of opening a URL in the user's default browser:
```javascript
var shell = require('shell');
const shell = require('electron').shell;
shell.openExternal('https://github.com');
```

70
docs/api/synopsis.md
View file

@ -9,40 +9,76 @@ desktop applications. Some modules are only available in the main process, some
are only available in the renderer process (web page), and some can be used in
both processes.
The basic rule is: if a module is
[GUI](https://en.wikipedia.org/wiki/Graphical_user_interface) or low-level
system related, then it should be only available in the main process. You need
to be familiar with the concept of
[main process vs. renderer process](../tutorial/quick-start.md#the-main-process)
scripts to be able to use those modules.
The basic rule is: if a module is [GUI][gui] or low-level system related, then
it should be only available in the main process. You need to be familiar with
the concept of [main process vs. renderer process][mai-process] scripts to be
able to use those modules.
The main process script is just like a normal Node.js script:
```javascript
var app = require('app');
var BrowserWindow = require('browser-window');
const electron = require('electron');
const app = electron.app;
const BrowserWindow = electron.BrowserWindow;
var window = null;
app.on('ready', function() {
window = new BrowserWindow({width: 800, height: 600});
window.loadUrl('https://github.com');
window.loadURL('https://github.com');
});
```
The renderer process is no different than a normal web page, except for the extra
ability to use node modules:
The renderer process is no different than a normal web page, except for the
extra ability to use node modules:
```html
<!DOCTYPE html>
<html>
<body>
<script>
var remote = require('remote');
console.log(remote.require('app').getVersion());
</script>
</body>
<body>
<script>
const remote = require('electron').remote;
console.log(remote.app.getVersion());
</script>
</body>
</html>
```
To run your app, read [Run your app](../tutorial/quick-start.md#run-your-app).
## Destructuring assignment
If you are using CoffeeScript or Babel, you can also use
[destructuring assignment][desctructuring-assignment] to make it easier to use
built-in modules:
```javascript
const {app, BrowserWindow} = require('electron')
```
However if you are using plain JavaScript, you have to wait until Chrome fully
supports ES6.
## Disable old styles of using built-in modules
Before v0.35.0, all built-in modules have to be used in the form of
`require('module-name')`, though it has [many disadvantages][issue-387], we are
still supporting it for compatibility with old apps.
To disable the old styles completely, you can set the
`ELECTRON_HIDE_INTERNAL_MODULES` environment variable:
```javascript
process.env.ELECTRON_HIDE_INTERNAL_MODULES = 'true'
```
Or call the `hideInternalModules` API:
```javascript
require('electron').hideInternalModules()
```
[gui]: https://en.wikipedia.org/wiki/Graphical_user_interface
[main-process]: ../tutorial/quick-start.md#the-main-process
[desctructuring-assignment]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment
[issue-387]: https://github.com/atom/electron/issues/387

46
docs/api/tray.md
View file

@ -4,9 +4,10 @@ A `Tray` represents an icon in an operating system's notification area, it is
usually attached with a context menu.
```javascript
var app = require('app');
var Menu = require('menu');
var Tray = require('tray');
const electron = require('electron');
const app = electron.app;
const Menu = electron.Menu;
const Tray = electron.Tray;
var appIcon = null;
app.on('ready', function(){
@ -30,10 +31,10 @@ __Platform limitations:__
* On Linux distributions that only have app indicator support, you have to
install `libappindicator1` to make the tray icon work.
* App indicator will only be shown when it has a context menu.
* When app indicator is used on Linux, the `clicked` event is ignored.
* When app indicator is used on Linux, the `click` event is ignored.
If you want to keep exact same behaviors on all platforms, you should not
rely on the `clicked` event and always attach a context menu to the tray icon.
rely on the `click` event and always attach a context menu to the tray icon.
## Class: Tray
@ -52,7 +53,7 @@ The `Tray` module emits the following events:
**Note:** Some events are only available on specific operating systems and are
labeled as such.
### Event: 'clicked'
### Event: 'click'
* `event` Event
* `altKey` Boolean
@ -69,7 +70,7 @@ Emitted when the tray icon is clicked.
__Note:__ The `bounds` payload is only implemented on OS X and Windows.
### Event: 'right-clicked' _OS X_ _Windows_
### Event: 'right-click' _OS X_ _Windows_
* `event` Event
* `altKey` Boolean
@ -84,7 +85,7 @@ __Note:__ The `bounds` payload is only implemented on OS X and Windows.
Emitted when the tray icon is right clicked.
### Event: 'double-clicked' _OS X_ _Windows_
### Event: 'double-click' _OS X_ _Windows_
* `event` Event
* `altKey` Boolean
@ -103,7 +104,7 @@ Emitted when the tray icon is double clicked.
Emitted when the tray balloon shows.
### Event: 'balloon-clicked' _Windows_
### Event: 'balloon-click' _Windows_
Emitted when the tray balloon is clicked.
@ -112,6 +113,10 @@ Emitted when the tray balloon is clicked.
Emitted when the tray balloon is closed because of timeout or user manually
closes it.
### Event: 'drop' _OS X_
Emitted when any dragged items are dropped on the tray icon.
### Event: 'drop-files' _OS X_
* `event`
@ -119,6 +124,18 @@ closes it.
Emitted when dragged files are dropped in the tray icon.
### Event: 'drag-enter' _OS X_
Emitted when a drag operation enters the tray icon.
### Event: 'drag-leave' _OS X_
Emitted when a drag operation exits the tray icon.
### Event: 'drag-end' _OS X_
Emitted when a drag operation ends on the tray or ends at another location.
## Methods
The `Tray` module has the following methods:
@ -158,7 +175,8 @@ Sets the title displayed aside of the tray icon in the status bar.
* `highlight` Boolean
Sets whether the tray icon is highlighted when it is clicked.
Sets whether the tray icon's background becomes highlighted (in blue)
when the tray icon is clicked. Defaults to true.
### `Tray.displayBalloon(options)` _Windows_
@ -169,12 +187,16 @@ Sets whether the tray icon is highlighted when it is clicked.
Displays a tray balloon.
### `Tray.popUpContextMenu([position])` _OS X_ _Windows_
### `Tray.popUpContextMenu([menu, position])` _OS X_ _Windows_
* `position` Object (optional)- The pop up position.
* `menu` Menu (optional)
* `position` Object (optional) - The pop up position.
* `x` Integer
* `y` Integer
Popups the context menu of tray icon. When `menu` is passed, the `menu` will
showed instead of the tray's context menu.
The `position` is only available on Windows, and it is (0, 0) by default.
### `Tray.setContextMenu(menu)`

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

@ -8,10 +8,10 @@ the [`BrowserWindow`](browser-window.md) object. An example of accessing the
`webContents` object:
```javascript
var BrowserWindow = require('browser-window');
const BrowserWindow = require('electron').BrowserWindow;
var win = new BrowserWindow({width: 800, height: 1500});
win.loadUrl("http://github.com");
win.loadURL("http://github.com");
var webContents = win.webContents;
```
@ -32,10 +32,11 @@ Returns:
* `event` Event
* `errorCode` Integer
* `errorDescription` String
* `validatedUrl` String
* `validatedURL` String
This event is like `did-finish-load` but emitted when the load failed or was
cancelled, e.g. `window.stop()` is invoked.
The full list of error codes and their meaning is available [here](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h).
### Event: 'did-frame-finish-load'
@ -60,8 +61,8 @@ Returns:
* `event` Event
* `status` Boolean
* `newUrl` String
* `originalUrl` String
* `newURL` String
* `originalURL` String
* `httpResponseCode` Integer
* `requestMethod` String
* `referrer` String
@ -75,8 +76,8 @@ Emitted when details regarding a requested resource are available.
Returns:
* `event` Event
* `oldUrl` String
* `newUrl` String
* `oldURL` String
* `newURL` String
* `isMainFrame` Boolean
* `httpResponseCode` Integer
* `requestMethod` String
@ -98,7 +99,7 @@ Emitted when the document in the given frame is loaded.
Returns:
* `event` Event
* `favicons` Array - Array of Urls
* `favicons` Array - Array of URLs
Emitted when page receives favicon urls.
@ -132,7 +133,7 @@ Emitted when a user or the page wants to start navigation. It can happen when th
`window.location` object is changed or a user clicks a link in the page.
This event will not emit when the navigation is started programmatically with
APIs like `webContents.loadUrl` and `webContents.back`.
APIs like `webContents.loadURL` and `webContents.back`.
Calling `event.preventDefault()` will prevent the navigation.
@ -154,39 +155,111 @@ Emitted when a plugin process has crashed.
Emitted when `webContents` is destroyed.
### 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'
Returns:
* `event` Event
* `url` URL
* `error` String - The error code
* `certificate` Object
* `data` Buffer - PEM encoded data
* `issuerName` String
* `callback` Function
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'
Returns:
* `event` Event
* `url` URL
* `certificateList` [Objects]
* `data` Buffer - PEM encoded data
* `issuerName` String - Issuer's Common Name
* `callback` Function
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'
Returns:
* `event` Event
* `request` Object
* `method` String
* `url` URL
* `referrer` URL
* `authInfo` Object
* `isProxy` Boolean
* `scheme` String
* `host` String
* `port` Integer
* `realm` String
* `callback` Function
Emitted when `webContents` wants to do basic auth.
The usage is the same with [the `login` event of `app`](app.md#event-login).
## Instance Methods
The `webContents` object has the following instance methods:
### `webContents.session`
Returns the `session` object used by this webContents.
See [session documentation](session.md) for this object's methods.
### `webContents.loadUrl(url[, options])`
### `webContents.loadURL(url[, options])`
* `url` URL
* `options` Object (optional), properties:
* `httpReferrer` String - A HTTP Referrer url.
* `userAgent` String - A user agent originating the request.
* `extraHeaders` String - Extra headers separated by "\n"
Loads the `url` in the window, the `url` must contain the protocol prefix,
e.g. the `http://` or `file://`.
### `webContents.getUrl()`
e.g. the `http://` or `file://`. If the load should bypass http cache then
use the `pragma` header to achieve it.
```javascript
var BrowserWindow = require('browser-window');
var win = new BrowserWindow({width: 800, height: 600});
win.loadUrl("http://github.com");
var currentUrl = win.webContents.getUrl();
const options = {"extraHeaders" : "pragma: no-cache\n"}
webContents.loadURL(url, options)
```
### `webContents.downloadURL(url)`
* `url` URL
Initiates a download of the resource at `url` without navigating. The
`will-download` event of `session` will be triggered.
### `webContents.getURL()`
Returns URL of the current web page.
```javascript
var win = new BrowserWindow({width: 800, height: 600});
win.loadURL("http://github.com");
var currentURL = win.webContents.getURL();
```
### `webContents.getTitle()`
Returns the title of the current web page.
@ -283,7 +356,7 @@ this limitation.
### `webContents.setAudioMuted(muted)`
+ `muted` Boolean
* `muted` Boolean
Mute the audio on the current web page.
@ -410,11 +483,11 @@ By default, an empty `options` will be regarded as:
```
```javascript
var BrowserWindow = require('browser-window');
var fs = require('fs');
const BrowserWindow = require('electron').BrowserWindow;
const fs = require('fs');
var win = new BrowserWindow({width: 800, height: 600});
win.loadUrl("http://github.com");
win.loadURL("http://github.com");
win.webContents.on("did-finish-load", function() {
// Use default printing options
@ -433,7 +506,14 @@ win.webContents.on("did-finish-load", function() {
* `path` String
Adds the specified path to DevTools workspace.
Adds the specified path to DevTools workspace. Must be used after DevTools
creation:
```javascript
mainWindow.webContents.on('devtools-opened', function() {
mainWindow.webContents.addWorkSpace(__dirname);
});
```
### `webContents.removeWorkSpace(path)`
@ -441,13 +521,48 @@ Adds the specified path to DevTools workspace.
Removes the specified path from DevTools workspace.
### `webContents.send(channel[, args...])`
### `webContents.openDevTools([options])`
* `options` Object (optional). Properties:
* `detach` Boolean - opens DevTools in a new window
Opens the developer tools.
### `webContents.closeDevTools()`
Closes the developer tools.
### `webContents.isDevToolsOpened()`
Returns whether the developer tools are opened.
### `webContents.toggleDevTools()`
Toggles the developer tools.
### `webContents.isDevToolsFocused()`
Returns whether the developer tools is focused.
### `webContents.inspectElement(x, y)`
* `x` Integer
* `y` Integer
Starts inspecting element at position (`x`, `y`).
### `webContents.inspectServiceWorker()`
Opens the developer tools for the service worker context.
### `webContents.send(channel[, arg1][, arg2][, ...])`
* `channel` String
* `args...` (optional)
* `arg` (optional)
Send `args...` to the web page via `channel` in an asynchronous message, the web
page can handle it by listening to the `channel` event of the `ipc` module.
Send an asynchronous message to renderer process via `channel`, you can also
send arbitrary arguments. The renderer process can handle the message by
listening to the `channel` event with the `ipcRenderer` module.
An example of sending messages from the main process to the renderer process:
@ -456,7 +571,7 @@ An example of sending messages from the main process to the renderer process:
var window = null;
app.on('ready', function() {
window = new BrowserWindow({width: 800, height: 600});
window.loadUrl('file://' + __dirname + '/index.html');
window.loadURL('file://' + __dirname + '/index.html');
window.webContents.on('did-finish-load', function() {
window.webContents.send('ping', 'whoooooooh!');
});
@ -468,7 +583,7 @@ app.on('ready', function() {
<html>
<body>
<script>
require('ipc').on('ping', function(message) {
require('electron').ipcRenderer.on('ping', function(event, message) {
console.log(message); // Prints "whoooooooh!"
});
</script>
@ -476,13 +591,6 @@ app.on('ready', function() {
</html>
```
**Note:**
1. The IPC message handler in web pages does not have an `event` parameter,
which is different from the handlers in the main process.
2. There is no way to send synchronous messages from the main process to a
renderer process, because it would be very easy to cause dead locks.
### `webContents.enableDeviceEmulation(parameters)`
`parameters` Object, properties:
@ -523,7 +631,7 @@ Disable device emulation enabled by `webContents.enableDeviceEmulation`.
* `event` Object
* `type` String (**required**) - The type of the event, can be `mouseDown`,
`mouseUp`, `mouseEnter`, `mouseLeave`, `contextMenu`, `mouseWheel`,
`keyDown`, `keyUp`, `char`.
`mouseMove`, `keyDown`, `keyUp`, `char`.
* `modifiers` Array - An array of modifiers of the event, can
include `shift`, `control`, `alt`, `meta`, `isKeypad`, `isAutoRepeat`,
`leftButtonDown`, `middleButtonDown`, `rightButtonDown`, `capsLock`,
@ -533,14 +641,17 @@ Sends an input `event` to the page.
For keyboard events, the `event` object also have following properties:
* `keyCode` String (**required**) - A single character that will be sent as
keyboard event. Can be any ASCII character on the keyboard, like `a`, `1`
and `=`.
* `keyCode` Char or String (**required**) - The character that will be sent
as the keyboard event. Can be a single UTF-8 character, or the name of the
key that generates the event. Accepted key names are `enter`, `backspace`,
`delete`, `tab`, `escape`, `control`, `alt`, `shift`, `end`, `home`, `insert`,
`left`, `up`, `right`, `down`, `pageUp`, `pageDown`, `printScreen`
For mouse events, the `event` object also have following properties:
* `x` Integer (**required**)
* `y` Integer (**required**)
* `button` String - The button pressed, can be `left`, `middle`, `right`
* `globalX` Integer
* `globalY` Integer
* `movementX` Integer
@ -565,9 +676,50 @@ For the `mouseWheel` event, the `event` object also have following properties:
Begin subscribing for presentation events and captured frames, the `callback`
will be called with `callback(frameBuffer)` when there is a presentation event.
The `frameBuffer` is a `Buffer` that contains raw pixel data, in the format of
32bit ARGB.
The `frameBuffer` is a `Buffer` that contains raw pixel data. On most machines,
the pixel data is effectively stored in 32bit BGRA format, but the actual
representation depends on the endianness of the processor (most modern
processors are little-endian, on machines with big-endian processors the data
is in 32bit ARGB format).
### `webContents.endFrameSubscription()`
End subscribing for frame presentation events.
### `webContents.savePage(fullPath, saveType, callback)`
* `fullPath` String - The full file path.
* `saveType` String - Specify the save type.
* `HTMLOnly` - Save only the HTML of the page.
* `HTMLComplete` - Save complete-html page.
* `MHTML` - Save complete-html page as MHTML.
* `callback` Function - `function(error) {}`.
* `error` Error
Returns true if the process of saving page has been initiated successfully.
```javascript
win.loadURL('https://github.com');
win.webContents.on('did-finish-load', function() {
win.webContents.savePage('/tmp/test.html', 'HTMLComplete', function(error) {
if (!error)
console.log("Save page successfully");
});
});
```
## Instance Properties
`WebContents` objects also have the following properties:
### `webContents.session`
Returns the [session](session.md) object used by this webContents.
### `webContents.devToolsWebContents`
Get the `WebContents` of DevTools for this `WebContents`.
**Note:** Users should never store this object because it may become `null`
when the DevTools has been closed.

10
docs/api/web-frame.md
View file

@ -6,7 +6,7 @@ web page.
An example of zooming current page to 200%.
```javascript
var webFrame = require('web-frame');
var webFrame = require('electron').webFrame;
webFrame.setZoomFactor(2);
```
@ -59,14 +59,14 @@ whether the word passed is correctly spelled.
An example of using [node-spellchecker][spellchecker] as provider:
```javascript
require('web-frame').setSpellCheckProvider("en-US", true, {
webFrame.setSpellCheckProvider("en-US", true, {
spellCheck: function(text) {
return !(require('spellchecker').isMisspelled(text));
}
});
```
### `webFrame.registerUrlSchemeAsSecure(scheme)`
### `webFrame.registerURLSchemeAsSecure(scheme)`
* `scheme` String
@ -76,14 +76,14 @@ Secure schemes do not trigger mixed content warnings. For example, `https` and
`data` are secure schemes because they cannot be corrupted by active network
attackers.
### `webFrame.registerUrlSchemeAsBypassingCsp(scheme)`
### `webFrame.registerURLSchemeAsBypassingCSP(scheme)`
* `scheme` String
Resources will be loaded from this `scheme` regardless of the current page's
Content Security Policy.
### `webFrame.registerUrlSchemeAsPrivileged(scheme)`
### `webFrame.registerURLSchemeAsPrivileged(scheme)`
* `scheme` String

42
docs/api/web-view-tag.md
View file

@ -164,13 +164,14 @@ The `webview` tag has the following methods:
**Note:** The webview element must be loaded before using the methods.
**Example**
```javascript
webview.addEventListener("dom-ready", function() {
webview.openDevTools();
});
```
### `<webview>.getUrl()`
### `<webview>.getURL()`
Returns URL of guest page.
@ -262,7 +263,7 @@ Injects CSS into the guest page.
* `code` String
* `userGesture` Boolean - Default `false`.
Evaluates `code` in page. If `userGesture` is set, it will the create user
Evaluates `code` in page. If `userGesture` is set, it will create the user
gesture context in the page. HTML APIs like `requestFullScreen`, which require
user action, can take advantage of this option for automation.
@ -355,15 +356,16 @@ Prints `webview`'s web page. Same with `webContents.print([options])`.
Prints webview's web page as PDF, Same with `webContents.printToPDF(options, callback)`
### `<webview>.send(channel[, args...])`
### `<webview>.send(channel[, arg1][, arg2][, ...])`
* `channel` String
* `arg` (optional)
Send `args..` to guest page via `channel` in asynchronous message, the guest
page can handle it by listening to the `channel` event of `ipc` module.
Send an asynchronous message to renderer process via `channel`, you can also
send arbitrary arguments. The renderer process can handle the message by
listening to the `channel` event with the `ipcRenderer` module.
See [WebContents.send](web-contents.md#webcontentssendchannel-args) for
See [webContents.send](web-contents.md#webcontentssendchannel-args) for
examples.
### `<webview>.sendInputEvent(event)`
@ -372,7 +374,7 @@ examples.
Sends an input `event` to the page.
See [WebContents.sendInputEvent](web-contents.md##webcontentssendinputeventevent)
See [webContents.sendInputEvent](web-contents.md##webcontentssendinputeventevent)
for detailed description of `event` object.
## DOM events
@ -401,7 +403,7 @@ Returns:
* `errorCode` Integer
* `errorDescription` String
* `validatedUrl` String
* `validatedURL` String
This event is like `did-finish-load`, but fired when the load failed or was
cancelled, e.g. `window.stop()` is invoked.
@ -427,8 +429,8 @@ Corresponds to the points in time when the spinner of the tab stops spinning.
Returns:
* `status` Boolean
* `newUrl` String
* `originalUrl` String
* `newURL` String
* `originalURL` String
* `httpResponseCode` Integer
* `requestMethod` String
* `referrer` String
@ -441,8 +443,8 @@ Fired when details regarding a requested resource is available.
Returns:
* `oldUrl` String
* `newUrl` String
* `oldURL` String
* `newURL` String
* `isMainFrame` Boolean
Fired when a redirect was received while requesting a resource.
@ -451,21 +453,21 @@ Fired when a redirect was received while requesting a resource.
Fired when document in the given frame is loaded.
### Event: 'page-title-set'
### Event: 'page-title-updated'
Returns:
* `title` String
* `explicitSet` Boolean
Fired when page title is set during navigation. `explicitSet` is false when title is synthesised from file
url.
Fired when page title is set during navigation. `explicitSet` is false when
title is synthesised from file url.
### Event: 'page-favicon-updated'
Returns:
* `favicons` Array - Array of Urls.
* `favicons` Array - Array of URLs.
Fired when page receives favicon urls.
@ -514,7 +516,7 @@ The following example code opens the new url in system's default browser.
```javascript
webview.addEventListener('new-window', function(e) {
require('shell').openExternal(e.url);
require('electron').shell.openExternal(e.url);
});
```
@ -554,9 +556,9 @@ webview.send('ping');
```javascript
// In guest page.
var ipc = require('ipc');
ipc.on('ping', function() {
ipc.sendToHost('pong');
var ipcRenderer = require('electron').ipcRenderer;
ipcRenderer.on('ping', function() {
ipcRenderer.sendToHost('pong');
});
```