From b084dc29ea2012381f9b307c8dfc402b4a2d7519 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Thu, 10 Nov 2016 12:25:26 -0800 Subject: [PATCH 1/9] move each API doc into its own file --- docs/api/browser-window-proxy.md | 53 ++++++ docs/api/client-request.md | 192 +++++++++++++++++++ docs/api/cookies.md | 106 +++++++++++ docs/api/debugger.md | 83 ++++++++ docs/api/incoming-message.md | 66 +++++++ docs/api/net.md | 269 +------------------------- docs/api/session.md | 313 ------------------------------- docs/api/web-contents.md | 88 +-------- docs/api/web-request.md | 205 ++++++++++++++++++++ docs/api/window-open.md | 54 ------ 10 files changed, 711 insertions(+), 718 deletions(-) create mode 100644 docs/api/browser-window-proxy.md create mode 100644 docs/api/client-request.md create mode 100644 docs/api/cookies.md create mode 100644 docs/api/debugger.md create mode 100644 docs/api/incoming-message.md create mode 100644 docs/api/web-request.md diff --git a/docs/api/browser-window-proxy.md b/docs/api/browser-window-proxy.md new file mode 100644 index 000000000000..a6d57299cfd7 --- /dev/null +++ b/docs/api/browser-window-proxy.md @@ -0,0 +1,53 @@ +## Class: BrowserWindowProxy + +> Manipulate the child browser window + +Process: [Renderer](../tutorial/quick-start.md#renderer-process) + +The `BrowserWindowProxy` object is returned from `window.open` and provides +limited functionality with the child window. + +### Instance Methods + +The `BrowserWindowProxy` object has the following instance methods: + +#### `win.blur()` + +Removes focus from the child window. + +#### `win.close()` + +Forcefully closes the child window without calling its unload event. + +#### `win.eval(code)` + +* `code` String + +Evaluates the code in the child window. + +#### `win.focus()` + +Focuses the child window (brings the window to front). + +#### `win.print()` + +Invokes the print dialog on the child window. + +#### `win.postMessage(message, targetOrigin)` + +* `message` String +* `targetOrigin` String + +Sends a message to the child window with the specified origin or `*` for no +origin preference. + +In addition to these methods, the child window implements `window.opener` object +with no properties and a single method. + +### Instance Properties + +The `BrowserWindowProxy` object has the following instance properties: + +#### `win.closed` + +A Boolean that is set to true after the child window gets closed. diff --git a/docs/api/client-request.md b/docs/api/client-request.md new file mode 100644 index 000000000000..bcde94dd8d8a --- /dev/null +++ b/docs/api/client-request.md @@ -0,0 +1,192 @@ +## Class: ClientRequest + +> Make HTTP/HTTPS requests. + +Process: [Main](../tutorial/quick-start.md#main-process) + +`ClientRequest` implements the [Writable Stream](https://nodejs.org/api/stream.html#stream_writable_streams) +interface and is therefore an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter). + +### `new ClientRequest(options)` + +* `options` (Object | String) - If `options` is a String, it is interpreted as +the request URL. If it is an object, it is expected to fully specify an HTTP request via the +following properties: + * `method` String (optional) - The HTTP request method. Defaults to the GET +method. + * `url` String (optional) - The request URL. Must be provided in the absolute +form with the protocol scheme specified as http or https. + * `session` Object (optional) - The [`Session`](session.md) instance with +which the request is associated. + * `partition` String (optional) - The name of the [`partition`](session.md) + with which the request is associated. Defaults to the empty string. The +`session` option prevails on `partition`. Thus if a `session` is explicitly +specified, `partition` is ignored. + * `protocol` String (optional) - The protocol scheme in the form 'scheme:'. +Currently supported values are 'http:' or 'https:'. Defaults to 'http:'. + * `host` String (optional) - The server host provided as a concatenation of +the hostname and the port number 'hostname:port' + * `hostname` String (optional) - The server host name. + * `port` Integer (optional) - The server's listening port number. + * `path` String (optional) - The path part of the request URL. + +`options` properties such as `protocol`, `host`, `hostname`, `port` and `path` +strictly follow the Node.js model as described in the +[URL](https://nodejs.org/api/url.html) module. + +For instance, we could have created the same request to 'github.com' as follows: + +```JavaScript +const request = net.request({ + method: 'GET', + protocol: 'https:', + hostname: 'github.com', + port: 443, + path: '/' +}) +``` + +### Instance Events + +#### Event: 'response' + +Returns: + +* `response` IncomingMessage - An object representing the HTTP response message. + +#### Event: 'login' + +Returns: + +* `authInfo` Object + * `isProxy` Boolean + * `scheme` String + * `host` String + * `port` Integer + * `realm` String +* `callback` Function + +Emitted when an authenticating proxy is asking for user credentials. + +The `callback` function is expected to be called back with user credentials: + +* `username` String +* `password` String + +```JavaScript +request.on('login', (authInfo, callback) => { + callback('username', 'password') +}) +``` +Providing empty credentials will cancel the request and report an authentication +error on the response object: + +```JavaScript +request.on('response', (response) => { + console.log(`STATUS: ${response.statusCode}`); + response.on('error', (error) => { + console.log(`ERROR: ${JSON.stringify(error)}`) + }) +}) +request.on('login', (authInfo, callback) => { + callback() +}) +``` + +#### Event: 'finish' + +Emitted just after the last chunk of the `request`'s data has been written into +the `request` object. + +#### Event: 'abort' + +Emitted when the `request` is aborted. The `abort` event will not be fired if +the `request` is already closed. + +#### Event: 'error' + +Returns: + +* `error` Error - an error object providing some information about the failure. + +Emitted when the `net` module fails to issue a network request. Typically when +the `request` object emits an `error` event, a `close` event will subsequently +follow and no response object will be provided. + +#### Event: 'close' + +Emitted as the last event in the HTTP request-response transaction. The `close` +event indicates that no more events will be emitted on either the `request` or +`response` objects. + +### Instance Properties + +#### `request.chunkedEncoding` + +A Boolean specifying whether the request will use HTTP chunked transfer encoding +or not. Defaults to false. The property is readable and writable, however it can +be set only before the first write operation as the HTTP headers are not yet put +on the wire. Trying to set the `chunkedEncoding` property after the first write +will throw an error. + +Using chunked encoding is strongly recommended if you need to send a large +request body as data will be streamed in small chunks instead of being +internally buffered inside Electron process memory. + +### Instance Methods + +#### `request.setHeader(name, value)` + +* `name` String - An extra HTTP header name. +* `value` String - An extra HTTP header value. + +Adds an extra HTTP header. The header name will issued as it is without +lowercasing. It can be called only before first write. Calling this method after +the first write will throw an error. + +#### `request.getHeader(name)` + +* `name` String - Specify an extra header name. + +Returns String - The value of a previously set extra header name. + +#### `request.removeHeader(name)` + +* `name` String - Specify an extra header name. + +Removes a previously set extra header name. This method can be called only +before first write. Trying to call it after the first write will throw an error. + +#### `request.write(chunk[, encoding][, callback])` + +* `chunk` (String | Buffer) - A chunk of the request body's data. If it is a +string, it is converted into a Buffer using the specified encoding. +* `encoding` String (optional) - Used to convert string chunks into Buffer +objects. Defaults to 'utf-8'. +* `callback` Function (optional) - Called after the write operation ends. + +`callback` is essentially a dummy function introduced in the purpose of keeping +similarity with the Node.js API. It is called asynchronously in the next tick +after `chunk` content have been delivered to the Chromium networking layer. +Contrary to the Node.js implementation, it is not guaranteed that `chunk` +content have been flushed on the wire before `callback` is called. + +Adds a chunk of data to the request body. The first write operation may cause +the request headers to be issued on the wire. After the first write operation, +it is not allowed to add or remove a custom header. + +#### `request.end([chunk][, encoding][, callback])` + +* `chunk` (String | Buffer) (optional) +* `encoding` String (optional) +* `callback` Function (optional) + +Sends the last chunk of the request data. Subsequent write or end operations +will not be allowed. The `finish` event is emitted just after the end operation. + +#### `request.abort()` + +Cancels an ongoing HTTP transaction. If the request has already emitted the +`close` event, the abort operation will have no effect. Otherwise an ongoing +event will emit `abort` and `close` events. Additionally, if there is an ongoing +response object,it will emit the `aborted` event. diff --git a/docs/api/cookies.md b/docs/api/cookies.md new file mode 100644 index 000000000000..37891caeb070 --- /dev/null +++ b/docs/api/cookies.md @@ -0,0 +1,106 @@ +## Class: Cookies + +> Query and modify a session's cookies. + +Process: [Main](../tutorial/quick-start.md#main-process) + +Instances of the `Cookies` class are accessed by using `cookies` property of +a `Session`. + +For example: + +```javascript +const {session} = require('electron') + +// Query all cookies. +session.defaultSession.cookies.get({}, (error, cookies) => { + console.log(error, cookies) +}) + +// Query all cookies associated with a specific url. +session.defaultSession.cookies.get({url: 'http://www.github.com'}, (error, cookies) => { + console.log(error, cookies) +}) + +// Set a cookie with the given cookie data; +// may overwrite equivalent cookies if they exist. +const cookie = {url: 'http://www.github.com', name: 'dummy_name', value: 'dummy'} +session.defaultSession.cookies.set(cookie, (error) => { + if (error) console.error(error) +}) +``` + +### Instance Events + +The following events are available on instances of `Cookies`: + +#### Event: 'changed' + +* `event` Event +* `cookie` [Cookie](structures/cookie.md) - The cookie that was changed +* `cause` String - The cause of the change with one of the following values: + * `explicit` - The cookie was changed directly by a consumer's action. + * `overwrite` - The cookie was automatically removed due to an insert + operation that overwrote it. + * `expired` - The cookie was automatically removed as it expired. + * `evicted` - The cookie was automatically evicted during garbage collection. + * `expired-overwrite` - The cookie was overwritten with an already-expired + expiration date. +* `removed` Boolean - `true` if the cookie was removed, `false` otherwise. + +Emitted when a cookie is changed because it was added, edited, removed, or +expired. + +### Instance Methods + +The following methods are available on instances of `Cookies`: + +#### `cookies.get(filter, callback)` + +* `filter` Object + * `url` String (optional) - Retrieves cookies which are associated with + `url`. Empty implies retrieving cookies of all urls. + * `name` String (optional) - Filters cookies by name. + * `domain` String (optional) - Retrieves cookies whose domains match or are + subdomains of `domains` + * `path` String (optional) - Retrieves cookies whose path matches `path`. + * `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. + +`cookies` is an Array of [`cookie`](structures/cookie.md) objects. + +#### `cookies.set(details, callback)` + +* `details` Object + * `url` String - The url to associate the cookie with. + * `name` String - The name of the cookie. Empty by default if omitted. + * `value` String - The value of the cookie. Empty by default if omitted. + * `domain` String - The domain of the cookie. Empty by default if omitted. + * `path` String - The path of the cookie. Empty by default if omitted. + * `secure` Boolean - Whether the cookie should be marked as Secure. Defaults to + false. + * `httpOnly` Boolean - Whether the cookie should be marked as HTTP only. + Defaults to false. + * `expirationDate` Double - The expiration date of the cookie as the number of + 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. + +#### `cookies.remove(url, name, callback)` + +* `url` String - The URL associated with the cookie. +* `name` String - The name of cookie to remove. +* `callback` Function + +Removes the cookies matching `url` and `name`, `callback` will called with +`callback()` on complete. diff --git a/docs/api/debugger.md b/docs/api/debugger.md new file mode 100644 index 000000000000..a0e20277c267 --- /dev/null +++ b/docs/api/debugger.md @@ -0,0 +1,83 @@ +## Class: Debugger + +> An alternate transport for Chrome's remote debugging protocol. + +Process: [Main](../tutorial/quick-start.md#main-process) + +Chrome Developer Tools has a [special binding][rdp] available at JavaScript +runtime that allows interacting with pages and instrumenting them. + +```javascript +const {BrowserWindow} = require('electron') +let win = new BrowserWindow() + +try { + win.webContents.debugger.attach('1.1') +} catch (err) { + console.log('Debugger attach failed : ', err) +} + +win.webContents.debugger.on('detach', (event, reason) => { + console.log('Debugger detached due to : ', reason) +}) + +win.webContents.debugger.on('message', (event, method, params) => { + if (method === 'Network.requestWillBeSent') { + if (params.request.url === 'https://www.github.com') { + win.webContents.debugger.detach() + } + } +}) + +win.webContents.debugger.sendCommand('Network.enable') +``` + +### Instance Methods + +#### `debugger.attach([protocolVersion])` + +* `protocolVersion` String (optional) - Requested debugging protocol version. + +Attaches the debugger to the `webContents`. + +#### `debugger.isAttached()` + +Returns `Boolean` - Whether a debugger is attached to the `webContents`. + +#### `debugger.detach()` + +Detaches the debugger from the `webContents`. + +#### `debugger.sendCommand(method[, commandParams, callback])` + +* `method` String - Method name, should be one of the methods defined by the + remote debugging protocol. +* `commandParams` Object (optional) - JSON object with request parameters. +* `callback` Function (optional) - Response + * `error` Object - Error message indicating the failure of the command. + * `result` Any - Response defined by the 'returns' attribute of + the command description in the remote debugging protocol. + +Send given command to the debugging target. + +### Instance Events + +#### Event: 'detach' + +* `event` Event +* `reason` String - Reason for detaching debugger. + +Emitted when debugging session is terminated. This happens either when +`webContents` is closed or devtools is invoked for the attached `webContents`. + +#### Event: 'message' + +* `event` Event +* `method` String - Method name. +* `params` Object - Event parameters defined by the 'parameters' + attribute in the remote debugging protocol. + +Emitted whenever debugging target issues instrumentation event. + +[rdp]: https://developer.chrome.com/devtools/docs/debugger-protocol +[`webContents.findInPage`]: web-contents.md#contentsfindinpagetext-options diff --git a/docs/api/incoming-message.md b/docs/api/incoming-message.md new file mode 100644 index 000000000000..345658e04289 --- /dev/null +++ b/docs/api/incoming-message.md @@ -0,0 +1,66 @@ +## Class: IncomingMessage + +> Handle responses to HTTP/HTTPS requests. + +Process: [Main](../tutorial/quick-start.md#main-process) + +`IncomingMessage` implements the [Readable Stream](https://nodejs.org/api/stream.html#stream_readable_streams) +interface and is therefore an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter). + +### Instance Events + +#### Event: 'data' + +Returns: + +* `chunk` Buffer - A chunk of response body's data. + +The `data` event is the usual method of transferring response data into +applicative code. + +#### Event: 'end' + +Indicates that response body has ended. + +#### Event: 'aborted' + +Emitted when a request has been canceled during an ongoing HTTP transaction. + +#### Event: 'error' + +Returns: + +`error` Error - Typically holds an error string identifying failure root cause. + +Emitted when an error was encountered while streaming response data events. For +instance, if the server closes the underlying while the response is still +streaming, an `error` event will be emitted on the response object and a `close` +event will subsequently follow on the request object. + +### Instance Properties + +An `IncomingMessage` instance has the following readable properties: + +#### `response.statusCode` + +An Integer indicating the HTTP response status code. + +#### `response.statusMessage` + +A String representing the HTTP status message. + +#### `response.headers` + +An Object representing the response HTTP headers. The `headers` object is +formatted as follows: + +* All header names are lowercased. +* Each header name produces an array-valued property on the headers object. +* Each header value is pushed into the array associated with its header name. + +#### `response.httpVersion` + +A String indicating the HTTP protocol version number. Typical values are '1.0' +or '1.1'. Additionally `httpVersionMajor` and `httpVersionMinor` are two +Integer-valued readable properties that return respectively the HTTP major and +minor version numbers. diff --git a/docs/api/net.md b/docs/api/net.md index 194f13551252..88891d60cef5 100644 --- a/docs/api/net.md +++ b/docs/api/net.md @@ -65,268 +65,7 @@ The `net` module has the following methods: Returns `ClientRequest` -Creates a `ClientRequest` instance using the provided `options` which are -directly forwarded to the `ClientRequest` constructor. The `net.request` method -would be used to issue both secure and insecure HTTP requests according to the -specified protocol scheme in the `options` object. - -## Class: ClientRequest - -> Make HTTP/HTTPS requests. - -Process: [Main](../tutorial/quick-start.md#main-process) - -`ClientRequest` implements the [Writable Stream](https://nodejs.org/api/stream.html#stream_writable_streams) -interface and is therefore an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter). - -### `new ClientRequest(options)` - -* `options` (Object | String) - If `options` is a String, it is interpreted as - the request URL. If it is an object, it is expected to fully specify an HTTP - request via the following properties: - * `method` String (optional) - The HTTP request method. Defaults to the GET - method. - * `url` String (optional) - The request URL. Must be provided in the absolute - form with the protocol scheme specified as http or https. - * `session` Object (optional) - The [`Session`](session.md) instance with - which the request is associated. - * `partition` String (optional) - The name of the [`partition`](session.md) - with which the request is associated. Defaults to the empty string. The - `session` option prevails on `partition`. Thus if a `session` is explicitly - specified, `partition` is ignored. - * `protocol` String (optional) - The protocol scheme in the form 'scheme:'. - Currently supported values are 'http:' or 'https:'. Defaults to 'http:'. - * `host` String (optional) - The server host provided as a concatenation of - the hostname and the port number 'hostname:port' - * `hostname` String (optional) - The server host name. - * `port` Integer (optional) - The server's listening port number. - * `path` String (optional) - The path part of the request URL. - -`options` properties such as `protocol`, `host`, `hostname`, `port` and `path` -strictly follow the Node.js model as described in the -[URL](https://nodejs.org/api/url.html) module. - -For instance, we could have created the same request to 'github.com' as follows: - -```javascript -const request = net.request({ - method: 'GET', - protocol: 'https:', - hostname: 'github.com', - port: 443, - path: '/' -}) -``` - -### Instance Events - -#### Event: 'response' - -Returns: - -* `response` IncomingMessage - An object representing the HTTP response message. - -#### Event: 'login' - -Returns: - -* `authInfo` Object - * `isProxy` Boolean - * `scheme` String - * `host` String - * `port` Integer - * `realm` String -* `callback` Function - -Emitted when an authenticating proxy is asking for user credentials. - -The `callback` function is expected to be called back with user credentials: - -* `username` String -* `password` String - -```javascript -request.on('login', (authInfo, callback) => { - callback('username', 'password') -}) -``` - -Providing empty credentials will cancel the request and report an authentication -error on the response object: - -```javascript -request.on('response', (response) => { - console.log(`STATUS: ${response.statusCode}`) - response.on('error', (error) => { - console.log(`ERROR: ${JSON.stringify(error)}`) - }) -}) -request.on('login', (authInfo, callback) => { - callback() -}) -``` - -#### Event: 'finish' - -Emitted just after the last chunk of the `request`'s data has been written into -the `request` object. - -#### Event: 'abort' - -Emitted when the `request` is aborted. The `abort` event will not be fired if -the `request` is already closed. - -#### Event: 'error' - -Returns: - -* `error` Error - an error object providing some information about the failure. - -Emitted when the `net` module fails to issue a network request. Typically when -the `request` object emits an `error` event, a `close` event will subsequently -follow and no response object will be provided. - -#### Event: 'close' - -Emitted as the last event in the HTTP request-response transaction. The `close` -event indicates that no more events will be emitted on either the `request` or -`response` objects. - -### Instance Properties - -#### `request.chunkedEncoding` - -A Boolean specifying whether the request will use HTTP chunked transfer encoding -or not. Defaults to false. The property is readable and writable, however it can -be set only before the first write operation as the HTTP headers are not yet put -on the wire. Trying to set the `chunkedEncoding` property after the first write -will throw an error. - -Using chunked encoding is strongly recommended if you need to send a large -request body as data will be streamed in small chunks instead of being -internally buffered inside Electron process memory. - -### Instance Methods - -#### `request.setHeader(name, value)` - -* `name` String - An extra HTTP header name. -* `value` String - An extra HTTP header value. - -Adds an extra HTTP header. The header name will issued as it is without -lowercasing. It can be called only before first write. Calling this method after -the first write will throw an error. - -#### `request.getHeader(name)` - -* `name` String - Specify an extra header name. - -Returns String - The value of a previously set extra header name. - -#### `request.removeHeader(name)` - -* `name` String - Specify an extra header name. - -Removes a previously set extra header name. This method can be called only -before first write. Trying to call it after the first write will throw an error. - -#### `request.write(chunk[, encoding][, callback])` - -* `chunk` (String | Buffer) - A chunk of the request body's data. If it is a - string, it is converted into a Buffer using the specified encoding. -* `encoding` String (optional) - Used to convert string chunks into Buffer - objects. Defaults to 'utf-8'. -* `callback` Function (optional) - Called after the write operation ends. - -`callback` is essentially a dummy function introduced in the purpose of keeping -similarity with the Node.js API. It is called asynchronously in the next tick -after `chunk` content have been delivered to the Chromium networking layer. -Contrary to the Node.js implementation, it is not guaranteed that `chunk` -content have been flushed on the wire before `callback` is called. - -Adds a chunk of data to the request body. The first write operation may cause -the request headers to be issued on the wire. After the first write operation, -it is not allowed to add or remove a custom header. - -#### `request.end([chunk][, encoding][, callback])` - -* `chunk` (String | Buffer) (optional) -* `encoding` String (optional) -* `callback` Function (optional) - -Sends the last chunk of the request data. Subsequent write or end operations -will not be allowed. The `finish` event is emitted just after the end operation. - -#### `request.abort()` - -Cancels an ongoing HTTP transaction. If the request has already emitted the -`close` event, the abort operation will have no effect. Otherwise an ongoing -event will emit `abort` and `close` events. Additionally, if there is an ongoing -response object,it will emit the `aborted` event. - -## Class: IncomingMessage - -> Handle responses to HTTP/HTTPS requests. - -Process: [Main](../tutorial/quick-start.md#main-process) - -`IncomingMessage` implements the [Readable Stream](https://nodejs.org/api/stream.html#stream_readable_streams) -interface and is therefore an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter). - -### Instance Events - -#### Event: 'data' - -Returns: - -* `chunk` Buffer - A chunk of response body's data. - -The `data` event is the usual method of transferring response data into -applicative code. - -#### Event: 'end' - -Indicates that response body has ended. - -#### Event: 'aborted' - -Emitted when a request has been canceled during an ongoing HTTP transaction. - -#### Event: 'error' - -Returns: - -`error` Error - Typically holds an error string identifying failure root cause. - -Emitted when an error was encountered while streaming response data events. For -instance, if the server closes the underlying while the response is still -streaming, an `error` event will be emitted on the response object and a `close` -event will subsequently follow on the request object. - -### Instance Properties - -An `IncomingMessage` instance has the following readable properties: - -#### `response.statusCode` - -An Integer indicating the HTTP response status code. - -#### `response.statusMessage` - -A String representing the HTTP status message. - -#### `response.headers` - -An Object representing the response HTTP headers. The `headers` object is -formatted as follows: - -* All header names are lowercased. -* Each header name produces an array-valued property on the headers object. -* Each header value is pushed into the array associated with its header name. - -#### `response.httpVersion` - -A String indicating the HTTP protocol version number. Typical values are '1.0' -or '1.1'. Additionally `httpVersionMajor` and `httpVersionMinor` are two -Integer-valued readable properties that return respectively the HTTP major and -minor version numbers. +Creates a [`ClientRequest`](./client-request.md) instance using the provided +`options` which are directly forwarded to the `ClientRequest` constructor. +The `net.request` method would be used to issue both secure and insecure HTTP +requests according to the specified protocol scheme in the `options` object. diff --git a/docs/api/session.md b/docs/api/session.md index 9b77ce3403a0..3f1e41cdaefb 100644 --- a/docs/api/session.md +++ b/docs/api/session.md @@ -374,316 +374,3 @@ app.on('ready', function () { }) }) ``` - -## Class: Cookies - -> Query and modify a session's cookies. - -Process: [Main](../tutorial/quick-start.md#main-process) - -Instances of the `Cookies` class are accessed by using `cookies` property of -a `Session`. - -For example: - -```javascript -const {session} = require('electron') - -// Query all cookies. -session.defaultSession.cookies.get({}, (error, cookies) => { - console.log(error, cookies) -}) - -// Query all cookies associated with a specific url. -session.defaultSession.cookies.get({url: 'http://www.github.com'}, (error, cookies) => { - console.log(error, cookies) -}) - -// Set a cookie with the given cookie data; -// may overwrite equivalent cookies if they exist. -const cookie = {url: 'http://www.github.com', name: 'dummy_name', value: 'dummy'} -session.defaultSession.cookies.set(cookie, (error) => { - if (error) console.error(error) -}) -``` - -### Instance Events - -The following events are available on instances of `Cookies`: - -#### Event: 'changed' - -* `event` Event -* `cookie` [Cookie](structures/cookie.md) - The cookie that was changed -* `cause` String - The cause of the change with one of the following values: - * `explicit` - The cookie was changed directly by a consumer's action. - * `overwrite` - The cookie was automatically removed due to an insert - operation that overwrote it. - * `expired` - The cookie was automatically removed as it expired. - * `evicted` - The cookie was automatically evicted during garbage collection. - * `expired-overwrite` - The cookie was overwritten with an already-expired - expiration date. -* `removed` Boolean - `true` if the cookie was removed, `false` otherwise. - -Emitted when a cookie is changed because it was added, edited, removed, or -expired. - -### Instance Methods - -The following methods are available on instances of `Cookies`: - -#### `cookies.get(filter, callback)` - -* `filter` Object - * `url` String (optional) - Retrieves cookies which are associated with - `url`. Empty implies retrieving cookies of all urls. - * `name` String (optional) - Filters cookies by name. - * `domain` String (optional) - Retrieves cookies whose domains match or are - subdomains of `domains` - * `path` String (optional) - Retrieves cookies whose path matches `path`. - * `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. - -`cookies` is an Array of [`cookie`](structures/cookie.md) objects. - -#### `cookies.set(details, callback)` - -* `details` Object - * `url` String - The url to associate the cookie with. - * `name` String - The name of the cookie. Empty by default if omitted. - * `value` String - The value of the cookie. Empty by default if omitted. - * `domain` String - The domain of the cookie. Empty by default if omitted. - * `path` String - The path of the cookie. Empty by default if omitted. - * `secure` Boolean - Whether the cookie should be marked as Secure. Defaults to - false. - * `httpOnly` Boolean - Whether the cookie should be marked as HTTP only. - Defaults to false. - * `expirationDate` Double - The expiration date of the cookie as the number of - 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. - -#### `cookies.remove(url, name, callback)` - -* `url` String - The URL associated with the cookie. -* `name` String - The name of cookie to remove. -* `callback` Function - -Removes the cookies matching `url` and `name`, `callback` will called with -`callback()` on complete. - -## Class: WebRequest - -> Intercept and modify the contents of a request at various stages of its lifetime. - -Process: [Main](../tutorial/quick-start.md#main-process) - -Instances of the `WebRequest` class are accessed by using the `webRequest` -property of a `Session`. - -The methods of `WebRequest` accept an optional `filter` and a `listener`. The -`listener` will be called with `listener(details)` when the API's event has -happened. The `details` object describes the request. Passing `null` -as `listener` will unsubscribe from the event. - -The `filter` object has a `urls` property which is an Array of URL -patterns that will be used to filter out the requests that do not match the URL -patterns. If the `filter` is omitted then all requests will be matched. - -For certain events the `listener` is passed with a `callback`, which should be -called with a `response` object when `listener` has done its work. - -An example of adding `User-Agent` header for requests: - -```javascript -const {session} = require('electron') - -// Modify the user agent for all requests to the following urls. -const filter = { - urls: ['https://*.github.com/*', '*://electron.github.io'] -} - -session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => { - details.requestHeaders['User-Agent'] = 'MyAgent' - callback({cancel: false, requestHeaders: details.requestHeaders}) -}) -``` - -### Instance Methods - -The following methods are available on instances of `WebRequest`: - -#### `webRequest.onBeforeRequest([filter, ]listener)` - -* `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. - -The `uploadData` is an array of `UploadData` objects. - -The `callback` has to be called with an `response` object. - -#### `webRequest.onBeforeSendHeaders([filter, ]listener)` - -* `filter` Object -* `listener` Function - -The `listener` will be called with `listener(details, callback)` before sending -an HTTP request, once the request headers are available. This may occur after a -TCP connection is made to the server, but before any http data is sent. - -* `details` Object - * `id` Integer - * `url` String - * `method` String - * `resourceType` String - * `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. - -#### `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. - -#### `webRequest.onHeadersReceived([filter, ]listener)` - -* `filter` Object -* `listener` Function - -The `listener` will be called with `listener(details, callback)` when HTTP -response headers of a request have been received. - -* `details` Object - * `id` String - * `url` String - * `method` String - * `resourceType` String - * `timestamp` Double - * `statusLine` String - * `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. - -#### `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. - -#### `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. - -#### `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. - -#### `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. diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index 27000434a508..4174c1a9ad20 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -1186,7 +1186,7 @@ A Session object ([session](session.md)) used by this webContents. #### `contents.hostWebContents` -A `WebContents` that might own this `WebContents`. +A [`WebContents`](web-contents.md) instance that might own this `WebContents`. #### `contents.devToolsWebContents` @@ -1197,88 +1197,4 @@ when the DevTools has been closed. #### `contents.debugger` -A Debugger instance for this webContents. - -## Class: Debugger - -> An alternate transport for Chrome's remote debugging protocol. - -Process: [Main](../tutorial/quick-start.md#main-process) - -Chrome Developer Tools has a [special binding][rdp] available at JavaScript -runtime that allows interacting with pages and instrumenting them. - -```javascript -const {BrowserWindow} = require('electron') -let win = new BrowserWindow() - -try { - win.webContents.debugger.attach('1.1') -} catch (err) { - console.log('Debugger attach failed : ', err) -} - -win.webContents.debugger.on('detach', (event, reason) => { - console.log('Debugger detached due to : ', reason) -}) - -win.webContents.debugger.on('message', (event, method, params) => { - if (method === 'Network.requestWillBeSent') { - if (params.request.url === 'https://www.github.com') { - win.webContents.debugger.detach() - } - } -}) - -win.webContents.debugger.sendCommand('Network.enable') -``` - -### Instance Methods - -#### `debugger.attach([protocolVersion])` - -* `protocolVersion` String (optional) - Requested debugging protocol version. - -Attaches the debugger to the `webContents`. - -#### `debugger.isAttached()` - -Returns `Boolean` - Whether a debugger is attached to the `webContents`. - -#### `debugger.detach()` - -Detaches the debugger from the `webContents`. - -#### `debugger.sendCommand(method[, commandParams, callback])` - -* `method` String - Method name, should be one of the methods defined by the - remote debugging protocol. -* `commandParams` Object (optional) - JSON object with request parameters. -* `callback` Function (optional) - Response - * `error` Object - Error message indicating the failure of the command. - * `result` Any - Response defined by the 'returns' attribute of - the command description in the remote debugging protocol. - -Send given command to the debugging target. - -### Instance Events - -#### Event: 'detach' - -* `event` Event -* `reason` String - Reason for detaching debugger. - -Emitted when debugging session is terminated. This happens either when -`webContents` is closed or devtools is invoked for the attached `webContents`. - -#### Event: 'message' - -* `event` Event -* `method` String - Method name. -* `params` Object - Event parameters defined by the 'parameters' - attribute in the remote debugging protocol. - -Emitted whenever debugging target issues instrumentation event. - -[rdp]: https://developer.chrome.com/devtools/docs/debugger-protocol -[`webContents.findInPage`]: web-contents.md#contentsfindinpagetext-options +A [Debugger](debugger.md) instance for this webContents. diff --git a/docs/api/web-request.md b/docs/api/web-request.md new file mode 100644 index 000000000000..c8f3af8b4e85 --- /dev/null +++ b/docs/api/web-request.md @@ -0,0 +1,205 @@ +## Class: WebRequest + +> Intercept and modify the contents of a request at various stages of its lifetime. + +Process: [Main](../tutorial/quick-start.md#main-process) + +Instances of the `WebRequest` class are accessed by using the `webRequest` +property of a `Session`. + +The methods of `WebRequest` accept an optional `filter` and a `listener`. The +`listener` will be called with `listener(details)` when the API's event has +happened. The `details` object describes the request. Passing `null` +as `listener` will unsubscribe from the event. + +The `filter` object has a `urls` property which is an Array of URL +patterns that will be used to filter out the requests that do not match the URL +patterns. If the `filter` is omitted then all requests will be matched. + +For certain events the `listener` is passed with a `callback`, which should be +called with a `response` object when `listener` has done its work. + +An example of adding `User-Agent` header for requests: + +```javascript +const {session} = require('electron') + +// Modify the user agent for all requests to the following urls. +const filter = { + urls: ['https://*.github.com/*', '*://electron.github.io'] +} + +session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => { + details.requestHeaders['User-Agent'] = 'MyAgent' + callback({cancel: false, requestHeaders: details.requestHeaders}) +}) +``` + +### Instance Methods + +The following methods are available on instances of `WebRequest`: + +#### `webRequest.onBeforeRequest([filter, ]listener)` + +* `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. + +The `uploadData` is an array of `UploadData` objects. + +The `callback` has to be called with an `response` object. + +#### `webRequest.onBeforeSendHeaders([filter, ]listener)` + +* `filter` Object +* `listener` Function + +The `listener` will be called with `listener(details, callback)` before sending +an HTTP request, once the request headers are available. This may occur after a +TCP connection is made to the server, but before any http data is sent. + +* `details` Object + * `id` Integer + * `url` String + * `method` String + * `resourceType` String + * `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. + +#### `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. + +#### `webRequest.onHeadersReceived([filter, ]listener)` + +* `filter` Object +* `listener` Function + +The `listener` will be called with `listener(details, callback)` when HTTP +response headers of a request have been received. + +* `details` Object + * `id` String + * `url` String + * `method` String + * `resourceType` String + * `timestamp` Double + * `statusLine` String + * `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. + +#### `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. + +#### `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. + +#### `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. + +#### `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. diff --git a/docs/api/window-open.md b/docs/api/window-open.md index ef4b02d1b9be..4759119e1b2c 100644 --- a/docs/api/window-open.md +++ b/docs/api/window-open.md @@ -40,57 +40,3 @@ has to be a field of `BrowserWindow`'s options. Sends a message to the parent window with the specified origin or `*` for no origin preference. - -## Class: BrowserWindowProxy - -> Manipulate the child browser window - -Process: [Renderer](../tutorial/quick-start.md#renderer-process) - -The `BrowserWindowProxy` object is returned from `window.open` and provides -limited functionality with the child window. - -### Instance Methods - -The `BrowserWindowProxy` object has the following instance methods: - -#### `win.blur()` - -Removes focus from the child window. - -#### `win.close()` - -Forcefully closes the child window without calling its unload event. - -#### `win.eval(code)` - -* `code` String - -Evaluates the code in the child window. - -#### `win.focus()` - -Focuses the child window (brings the window to front). - -#### `win.print()` - -Invokes the print dialog on the child window. - -#### `win.postMessage(message, targetOrigin)` - -* `message` String -* `targetOrigin` String - -Sends a message to the child window with the specified origin or `*` for no -origin preference. - -In addition to these methods, the child window implements `window.opener` object -with no properties and a single method. - -### Instance Properties - -The `BrowserWindowProxy` object has the following instance properties: - -#### `win.closed` - -A Boolean that is set to true after the child window gets closed. From 2b689a21e7700354b652428f7f0a33e46ca6dabf Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Mon, 14 Nov 2016 14:54:16 -0800 Subject: [PATCH 2/9] fix structure headings --- docs/api/structures/upload-file-system.md | 2 +- docs/api/structures/upload-file.md | 2 +- docs/api/structures/upload-raw-data.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/structures/upload-file-system.md b/docs/api/structures/upload-file-system.md index 448932cc9511..d62b0a8ba788 100644 --- a/docs/api/structures/upload-file-system.md +++ b/docs/api/structures/upload-file-system.md @@ -1,4 +1,4 @@ -# Upload FileSystem Object +# UploadFileSystem Object * `type` String - `fileSystem`. * `filsSystemURL` String - FileSystem url to read data for upload. diff --git a/docs/api/structures/upload-file.md b/docs/api/structures/upload-file.md index 0c3009a1e4ca..8a2197301444 100644 --- a/docs/api/structures/upload-file.md +++ b/docs/api/structures/upload-file.md @@ -1,4 +1,4 @@ -# Upload File Object +# UploadFile Object * `type` String - `file`. * `filePath` String - Path of file to be uploaded. diff --git a/docs/api/structures/upload-raw-data.md b/docs/api/structures/upload-raw-data.md index 5632d8e2c6ec..4fe162311fa1 100644 --- a/docs/api/structures/upload-raw-data.md +++ b/docs/api/structures/upload-raw-data.md @@ -1,4 +1,4 @@ -# Upload RawData Object +# UploadRawData Object * `type` String - `rawData`. * `bytes` Buffer - Data to be uploaded. From 4770d2b526c170c81f87926be51cd2e71feb76c8 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Mon, 14 Nov 2016 14:54:28 -0800 Subject: [PATCH 3/9] returns an instance, not the module --- docs/api/native-image.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/native-image.md b/docs/api/native-image.md index 7ca8c18c489a..54d7631f490e 100644 --- a/docs/api/native-image.md +++ b/docs/api/native-image.md @@ -18,7 +18,7 @@ let win = new BrowserWindow({icon: '/Users/somebody/images/window.png'}) console.log(appIcon, win) ``` -Or read the image from the clipboard which returns a `nativeImage`: +Or read the image from the clipboard which returns a `NativeImage`: ```javascript const {clipboard, Tray} = require('electron') From d6684c4dcdc545ad00dd8c0d715597185f6a7cbb Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Mon, 14 Nov 2016 14:55:25 -0800 Subject: [PATCH 4/9] fix UploadBlob heading --- docs/api/structures/upload-blob.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/structures/upload-blob.md b/docs/api/structures/upload-blob.md index 655a733de73c..be93cacb495e 100644 --- a/docs/api/structures/upload-blob.md +++ b/docs/api/structures/upload-blob.md @@ -1,4 +1,4 @@ -# Upload Blob Object +# UploadBlob Object * `type` String - `blob`. * `blobUUID` String - UUID of blob data to upload. From 39330affda4bf1f30bfe7188f34b4522435aeb06 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Mon, 14 Nov 2016 16:14:19 -0800 Subject: [PATCH 5/9] DownloadItem only needs one heading --- docs/api/download-item.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/api/download-item.md b/docs/api/download-item.md index 4887966e6c5d..62df151f9238 100644 --- a/docs/api/download-item.md +++ b/docs/api/download-item.md @@ -1,4 +1,4 @@ -# DownloadItem +## Class: DownloadItem > Control file downloads from remote sources. @@ -37,8 +37,6 @@ win.webContents.session.on('will-download', (event, item, webContents) => { }) ``` -## Class: DownloadItem - ### Instance Events #### Event: 'updated' From c9739abf7fae03edd89fdd8dd9988306b69905be Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Mon, 14 Nov 2016 16:14:32 -0800 Subject: [PATCH 6/9] add description and process for BrowserWindow class --- docs/api/browser-window.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md index 7bf02e6599e9..95d3e826683c 100644 --- a/docs/api/browser-window.md +++ b/docs/api/browser-window.md @@ -109,6 +109,10 @@ child.once('ready-to-show', () => { ## Class: BrowserWindow +> Create and control browser windows. + +Process: [Main](../tutorial/quick-start.md#main-process) + `BrowserWindow` is an [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter). From 5979dab13cbcd1270ec35961c8e9b90c908cd946 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Mon, 14 Nov 2016 16:24:48 -0800 Subject: [PATCH 7/9] fix some class headings --- docs/api/menu-item.md | 6 +----- docs/api/menu.md | 4 +--- docs/api/tray.md | 7 +++---- 3 files changed, 5 insertions(+), 12 deletions(-) diff --git a/docs/api/menu-item.md b/docs/api/menu-item.md index 90d57478b151..5b5324df031c 100644 --- a/docs/api/menu-item.md +++ b/docs/api/menu-item.md @@ -1,4 +1,4 @@ -# MenuItem +## Class: MenuItem > Add items to native application menus and context menus. @@ -6,10 +6,6 @@ Process: [Main](../tutorial/quick-start.md#main-process) See [`Menu`](menu.md) for examples. -## Class: MenuItem - -Create a new `MenuItem` with the following method: - ### `new MenuItem(options)` * `options` Object diff --git a/docs/api/menu.md b/docs/api/menu.md index 37085fcd3990..1410c1058654 100644 --- a/docs/api/menu.md +++ b/docs/api/menu.md @@ -1,4 +1,4 @@ -# Menu +## Class: Menu > Create native application menus and context menus. @@ -217,8 +217,6 @@ window.addEventListener('contextmenu', (e) => { ``` -## Class: Menu - ### `new Menu()` Creates a new menu. diff --git a/docs/api/tray.md b/docs/api/tray.md index 1e1d8524aaaa..f83117bdb9a8 100644 --- a/docs/api/tray.md +++ b/docs/api/tray.md @@ -1,9 +1,11 @@ -# Tray +## Class: Tray > Add icons and context menus to the system's notification area. Process: [Main](../tutorial/quick-start.md#main-process) +`Tray` is an [EventEmitter][event-emitter]. + ```javascript const {app, Menu, Tray} = require('electron') @@ -55,9 +57,6 @@ app.on('ready', () => { If you want to keep exact same behaviors on all platforms, you should not rely on the `click` event and always attach a context menu to the tray icon. -## Class: Tray - -`Tray` is an [EventEmitter][event-emitter]. ### `new Tray(image)` From a7fdd0475186713ccf1ffe41d81f834869d8a390 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Mon, 14 Nov 2016 16:41:15 -0800 Subject: [PATCH 8/9] move menu constructor docs to top of file --- docs/api/menu.md | 159 ++++++++++++++++++++++++----------------------- 1 file changed, 80 insertions(+), 79 deletions(-) diff --git a/docs/api/menu.md b/docs/api/menu.md index 1410c1058654..b4e80689ad47 100644 --- a/docs/api/menu.md +++ b/docs/api/menu.md @@ -4,6 +4,86 @@ Process: [Main](../tutorial/quick-start.md#main-process) +### `new Menu()` + +Creates a new menu. + +### Static Methods + +The `menu` class has the following static methods: + +#### `Menu.setApplicationMenu(menu)` + +* `menu` Menu + +Sets `menu` as the application menu on macOS. On Windows and Linux, the `menu` +will be set as each window's top menu. + +**Note:** This API has to be called after the `ready` event of `app` module. + +#### `Menu.getApplicationMenu()` + +Returns `Menu` - The application menu, if set, or `null`, if not set. + +#### `Menu.sendActionToFirstResponder(action)` _macOS_ + +* `action` String + +Sends the `action` to the first responder of application. This is used for +emulating default Cocoa menu behaviors, usually you would just use the +`role` property of `MenuItem`. + +See the [macOS Cocoa Event Handling Guide](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/EventOverview/EventArchitecture/EventArchitecture.html#//apple_ref/doc/uid/10000060i-CH3-SW7) +for more information on macOS' native actions. + +#### `Menu.buildFromTemplate(template)` + +* `template` MenuItemConstructorOptions[] + +Returns `Menu` + +Generally, the `template` is just an array of `options` for constructing a +[MenuItem](menu-item.md). The usage can be referenced above. + +You can also attach other fields to the element of the `template` and they +will become properties of the constructed menu items. + +### Instance Methods + +The `menu` object has the following instance methods: + +#### `menu.popup([browserWindow, x, y, positioningItem])` + +* `browserWindow` BrowserWindow (optional) - Default is `BrowserWindow.getFocusedWindow()`. +* `x` Number (optional) - Default is the current mouse cursor position. +* `y` Number (**required** if `x` is used) - Default is the current mouse cursor position. +* `positioningItem` Number (optional) _macOS_ - The index of the menu item to + be positioned under the mouse cursor at the specified coordinates. Default is + -1. + +Pops up this menu as a context menu in the `browserWindow`. + +#### `menu.append(menuItem)` + +* `menuItem` MenuItem + +Appends the `menuItem` to the menu. + +#### `menu.insert(pos, menuItem)` + +* `pos` Integer +* `menuItem` MenuItem + +Inserts the `menuItem` to the `pos` position of the menu. + +### Instance Properties + +`menu` objects also have the following properties: + +#### `menu.items` + +A MenuItem[] array containing the menu's items. + Each `Menu` consists of multiple [`MenuItem`](menu-item.md)s and each `MenuItem` can have a submenu. @@ -217,85 +297,6 @@ window.addEventListener('contextmenu', (e) => { ``` -### `new Menu()` - -Creates a new menu. - -### Static Methods - -The `menu` class has the following static methods: - -#### `Menu.setApplicationMenu(menu)` - -* `menu` Menu - -Sets `menu` as the application menu on macOS. On Windows and Linux, the `menu` -will be set as each window's top menu. - -**Note:** This API has to be called after the `ready` event of `app` module. - -#### `Menu.getApplicationMenu()` - -Returns `Menu` - The application menu, if set, or `null`, if not set. - -#### `Menu.sendActionToFirstResponder(action)` _macOS_ - -* `action` String - -Sends the `action` to the first responder of application. This is used for -emulating default Cocoa menu behaviors, usually you would just use the -`role` property of `MenuItem`. - -See the [macOS Cocoa Event Handling Guide](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/EventOverview/EventArchitecture/EventArchitecture.html#//apple_ref/doc/uid/10000060i-CH3-SW7) -for more information on macOS' native actions. - -#### `Menu.buildFromTemplate(template)` - -* `template` MenuItemConstructorOptions[] - -Returns `Menu` - -Generally, the `template` is just an array of `options` for constructing a -[MenuItem](menu-item.md). The usage can be referenced above. - -You can also attach other fields to the element of the `template` and they -will become properties of the constructed menu items. - -### Instance Methods - -The `menu` object has the following instance methods: - -#### `menu.popup([browserWindow, x, y, positioningItem])` - -* `browserWindow` BrowserWindow (optional) - Default is `BrowserWindow.getFocusedWindow()`. -* `x` Number (optional) - Default is the current mouse cursor position. -* `y` Number (**required** if `x` is used) - Default is the current mouse cursor position. -* `positioningItem` Number (optional) _macOS_ - The index of the menu item to - be positioned under the mouse cursor at the specified coordinates. Default is - -1. - -Pops up this menu as a context menu in the `browserWindow`. - -#### `menu.append(menuItem)` - -* `menuItem` MenuItem - -Appends the `menuItem` to the menu. - -#### `menu.insert(pos, menuItem)` - -* `pos` Integer -* `menuItem` MenuItem - -Inserts the `menuItem` to the `pos` position of the menu. - -### Instance Properties - -`menu` objects also have the following properties: - -#### `menu.items` - -A MenuItem[] array containing the menu's items. ## Notes on macOS Application Menu From f9683ff99f8452ca8d589590ef9640769facdcda Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Tue, 15 Nov 2016 11:41:52 -0800 Subject: [PATCH 9/9] use unreleased linter --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 234fa6b78313..425503f4e0a7 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,7 @@ "asar": "^0.11.0", "browserify": "^13.1.0", "electabul": "~0.0.4", - "electron-docs-linter": "1.14.1", + "electron-docs-linter": "^1.15.0", "request": "*", "standard": "^8.4.0", "standard-markdown": "^2.1.1"