Merge pull request #2533 from atom/jl-snd-docs
Standardize Docs: app, auto-updater, styleguide
This commit is contained in:
Jessica Lord
commit
ac84f56e36
3 changed files with 215 additions and 114 deletions
219
docs/api/app.md
219
docs/api/app.md
|
|
@ -2,7 +2,8 @@
|
|||
|
||||
The `app` module is responsible for controlling the application's lifecycle.
|
||||
|
||||
The following example shows how to quit the application when the last window is closed:
|
||||
The following example shows how to quit the application when the last window is
|
||||
closed:
|
||||
|
||||
```javascript
|
||||
var app = require('app');
|
||||
|
|
@ -11,30 +12,36 @@ app.on('window-all-closed', function() {
|
|||
});
|
||||
```
|
||||
|
||||
## Event: will-finish-launching
|
||||
## Events
|
||||
|
||||
The `app` object emits the following events:
|
||||
|
||||
### 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,
|
||||
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.
|
||||
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.
|
||||
|
||||
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'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
|
||||
|
|
@ -42,7 +49,9 @@ 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'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
|
||||
|
|
@ -50,28 +59,32 @@ 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'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `path` String
|
||||
|
||||
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).
|
||||
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).
|
||||
|
||||
You should call `event.preventDefault()` if you want to handle this event.
|
||||
|
||||
## Event: open-url
|
||||
### Event: 'open-url'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `url` String
|
||||
|
|
@ -81,20 +94,24 @@ 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.
|
||||
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'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `window` BrowserWindow
|
||||
|
||||
Emitted when a [browserWindow](browser-window.md) gets blurred.
|
||||
|
||||
## Event: browser-window-focus
|
||||
### Event: 'browser-window-focus'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `window` BrowserWindow
|
||||
|
|
@ -105,6 +122,8 @@ Emitted when a [browserWindow](browser-window.md) gets focused.
|
|||
|
||||
Emitted when a client certificate is requested.
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `webContents` [WebContents](browser-window.md#class-webcontents)
|
||||
* `url` String
|
||||
|
|
@ -113,37 +132,43 @@ 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
|
||||
from the store.
|
||||
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 `app` object has the following methods:
|
||||
|
||||
**Note** Some methods are only available on specific operating systems and are labeled as such.
|
||||
|
||||
### `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.
|
||||
|
||||
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.
|
||||
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.getAppPath()
|
||||
### `app.getAppPath()`
|
||||
|
||||
Returns the current application directory.
|
||||
|
||||
## app.getPath(name)
|
||||
### `app.getPath(name)`
|
||||
|
||||
* `name` String
|
||||
|
||||
|
|
@ -152,25 +177,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 +204,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.
|
||||
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 +226,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 +234,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 +243,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)` _Windows_
|
||||
|
||||
* `tasks` Array - Array of `Task` objects
|
||||
|
||||
|
|
@ -230,92 +255,78 @@ 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.
|
||||
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])` _OS X_
|
||||
|
||||
* `type` String - Can be `critical` or `informational`. The default is
|
||||
* `type` String (optional) - Can be `critical` or `informational`. The default is
|
||||
`informational`
|
||||
|
||||
When `critical` is passed, the dock icon will bounce until either the
|
||||
application becomes active or the request is canceled.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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)` _OS X_
|
||||
|
||||
* `id` Integer
|
||||
|
||||
Cancel the bounce of `id`.
|
||||
|
||||
**Note:** This API is only available on OS X.
|
||||
|
||||
## app.dock.setBadge(text)
|
||||
### `app.dock.setBadge(text)` _OS X_
|
||||
|
||||
* `text` String
|
||||
|
||||
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()` _OS X_
|
||||
|
||||
Returns the badge string of the dock.
|
||||
|
||||
**Note:** This API is only available on OS X.
|
||||
|
||||
## app.dock.hide()
|
||||
### `app.dock.hide()` _OS X_
|
||||
|
||||
Hides the dock icon.
|
||||
|
||||
**Note:** This API is only available on OS X.
|
||||
|
||||
## app.dock.show()
|
||||
### `app.dock.show()` _OS X_
|
||||
|
||||
Shows the dock icon.
|
||||
|
||||
**Note:** This API is only available on OS X.
|
||||
|
||||
## app.dock.setMenu(menu)
|
||||
### `app.dock.setMenu(menu)` _OS X_
|
||||
|
||||
* `menu` Menu
|
||||
|
||||
Sets the application's [dock menu][dock-menu].
|
||||
|
||||
**Note:** This API is only available on OS X.
|
||||
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# auto-updater
|
||||
# autoUpdater
|
||||
|
||||
**This module has only been implemented for OS X.**
|
||||
|
||||
|
|
@ -98,27 +98,35 @@ appropriate format.
|
|||
|
||||
`pub_date` (if present) must be formatted according to ISO 8601.
|
||||
|
||||
## Event: error
|
||||
## Events
|
||||
|
||||
The `autoUpdater` object emits the following events:
|
||||
|
||||
### Event: 'error'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `message` String
|
||||
|
||||
Emitted when there is an error while updating.
|
||||
|
||||
## Event: checking-for-update
|
||||
### Event: 'checking-for-update'
|
||||
|
||||
Emitted when checking if an update has started.
|
||||
|
||||
## Event: update-available
|
||||
### Event: 'update-available'
|
||||
|
||||
Emitted when there is an available update. The update is downloaded
|
||||
automatically.
|
||||
|
||||
## Event: update-not-available
|
||||
### Event: 'update-not-available'
|
||||
|
||||
Emitted when there is no available update.
|
||||
|
||||
## Event: update-downloaded
|
||||
### Event: 'update-downloaded'
|
||||
|
||||
Returns:
|
||||
|
||||
* `event` Event
|
||||
* `releaseNotes` String
|
||||
|
|
@ -127,17 +135,21 @@ Emitted when there is no available update.
|
|||
* `updateUrl` String
|
||||
* `quitAndUpdate` Function
|
||||
|
||||
Emitted when an update has been downloaded. Calling `quitAndUpdate()` will restart
|
||||
the application and install the update.
|
||||
Emitted when an update has been downloaded. Calling `quitAndUpdate()` will
|
||||
restart the application and install the update.
|
||||
|
||||
## autoUpdater.setFeedUrl(url)
|
||||
## Methods
|
||||
|
||||
The `autoUpdater` object has the following methods:
|
||||
|
||||
### `autoUpdater.setFeedUrl(url)`
|
||||
|
||||
* `url` String
|
||||
|
||||
Set the `url` and initialize the auto updater. The `url` cannot be changed
|
||||
once it is set.
|
||||
|
||||
## autoUpdater.checkForUpdates()
|
||||
### `autoUpdater.checkForUpdates()`
|
||||
|
||||
Ask the server whether there is an update. You must call `setFeedUrl` before
|
||||
using this API.
|
||||
|
|
|
|||
78
docs/styleguide.md
Normal file
78
docs/styleguide.md
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
# Electron Documentation Styleguide
|
||||
|
||||
Find the appropriate section for your task: [reading Electron documentation](#)
|
||||
or [writing Electron documentation](#).
|
||||
|
||||
## Writing Electron Documentation
|
||||
|
||||
These are the ways that we construct the Electron documentation.
|
||||
|
||||
- Maximum one `h1` title per page.
|
||||
- Use `bash` instead of `cmd` in code blocks (because of syntax highlighter).
|
||||
- Doc `h1` titles should match object name (i.e. `browser-window` →
|
||||
`BrowserWindow`).
|
||||
- Hyphen separated filenames, however, are fine.
|
||||
- No headers following headers, add at least a one-sentence description.
|
||||
- Methods headers are wrapped in `code` ticks.
|
||||
- Event headers are wrapped in single 'quotation' marks.
|
||||
- No nesting lists more than 2 levels (unfortunately because of markdown
|
||||
renderer).
|
||||
- Add section titles: Events, Class Methods and Instance Methods.
|
||||
- Use 'will' over 'would' when describing outcomes.
|
||||
- Events and methods are `h3` headers.
|
||||
- Optional arguments written as `function (required[, optional])`.
|
||||
- Optional arguments are denoted when called out in list.
|
||||
- Line length is 80-column wrapped.
|
||||
- Platform specific methods are noted in italics following method header.
|
||||
- ```### `method(foo, bar)` _OS X_```
|
||||
|
||||
## Reading Electron Documentation
|
||||
|
||||
Here are some tips for understanding Electron documentation syntax.
|
||||
|
||||
### Methods
|
||||
|
||||
An example of [method](https://developer.mozilla.org/en-US/docs/Glossary/Method)
|
||||
documentation:
|
||||
|
||||
---
|
||||
|
||||
`methodName(required[, optional]))`
|
||||
|
||||
* `require` String, **required**
|
||||
* `optional` Integer
|
||||
|
||||
---
|
||||
|
||||
The method name is followed by the arguments it takes. Optional arguments are
|
||||
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)
|
||||
or a custom type like Electron's [`webContent`](api/web-content.md).
|
||||
|
||||
### Events
|
||||
|
||||
An example of [event](https://developer.mozilla.org/en-US/docs/Web/API/Event)
|
||||
documentation:
|
||||
|
||||
---
|
||||
|
||||
Event: 'wake-up'
|
||||
|
||||
Returns:
|
||||
|
||||
* `time` String
|
||||
|
||||
---
|
||||
|
||||
The event is a string that is used after a `.on` listener method. If it returns
|
||||
a value it and its type is noted below. If you were to listen and respond to
|
||||
this event it might look something like this:
|
||||
|
||||
```javascript
|
||||
Alarm.on('wake-up', function(time) {
|
||||
console.log(time)
|
||||
})
|
||||
```
|
||||
Loading…
Reference in a new issue