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

Merge pull request #2585 from atom/jl-std-docs-2

Browse source 
Standardize: clipboard, content-tracing, crash-reporter
This commit is contained in:
Jessica Lord 2015-08-28 13:51:16 -07:00
commit 609961a1de
3 changed files with 140 additions and 115 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

68
docs/api/clipboard.md
View file

@ -1,7 +1,7 @@
# clipboard # clipboard
The `clipboard` provides methods to perform copy and paste operations. The following example The `clipboard` module provides methods to perform copy and paste operations.
shows how to write a string to the clipboard: The following example shows how to write a string to the clipboard:
```javascript ```javascript
var clipboard = require('clipboard'); var clipboard = require('clipboard');
@ -17,59 +17,67 @@ clipboard.writeText('Example String', 'selection');
console.log(clipboard.readText('selection')); console.log(clipboard.readText('selection'));
``` ```
## clipboard.readText([type]) ## Methods
* `type` String The `clipboard` module has the following methods:
**Note:** Experimental APIs are marked as such and could be removed in future.
### `clipboard.readText([type])`
* `type` String (optional)
Returns the content in the clipboard as plain text. Returns the content in the clipboard as plain text.
## clipboard.writeText(text[, type]) ### `clipboard.writeText(text[, type])`
* `text` String * `text` String
* `type` String * `type` String (optional)
Writes the `text` into the clipboard as plain text. Writes the `text` into the clipboard as plain text.
## clipboard.readHtml([type]) ### `clipboard.readHtml([type])`
* `type` String * `type` String (optional)
Returns the content in the clipboard as markup. Returns the content in the clipboard as markup.
## clipboard.writeHtml(markup[, type]) ### `clipboard.writeHtml(markup[, type])`
* `markup` String * `markup` String
* `type` String * `type` String (optional)
Writes `markup` into the clipboard. Writes `markup` to the clipboard.
## clipboard.readImage([type]) ### `clipboard.readImage([type])`
* `type` String * `type` String (optional)
Returns the content in the clipboard as a [NativeImage](native-image.md). Returns the content in the clipboard as a [NativeImage](native-image.md).
## clipboard.writeImage(image[, type]) ### `clipboard.writeImage(image[, type])`
* `image` [NativeImage](native-image.md) * `image` [NativeImage](native-image.md)
* `type` String * `type` String (optional)
Writes `image` into the clipboard. Writes `image` to the clipboard.
## clipboard.clear([type]) ### `clipboard.clear([type])`
* `type` String * `type` String (optional)
Clears the clipboard. Clears the clipboard content.
## clipboard.availableFormats([type]) ### `clipboard.availableFormats([type])`
Returns an array of supported `format` for the clipboard `type`. * `type` String (optional)
## clipboard.has(data[, type]) Returns an array of supported formats for the clipboard `type`.
### `clipboard.has(data[, type])` _Experimental_
* `data` String * `data` String
* `type` String * `type` String (optional)
Returns whether the clipboard supports the format of specified `data`. Returns whether the clipboard supports the format of specified `data`.
@ -78,27 +86,23 @@ var clipboard = require('clipboard');
console.log(clipboard.has('<p>selection</p>')); console.log(clipboard.has('<p>selection</p>'));
``` ```
**Note:** This API is experimental and could be removed in future. ### `clipboard.read(data[, type])` _Experimental_
## clipboard.read(data[, type])
* `data` String * `data` String
* `type` String * `type` String (optional)
Reads `data` from the clipboard. Reads `data` from the clipboard.
**Note:** This API is experimental and could be removed in future. ### `clipboard.write(data[, type])`
## clipboard.write(data[, type])
* `data` Object * `data` Object
* `text` String * `text` String
* `html` String * `html` String
* `image` [NativeImage](native-image.md) * `image` [NativeImage](native-image.md)
* `type` String * `type` String (optional)
```javascript ```javascript
var clipboard = require('clipboard'); var clipboard = require('clipboard');
clipboard.write({text: 'test', html: "<b>test</b>"}); clipboard.write({text: 'test', html: "<b>test</b>"});
``` ```
Writes `data` into clipboard. Writes `data` to the clipboard.

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

@ -1,12 +1,13 @@
# content-tracing # contentTracing
The `content-trace` module is used to collect tracing data generated by the The `content-tracing` module is used to collect tracing data generated by the
underlying Chromium content module. This module does not include a web interface underlying Chromium content module. This module does not include a web interface
so you need to open `chrome://tracing/` in a Chrome browser and load the generated so you need to open `chrome://tracing/` in a Chrome browser and load the
file to view the result. generated file to view the result.
```javascript ```javascript
var tracing = require('content-tracing'); var contentTracing = require('content-tracing');
tracing.startRecording('*', tracing.DEFAULT_OPTIONS, function() { tracing.startRecording('*', tracing.DEFAULT_OPTIONS, function() {
console.log('Tracing started'); console.log('Tracing started');
@ -18,17 +19,21 @@ tracing.startRecording('*', tracing.DEFAULT_OPTIONS, function() {
}); });
``` ```
## tracing.getCategories(callback) ## Methods
The `content-tracing` module has the following methods:
### `contentTracing.getCategories(callback)`
* `callback` Function * `callback` Function
Get a set of category groups. The category groups can change as new code paths Get a set of category groups. The category groups can change as new code paths
are reached. are reached.
Once all child processes have acked to the `getCategories` request, `callback` Once all child processes have acknowledged the `getCategories` request the
is invoked with an array of category groups. `callback` is invoked with an array of category groups.
## tracing.startRecording(categoryFilter, traceOptions, callback) ### `contentTracing.startRecording(categoryFilter, traceOptions, callback)`
* `categoryFilter` String * `categoryFilter` String
* `traceOptions` String * `traceOptions` String
@ -36,9 +41,9 @@ is invoked with an array of category groups.
Start recording on all processes. Start recording on all processes.
Recording begins immediately locally, and asynchronously on child processes Recording begins immediately locally and asynchronously on child processes
as soon as they receive the EnableRecording request. Once all child processes as soon as they receive the EnableRecording request. The `callback` will be
have acked to the `startRecording` request, `callback` will be called back. called once all child processes have acknowledged the `startRecording` request.
`categoryFilter` is a filter to control what category groups should be `categoryFilter` is a filter to control what category groups should be
traced. A filter can have an optional `-` prefix to exclude category groups traced. A filter can have an optional `-` prefix to exclude category groups
@ -51,8 +56,8 @@ Examples:
* `test_MyTest*,test_OtherStuff`, * `test_MyTest*,test_OtherStuff`,
* `"-excluded_category1,-excluded_category2` * `"-excluded_category1,-excluded_category2`
`traceOptions` controls what kind of tracing is enabled, it is a comma-delimited list. `traceOptions` controls what kind of tracing is enabled, it is a comma-delimited
Possible options are: list. Possible options are:
* `record-until-full` * `record-until-full`
* `record-continuously` * `record-continuously`
@ -62,34 +67,34 @@ Possible options are:
The first 3 options are trace recoding modes and hence mutually exclusive. The first 3 options are trace recoding modes and hence mutually exclusive.
If more than one trace recording modes appear in the `traceOptions` string, If more than one trace recording modes appear in the `traceOptions` string,
the last one takes precedence. If none of the trace recording mode is specified, the last one takes precedence. If none of the trace recording modes are
recording mode is `record-until-full`. specified, recording mode is `record-until-full`.
The trace option will first be reset to the default option (record_mode set to The trace option will first be reset to the default option (`record_mode` set to
`record-until-full`, enable_sampling and enable_systrace set to false) `record-until-full`, `enable_sampling` and `enable_systrace` set to `false`)
before options parsed from `traceOptions` are applied on it. before options parsed from `traceOptions` are applied on it.
## tracing.stopRecording(resultFilePath, callback) ### `contentTracing.stopRecording(resultFilePath, callback)`
* `resultFilePath` String * `resultFilePath` String
* `callback` Function * `callback` Function
Stop recording on all processes. Stop recording on all processes.
Child processes typically are caching trace data and only rarely flush and send Child processes typically cache trace data and only rarely flush and send
trace data back to the main process. That is because it may be an expensive trace data back to the main process. This helps to minimize the runtime overhead
operation to send the trace data over IPC, and we would like to avoid much of tracing since sending trace data over IPC can be an expensive operation. So,
runtime overhead of tracing. So, to end tracing, we must asynchronously ask all to end tracing, we must asynchronously ask all child processes to flush any
child processes to flush any pending trace data. pending trace data.
Once all child processes have acked to the `stopRecording` request, `callback` Once all child processes have acknowledged the `stopRecording` request,
will be called back with a file that contains the traced data. `callback` will be called with a file that contains the traced data.
Trace data will be written into `resultFilePath` if it is not empty, or into a Trace data will be written into `resultFilePath` if it is not empty or into a
temporary file. The actual file path will be passed to `callback` if it's not temporary file. The actual file path will be passed to `callback` if it's not
null. `null`.
## tracing.startMonitoring(categoryFilter, traceOptions, callback) ### `contentTracing.startMonitoring(categoryFilter, traceOptions, callback)`
* `categoryFilter` String * `categoryFilter` String
* `traceOptions` String * `traceOptions` String
@ -97,46 +102,47 @@ null.
Start monitoring on all processes. Start monitoring on all processes.
Monitoring begins immediately locally, and asynchronously on child processes as Monitoring begins immediately locally and asynchronously on child processes as
soon as they receive the `startMonitoring` request. soon as they receive the `startMonitoring` request.
Once all child processes have acked to the `startMonitoring` request, Once all child processes have acknowledged the `startMonitoring` request the
`callback` will be called back. `callback` will be called.
## tracing.stopMonitoring(callback); ### `contentTracing.stopMonitoring(callback)`
* `callback` Function * `callback` Function
Stop monitoring on all processes. Stop monitoring on all processes.
Once all child processes have acked to the `stopMonitoring` request, `callback` Once all child processes have acknowledged the `stopMonitoring` request the
is called back. `callback` is called.
## tracing.captureMonitoringSnapshot(resultFilePath, callback) ### `contentTracing.captureMonitoringSnapshot(resultFilePath, callback)`
* `resultFilePath` String * `resultFilePath` String
* `callback` Function * `callback` Function
Get the current monitoring traced data. Get the current monitoring traced data.
Child processes typically are caching trace data and only rarely flush and send Child processes typically cache trace data and only rarely flush and send
trace data back to the main process. That is because it may be an expensive trace data back to the main process. This is because it may be an expensive
operation to send the trace data over IPC, and we would like to avoid unneeded operation to send the trace data over IPC and we would like to avoid unneeded
runtime overhead of tracing. So, to end tracing, we must asynchronously ask all runtime overhead from tracing. So, to end tracing, we must asynchronously ask
child processes to flush any pending trace data. all child processes to flush any pending trace data.
Once all child processes have acked to the `captureMonitoringSnapshot` request, Once all child processes have acknowledged the `captureMonitoringSnapshot`
the `callback` will be invoked with a file that contains the traced data. request the `callback` will be called with a file that contains the traced data.
## tracing.getTraceBufferUsage(callback) ### `contentTracing.getTraceBufferUsage(callback)`
* `callback` Function * `callback` Function
Get the maximum across processes of trace buffer percent full state. When the Get the maximum usage across processes of trace buffer as a percentage of the
TraceBufferUsage value is determined, the `callback` is called. full state. When the TraceBufferUsage value is determined the `callback` is
called.
## tracing.setWatchEvent(categoryName, eventName, callback) ### `contentTracing.setWatchEvent(categoryName, eventName, callback)`
* `categoryName` String * `categoryName` String
* `eventName` String * `eventName` String
@ -145,7 +151,7 @@ TraceBufferUsage value is determined, the `callback` is called.
`callback` will will be called every time the given event occurs on any `callback` will will be called every time the given event occurs on any
process. process.
## tracing.cancelWatchEvent() ### `contentTracing.cancelWatchEvent()`
Cancel the watch event. If tracing is enabled, this may race with the watch Cancel the watch event. This may lead to a race condition with the watch event
event callback. callback if tracing is enabled.

81
docs/api/crash-reporter.md
View file

@ -1,9 +1,13 @@
# crash-reporter # crashReporter
The following is an example of automatically submitting a crash report to a remote server: The `crash-reporter` module enables sending your app's crash reports.
The following is an example of automatically submitting a crash report to a
remote server:
```javascript ```javascript
crashReporter = require('crash-reporter'); var crashReporter = require('crash-reporter');
crashReporter.start({ crashReporter.start({
productName: 'YourName', productName: 'YourName',
companyName: 'YourCompany', companyName: 'YourCompany',
@ -12,49 +16,60 @@ crashReporter.start({
}); });
``` ```
## crashReporter.start(options) ## Methods
* `options` Object The `crash-reporter` module has the following methods:
* `productName` String, default: Electron
* `companyName` String, default: GitHub, Inc
* `submitUrl` String, default: http://54.249.141.255:1127/post
* URL that crash reports will be sent to as POST
* `autoSubmit` Boolean, default: true
* Send the crash report without user interaction
* `ignoreSystemCrashHandler` Boolean, default: false
* `extra` Object
* An object you can define that will be sent along with the report.
* Only string properties are sent correctly.
* Nested objects are not supported.
Developers are required to call this method before using other `crashReporter` APIs. ### `crashReporter.start(options)`
`options` Object, properties:
* `productName` String, default: Electron.
* `companyName` String, default: GitHub, Inc.
* `submitUrl` String, default: http://54.249.141.255:1127/post.
* URL that crash reports will be sent to as POST.
* `autoSubmit` Boolean, default: `true`.
* Send the crash report without user interaction.
* `ignoreSystemCrashHandler` Boolean, default: `false`.
* `extra` Object
* An object you can define that will be sent along with the report.
* Only string properties are sent correctly.
* Nested objects are not supported.
You are required to call this method before using other `crashReporter`
APIs.
**Note:** On OS X, Electron uses a new `crashpad` client, which is different **Note:** On OS X, Electron uses a new `crashpad` client, which is different
from `breakpad` on Windows and Linux. To enable the crash collection feature, from `breakpad` on Windows and Linux. To enable the crash collection feature,
you are required to call `crashReporter.start` API to initialize `crashpad` in the you are required to call the `crashReporter.start` API to initialize `crashpad`
main process and in each renderer process from which you wish to collect crash reports. in the main process and in each renderer process from which you wish to collect
crash reports.
## crashReporter.getLastCrashReport() ### `crashReporter.getLastCrashReport()`
Returns the date and ID of the last crash report. If no crash reports have been Returns the date and ID of the last crash report. If no crash reports have been
sent or the crash reporter has not been started, `null` is returned. sent or the crash reporter has not been started, `null` is returned.
## crashReporter.getUploadedReports() ### `crashReporter.getUploadedReports()`
Returns all uploaded crash reports. Each report contains the date and uploaded ID. Returns all uploaded crash reports. Each report contains the date and uploaded
ID.
# crash-reporter payload ## crash-reporter Payload
The crash reporter will send the following data to the `submitUrl` as `POST`: The crash reporter will send the following data to the `submitUrl` as `POST`:
* `rept` String - e.g. 'electron-crash-service' * `rept` String - e.g. 'electron-crash-service'.
* `ver` String - The version of Electron * `ver` String - The version of Electron.
* `platform` String - e.g. 'win32' * `platform` String - e.g. 'win32'.
* `process_type` String - e.g. 'renderer' * `process_type` String - e.g. 'renderer'.
* `ptime` Number * `ptime` Number
* `_version` String - The version in `package.json` * `_version` String - The version in `package.json`.
* `_productName` String - The product name in the `crashReporter` `options` object * `_productName` String - The product name in the `crashReporter` `options`
* `prod` String - Name of the underlying product. In this case Electron object.
* `_companyName` String - The company name in the `crashReporter` `options` object * `prod` String - Name of the underlying product. In this case Electron.
* `upload_file_minidump` File - The crashreport as file * `_companyName` String - The company name in the `crashReporter` `options`
* All level one properties of the `extra` object in the `crashReporter` `options` object object.
* `upload_file_minidump` File - The crash report as file.
* All level one properties of the `extra` object in the `crashReporter`.
`options` object