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

Specifiy function param types in docs

Browse source
This commit is contained in:
Samuel Attard 2016-10-13 17:30:57 +11:00
parent 7584e73d70
commit 20323e7032
No known key found for this signature in database
GPG key ID: 273DC1869D8F13EF
13 changed files with 226 additions and 133 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docs/api/app.md
View file

@ -193,6 +193,7 @@ Returns:
* `validExpiry` Integer - End date of the certificate being valid in seconds
* `fingerprint` String - Fingerprint of the certificate
* `callback` Function
* `isTrusted` Boolean - Whether to consider the certificate as trusted
Emitted when failed to verify the `certificate` for `url`, to trust the
certificate you should prevent the default behavior with
@ -221,6 +222,7 @@ Returns:
* `url` URL
* `certificateList` [Certificate[]](structures/certificate.md)
* `callback` Function
* `certificate` [Certificate](structures/certificate.md)
Emitted when a client certificate is requested.
@ -255,6 +257,8 @@ Returns:
* `port` Integer
* `realm` String
* `callback` Function
* `username` String
* `password` String
Emitted when `webContents` wants to do basic auth.
@ -696,6 +700,8 @@ app.setJumpList([
### `app.makeSingleInstance(callback)`
* `callback` Function
* `argv` String[] - An array of the second instance's command line arguments
* `workingDirectory` String - The second instance's working directory
This method makes your application a Single Instance Application - instead of
allowing multiple instances of your app to run, this will ensure that only a

1
docs/api/browser-window.md
View file

@ -950,6 +950,7 @@ Whether `Boolean` - Whether the window's document has been edited.
* `rect` [Rectangle](structures/rectangle.md) (optional) - The bounds to capture
* `callback` Function
* `image` [NativeImage](native-image.md)
Same as `webContents.capturePage([rect, ]callback)`.

5
docs/api/content-tracing.md
View file

@ -33,6 +33,7 @@ The `contentTracing` module has the following methods:
### `contentTracing.getCategories(callback)`
* `callback` Function
* `categories` String[]
Get a set of category groups. The category groups can change as new code paths
are reached.
@ -86,6 +87,7 @@ before options parsed from `traceOptions` are applied on it.
* `resultFilePath` String
* `callback` Function
* `resultFilePath` String
Stop recording on all processes.
@ -130,6 +132,7 @@ Once all child processes have acknowledged the `stopMonitoring` request the
* `resultFilePath` String
* `callback` Function
* `resultFilePath`
Get the current monitoring traced data.
@ -146,6 +149,8 @@ request the `callback` will be called with a file that contains the traced data.
### `contentTracing.getTraceBufferUsage(callback)`
* `callback` Function
* `value` Number
* `percentage` Number
Get the maximum usage across processes of trace buffer as a percentage of the
full state. When the TraceBufferUsage value is determined the `callback` is

21
docs/api/desktop-capturer.md
View file

@ -61,25 +61,14 @@ The `desktopCapturer` module has the following methods:
* `thumbnailSize` Object (optional) - The suggested size that the media source
thumbnail should be scaled to, defaults to `{width: 150, height: 150}`.
* `callback` Function
* `error` Error
* `sources` [DesktopCapturerSource[]](structures/desktop-capturer-source.md)
Starts gathering information about all available desktop media sources,
and calls `callback(error, sources)` when finished.
`sources` is an array of `Source` objects, each `Source` represents a
screen or an individual window that can be captured, and has the following
properties:
* `id` String - The identifier of a window or screen that can be used as a
`chromeMediaSourceId` constraint when calling
[`navigator.webkitGetUserMedia`]. The format of the identifier will be
`window:XX` or `screen:XX`, where `XX` is a random generated number.
* `name` String - A screen source will be named either `Entire Screen` or
`Screen <index>`, while the name of a window source will match the window
title.
* `thumbnail` [NativeImage](native-image.md) - A thumbnail image. **Note:**
There is no guarantee that the size of the thumbnail is the same as the
`thumnbailSize` specified in the `options` passed to
`desktopCapturer.getSources`. The actual size depends on the scale of the
screen or window.
`sources` is an array of [`DesktopCapturerSource`](structures/desktop-capturer-source.md)
objects, each `Source` represents a screen or an individual window that can be
captured.
[`navigator.webkitGetUserMedia`]: https://developer.mozilla.org/en/docs/Web/API/Navigator/getUserMedia

3
docs/api/dialog.md
View file

@ -34,6 +34,7 @@ The `dialog` module has the following methods:
contain `openFile`, `openDirectory`, `multiSelections`, `createDirectory`
and `showHiddenFiles`.
* `callback` Function (optional)
* `filePaths` String[] - An array of file paths chosen by the user
On success this method returns an array of file paths chosen by the user,
otherwise it returns `undefined`.
@ -74,6 +75,7 @@ shown.
left empty the default label will be used.
* `filters` String[]
* `callback` Function (optional)
* `filename` String
On success this method returns the path of the file chosen by the user,
otherwise it returns `undefined`.
@ -110,6 +112,7 @@ will be passed via `callback(filename)`
the style of modern Windows apps. If you don't like this behavior, you can
set `noLink` to `true`.
* `callback` Function
* `response` Number - The index of the button that was clicked
Shows a message box, it will block the process until the message box is closed.
It returns the index of the clicked button.

3
docs/api/menu-item.md
View file

@ -13,6 +13,9 @@ Create a new `MenuItem` with the following method:
* `options` Object
* `click` Function - Will be called with
`click(menuItem, browserWindow, event)` when the menu item is clicked.
* `menuItem` MenuItem
* `browserWindow` BrowserWindow
* `event` Event
* `role` String - Define the action of the menu item, when specified the
`click` property will be ignored.
* `type` String - Can be `normal`, `separator`, `submenu`, `checkbox` or

107
docs/api/protocol.md
View file

@ -76,7 +76,15 @@ module gets emitted.
* `scheme` String
* `handler` Function
* `request` Object
* `url` String
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `filePath` String (optional)
* `completion` Function (optional)
* `error` Error
Registers a protocol of `scheme` that will send the file as a response. The
`handler` will be called with `handler(request, callback)` when a `request` is
@ -84,21 +92,6 @@ going to be created with `scheme`. `completion` will be called with
`completion(null)` when `scheme` is successfully registered or
`completion(error)` when failed.
* `request` Object
* `url` String
* `referrer` String
* `method` String
* `uploadData` Array (optional)
* `callback` Function
The `uploadData` is an array of `data` objects:
* `data` Object
* `bytes` Buffer - Content being sent.
* `file` String - Path of file being uploaded.
* `blobUUID` String - UUID of blob data. Use [ses.getBlobData](session.md#sesgetblobdataidentifier-callback) method
to retrieve the data.
To handle the `request`, the `callback` should be called with either the file's
path or an object that has a `path` property, e.g. `callback(filePath)` or
`callback({path: filePath})`.
@ -117,7 +110,15 @@ treated as a standard scheme.
* `scheme` String
* `handler` Function
* `request` Object
* `url` String
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `buffer` Buffer (optional)
* `completion` Function (optional)
* `error` Error
Registers a protocol of `scheme` that will send a `Buffer` as a response.
@ -141,7 +142,15 @@ protocol.registerBufferProtocol('atom', (request, callback) => {
* `scheme` String
* `handler` Function
* `request` Object
* `url` String
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `data` String (optional)
* `completion` Function (optional)
* `error` Error
Registers a protocol of `scheme` that will send a `String` as a response.
@ -153,7 +162,21 @@ should be called with either a `String` or an object that has the `data`,
* `scheme` String
* `handler` Function
* `request` Object
* `url` String
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `redirectRequest` Object
* `url` String
* `method` String
* `session` Object (optional)
* `uploadData` Object (optional)
* `contentType` String - MIME type of the content.
* `data` String - Content to be sent.
* `completion` Function (optional)
* `error` Error
Registers a protocol of `scheme` that will send an HTTP request as a response.
@ -161,25 +184,16 @@ The usage is the same with `registerFileProtocol`, except that the `callback`
should be called with a `redirectRequest` object that has the `url`, `method`,
`referrer`, `uploadData` and `session` properties.
* `redirectRequest` Object
* `url` String
* `method` String
* `session` Object (optional)
* `uploadData` Object (optional)
By default the HTTP request will reuse the current session. If you want the
request to have a different session you should set `session` to `null`.
For POST requests the `uploadData` object must be provided.
* `uploadData` object
* `contentType` String - MIME type of the content.
* `data` String - Content to be sent.
### `protocol.unregisterProtocol(scheme[, completion])`
* `scheme` String
* `completion` Function (optional)
* `error` Error
Unregisters the custom protocol of `scheme`.
@ -187,6 +201,7 @@ Unregisters the custom protocol of `scheme`.
* `scheme` String
* `callback` Function
* `error` Error
The `callback` will be called with a boolean that indicates whether there is
already a handler for `scheme`.
@ -195,7 +210,15 @@ already a handler for `scheme`.
* `scheme` String
* `handler` Function
* `request` Object
* `url` String
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `filePath` String
* `completion` Function (optional)
* `error` Error
Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
which sends a file as a response.
@ -204,7 +227,15 @@ which sends a file as a response.
* `scheme` String
* `handler` Function
* `request` Object
* `url` String
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `data` String (optional)
* `completion` Function (optional)
* `error` Error
Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
which sends a `String` as a response.
@ -213,7 +244,15 @@ which sends a `String` as a response.
* `scheme` String
* `handler` Function
* `request` Object
* `url` String
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `buffer` Buffer (optional)
* `completion` Function (optional)
* `error` Error
Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
which sends a `Buffer` as a response.
@ -222,7 +261,21 @@ which sends a `Buffer` as a response.
* `scheme` String
* `handler` Function
* `request` Object
* `url` String
* `referrer` String
* `method` String
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `redirectRequest` Object
* `url` String
* `method` String
* `session` Object (optional)
* `uploadData` Object (optional)
* `contentType` String - MIME type of the content.
* `data` String - Content to be sent.
* `completion` Function (optional)
* `error` Error
Intercepts `scheme` protocol and uses `handler` as the protocol's new handler
which sends a new HTTP request as a response.
@ -230,7 +283,9 @@ which sends a new HTTP request as a response.
### `protocol.uninterceptProtocol(scheme[, completion])`
* `scheme` String
* `completion` Function
* `completion` Function (optional)
* `error` Error
Remove the interceptor installed for `scheme` and restore its original handler.

172
docs/api/session.md
View file

@ -200,6 +200,7 @@ The `proxyBypassRules` is a comma separated list of rules described below:
* `url` URL
* `callback` Function
* `proxy` Object
Resolves the proxy information for `url`. The `callback` will be called with
`callback(proxy)` when the request is performed.
@ -245,6 +246,10 @@ the original network configuration.
#### `ses.setCertificateVerifyProc(proc)`
* `proc` Function
* `hostname` String
* `certificate` [Certificate](structures/certificate.md)
* `callback` Function
* `isTrusted` Boolean - Determines if the certificate should be trusted
Sets the certificate verify proc for `session`, the `proc` will be called with
`proc(hostname, certificate, callback)` whenever a server certificate
@ -269,7 +274,8 @@ win.webContents.session.setCertificateVerifyProc((hostname, cert, callback) => {
* `webContents` Object - [WebContents](web-contents.md) requesting the permission.
* `permission` String - Enum of 'media', 'geolocation', 'notifications', 'midiSysex',
'pointerLock', 'fullscreen', 'openExternal'.
* `callback` Function - Allow or deny the permission.
* `callback` Function
* `permissionGranted` Boolean - Allow or deny the permission
Sets the handler which can be used to respond to permission requests for the `session`.
Calling `callback(true)` will allow the permission and `callback(false)` will reject it.
@ -432,6 +438,8 @@ The following methods are available on instances of `Cookies`:
* `secure` Boolean (optional) - Filters cookies by their Secure property.
* `session` Boolean (optional) - Filters out session or persistent cookies.
* `callback` Function
* `error` Error
* `cookies` Cookies[]
Sends a request to get all cookies matching `details`, `callback` will be called
with `callback(error, cookies)` on complete.
@ -468,6 +476,7 @@ with `callback(error, cookies)` on complete.
seconds since the UNIX epoch. If omitted then the cookie becomes a session
cookie and will not be retained between sessions.
* `callback` Function
* `error` Error
Sets a cookie with `details`, `callback` will be called with `callback(error)`
on complete.
@ -524,34 +533,26 @@ The following methods are available on instances of `WebRequest`:
* `filter` Object
* `listener` Function
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `uploadData` [UploadData[]](structures/upload-data.md)
* `callback` Function
* `response` Object
* `cancel` Boolean (optional)
* `redirectURL` String (optional) - The original request is prevented from
being sent or completed and is instead redirected to the given URL.
The `listener` will be called with `listener(details, callback)` when a request
is about to occur.
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `uploadData` Array (optional)
* `callback` Function
The `uploadData` is an array of `data` objects:
* `data` Object
* `bytes` Buffer - Content being sent.
* `file` String - Path of file being uploaded.
* `blobUUID` String - UUID of blob data. Use [ses.getBlobData](session.md#sesgetblobdataidentifier-callback) method
to retrieve the data.
The `uploadData` is an array of `UploadData` objects:
The `callback` has to be called with an `response` object:
* `response` Object
* `cancel` Boolean (optional)
* `redirectURL` String (optional) - The original request is prevented from
being sent or completed, and is instead redirected to the given URL.
#### `webRequest.onBeforeSendHeaders([filter, ]listener)`
* `filter` Object
@ -569,31 +570,29 @@ TCP connection is made to the server, but before any http data is sent.
* `timestamp` Double
* `requestHeaders` Object
* `callback` Function
* `response` Object
* `cancel` Boolean (optional)
* `requestHeaders` Object (optional) - When provided, request will be made
with these headers.
The `callback` has to be called with an `response` object:
* `response` Object
* `cancel` Boolean (optional)
* `requestHeaders` Object (optional) - When provided, request will be made
with these headers.
#### `webRequest.onSendHeaders([filter, ]listener)`
* `filter` Object
* `listener` Function
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `requestHeaders` Object
The `listener` will be called with `listener(details)` just before a request is
going to be sent to the server, modifications of previous `onBeforeSendHeaders`
response are visible by the time this listener is fired.
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `requestHeaders` Object
#### `webRequest.onHeadersReceived([filter, ]listener)`
* `filter` Object
@ -612,90 +611,85 @@ response headers of a request have been received.
* `statusCode` Integer
* `responseHeaders` Object
* `callback` Function
* `response` Object
* `cancel` Boolean
* `responseHeaders` Object (optional) - When provided, the server is assumed
to have responded with these headers.
* `statusLine` String (optional) - Should be provided when overriding
`responseHeaders` to change header status otherwise original response
header's status will be used.
The `callback` has to be called with an `response` object:
* `response` Object
* `cancel` Boolean
* `responseHeaders` Object (optional) - When provided, the server is assumed
to have responded with these headers.
* `statusLine` String (optional) - Should be provided when overriding
`responseHeaders` to change header status otherwise original response
header's status will be used.
The `callback` has to be called with an `response` object.
#### `webRequest.onResponseStarted([filter, ]listener)`
* `filter` Object
* `listener` Function
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `responseHeaders` Object
* `fromCache` Boolean - Indicates whether the response was fetched from disk
cache.
* `statusCode` Integer
* `statusLine` String
The `listener` will be called with `listener(details)` when first byte of the
response body is received. For HTTP requests, this means that the status line
and response headers are available.
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `responseHeaders` Object
* `fromCache` Boolean - Indicates whether the response was fetched from disk
cache.
* `statusCode` Integer
* `statusLine` String
#### `webRequest.onBeforeRedirect([filter, ]listener)`
* `filter` Object
* `listener` Function
* `details` Object
* `id` String
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `redirectURL` String
* `statusCode` Integer
* `ip` String (optional) - The server IP address that the request was
actually sent to.
* `fromCache` Boolean
* `responseHeaders` Object
The `listener` will be called with `listener(details)` when a server initiated
redirect is about to occur.
* `details` Object
* `id` String
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `redirectURL` String
* `statusCode` Integer
* `ip` String (optional) - The server IP address that the request was
actually sent to.
* `fromCache` Boolean
* `responseHeaders` Object
#### `webRequest.onCompleted([filter, ]listener)`
* `filter` Object
* `listener` Function
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `responseHeaders` Object
* `fromCache` Boolean
* `statusCode` Integer
* `statusLine` String
The `listener` will be called with `listener(details)` when a request is
completed.
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `responseHeaders` Object
* `fromCache` Boolean
* `statusCode` Integer
* `statusLine` String
#### `webRequest.onErrorOccurred([filter, ]listener)`
* `filter` Object
* `listener` Function
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `fromCache` Boolean
* `error` String - The error description.
The `listener` will be called with `listener(details)` when an error occurs.
* `details` Object
* `id` Integer
* `url` String
* `method` String
* `resourceType` String
* `timestamp` Double
* `fromCache` Boolean
* `error` String - The error description.

14
docs/api/structures/desktop-capturer-source.md Normal file
View file

@ -0,0 +1,14 @@
# Desktop Capturer Source Object
* `id` String - The identifier of a window or screen that can be used as a
`chromeMediaSourceId` constraint when calling
[`navigator.webkitGetUserMedia`]. The format of the identifier will be
`window:XX` or `screen:XX`, where `XX` is a random generated number.
* `name` String - A screen source will be named either `Entire Screen` or
`Screen <index>`, while the name of a window source will match the window
title.
* `thumbnail` [NativeImage](../native-image.md) - A thumbnail image. **Note:**
There is no guarantee that the size of the thumbnail is the same as the
`thumnbailSize` specified in the `options` passed to
`desktopCapturer.getSources`. The actual size depends on the scale of the
screen or window.

6
docs/api/structures/upload-data.md Normal file
View file

@ -0,0 +1,6 @@
# ThumbarButton Object
* `bytes` Buffer - Content being sent.
* `file` String - Path of file being uploaded.
* `blobUUID` String - UUID of blob data. Use [ses.getBlobData](../session.md#sesgetblobdataidentifier-callback) method
to retrieve the data.

4
docs/api/system-preferences.md
View file

@ -63,6 +63,8 @@ that contains the user information dictionary sent along with the notification.
* `event` String
* `callback` Function
* `event` String
* `userInfo` Object
Subscribes to native notifications of macOS, `callback` will be called with
`callback(event, userInfo)` when the corresponding `event` happens. The
@ -90,6 +92,8 @@ Removes the subscriber with `id`.
* `event` String
* `callback` Function
* `event` String
* `userInfo` Object
Same as `subscribeNotification`, but uses `NSNotificationCenter` for local defaults.
This is necessary for events such as `NSUserDefaultsDidChangeNotification`

15
docs/api/web-contents.md
View file

@ -249,6 +249,7 @@ Returns:
* `error` String - The error code
* `certificate` [Certificate](structures/certificate.md)
* `callback` Function
* `isTrusted` Boolean - Indicates whether the certificate can be considered trusted
Emitted when failed to verify the `certificate` for `url`.
@ -263,6 +264,7 @@ Returns:
* `url` URL
* `certificateList` Certificate[]
* `callback` Function
* `certificate` [Certificate](structures/certificate.md) - Must be a certificate from the given list
Emitted when a client certificate is requested.
@ -285,6 +287,8 @@ Returns:
* `port` Integer
* `realm` String
* `callback` Function
* `username` String
* `password` String
Emitted when `webContents` wants to do basic auth.
@ -622,7 +626,7 @@ Injects CSS into the current web page.
* `code` String
* `userGesture` Boolean (optional)
* `callback` Function (optional) - Called after script has been executed.
* `result`
* `result` Any
Evaluates `code` in page.
@ -650,6 +654,7 @@ zoom percent divided by 100, so 300% = 3.0.
#### `contents.getZoomFactor(callback)`
* `callback` Function
* `zoomFactor` Number
Sends a request to get current zoom factor, the `callback` will be called with
`callback(zoomFactor)`.
@ -665,6 +670,7 @@ limits of 300% and 50% of original size, respectively.
#### `contents.getZoomLevel(callback)`
* `callback` Function
* `zoomLevel` Number
Sends a request to get current zoom level, the `callback` will be called with
`callback(zoomLevel)`.
@ -782,6 +788,7 @@ console.log(requestId)
* `rect` [Rectangle](structures/rectangle.md) (optional) - The area of the page to be captured
* `callback` Function
* `image` [NativeImage](native-image.md)
Captures a snapshot of the page within `rect`. Upon completion `callback` will
be called with `callback(image)`. The `image` is an instance of
@ -791,6 +798,7 @@ be called with `callback(image)`. The `image` is an instance of
#### `contents.hasServiceWorker(callback)`
* `callback` Function
* `hasWorker` Boolean
Checks if any ServiceWorker is registered and returns a boolean as
response to `callback`.
@ -798,6 +806,7 @@ response to `callback`.
#### `contents.unregisterServiceWorker(callback)`
* `callback` Function
* `success` Boolean
Unregisters any ServiceWorker if present and returns a boolean as
response to `callback` when the JS promise is fulfilled or false
@ -830,6 +839,8 @@ Use `page-break-before: always; ` CSS style to force to print to a new page.
* `printSelectionOnly` Boolean - Whether to print selection only.
* `landscape` Boolean - `true` for landscape, `false` for portrait.
* `callback` Function
* `error` Error
* `data` Buffer
Prints window's web page as PDF with Chromium's preview printing custom
settings.
@ -1047,6 +1058,8 @@ For the `mouseWheel` event, the `event` object also have following properties:
* `onlyDirty` Boolean (optional) - Defaults to `false`
* `callback` Function
* `frameBuffer` Buffer
* `dirtyRect` [Rectangle](structures/rectangle.md)
Begin subscribing for presentation events and captured frames, the `callback`
will be called with `callback(frameBuffer, dirtyRect)` when there is a

2
docs/api/web-view-tag.md
View file

@ -347,7 +347,7 @@ Injects CSS into the guest page.
* `code` String
* `userGesture` Boolean - Default `false`.
* `callback` Function (optional) - Called after script has been executed.
* `result`
* `result` Any
Evaluates `code` in page. If `userGesture` is set, it will create the user
gesture context in the page. HTML APIs like `requestFullScreen`, which require