electron/docs/api/browser/app.md

150 lines
4.3 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 life time.
The example of quitting the whole application when the last window is closed:
```javascript
var app = require('app');
app.on('window-all-closed', function() {
app.quit();
});
```
## Event: will-finish-launching
Emitted when application has done basic startup. On Windows and Linux it is the
same with `ready` event, on OS X this event represents the
`applicationWillFinishLaunching` message of `NSApplication`, usually you would
setup listeners to `open-file` and `open-url` events here, and start the crash
reporter and auto updater.
2013-08-14 22:43:35 +00:00
Under most cases you should just do everything in `ready` event.
2013-08-14 22:43:35 +00:00
## Event: ready
Emitted when atom-shell has done everything initializaiton.
2013-08-14 22:43:35 +00:00
## Event: window-all-closed
Emitted when all windows have been closed.
This event is only emitted when the application is not going to quit. If a
user pressed `Cmd + Q`, or the developer called `app.quit()`, atom-shell would
first try to close all windows and then emit the `will-quit` event, and in
this case the `window-all-closed` would not be emitted.
2013-08-14 22:43:35 +00:00
## Event: will-quit
* `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
See description of `window-all-closed` for the differences between `will-quit`
and it.
2013-08-14 22:43:35 +00:00
## Event: open-file
* `event` Event
* `path` String
Emitted when user wants to open a file with the application, it usually
happens when the application is already opened and then OS wants to reuse the
application to open file.
2013-08-14 22:43:35 +00:00
You should call `event.preventDefault()` if you want to handle this event.
## Event: open-url
* `event` Event
* `url` String
Emitted when user wants to open a URL with the application, this 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.
## app.quit()
Try to close all windows. If all windows are successfully closed, the
`will-quit` event will be emitted and by default the application would be
terminated.
2013-08-14 22:43:35 +00:00
This method guarantees all `beforeunload` and `unload` handlers are correctly
executed. It is possible that a window cancels the quitting by returning
`false` in `beforeunload` handler.
2013-08-14 22:43:35 +00:00
## app.terminate()
Quit the application directly, it will not try to close all windows so cleanup
code will not run.
2013-08-14 22:43:35 +00:00
## app.getVersion()
Returns the version of loaded application, if no version is found in
application's `package.json`, the version of current bundle or executable would
be returned.
## app.getName()
Returns current application's name, the name in `package.json` would be
used.
Usually the `name` field of `package.json` is a short lowercased name, according
to the spec of npm modules. So usually you should also specify a `productName`
field, which is your application's full capitalized name, and it will be
preferred over `name` by atom-shell.
2013-08-14 22:43:35 +00:00
## app.commandLine.appendSwitch(switch, [value])
Append a switch [with optional value] to Chromium's command line.
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
## app.commandLine.appendArgument(value)
Append an argument to Chromium's command line. The argument will quoted properly.
**Note:** This will not affect `process.argv`.
## app.dock.bounce([type])
* `type` String - Can be `critical` or `informational`, the default is
* `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
When `informational` is passed, the dock icon will bounce for one second. The
request, though, remains active until either the application becomes active or
the request is canceled.
2013-08-14 22:43:35 +00:00
An ID representing the request would be returned.
**Note:** This API is only available on Mac.
## app.dock.cancelBounce(id)
* `id` Integer
Cancel the bounce of `id`.
**Note:** This API is only available on Mac.
## app.dock.setBadge(text)
* `text` String
Sets the string to be displayed in the docks badging area.
**Note:** This API is only available on Mac.
## app.dock.getBadge()
Returns the badge string of the dock.
**Note:** This API is only available on Mac.