electron/docs/api/app.md

353 lines
10 KiB
Markdown
Raw Normal View History

2013-09-09 07:35:57 +00:00
# app
2013-08-14 22:43:35 +00:00
The `app` module is responsible for controlling the application's lifecycle.
2013-08-14 22:43:35 +00:00
2015-08-24 12:38:29 +00:00
The following example shows how to quit the application when the last window is
closed:
2013-08-14 22:43:35 +00:00
```javascript
var app = require('app');
app.on('window-all-closed', function() {
app.quit();
});
```
2015-08-19 16:28:48 +00:00
## Events
The `app` object emits the following events:
2015-08-19 16:28:48 +00:00
### Event: 'will-finish-launching'
2013-08-14 22:43:35 +00:00
Emitted when the application has finished basic startup. On Windows and Linux,
the `will-finish-launching` event is the same as the `ready` event; on OS X,
2015-08-24 12:38:29 +00:00
this event represents the `applicationWillFinishLaunching` notification of
`NSApplication`. You would usually set up listeners for the `open-file` and
`open-url` events here, and start the crash reporter and auto updater.
2013-08-14 22:43:35 +00:00
In most cases, you should just do everything in the `ready` event handler.
2013-08-14 22:43:35 +00:00
2015-08-19 16:28:48 +00:00
### Event: 'ready'
2015-08-07 05:15:59 +00:00
Emitted when Electron has finished initialization.
2013-08-14 22:43:35 +00:00
2015-08-19 16:28:48 +00:00
### Event: 'window-all-closed'
2013-08-14 22:43:35 +00:00
Emitted when all windows have been closed.
This event is only emitted when the application is not going to quit. If the
2015-08-19 16:28:48 +00:00
user pressed `Cmd + Q`, or the developer called `app.quit()`, Electron will
first try to close all the windows and then emit the `will-quit` event, and in
this case the `window-all-closed` event would not be emitted.
2013-08-14 22:43:35 +00:00
2015-08-19 16:28:48 +00:00
### Event: 'before-quit'
Returns:
* `event` Event
Emitted before the application starts closing its windows.
Calling `event.preventDefault()` will prevent the default behaviour, which is
terminating the application.
2015-08-19 16:28:48 +00:00
### Event: 'will-quit'
2013-08-14 22:43:35 +00:00
Returns:
2013-08-14 22:43:35 +00:00
* `event` Event
Emitted when all windows have been closed and the application will quit.
Calling `event.preventDefault()` will prevent the default behaviour, which is
terminating the application.
2013-08-14 22:43:35 +00:00
2015-08-24 12:38:29 +00:00
See the description of the `window-all-closed` event for the differences between
the `will-quit` and `window-all-closed` events.
2013-08-14 22:43:35 +00:00
2015-08-19 16:28:48 +00:00
### Event: 'quit'
2014-09-25 13:47:54 +00:00
Emitted when the application is quitting.
2014-09-25 13:47:54 +00:00
2015-08-19 16:28:48 +00:00
### Event: 'open-file'
2013-08-14 22:43:35 +00:00
Returns:
2013-08-14 22:43:35 +00:00
* `event` Event
* `path` String
2015-08-24 12:38:29 +00:00
Emitted when the user wants to open a file with the application. The `open-file`
event is usually emitted when the application is already open and the OS wants
to reuse the application to open the file. `open-file` is also emitted when a
file is dropped onto the dock and the application is not yet running. Make sure
to listen for the `open-file` event very early in your application startup to
handle this case (even before the `ready` event is emitted).
2013-08-14 22:43:35 +00:00
You should call `event.preventDefault()` if you want to handle this event.
2015-08-19 16:28:48 +00:00
### Event: 'open-url'
2013-08-14 22:43:35 +00:00
Returns:
2013-08-14 22:43:35 +00:00
* `event` Event
* `url` String
Emitted when the user wants to open a URL with the application. The URL scheme
must be registered to be opened by your application.
2013-08-14 22:43:35 +00:00
You should call `event.preventDefault()` if you want to handle this event.
### Event: 'activate' _OS X_
Returns:
* `event` Event
* `hasVisibleWindows` Boolean
Emitted when the application is activated, which usually happens when clicks on
the applications's dock icon.
2015-08-19 16:28:48 +00:00
### Event: 'browser-window-blur'
Returns:
* `event` Event
* `window` BrowserWindow
Emitted when a [browserWindow](browser-window.md) gets blurred.
2015-08-19 16:28:48 +00:00
### Event: 'browser-window-focus'
Returns:
* `event` Event
* `window` BrowserWindow
Emitted when a [browserWindow](browser-window.md) gets focused.
2015-09-14 09:02:36 +00:00
### Event: 'browser-window-created'
Returns:
* `event` Event
* `window` BrowserWindow
Emitted when a new [browserWindow](browser-window.md) is created.
### Event: 'select-certificate'
Emitted when a client certificate is requested.
Returns:
* `event` Event
* `webContents` [WebContents](browser-window.md#class-webcontents)
* `url` String
* `certificateList` [Objects]
* `data` PEM encoded data
* `issuerName` Issuer's Common Name
* `callback` Function
2015-08-19 16:28:48 +00:00
```javascript
app.on('select-certificate', function(event, host, url, list, callback) {
event.preventDefault();
callback(list[0]);
})
```
2015-08-24 12:38:29 +00:00
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.
### Event: 'gpu-process-crashed'
2015-06-25 13:53:22 +00:00
Emitted when the gpu process crashes.
2015-06-25 13:53:22 +00:00
2015-08-19 16:28:48 +00:00
## Methods
The `app` object has the following methods:
2015-08-19 16:28:48 +00:00
2015-09-09 21:09:14 +00:00
**Note:** Some methods are only available on specific operating systems and are labeled as such.
2015-08-19 16:28:48 +00:00
### `app.quit()`
2013-08-14 22:43:35 +00:00
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.
2013-08-14 22:43:35 +00:00
2015-08-24 12:38:29 +00:00
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.
2013-08-14 22:43:35 +00:00
2015-08-19 16:28:48 +00:00
### `app.getAppPath()`
2015-07-06 09:35:35 +00:00
Returns the current application directory.
2015-08-19 16:28:48 +00:00
### `app.getPath(name)`
2015-01-19 02:25:31 +00:00
* `name` String
2015-01-19 02:25:31 +00:00
Retrieves a path to a special directory or file associated with `name`. On
failure an `Error` is thrown.
2015-01-19 02:25:31 +00:00
You can request the following paths by the name:
2015-01-19 02:25:31 +00:00
2015-08-19 16:28:48 +00:00
* `home` User's home directory.
* `appData` Per-user application data directory, which by default points to:
2015-01-19 02:25:31 +00:00
* `%APPDATA%` on Windows
2015-01-19 05:10:42 +00:00
* `$XDG_CONFIG_HOME` or `~/.config` on Linux
2015-01-19 02:25:31 +00:00
* `~/Library/Application Support` on OS X
2015-08-19 16:28:48 +00:00
* `userData` The directory for storing your app's configuration files, which by
default it is the `appData` 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.
2015-01-19 02:25:31 +00:00
2015-08-19 16:28:48 +00:00
### `app.setPath(name, path)`
2015-01-19 02:25:31 +00:00
* `name` String
* `path` String
Overrides the `path` to a special directory or file associated with `name`. If
2015-01-19 02:25:31 +00:00
the path specifies a directory that does not exist, the directory will be
created by this method. On failure an `Error` is thrown.
2015-01-19 02:25:31 +00:00
2015-08-19 16:28:48 +00:00
You can only override paths of a `name` defined in `app.getPath`.
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.
2015-08-19 16:28:48 +00:00
### `app.getVersion()`
2013-08-14 22:43:35 +00:00
Returns the version of the loaded application. If no version is found in the
2015-08-24 12:38:29 +00:00
application's `package.json` file, the version of the current bundle or
executable is returned.
2015-08-19 16:28:48 +00:00
### `app.getName()`
Returns the current application's name, which is the name in the application's
`package.json` file.
Usually the `name` field of `package.json` is a short lowercased name, according
to the npm modules spec. You should usually also specify a `productName`
field, which is your application's full capitalized name, and which will be
2015-04-16 03:31:12 +00:00
preferred over `name` by Electron.
2013-08-14 22:43:35 +00:00
2015-09-16 08:17:49 +00:00
### `app.getLocale()`
Returns the current application locale.
2015-08-19 16:28:48 +00:00
### `app.resolveProxy(url, callback)`
2014-08-19 13:26:45 +00:00
* `url` URL
* `callback` Function
Resolves the proxy information for `url`. The `callback` will be called with
`callback(proxy)` when the request is performed.
2014-08-19 13:26:45 +00:00
2015-08-19 16:28:48 +00:00
### `app.addRecentDocument(path)`
2014-11-17 11:02:37 +00:00
* `path` String
Adds `path` to the recent documents list.
2014-11-17 11:02:37 +00:00
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.
2014-11-17 11:02:37 +00:00
2015-08-19 16:28:48 +00:00
### `app.clearRecentDocuments()`
2014-11-17 11:02:37 +00:00
Clears the recent documents list.
2015-08-24 22:33:07 +00:00
### `app.setUserTasks(tasks)` _Windows_
2014-11-17 11:50:34 +00:00
* `tasks` Array - Array of `Task` objects
Adds `tasks` to the [Tasks][tasks] category of the JumpList on Windows.
2014-11-17 11:50:34 +00:00
`tasks` is an array of `Task` objects in the following format:
2014-11-17 11:50:34 +00:00
2015-08-19 16:28:48 +00:00
`Task` Object
* `program` String - Path of the program to execute, usually you should
specify `process.execPath` which opens the current program.
* `arguments` String - The command line arguments when `program` is
executed.
* `title` String - The string to be displayed in a JumpList.
* `description` String - Description of this task.
* `iconPath` String - The absolute path to an icon to be displayed in a
2015-08-24 12:38:29 +00:00
JumpList, which can be an arbitrary resource file that contains an icon. You
can usually specify `process.execPath` to show the icon of the program.
2015-08-19 16:28:48 +00:00
* `iconIndex` Integer - The icon index in the icon file. If an icon file
consists of two or more icons, set this value to identify the icon. If an
icon file consists of one icon, this value is 0.
2014-11-17 11:50:34 +00:00
### `app.allowNTLMCredentialsForAllDomains(allow)`
* `allow` Boolean
Dynamically sets whether to always send credentials for HTTP NTLM or Negotiate
2015-10-20 19:35:56 +00:00
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.
2015-08-19 16:28:48 +00:00
### `app.commandLine.appendSwitch(switch[, value])`
2013-08-14 22:43:35 +00:00
2015-08-19 16:28:48 +00:00
Append a switch (with optional `value`) to Chromium's command line.
2013-08-14 22:43:35 +00:00
2013-10-05 05:03:08 +00:00
**Note:** This will not affect `process.argv`, and is mainly used by developers
to control some low-level Chromium behaviors.
2013-08-14 22:43:35 +00:00
2015-08-19 16:28:48 +00:00
### `app.commandLine.appendArgument(value)`
2013-08-14 22:43:35 +00:00
2015-08-24 12:38:29 +00:00
Append an argument to Chromium's command line. The argument will be quoted
correctly.
2013-08-14 22:43:35 +00:00
**Note:** This will not affect `process.argv`.
2015-08-24 22:33:07 +00:00
### `app.dock.bounce([type])` _OS X_
2013-08-14 22:43:35 +00:00
2015-08-24 12:56:19 +00:00
* `type` String (optional) - Can be `critical` or `informational`. The default is
2015-03-30 08:13:11 +00:00
`informational`
2013-08-14 22:43:35 +00:00
When `critical` is passed, the dock icon will bounce until either the
application becomes active or the request is canceled.
2013-08-14 22:43:35 +00:00
2015-08-24 12:38:29 +00:00
When `informational` is passed, the dock icon will bounce for one second.
However, the request remains active until either the application becomes active
or the request is canceled.
2013-08-14 22:43:35 +00:00
2015-08-19 16:28:48 +00:00
Returns an ID representing the request.
2013-08-14 22:43:35 +00:00
2015-08-24 22:33:07 +00:00
### `app.dock.cancelBounce(id)` _OS X_
2013-08-14 22:43:35 +00:00
* `id` Integer
Cancel the bounce of `id`.
2015-08-24 22:33:07 +00:00
### `app.dock.setBadge(text)` _OS X_
2013-08-14 22:43:35 +00:00
* `text` String
Sets the string to be displayed in the docks badging area.
2015-08-24 22:33:07 +00:00
### `app.dock.getBadge()` _OS X_
2013-08-14 22:43:35 +00:00
Returns the badge string of the dock.
2015-08-24 22:33:07 +00:00
### `app.dock.hide()` _OS X_
Hides the dock icon.
2015-08-24 22:33:07 +00:00
### `app.dock.show()` _OS X_
Shows the dock icon.
2015-08-24 22:33:07 +00:00
### `app.dock.setMenu(menu)` _OS X_
2014-11-17 10:48:02 +00:00
* `menu` Menu
Sets the application's [dock menu][dock-menu].
2014-11-17 10:48:02 +00:00
[dock-menu]:https://developer.apple.com/library/mac/documentation/Carbon/Conceptual/customizing_docktile/concepts/dockconcepts.html#//apple_ref/doc/uid/TP30000986-CH2-TPXREF103
2014-11-17 11:50:34 +00:00
[tasks]:http://msdn.microsoft.com/en-us/library/windows/desktop/dd378460(v=vs.85).aspx#tasks