Merge branch 'master' into desktop-capture-api

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

View file

@ -1,6 +1,17 @@
Please make sure that you use the documents that match your Electron version.
The version number should be a part of the page URL. If it's not, you are
probably using the documentation of a development branch which may contain API
changes that are not compatible with your Electron version. If that's the case,
you can switch to a different version of the documentation at the
[available versions](http://electron.atom.io/docs/) list on atom.io, or if
you're using the GitHub interface, open the "Switch branches/tags" dropdown and
select the tag that matches your version.
## Guides
* [Supported Platforms](tutorial/supported-platforms.md)
* [Application Distribution](tutorial/application-distribution.md)
* [Mac App Store Submission Guide](tutorial/mac-app-store-submission-guide.md)
* [Application Packaging](tutorial/application-packaging.md)
* [Using Native Node Modules](tutorial/using-native-node-modules.md)
* [Debugging Main Process](tutorial/debugging-main-process.md)
@ -19,6 +30,7 @@
* [Synopsis](api/synopsis.md)
* [Process Object](api/process.md)
* [Supported Chrome Command Line Switches](api/chrome-command-line-switches.md)
* [Environment Variables](api/environment-variables.md)
### Custom DOM Elements:
@ -29,33 +41,33 @@
### Modules for the Main Process:
* [app](api/app.md)
* [auto-updater](api/auto-updater.md)
* [browser-window](api/browser-window.md)
* [content-tracing](api/content-tracing.md)
* [autoUpdater](api/auto-updater.md)
* [BrowserWindow](api/browser-window.md)
* [contentTracing](api/content-tracing.md)
* [dialog](api/dialog.md)
* [global-shortcut](api/global-shortcut.md)
* [ipc (main process)](api/ipc-main-process.md)
* [menu](api/menu.md)
* [menu-item](api/menu-item.md)
* [power-monitor](api/power-monitor.md)
* [power-save-blocker](api/power-save-blocker.md)
* [globalShortcut](api/global-shortcut.md)
* [ipcMain](api/ipc-main.md)
* [Menu](api/menu.md)
* [MenuItem](api/menu-item.md)
* [powerMonitor](api/power-monitor.md)
* [powerSaveBlocker](api/power-save-blocker.md)
* [protocol](api/protocol.md)
* [session](api/session.md)
* [web-contents](api/web-contents.md)
* [tray](api/tray.md)
* [webContents](api/web-contents.md)
* [Tray](api/tray.md)
### Modules for the Renderer Process (Web Page):
* [desktop-capturer](api/desktop-capturer.md)
* [ipc (renderer)](api/ipc-renderer.md)
* [desktopCapturer](api/desktop-capturer.md)
* [ipcRenderer](api/ipc-renderer.md)
* [remote](api/remote.md)
* [web-frame](api/web-frame.md)
* [webFrame](api/web-frame.md)
### Modules for Both Processes:
* [clipboard](api/clipboard.md)
* [crash-reporter](api/crash-reporter.md)
* [native-image](api/native-image.md)
* [crashReporter](api/crash-reporter.md)
* [nativeImage](api/native-image.md)
* [screen](api/screen.md)
* [shell](api/shell.md)
@ -65,7 +77,7 @@
* [Source Code Directory Structure](development/source-code-directory-structure.md)
* [Technical Differences to NW.js (formerly node-webkit)](development/atom-shell-vs-node-webkit.md)
* [Build System Overview](development/build-system-overview.md)
* [Build Instructions (Mac)](development/build-instructions-osx.md)
* [Build Instructions (OS X)](development/build-instructions-osx.md)
* [Build Instructions (Windows)](development/build-instructions-windows.md)
* [Build Instructions (Linux)](development/build-instructions-linux.md)
* [Setting Up Symbol Server in debugger](development/setting-up-symbol-server.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

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, its 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

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 windows 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()`

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.

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.

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() {

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.

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.

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

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')`.

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

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.

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

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.

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.

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)

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)`

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');
});
});

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));

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

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

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

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
});
}
});

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 sessions 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 sessions 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);
});
```

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');
```

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

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)`

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.

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

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');
});
```

View file

@ -35,7 +35,7 @@ __3. Node Integration__
In NW.js, the Node integration in web pages requires patching Chromium to
work, while in Electron we chose a different way to integrate the libuv loop
with each platform's message loop to avoid hacking Chromium. See the
[`node_bindings`](../../atom/common/) code for how that was done.
[`node_bindings`][node-bindings] code for how that was done.
__4. Multi-context__
@ -46,3 +46,5 @@ of how NW.js was implemented.
By using the [multi-context](http://strongloop.com/strongblog/whats-new-node-js-v0-12-multiple-context-execution/)
feature of Node, Electron doesn't introduce a new JavaScript context in web
pages.
[node-bindings]: https://github.com/atom/electron/tree/master/atom/common

View file

@ -65,7 +65,11 @@ notated by brackets surrounding the optional argument as well as the comma
required if this optional argument follows another argument.
Below the method is more detailed information on each of the arguments. The type
of argument is notated by either the common types: [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String), [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object), [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
of argument is notated by either the common types:
[`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String),
[`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number),
[`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object),
[`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
or a custom type like Electron's [`webContent`](api/web-content.md).
### Events

View file

@ -35,7 +35,7 @@ exposing your app's source code to users.
To use an `asar` archive to replace the `app` folder, you need to rename the
archive to `app.asar`, and put it under Electron's resources directory like
below, and Electron will then try read the archive and start from it.
below, and Electron will then try to read the archive and start from it.
On OS X:

View file

@ -51,14 +51,14 @@ $ asar list /path/to/example.asar
Read a file in the `asar` archive:
```javascript
var fs = require('fs');
const fs = require('fs');
fs.readFileSync('/path/to/example.asar/file.txt');
```
List all files under the root of the archive:
```javascript
var fs = require('fs');
const fs = require('fs');
fs.readdirSync('/path/to/example.asar');
```
@ -71,9 +71,9 @@ require('/path/to/example.asar/dir/module.js');
You can also display a web page in an `asar` archive with `BrowserWindow`:
```javascript
var BrowserWindow = require('browser-window');
const BrowserWindow = require('electron').BrowserWindow;
var win = new BrowserWindow({width: 800, height: 600});
win.loadUrl('file:///path/to/example.asar/static/index.html');
win.loadURL('file:///path/to/example.asar/static/index.html');
```
### Web API
@ -103,6 +103,14 @@ var originalFs = require('original-fs');
originalFs.readFileSync('/path/to/example.asar');
```
You can also set `process.noAsar` to `true` to disable the support for `asar` in
the `fs` module:
```javascript
process.noAsar = true;
fs.readFileSync('/path/to/example.asar');
```
## Limitations on Node API
Even though we tried hard to make `asar` archives in the Node API work like
@ -132,6 +140,7 @@ work. This adds a little overhead for those APIs.
APIs that requires extra unpacking are:
* `child_process.execFile`
* `child_process.execFileSync`
* `fs.open`
* `fs.openSync`
* `process.dlopen` - Used by `require` on native modules
@ -143,6 +152,17 @@ archives is generated by guessing, because those files do not exist on the
filesystem. So you should not trust the `Stats` object except for getting file
size and checking file type.
### Executing Binaries Inside `asar` Archive
There are Node APIs that can execute binaries like `child_process.exec`,
`child_process.spawn` and `child_process.execFile`, but only `execFile` is
supported to execute binaries inside `asar` archive.
This is because `exec` and `spawn` accept `command` instead of `file` as input,
and `command`s are executed under shell. There is no reliable way to determine
whether a command uses a file in asar archive, and even if we do, we can not be
sure whether we can replace the path in command without side effects.
## Adding Unpacked Files in `asar` Archive
As stated above, some Node APIs will unpack the file to filesystem when

View file

@ -19,7 +19,7 @@ Like `--debug` but pauses the script on the first line.
## Use node-inspector for Debugging
__Note:__ Electron uses node v0.11.13, which currently doesn't work very well
__Note:__ Electron doesn't currently work very well
with node-inspector, and the main process will crash if you inspect the
`process` object under node-inspector's console.

View file

@ -8,6 +8,67 @@ applications can put a custom menu in the dock menu.
This guide explains how to integrate your application into those desktop
environments with Electron APIs.
## Notifications (Windows, Linux, OS X)
All three operating systems provide means for applications to send notifications
to the user. Electron conveniently allows developers to send notifications with
the [HTML5 Notification API](https://notifications.spec.whatwg.org/), using
the currently running operating system's native notification APIs to display it.
```javascript
var myNotification = new Notification('Title', {
body: 'Lorem Ipsum Dolor Sit Amet'
});
myNotification.onclick = function () {
console.log('Notification clicked')
}
```
While code and user experience across operating systems are similar, but there
are fine differences.
### Windows
* On Windows 10, notifications "just work".
* On Windows 8.1 and Windows 8, a shortcut to your app, with a [Application User
Model ID][app-user-model-id], must be installed to the Start screen. Note,
however, that it does not need to be pinned to the Start screen.
* On Windows 7 and below, notifications are not supported. You can however send
"balloon notifications" using the [Tray API](tray-balloon).
To use an image in your notification, pass a local image file (preferably `png`)
in the `icon` property of your notification's options. The notification will
still display if you submit and incorrect or `http/https`-based URL, but the
image will not be displayed.
```javascript
new Notification('Title', {
body: 'Notification with icon',
icon: 'file:///C:/Users/feriese/Desktop/icon.png'
});
```
Keep furthermore in mind that the maximum length for the body is 250 characters,
with the Windows team recommending that notifications should be kept to 200
characters.
### Linux
Notifications are sent using `libnotify`, it can show notifications on any
desktop environment that follows [Desktop Notifications
Specification][notification-spec], including Cinnamon, Enlightenment, Unity,
GNOME, KDE.
### OS X
Notifications are straight-forward on OS X, you should however be aware of
[Apple's Human Interface guidelines regarding
notifications](https://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/OSXHIGuidelines/NotificationCenter.html).
Note that notifications are limited to 256 bytes in size - and will be truncated
if you exceed that limit.
## Recent documents (Windows & OS X)
Windows and OS X provide easy access to a list of recent documents opened by
@ -25,7 +86,6 @@ To add a file to recent documents, you can use the
[app.addRecentDocument][addrecentdocument] API:
```javascript
var app = require('app');
app.addRecentDocument('/Users/USERNAME/Desktop/work.type');
```
@ -43,7 +103,8 @@ registered as a handler of the file type of the document, otherwise the file
won't appear in JumpList even after you have added it. You can find everything
on registering your application in [Application Registration][app-registration].
When a user clicks a file from the JumpList, a new instance of your application will be started with the path of the file added as a command line argument.
When a user clicks a file from the JumpList, a new instance of your application
will be started with the path of the file added as a command line argument.
### OS X Notes
@ -63,8 +124,10 @@ To set your custom dock menu, you can use the `app.dock.setMenu` API, which is
only available on OS X:
```javascript
var app = require('app');
var Menu = require('menu');
const electron = require('electron');
const app = electron.app;
const Menu = electron.Menu;
var dockMenu = Menu.buildFromTemplate([
{ label: 'New Window', click: function() { console.log('New Window'); } },
{ label: 'New Window with Settings', submenu: [
@ -110,7 +173,6 @@ To set user tasks for your application, you can use
[app.setUserTasks][setusertaskstasks] API:
```javascript
var app = require('app');
app.setUserTasks([
{
program: process.execPath,
@ -154,12 +216,13 @@ __Thumbnail toolbar of Windows Media Player:__
![player](https://i-msdn.sec.s-msft.com/dynimg/IC420540.png)
You can use [BrowserWindow.setThumbarButtons][setthumbarbuttons] to set thumbnail
toolbar in your application:
You can use [BrowserWindow.setThumbarButtons][setthumbarbuttons] to set
thumbnail toolbar in your application:
```javascript
const BrowserWindow = require('electron').BrowserWindow;
const path = require('path');
```
var BrowserWindow = require('browser-window');
var path = require('path');
var win = new BrowserWindow({
width: 800,
height: 600
@ -188,8 +251,8 @@ win.setThumbarButtons([]);
## Unity Launcher Shortcuts (Linux)
In Unity, you can add custom entries to its launcher via modifying the `.desktop`
file, see [Adding Shortcuts to a Launcher][unity-launcher].
In Unity, you can add custom entries to its launcher via modifying the
`.desktop` file, see [Adding Shortcuts to a Launcher][unity-launcher].
__Launcher shortcuts of Audacious:__
@ -223,7 +286,7 @@ window.setProgressBar(0.5);
## Represented File of Window (OS X)
On OS X a window can set its represented file, so the file's icon can show in
the title bar and when users Command-Click or Control-Click on the tile a path
the title bar and when users Command-Click or Control-Click on the title a path
popup will show.
You can also set the edited state of a window so that the file icon can indicate
@ -252,3 +315,6 @@ window.setDocumentEdited(true);
[app-registration]: http://msdn.microsoft.com/en-us/library/windows/desktop/ee872121(v=vs.85).aspx
[unity-launcher]: https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles#Adding_shortcuts_to_a_launcher
[setthumbarbuttons]: ../api/browser-window.md#browserwindowsetthumbarbuttonsbuttons
[tray-balloon]: ../api/tray.md#traydisplayballoonoptions-windows
[app-user-model-id]: https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v=vs.85).aspx
[notification-spec]: https://developer.gnome.org/notification-spec/

View file

@ -8,6 +8,8 @@ the `BrowserWindow.addDevToolsExtension` API to load them. The loaded extensions
will be remembered so you don't need to call the API every time when creating
a window.
** NOTE: React DevTools does not work, follow the issue here https://github.com/atom/electron/issues/915 **
For example, to use the [React DevTools Extension](https://github.com/facebook/react-devtools)
, first you need to download its source code:
@ -16,18 +18,21 @@ $ cd /some-directory
$ git clone --recursive https://github.com/facebook/react-devtools.git
```
Follow the instructions in [`react-devtools/shells/chrome/Readme.md`](https://github.com/facebook/react-devtools/blob/master/shells/chrome/Readme.md) to build the extension.
Then you can load the extension in Electron by opening DevTools in any window,
and running the following code in the DevTools console:
```javascript
require('remote').require('browser-window').addDevToolsExtension('/some-directory/react-devtools');
const BrowserWindow = require('electron').remote.BrowserWindow;
BrowserWindow.addDevToolsExtension('/some-directory/react-devtools/shells/chrome');
```
To unload the extension, you can call the `BrowserWindow.removeDevToolsExtension`
API with its name and it will not load the next time you open the DevTools:
```javascript
require('remote').require('browser-window').removeDevToolsExtension('React Developer Tools');
BrowserWindow.removeDevToolsExtension('React Developer Tools');
```
## Format of DevTools Extension

View file

@ -0,0 +1,120 @@
# Mac App Store Submission Guide
Since v0.34.0, Electron allows submitting packaged apps to the Mac App Store
(MAS). This guide provides information on: how to submit your app and the
limitations of the MAS build.
__Note:__ Submitting an app to Mac App Store requires enrolling [Apple Developer
Program][developer-program], which costs money.
## How to Submit Your App
The following steps introduce a simple way to submit your app to Mac App Store.
However, these steps do not ensure your app will be approved by Apple; you
still need to read Apple's [Submitting Your App][submitting-your-app] guide on
how to meet the Mac App Store requirements.
### Get Certificate
To submit your app to the Mac App Store, you first must get a certificate from
Apple. You can follow these [existing guides][nwjs-guide] on web.
### Sign Your App
After getting the certificate from Apple, you can package your app by following
[Application Distribution](application-distribution.md), and then proceed to
signing your app. This step is basically the same with other programs, but the
key is to sign every dependency of Electron one by one.
First, you need to prepare two entitlements files.
`child.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.app-sandbox</key>
<true/>
<key>com.apple.security.inherit</key>
<true/>
</dict>
</plist>
```
`parent.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.app-sandbox</key>
<true/>
</dict>
</plist>
```
And then sign your app with the following script:
```bash
#!/bin/bash
# Name of your app.
APP="YourApp"
# The path of you app to sign.
APP_PATH="/path/to/YouApp.app"
# The path to the location you want to put the signed package.
RESULT_PATH="~/Desktop/$APP.pkg"
# The name of certificates you requested.
APP_KEY="3rd Party Mac Developer Application: Company Name (APPIDENTITY)"
INSTALLER_KEY="3rd Party Mac Developer Installer: Company Name (APPIDENTITY)"
FRAMEWORKS_PATH="$APP_PATH/Contents/Frameworks"
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/Electron Framework.framework/Libraries/libnode.dylib"
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/Electron Framework.framework/Electron Framework"
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/Electron Framework.framework/"
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/$APP Helper.app/"
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/$APP Helper EH.app/"
codesign --deep -fs "$APP_KEY" --entitlements child.plist "$FRAMEWORKS_PATH/$APP Helper NP.app/"
codesign -fs "$APP_KEY" --entitlements parent.plist "$APP_PATH"
productbuild --component "$APP_PATH" /Applications --sign "$INSTALLER_KEY" "$RESULT_PATH"
```
If you are new to app sandboxing under OS X, you should also read through
Apple's [Enabling App Sandbox][enable-app-sandbox] to have a basic idea, then
add keys for the permissions needed by your app to the entitlements files.
### Upload Your App and Submit for Review
After signing your app, you can use Application Loader to upload it to iTunes
Connect for processing, making sure you have [created a record][create-record]
before uploading. Then you can [submit your app for review][submit-for-review].
## Limitations of MAS Build
In order to satisfy all requirements for app sandboxing, the following modules
have been disabled in the MAS build:
* `crash-reporter`
* `auto-updater`
and the following behaviors have been changed:
* Video capture may not work for some machines.
* Certain accessibility features may not work.
* Apps will not be aware of DNS changes.
Also, due to the usage of app sandboxing, the resources which can be accessed by
the app are strictly limited; you can read [App Sandboxing][app-sandboxing] for
more information.
[developer-program]: https://developer.apple.com/support/compare-memberships/
[submitting-your-app]: https://developer.apple.com/library/mac/documentation/IDEs/Conceptual/AppDistributionGuide/SubmittingYourApp/SubmittingYourApp.html
[nwjs-guide]: https://github.com/nwjs/nw.js/wiki/Mac-App-Store-%28MAS%29-Submission-Guideline#first-steps
[enable-app-sandbox]: https://developer.apple.com/library/ios/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html
[create-record]: https://developer.apple.com/library/ios/documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/Chapters/CreatingiTunesConnectRecord.html
[submit-for-review]: https://developer.apple.com/library/ios/documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/Chapters/SubmittingTheApp.html
[app-sandboxing]: https://developer.apple.com/app-sandboxing/

View file

@ -6,13 +6,14 @@ using standard HTML5 APIs, as shown in the following example.
_main.js_
```javascript
var app = require('app');
var BrowserWindow = require('browser-window');
var onlineStatusWindow;
const electron = require('electron');
const app = electron.app;
const BrowserWindow = electron.BrowserWindow;
var onlineStatusWindow;
app.on('ready', function() {
onlineStatusWindow = new BrowserWindow({ width: 0, height: 0, show: false });
onlineStatusWindow.loadUrl('file://' + __dirname + '/online-status.html');
onlineStatusWindow.loadURL('file://' + __dirname + '/online-status.html');
});
```
@ -21,18 +22,18 @@ _online-status.html_
```html
<!DOCTYPE html>
<html>
<body>
<script>
var alertOnlineStatus = function() {
window.alert(navigator.onLine ? 'online' : 'offline');
};
<body>
<script>
var alertOnlineStatus = function() {
window.alert(navigator.onLine ? 'online' : 'offline');
};
window.addEventListener('online', alertOnlineStatus);
window.addEventListener('offline', alertOnlineStatus);
window.addEventListener('online', alertOnlineStatus);
window.addEventListener('offline', alertOnlineStatus);
alertOnlineStatus();
</script>
</body>
alertOnlineStatus();
</script>
</body>
</html>
```
@ -45,17 +46,18 @@ to the main process and handled as needed, as shown in the following example.
_main.js_
```javascript
var app = require('app');
var ipc = require('ipc');
var BrowserWindow = require('browser-window');
var onlineStatusWindow;
const electron = require('electron');
const app = electron.app;
const ipcMain = electron.ipcMain;
const BrowserWindow = electron.BrowserWindow;
var onlineStatusWindow;
app.on('ready', function() {
onlineStatusWindow = new BrowserWindow({ width: 0, height: 0, show: false });
onlineStatusWindow.loadUrl('file://' + __dirname + '/online-status.html');
onlineStatusWindow.loadURL('file://' + __dirname + '/online-status.html');
});
ipc.on('online-status-changed', function(event, status) {
ipcMain.on('online-status-changed', function(event, status) {
console.log(status);
});
```
@ -65,18 +67,18 @@ _online-status.html_
```html
<!DOCTYPE html>
<html>
<body>
<script>
var ipc = require('ipc');
var updateOnlineStatus = function() {
ipc.send('online-status-changed', navigator.onLine ? 'online' : 'offline');
};
<body>
<script>
const ipcRenderer = require('electron').ipcRenderer;
var updateOnlineStatus = function() {
ipcRenderer.send('online-status-changed', navigator.onLine ? 'online' : 'offline');
};
window.addEventListener('online', updateOnlineStatus);
window.addEventListener('offline', updateOnlineStatus);
window.addEventListener('online', updateOnlineStatus);
window.addEventListener('offline', updateOnlineStatus);
updateOnlineStatus();
</script>
</body>
updateOnlineStatus();
</script>
</body>
</html>
```

View file

@ -2,7 +2,7 @@
Electron enables you to create desktop applications with pure JavaScript by
providing a runtime with rich native (operating system) APIs. You could see it
as a variant of the io.js runtime that is focused on desktop applications
as a variant of the Node.js runtime that is focused on desktop applications
instead of web servers.
This doesn't mean Electron is a JavaScript binding to graphical user interface
@ -22,8 +22,9 @@ multi-process architecture is also used. Each web page in Electron runs in
its own process, which is called __the renderer process__.
In normal browsers, web pages usually run in a sandboxed environment and are not
allowed access to native resources. Electron users, however, have the power to use
io.js APIs in web pages allowing lower level operating system interactions.
allowed access to native resources. Electron users, however, have the power to
use Node.js APIs in web pages allowing lower level operating system
interactions.
### Differences Between Main Process and Renderer Process
@ -77,11 +78,12 @@ The `main.js` should create windows and handle system events, a typical
example being:
```javascript
var app = require('app'); // Module to control application life.
var BrowserWindow = require('browser-window'); // Module to create native browser window.
const electron = require('electron');
const app = electron.app; // Module to control application life.
const BrowserWindow = electron.BrowserWindow; // Module to create native browser window.
// Report crashes to our server.
require('crash-reporter').start();
electron.crashReporter.start();
// Keep a global reference of the window object, if you don't, the window will
// be closed automatically when the JavaScript object is garbage collected.
@ -103,10 +105,10 @@ app.on('ready', function() {
mainWindow = new BrowserWindow({width: 800, height: 600});
// and load the index.html of the app.
mainWindow.loadUrl('file://' + __dirname + '/index.html');
mainWindow.loadURL('file://' + __dirname + '/index.html');
// Open the DevTools.
mainWindow.openDevTools();
mainWindow.webContents.openDevTools();
// Emitted when the window is closed.
mainWindow.on('closed', function() {
@ -129,8 +131,9 @@ Finally the `index.html` is the web page you want to show:
</head>
<body>
<h1>Hello World!</h1>
We are using io.js <script>document.write(process.version)</script>
and Electron <script>document.write(process.versions['electron'])</script>.
We are using node <script>document.write(process.versions.node)</script>,
Chrome <script>document.write(process.versions.chrome)</script>,
and Electron <script>document.write(process.versions.electron)</script>.
</body>
</html>
```
@ -143,8 +146,8 @@ working as expected.
### electron-prebuilt
If you've installed `electron-prebuilt` globally with `npm`, then you need only
run the following in your app's source directory:
If you've installed `electron-prebuilt` globally with `npm`, then you will only need
to run the following in your app's source directory:
```bash
electron .
@ -158,7 +161,7 @@ If you've installed it locally, then run:
### Manually Downloaded Electron Binary
If you downloaded Electron manually, you can also just use the included
If you downloaded Electron manually, you can also use the included
binary to execute your app directly.
#### Windows
@ -187,3 +190,19 @@ it from [here](https://github.com/atom/electron/releases).
After you're done writing your app, you can create a distribution by
following the [Application Distribution](./application-distribution.md) guide
and then executing the packaged app.
### Try this Example
Clone and run the code in this tutorial by using the [`atom/electron-quick-start`](https://github.com/atom/electron-quick-start)
repository.
**Note**: Running this requires [Git](https://git-scm.com) and [Node.js](https://nodejs.org/en/download/) (which includes [npm](https://npmjs.org)) on your system.
```bash
# Clone the repository
$ git clone https://github.com/atom/electron-quick-start
# Go into the repository
$ cd electron-quick-start
# Install dependencies and run the app
$ npm install && npm start
```

View file

@ -0,0 +1,31 @@
# Supported Platforms
Following platforms are supported by Electron:
### OS X
Only 64bit binaries are provided for OS X, and the minimum OS X version
supported is OS X 10.8.
### Windows
Windows 7 and later are supported, older operating systems are not supported
(and do not work).
Both `x86` and `amd64` (x64) binaries are provided for Windows. Please note, the
`ARM` version of Windows is not supported for now.
### Linux
The prebuilt `ia32`(`i686`) and `x64`(`amd64`) binaries of Electron are built on
Ubuntu 12.04, the `arm` binary is built against ARM v7 with hard-float ABI and
NEON for Debian Wheezy.
Whether the prebuilt binary can run on a distribution depends on whether the
distribution includes the libraries that Electron is linked to on the building
platform, so only Ubuntu 12.04 is guaranteed to work, but following platforms
are also verified to be able to run the prebuilt binaries of Electron:
* Ubuntu 12.04 and later
* Fedora 21
* Debian 8

View file

@ -6,16 +6,17 @@ the location of Electron's headers when building native modules.
## Native Node Module Compatibility
Since Node v0.11.x there were vital changes in the V8 API. So generally all
native modules written for Node v0.10.x won't work for newer Node or io.js
versions. And because Electron internally uses __io.js v3.1.0__, it has the
same problem.
Native modules might break when Node starts using a new version of V8.
To make sure the module you're interested in will work with Electron, you should
check if it supports the internal Node version used by Electron.
You can check what version of Node is used in Electron by looking it up in
the [releases](https://github.com/atom/electron/releases) page or by using
`process.version` (see [Quick Start](https://github.com/atom/electron/blob/master/docs/tutorial/quick-start.md)
for example).
To solve this, you should use modules that support Node v0.11.x or later,
[many modules](https://www.npmjs.org/browse/depended/nan) do support both now.
For old modules that only support Node v0.10.x, you should use the
[nan](https://github.com/rvagg/nan) module to port it to v0.11.x or later
versions of Node or io.js.
Consider using [NAN](https://github.com/nodejs/nan/) for your own modules, since
it makes it easier to support multiple versions of Node. It's also helpful for
porting old modules to newer versions of Node so they can work with Electron.
## How to Install Native Modules
@ -30,8 +31,11 @@ which handles the manual steps of downloading headers and building native module
```sh
npm install --save-dev electron-rebuild
# Every time you run npm install, run this
node ./node_modules/.bin/electron-rebuild
# Every time you run "npm install", run this
./node_modules/.bin/electron-rebuild
# On Windows if you have trouble, try:
.\node_modules\.bin\electron-rebuild.cmd
```
### The npm Way

View file

@ -19,26 +19,9 @@ before the app ready event. Also, add the `plugins` switch of `browser-window`.
For example:
```javascript
var app = require('app');
var BrowserWindow = require('browser-window');
// Report crashes to our server.
require('crash-reporter').start();
// Keep a global reference of the window object, if you don't, the window will
// be closed automatically when the javascript object is GCed.
var mainWindow = null;
// Quit when all windows are closed.
app.on('window-all-closed', function() {
if (process.platform != 'darwin') {
app.quit();
}
});
// Specify flash path.
// On Windows, it might be /path/to/pepflashplayer.dll
// On Mac, /path/to/PepperFlashPlayer.plugin
// On OS X, /path/to/PepperFlashPlayer.plugin
// On Linux, /path/to/libpepflashplayer.so
app.commandLine.appendSwitch('ppapi-flash-path', '/path/to/libpepflashplayer.so');
@ -53,7 +36,7 @@ app.on('ready', function() {
'plugins': true
}
});
mainWindow.loadUrl('file://' + __dirname + '/index.html');
mainWindow.loadURL('file://' + __dirname + '/index.html');
// Something else
});
```

View file

@ -41,14 +41,17 @@ upstream, except that you have to manually specify how to connect chrome driver
and where to find Electron's binary:
```javascript
var webdriver = require('selenium-webdriver');
const webdriver = require('selenium-webdriver');
var driver = new webdriver.Builder()
// The "9515" is the port opened by chrome driver.
.usingServer('http://localhost:9515')
.withCapabilities({chromeOptions: {
// Here is the path to your Electron binary.
binary: '/Path-to-Your-App.app/Contents/MacOS/Atom'}})
.withCapabilities({
chromeOptions: {
// Here is the path to your Electron binary.
binary: '/Path-to-Your-App.app/Contents/MacOS/Atom',
}
})
.forBrowser('electron')
.build();
@ -74,7 +77,7 @@ driver.
First you need to download the `chromedriver` binary, and run it:
```bash
$ chromedriver --url-base=/wd/hub --port=9515
$ chromedriver --url-base=wd/hub --port=9515
Starting ChromeDriver (v2.10.291558) on port 9515
Only local connections are allowed.
```
@ -90,13 +93,16 @@ $ npm install webdriverio
### 3. Connect to chrome driver
```javascript
var webdriverio = require('webdriverio');
const webdriverio = require('webdriverio');
var options = {
host: "localhost", // Use localhost as chrome driver server
port: 9515, // "9515" is the port opened by chrome driver.
desiredCapabilities: {
browserName: 'chrome',
chromeOptions: {binary: '/Path-to-Your-App.app/Electron'} // Path to your Electron binary.
chromeOptions: {
binary: '/Path-to-Your-App/electron', // Path to your Electron binary.
args: [/* cli arguments */] // Optional, perhaps 'app=' + /path/to/your/app/
}
}
};
@ -119,4 +125,8 @@ To test your application without rebuilding Electron, simply
[place](https://github.com/atom/electron/blob/master/docs/tutorial/application-distribution.md)
your app source into Electron's resource directory.
Alternatively, pass an argument to run with your electron binary that points to
your app's folder. This eliminates the need to copy-paste your app into
Electron's resource directory.
[chrome-driver]: https://sites.google.com/a/chromium.org/chromedriver/