mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

Merge pull request #2533 from atom/jl-snd-docs

Browse source 
Standardize Docs: app, auto-updater, styleguide
This commit is contained in:
Jessica Lord 2015-08-25 14:37:48 -07:00
commit ac84f56e36
3 changed files with 215 additions and 114 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

209
docs/api/app.md
View file

@ -2,7 +2,8 @@
The `app` module is responsible for controlling the application's lifecycle. 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 ```javascript
var app = require('app'); 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, 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, the `will-finish-launching` event is the same as the `ready` event; on OS X,
this event represents the `applicationWillFinishLaunching` notification of `NSApplication`. this event represents the `applicationWillFinishLaunching` notification of
You would usually set up listeners for the `open-file` and `open-url` events here, `NSApplication`. You would usually set up listeners for the `open-file` and
and start the crash reporter and auto updater. `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. In most cases, you should just do everything in the `ready` event handler.
## Event: ready ### Event: 'ready'
Emitted when Electron has finished initialization. Emitted when Electron has finished initialization.
## Event: window-all-closed ### Event: 'window-all-closed'
Emitted when all windows have been closed. Emitted when all windows have been closed.
This event is only emitted when the application is not going to quit. If the 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 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. this case the `window-all-closed` event would not be emitted.
## Event: before-quit ### Event: 'before-quit'
Returns:
* `event` Event * `event` Event
@ -42,7 +49,9 @@ Emitted before the application starts closing its windows.
Calling `event.preventDefault()` will prevent the default behaviour, which is Calling `event.preventDefault()` will prevent the default behaviour, which is
terminating the application. terminating the application.
## Event: will-quit ### Event: 'will-quit'
Returns:
* `event` Event * `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 Calling `event.preventDefault()` will prevent the default behaviour, which is
terminating the application. terminating the application.
See the description of the `window-all-closed` event for the differences between the `will-quit` See the description of the `window-all-closed` event for the differences between
and `window-all-closed` events. the `will-quit` and `window-all-closed` events.
## Event: quit ### Event: 'quit'
Emitted when the application is quitting. Emitted when the application is quitting.
## Event: open-file ### Event: 'open-file'
Returns:
* `event` Event * `event` Event
* `path` String * `path` String
Emitted when the user wants to open a file with the application. The `open-file` event Emitted when the user wants to open a file with the application. The `open-file`
is usually emitted when the application is already open and the OS wants to reuse the event is usually emitted when the application is already open and the OS wants
application to open the file. `open-file` is also emitted when a file is dropped onto the to reuse the application to open the file. `open-file` is also emitted when a
dock and the application is not yet running. Make sure to listen for the `open-file` file is dropped onto the dock and the application is not yet running. Make sure
event very early in your application startup to handle this case (even before the to listen for the `open-file` event very early in your application startup to
`ready` event is emitted). handle this case (even before the `ready` event is emitted).
You should call `event.preventDefault()` if you want to handle this event. You should call `event.preventDefault()` if you want to handle this event.
## Event: open-url ### Event: 'open-url'
Returns:
* `event` Event * `event` Event
* `url` String * `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. 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 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 usually happens when the user has closed all of the application's windows and
clicks on the application's dock icon. then clicks on the application's dock icon.
## Event: browser-window-blur ### Event: 'browser-window-blur'
Returns:
* `event` Event * `event` Event
* `window` BrowserWindow * `window` BrowserWindow
Emitted when a [browserWindow](browser-window.md) gets blurred. Emitted when a [browserWindow](browser-window.md) gets blurred.
## Event: browser-window-focus ### Event: 'browser-window-focus'
Returns:
* `event` Event * `event` Event
* `window` BrowserWindow * `window` BrowserWindow
@ -105,6 +122,8 @@ Emitted when a [browserWindow](browser-window.md) gets focused.
Emitted when a client certificate is requested. Emitted when a client certificate is requested.
Returns:
* `event` Event * `event` Event
* `webContents` [WebContents](browser-window.md#class-webcontents) * `webContents` [WebContents](browser-window.md#class-webcontents)
* `url` String * `url` String
@ -113,37 +132,43 @@ Emitted when a client certificate is requested.
* `issuerName` Issuer's Common Name * `issuerName` Issuer's Common Name
* `callback` Function * `callback` Function
``` ```javascript
app.on('select-certificate', function(event, host, url, list, callback) { app.on('select-certificate', function(event, host, url, list, callback) {
event.preventDefault(); event.preventDefault();
callback(list[0]); callback(list[0]);
}) })
``` ```
`url` corresponds to the navigation entry requesting the client certificate. The `url` corresponds to the navigation entry requesting the client certificate
`callback` needs to be called with an entry filtered from the list. and `callback` needs to be called with an entry filtered from the list. Using
`event.preventDefault()` prevents the application from using the first certificate `event.preventDefault()` prevents the application from using the first
from the store. certificate from the store.
### Event: 'gpu-process-crashed' ### Event: 'gpu-process-crashed'
Emitted when the gpu process crashes. 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 windows are successfully closed, the `will-quit` event will be emitted and by
default the application will terminate. default the application will terminate.
This method guarantees that all `beforeunload` and `unload` event handlers are correctly This method guarantees that all `beforeunload` and `unload` event handlers are
executed. It is possible that a window cancels the quitting by returning correctly executed. It is possible that a window cancels the quitting by
`false` in the `beforeunload` event handler. returning `false` in the `beforeunload` event handler.
## app.getAppPath() ### `app.getAppPath()`
Returns the current application directory. Returns the current application directory.
## app.getPath(name) ### `app.getPath(name)`
* `name` String * `name` String
@ -152,25 +177,25 @@ failure an `Error` is thrown.
You can request the following paths by the name: You can request the following paths by the name:
* `home`: User's home directory * `home` User's home directory.
* `appData`: Per-user application data directory, which by default points to: * `appData` Per-user application data directory, which by default points to:
* `%APPDATA%` on Windows * `%APPDATA%` on Windows
* `$XDG_CONFIG_HOME` or `~/.config` on Linux * `$XDG_CONFIG_HOME` or `~/.config` on Linux
* `~/Library/Application Support` on OS X * `~/Library/Application Support` on OS X
* `userData`: The directory for storing your app's configuration files, which by * `userData` The directory for storing your app's configuration files, which by
default it is the `appData` directory appended with your app's name default it is the `appData` directory appended with your app's name.
* `cache`: Per-user application cache directory, which by default points to: * `cache` Per-user application cache directory, which by default points to:
* `%APPDATA%` on Windows (which doesn't have a universal cache location) * `%APPDATA%` on Windows (which doesn't have a universal cache location)
* `$XDG_CACHE_HOME` or `~/.cache` on Linux * `$XDG_CACHE_HOME` or `~/.cache` on Linux
* `~/Library/Caches` on OS X * `~/Library/Caches` on OS X
* `userCache`: The directory for placing your app's caches, by default it is the * `userCache` The directory for placing your app's caches, by default it is the
`cache` directory appended with your app's name `cache` directory appended with your app's name.
* `temp`: Temporary directory * `temp` Temporary directory.
* `userDesktop`: The current user's Desktop directory * `userDesktop` The current user's Desktop directory.
* `exe`: The current executable file * `exe` The current executable file.
* `module`: The `libchromiumcontent` library * `module` The `libchromiumcontent` library.
## app.setPath(name, path) ### `app.setPath(name, path)`
* `name` String * `name` String
* `path` 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 the path specifies a directory that does not exist, the directory will be
created by this method. On failure an `Error` is thrown. 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 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. `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 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 application's `package.json` file, the version of the current bundle or
returned. executable is returned.
## app.getName() ### `app.getName()`
Returns the current application's name, which is the name in the application's Returns the current application's name, which is the name in the application's
`package.json` file. `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 field, which is your application's full capitalized name, and which will be
preferred over `name` by Electron. preferred over `name` by Electron.
## app.resolveProxy(url, callback) ### `app.resolveProxy(url, callback)`
* `url` URL * `url` URL
* `callback` Function * `callback` Function
@ -209,7 +234,7 @@ preferred over `name` by Electron.
Resolves the proxy information for `url`. The `callback` will be called with Resolves the proxy information for `url`. The `callback` will be called with
`callback(proxy)` when the request is performed. `callback(proxy)` when the request is performed.
## app.addRecentDocument(path) ### `app.addRecentDocument(path)`
* `path` String * `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 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. bar, and on OS X you can visit it from dock menu.
## app.clearRecentDocuments() ### `app.clearRecentDocuments()`
Clears the recent documents list. Clears the recent documents list.
## app.setUserTasks(tasks) ### `app.setUserTasks(tasks)` _Windows_
* `tasks` Array - Array of `Task` objects * `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: `tasks` is an array of `Task` objects in following format:
* `Task` Object `Task` Object
* `program` String - Path of the program to execute, usually you should * `program` String - Path of the program to execute, usually you should
specify `process.execPath` which opens the current program specify `process.execPath` which opens the current program.
* `arguments` String - The command line arguments when `program` is * `arguments` String - The command line arguments when `program` is
executed executed.
* `title` String - The string to be displayed in a JumpList * `title` String - The string to be displayed in a JumpList.
* `description` String - Description of this task * `description` String - Description of this task.
* `iconPath` String - The absolute path to an icon to be displayed in a * `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 JumpList, which can be an arbitrary resource file that contains an icon. You
usually specify `process.execPath` to show the icon of the program 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 * `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 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 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 **Note:** This will not affect `process.argv`, and is mainly used by developers
to control some low-level Chromium behaviors. 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`. **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` `informational`
When `critical` is passed, the dock icon will bounce until either the When `critical` is passed, the dock icon will bounce until either the
application becomes active or the request is canceled. application becomes active or the request is canceled.
When `informational` is passed, the dock icon will bounce for one second. However, When `informational` is passed, the dock icon will bounce for one second.
the request remains active until either the application becomes active or However, the request remains active until either the application becomes active
the request is canceled. 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)` _OS X_
## app.dock.cancelBounce(id)
* `id` Integer * `id` Integer
Cancel the bounce of `id`. Cancel the bounce of `id`.
**Note:** This API is only available on OS X. ### `app.dock.setBadge(text)` _OS X_
## app.dock.setBadge(text)
* `text` String * `text` String
Sets the string to be displayed in the dock’s badging area. Sets the string to be displayed in the dock’s badging area.
**Note:** This API is only available on OS X. ### `app.dock.getBadge()` _OS X_
## app.dock.getBadge()
Returns the badge string of the dock. Returns the badge string of the dock.
**Note:** This API is only available on OS X. ### `app.dock.hide()` _OS X_
## app.dock.hide()
Hides the dock icon. Hides the dock icon.
**Note:** This API is only available on OS X. ### `app.dock.show()` _OS X_
## app.dock.show()
Shows the dock icon. Shows the dock icon.
**Note:** This API is only available on OS X. ### `app.dock.setMenu(menu)` _OS X_
## app.dock.setMenu(menu)
* `menu` Menu * `menu` Menu
Sets the application's [dock menu][dock-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 [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 [tasks]:http://msdn.microsoft.com/en-us/library/windows/desktop/dd378460(v=vs.85).aspx#tasks

32
docs/api/auto-updater.md
View file

@ -1,4 +1,4 @@
# auto-updater # autoUpdater
**This module has only been implemented for OS X.** **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. `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 * `event` Event
* `message` String * `message` String
Emitted when there is an error while updating. Emitted when there is an error while updating.
## Event: checking-for-update ### Event: 'checking-for-update'
Emitted when checking if an update has started. 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 Emitted when there is an available update. The update is downloaded
automatically. automatically.
## Event: update-not-available ### Event: 'update-not-available'
Emitted when there is no available update. Emitted when there is no available update.
## Event: update-downloaded ### Event: 'update-downloaded'
Returns:
* `event` Event * `event` Event
* `releaseNotes` String * `releaseNotes` String
@ -127,17 +135,21 @@ Emitted when there is no available update.
* `updateUrl` String * `updateUrl` String
* `quitAndUpdate` Function * `quitAndUpdate` Function
Emitted when an update has been downloaded. Calling `quitAndUpdate()` will restart Emitted when an update has been downloaded. Calling `quitAndUpdate()` will
the application and install the update. restart the application and install the update.
## autoUpdater.setFeedUrl(url) ## Methods
The `autoUpdater` object has the following methods:
### `autoUpdater.setFeedUrl(url)`
* `url` String * `url` String
Set the `url` and initialize the auto updater. The `url` cannot be changed Set the `url` and initialize the auto updater. The `url` cannot be changed
once it is set. once it is set.
## autoUpdater.checkForUpdates() ### `autoUpdater.checkForUpdates()`
Ask the server whether there is an update. You must call `setFeedUrl` before Ask the server whether there is an update. You must call `setFeedUrl` before
using this API. using this API.

78
docs/styleguide.md Normal file
View 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)
})
```