diff --git a/docs/api/app.md b/docs/api/app.md index 8223643a375..db34d37ec59 100644 --- a/docs/api/app.md +++ b/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 diff --git a/docs/api/auto-updater.md b/docs/api/auto-updater.md index 5274fc6c467..4e1dc5e0deb 100644 --- a/docs/api/auto-updater.md +++ b/docs/api/auto-updater.md @@ -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. diff --git a/docs/styleguide.md b/docs/styleguide.md new file mode 100644 index 00000000000..23c590e6421 --- /dev/null +++ b/docs/styleguide.md @@ -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) +}) +```