From 624b6b97626d9baef48f60b67d84031b0a614870 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Wed, 19 Aug 2015 18:28:48 +0200 Subject: [PATCH] Standardize app.md --- docs/api/app.md | 138 +++++++++++++++++++++++++----------------------- 1 file changed, 72 insertions(+), 66 deletions(-) diff --git a/docs/api/app.md b/docs/api/app.md index 8223643a375f..2a625ec3c18e 100644 --- a/docs/api/app.md +++ b/docs/api/app.md @@ -11,7 +11,11 @@ app.on('window-all-closed', function() { }); ``` -## Event: will-finish-launching +## Events + +The following are events on `app`. + +### Event: 'will-finish-launching' 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, @@ -21,20 +25,20 @@ and start the crash reporter and auto updater. In most cases, you should just do everything in the `ready` event handler. -## Event: ready +### Event: 'ready' Emitted when Electron has finished initialization. -## Event: window-all-closed +### 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 the -user pressed `Cmd + Q`, or the developer called `app.quit()`, Electron would +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. -## Event: before-quit +### Event: 'before-quit' * `event` Event @@ -42,7 +46,7 @@ Emitted before the application starts closing its windows. Calling `event.preventDefault()` will prevent the default behaviour, which is terminating the application. -## Event: will-quit +### Event: 'will-quit' * `event` Event @@ -50,14 +54,13 @@ 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. -See the description of the `window-all-closed` event for the differences between the `will-quit` -and `window-all-closed` events. +See the description of the `window-all-closed` event for the differences between the `will-quit` and `window-all-closed` events. -## Event: quit +### Event: 'quit' Emitted when the application is quitting. -## Event: open-file +### Event: 'open-file' * `event` Event * `path` String @@ -71,7 +74,7 @@ event very early in your application startup to handle this case (even before th You should call `event.preventDefault()` if you want to handle this event. -## Event: open-url +### Event: 'open-url' * `event` Event * `url` String @@ -81,20 +84,20 @@ must be registered to be opened by your application. You should call `event.preventDefault()` if you want to handle this event. -## Event: activate-with-no-open-windows +### Event: 'activate-with-no-open-windows' Emitted when the application is activated while there are no open windows, which usually happens when the user has closed all of the application's windows and then clicks on the application's dock icon. -## Event: browser-window-blur +### Event: 'browser-window-blur' * `event` Event * `window` BrowserWindow Emitted when a [browserWindow](browser-window.md) gets blurred. -## Event: browser-window-focus +### Event: 'browser-window-focus' * `event` Event * `window` BrowserWindow @@ -113,25 +116,28 @@ Emitted when a client certificate is requested. * `issuerName` Issuer's Common Name * `callback` Function -``` +```javascript app.on('select-certificate', function(event, host, url, list, callback) { event.preventDefault(); callback(list[0]); }) ``` -`url` corresponds to the navigation entry requesting the client certificate. -`callback` needs to be called with an entry filtered from the list. -`event.preventDefault()` prevents the application from using the first certificate +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' Emitted when the gpu process crashes. -## app.quit() +## Methods -Try to close all windows. The `before-quit` event will first be emitted. If all +The following are methods on the `app` class. + +### `app.quit()` + +Try to close all windows. The `before-quit` event will emitted first. If all windows are successfully closed, the `will-quit` event will be emitted and by default the application will terminate. @@ -139,11 +145,11 @@ This method guarantees that all `beforeunload` and `unload` event handlers are c executed. It is possible that a window cancels the quitting by returning `false` in the `beforeunload` event handler. -## app.getAppPath() +### `app.getAppPath()` Returns the current application directory. -## app.getPath(name) +### `app.getPath(name)` * `name` String @@ -152,25 +158,25 @@ failure an `Error` is thrown. You can request the following paths by the name: -* `home`: User's home directory -* `appData`: Per-user application data directory, which by default points to: +* `home` User's home directory. +* `appData` Per-user application data directory, which by default points to: * `%APPDATA%` on Windows * `$XDG_CONFIG_HOME` or `~/.config` on Linux * `~/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: +* `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 +* `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. -## app.setPath(name, path) +### `app.setPath(name, path)` * `name` String * `path` String @@ -179,19 +185,19 @@ Overrides the `path` to a special directory or file associated with `name`. If the path specifies a directory that does not exist, the directory will be created by this method. On failure an `Error` is thrown. -You can only override paths of `name`s defined in `app.getPath`. +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` +By default, web pages's 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. -## app.getVersion() +### `app.getVersion()` Returns the version of the loaded application. If no version is found in the application's `package.json` file, the version of the current bundle or executable is returned. -## app.getName() +### `app.getName()` Returns the current application's name, which is the name in the application's `package.json` file. @@ -201,7 +207,7 @@ 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 preferred over `name` by Electron. -## app.resolveProxy(url, callback) +### `app.resolveProxy(url, callback)` * `url` URL * `callback` Function @@ -209,7 +215,7 @@ preferred over `name` by Electron. 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)` * `path` String @@ -218,11 +224,11 @@ 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()` Clears the recent documents list. -## app.setUserTasks(tasks) +### `app.setUserTasks(tasks)` * `tasks` Array - Array of `Task` objects @@ -230,36 +236,36 @@ Adds `tasks` to the [Tasks][tasks] category of the JumpList on Windows. `tasks` is an array of `Task` objects in following format: -* `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 - 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 - * `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 +`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 + 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. +* `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. **Note:** This API is only available on Windows. -## app.commandLine.appendSwitch(switch, [value]) +### `app.commandLine.appendSwitch(switch[, value])` -Append a switch [with optional value] to Chromium's command line. +Append a switch (with optional `value`) to Chromium's command line. **Note:** This will not affect `process.argv`, and is mainly used by developers to control some low-level Chromium behaviors. -## app.commandLine.appendArgument(value) +### `app.commandLine.appendArgument(value)` Append an argument to Chromium's command line. The argument will be quoted correctly. **Note:** This will not affect `process.argv`. -## app.dock.bounce([type]) +### app.dock.bounce([type]) * `type` String - Can be `critical` or `informational`. The default is `informational` @@ -271,11 +277,11 @@ When `informational` is passed, the dock icon will bounce for one second. Howeve the request remains active until either the application becomes active or the request is canceled. -An ID representing the request is returned. +Returns an ID representing the request. **Note:** This API is only available on OS X. -## app.dock.cancelBounce(id) +### `app.dock.cancelBounce(id)` * `id` Integer @@ -283,7 +289,7 @@ Cancel the bounce of `id`. **Note:** This API is only available on OS X. -## app.dock.setBadge(text) +### `app.dock.setBadge(text)` * `text` String @@ -291,25 +297,25 @@ Sets the string to be displayed in the dock’s badging area. **Note:** This API is only available on OS X. -## app.dock.getBadge() +### `app.dock.getBadge()` Returns the badge string of the dock. **Note:** This API is only available on OS X. -## app.dock.hide() +### `app.dock.hide()` Hides the dock icon. **Note:** This API is only available on OS X. -## app.dock.show() +### `app.dock.show()` Shows the dock icon. **Note:** This API is only available on OS X. -## app.dock.setMenu(menu) +### `app.dock.setMenu(menu)` * `menu` Menu