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

docs: Improved documentation (#13403)

Browse source
This commit is contained in:
Tiago Danin 2018-07-20 14:58:19 -03:00 committed by Shelley Vohr
parent 2440d03595
commit 1fd6d38a0a
18 changed files with 79 additions and 79 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/api/app.md
View file

@ -881,7 +881,7 @@ Changes the [Application User Model ID][app-user-model-id] to `id`.
Imports the certificate in pkcs12 format into the platform certificate store. Imports the certificate in pkcs12 format into the platform certificate store.
`callback` is called with the `result` of import operation, a value of `0` `callback` is called with the `result` of import operation, a value of `0`
indicates success while any other value indicates failure according to chromium [net_error_list](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h). indicates success while any other value indicates failure according to Chromium [net_error_list](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h).
### `app.disableHardwareAcceleration()` ### `app.disableHardwareAcceleration()`
@ -1033,7 +1033,7 @@ const stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedReso
stopAccessingSecurityScopedResource() stopAccessingSecurityScopedResource()
``` ```
Start accessing a security scoped resource. With this method electron applications that are packaged for the Mac App Store may reach outside their sandbox to access files chosen by the user. See [Apple's documentation](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16) for a description of how this system works. Start accessing a security scoped resource. With this method Electron applications that are packaged for the Mac App Store may reach outside their sandbox to access files chosen by the user. See [Apple's documentation](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16) for a description of how this system works.
### `app.commandLine.appendSwitch(switch[, value])` ### `app.commandLine.appendSwitch(switch[, value])`

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

@ -59,11 +59,11 @@ The `role` property can have following values:
* `delete` * `delete`
* `minimize` - Minimize current window. * `minimize` - Minimize current window.
* `close` - Close current window. * `close` - Close current window.
* `quit`- Quit the application. * `quit` - Quit the application.
* `reload` - Reload the current window. * `reload` - Reload the current window.
* `forceReload` - Reload the current window ignoring the cache. * `forceReload` - Reload the current window ignoring the cache.
* `toggleDevTools` - Toggle developer tools in the current window. * `toggleDevTools` - Toggle developer tools in the current window.
* `toggleFullScreen`- Toggle full screen mode on the current window. * `toggleFullScreen` - Toggle full screen mode on the current window.
* `resetZoom` - Reset the focused page's zoom level to the original size. * `resetZoom` - Reset the focused page's zoom level to the original size.
* `zoomIn` - Zoom in the focused page by 10%. * `zoomIn` - Zoom in the focused page by 10%.
* `zoomOut` - Zoom out the focused page by 10%. * `zoomOut` - Zoom out the focused page by 10%.

46
docs/api/sandbox-option.md
View file

@ -2,7 +2,7 @@
> Create a browser window with a renderer that can run inside Chromium OS sandbox. With this > Create a browser window with a renderer that can run inside Chromium OS sandbox. With this
option enabled, the renderer must communicate via IPC to the main process in order to access node APIs. option enabled, the renderer must communicate via IPC to the main process in order to access node APIs.
However, in order to enable the Chromium OS sandbox, electron must be run with the `--enable-sandbox` However, in order to enable the Chromium OS sandbox, Electron must be run with the `--enable-sandbox`
command line argument. command line argument.
One of the key security features of Chromium is that all blink rendering/JavaScript One of the key security features of Chromium is that all blink rendering/JavaScript
@ -14,26 +14,26 @@ to the system by delegating tasks to the main process via IPC.
[Here's](https://www.chromium.org/developers/design-documents/sandbox) more [Here's](https://www.chromium.org/developers/design-documents/sandbox) more
information about the sandbox. information about the sandbox.
Since a major feature in electron is the ability to run node.js in the Since a major feature in Electron is the ability to run Node.js in the
renderer process (making it easier to develop desktop applications using web renderer process (making it easier to develop desktop applications using web
technologies), the sandbox is disabled by electron. This is because technologies), the sandbox is disabled by electron. This is because
most node.js APIs require system access. `require()` for example, is not most Node.js APIs require system access. `require()` for example, is not
possible without file system permissions, which are not available in a sandboxed possible without file system permissions, which are not available in a sandboxed
environment. environment.
Usually this is not a problem for desktop applications since the code is always Usually this is not a problem for desktop applications since the code is always
trusted, but it makes electron less secure than chromium for displaying trusted, but it makes Electron less secure than Chromium for displaying
untrusted web content. For applications that require more security, the untrusted web content. For applications that require more security, the
`sandbox` flag will force electron to spawn a classic chromium renderer that is `sandbox` flag will force Electron to spawn a classic Chromium renderer that is
compatible with the sandbox. compatible with the sandbox.
A sandboxed renderer doesn't have a node.js environment running and doesn't A sandboxed renderer doesn't have a Node.js environment running and doesn't
expose node.js JavaScript APIs to client code. The only exception is the preload script, expose Node.js JavaScript APIs to client code. The only exception is the preload script,
which has access to a subset of the electron renderer API. which has access to a subset of the Electron renderer API.
Another difference is that sandboxed renderers don't modify any of the default Another difference is that sandboxed renderers don't modify any of the default
JavaScript APIs. Consequently, some APIs such as `window.open` will work as they JavaScript APIs. Consequently, some APIs such as `window.open` will work as they
do in chromium (i.e. they do not return a [`BrowserWindowProxy`](browser-window-proxy.md)). do in Chromium (i.e. they do not return a [`BrowserWindowProxy`](browser-window-proxy.md)).
## Example ## Example
@ -51,9 +51,9 @@ app.on('ready', () => {
}) })
``` ```
In the above code the [`BrowserWindow`](browser-window.md) that was created has node.js disabled and can communicate In the above code the [`BrowserWindow`](browser-window.md) that was created has Node.js disabled and can communicate
only via IPC. The use of this option stops electron from creating a node.js runtime in the renderer. Also, only via IPC. The use of this option stops Electron from creating a Node.js runtime in the renderer. Also,
within this new window `window.open` follows the native behaviour (by default electron creates a [`BrowserWindow`](browser-window.md) within this new window `window.open` follows the native behaviour (by default Electron creates a [`BrowserWindow`](browser-window.md)
and returns a proxy to this via `window.open`). and returns a proxy to this via `window.open`).
It is important to note that this option alone won't enable the OS-enforced sandbox. To enable this feature, the It is important to note that this option alone won't enable the OS-enforced sandbox. To enable this feature, the
@ -75,19 +75,19 @@ app.on('ready', () => {
Note that it is not enough to call Note that it is not enough to call
`app.commandLine.appendSwitch('--enable-sandbox')`, as electron/node startup `app.commandLine.appendSwitch('--enable-sandbox')`, as electron/node startup
code runs after it is possible to make changes to chromium sandbox settings. The code runs after it is possible to make changes to Chromium sandbox settings. The
switch must be passed to electron on the command-line: switch must be passed to Electron on the command-line:
```sh ```sh
electron --enable-sandbox app.js electron --enable-sandbox app.js
``` ```
It is not possible to have the OS sandbox active only for some renderers, if It is not possible to have the OS sandbox active only for some renderers, if
`--enable-sandbox` is enabled, normal electron windows cannot be created. `--enable-sandbox` is enabled, normal Electron windows cannot be created.
If you need to mix sandboxed and non-sandboxed renderers in one application, If you need to mix sandboxed and non-sandboxed renderers in one application,
omit the `--enable-sandbox` argument. Without this argument, windows omit the `--enable-sandbox` argument. Without this argument, windows
created with `sandbox: true` will still have node.js disabled and communicate created with `sandbox: true` will still have Node.js disabled and communicate
only via IPC, which by itself is already a gain from security POV. only via IPC, which by itself is already a gain from security POV.
## Preload ## Preload
@ -112,7 +112,7 @@ and preload.js:
```js ```js
// This file is loaded whenever a javascript context is created. It runs in a // This file is loaded whenever a javascript context is created. It runs in a
// private scope that can access a subset of electron renderer APIs. We must be // private scope that can access a subset of Electron renderer APIs. We must be
// careful to not leak any objects into the global scope! // careful to not leak any objects into the global scope!
const fs = require('fs') const fs = require('fs')
const {ipcRenderer} = require('electron') const {ipcRenderer} = require('electron')
@ -136,7 +136,7 @@ window.open = customWindowOpen
Important things to notice in the preload script: Important things to notice in the preload script:
- Even though the sandboxed renderer doesn't have node.js running, it still has - Even though the sandboxed renderer doesn't have Node.js running, it still has
access to a limited node-like environment: `Buffer`, `process`, `setImmediate` access to a limited node-like environment: `Buffer`, `process`, `setImmediate`
and `require` are available. and `require` are available.
- The preload script can indirectly access all APIs from the main process through the - The preload script can indirectly access all APIs from the main process through the
@ -146,7 +146,7 @@ Important things to notice in the preload script:
- The preload script must be contained in a single script, but it is possible to have - The preload script must be contained in a single script, but it is possible to have
complex preload code composed with multiple modules by using a tool like complex preload code composed with multiple modules by using a tool like
browserify, as explained below. In fact, browserify is already used by browserify, as explained below. In fact, browserify is already used by
electron to provide a node-like environment to the preload script. Electron to provide a node-like environment to the preload script.
To create a browserify bundle and use it as a preload script, something like To create a browserify bundle and use it as a preload script, something like
the following should be used: the following should be used:
@ -178,7 +178,7 @@ following modules:
- `timers` - `timers`
- `url` - `url`
More may be added as needed to expose more electron APIs in the sandbox, but any More may be added as needed to expose more Electron APIs in the sandbox, but any
module in the main process can already be used through module in the main process can already be used through
`electron.remote.require`. `electron.remote.require`.
@ -186,7 +186,7 @@ module in the main process can already be used through
Please use the `sandbox` option with care, as it is still an experimental Please use the `sandbox` option with care, as it is still an experimental
feature. We are still not aware of the security implications of exposing some feature. We are still not aware of the security implications of exposing some
electron renderer APIs to the preload script, but here are some things to Electron renderer APIs to the preload script, but here are some things to
consider before rendering untrusted content: consider before rendering untrusted content:
- A preload script can accidentally leak privileged APIs to untrusted code. - A preload script can accidentally leak privileged APIs to untrusted code.
@ -194,9 +194,9 @@ consider before rendering untrusted content:
APIs, effectively granting full access to the system through the `remote` APIs, effectively granting full access to the system through the `remote`
module. module.
Since rendering untrusted content in electron is still uncharted territory, Since rendering untrusted content in Electron is still uncharted territory,
the APIs exposed to the sandbox preload script should be considered more the APIs exposed to the sandbox preload script should be considered more
unstable than the rest of electron APIs, and may have breaking changes to fix unstable than the rest of Electron APIs, and may have breaking changes to fix
security issues. security issues.
One planned enhancement that should greatly increase security is to block IPC One planned enhancement that should greatly increase security is to block IPC

12
docs/api/structures/certificate-principal.md
View file

@ -1,8 +1,8 @@
# CertificatePrincipal Object # CertificatePrincipal Object
* `commonName` String - Common Name * `commonName` String - Common Name.
* `organizations` String[] - Organization names * `organizations` String[] - Organization names.
* `organizationUnits` String[] - Organization Unit names * `organizationUnits` String[] - Organization Unit names.
* `locality` String - Locality * `locality` String - Locality.
* `state` String - State or province * `state` String - State or province.
* `country` String - Country or region * `country` String - Country or region.

26
docs/api/structures/gpu-feature-status.md
View file

@ -1,18 +1,18 @@
# GPUFeatureStatus Object # GPUFeatureStatus Object
* `2d_canvas` String - Canvas * `2d_canvas` String - Canvas.
* `flash_3d` String - Flash * `flash_3d` String - Flash.
* `flash_stage3d` String - Flash Stage3D * `flash_stage3d` String - Flash Stage3D.
* `flash_stage3d_baseline` String - Flash Stage3D Baseline profile * `flash_stage3d_baseline` String - Flash Stage3D Baseline profile.
* `gpu_compositing` String - Compositing * `gpu_compositing` String - Compositing.
* `multiple_raster_threads` String - Multiple Raster Threads * `multiple_raster_threads` String - Multiple Raster Threads.
* `native_gpu_memory_buffers` String - Native GpuMemoryBuffers * `native_gpu_memory_buffers` String - Native GpuMemoryBuffers.
* `rasterization` String - Rasterization * `rasterization` String - Rasterization.
* `video_decode` String - Video Decode * `video_decode` String - Video Decode.
* `video_encode` String - Video Encode * `video_encode` String - Video Encode.
* `vpx_decode` String - VPx Video Decode * `vpx_decode` String - VPx Video Decode.
* `webgl` String - WebGL * `webgl` String - WebGL.
* `webgl2` String - WebGL2 * `webgl2` String - WebGL2.
Possible values: Possible values:

4
docs/api/structures/mime-typed-buffer.md
View file

@ -1,4 +1,4 @@
# MimeTypedBuffer Object # MimeTypedBuffer Object
* `mimeType` String - The mimeType of the Buffer that you are sending * `mimeType` String - The mimeType of the Buffer that you are sending.
* `data` Buffer - The actual Buffer content * `data` Buffer - The actual Buffer content.

8
docs/api/structures/rectangle.md
View file

@ -1,6 +1,6 @@
# Rectangle Object # Rectangle Object
* `x` Number - The x coordinate of the origin of the rectangle (must be an integer) * `x` Number - The x coordinate of the origin of the rectangle (must be an integer).
* `y` Number - The y coordinate of the origin of the rectangle (must be an integer) * `y` Number - The y coordinate of the origin of the rectangle (must be an integer).
* `width` Number - The width of the rectangle (must be an integer) * `width` Number - The width of the rectangle (must be an integer).
* `height` Number - The height of the rectangle (must be an integer) * `height` Number - The height of the rectangle (must be an integer).

4
docs/api/structures/scrubber-item.md
View file

@ -1,4 +1,4 @@
# ScrubberItem Object # ScrubberItem Object
* `label` String (optional) - The text to appear in this item * `label` String (optional) - The text to appear in this item.
* `icon` NativeImage (optional) - The image to appear in this item * `icon` NativeImage (optional) - The image to appear in this item.

6
docs/api/structures/segmented-control-segment.md
View file

@ -1,5 +1,5 @@
# SegmentedControlSegment Object # SegmentedControlSegment Object
* `label` String (optional) - The text to appear in this segment * `label` String (optional) - The text to appear in this segment.
* `icon` NativeImage (optional) - The image to appear in this segment * `icon` NativeImage (optional) - The image to appear in this segment.
* `enabled` Boolean (optional) - Whether this segment is selectable. Default: true * `enabled` Boolean (optional) - Whether this segment is selectable. Default: true.

6
docs/api/structures/stream-protocol-response.md
View file

@ -1,5 +1,5 @@
# StreamProtocolResponse Object # StreamProtocolResponse Object
* `statusCode` Number - The HTTP response code * `statusCode` Number - The HTTP response code.
* `headers` Object - An object containing the response headers * `headers` Object - An object containing the response headers.
* `data` ReadableStream - A Node.js readable stream representing the response body * `data` ReadableStream - A Node.js readable stream representing the response body.

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

@ -1468,7 +1468,7 @@ process.
#### `contents.getProcessId()` #### `contents.getProcessId()`
Returns `Integer` - The chromium internal `pid` of the associated renderer. Can Returns `Integer` - The Chromium internal `pid` of the associated renderer. Can
be compared to the `frameProcessId` passed by frame specific navigation events be compared to the `frameProcessId` passed by frame specific navigation events
(e.g. `did-frame-navigate`) (e.g. `did-frame-navigate`)

2
docs/api/web-frame.md
View file

@ -4,7 +4,7 @@
Process: [Renderer](../glossary.md#renderer-process) Process: [Renderer](../glossary.md#renderer-process)
`webFrame` export of the electron module is an instance of the `WebFrame` `webFrame` export of the Electron module is an instance of the `WebFrame`
class representing the top frame of the current `BrowserWindow`. Sub-frames can class representing the top frame of the current `BrowserWindow`. Sub-frames can
be retrieved by certain properties and methods (e.g. `webFrame.firstChild`). be retrieved by certain properties and methods (e.g. `webFrame.firstChild`).

2
docs/development/build-instructions-gn.md
View file

@ -87,7 +87,7 @@ this document :)
## Tests ## Tests
To run the tests, you'll first need to build the test modules against the To run the tests, you'll first need to build the test modules against the
same version of node.js that was built as part of the build process. same version of Node.js that was built as part of the build process.
```sh ```sh
$ (cd electron/spec && npm i --nodedir=../../third_party/electron_node) $ (cd electron/spec && npm i --nodedir=../../third_party/electron_node)

2
docs/development/coding-style.md
View file

@ -40,7 +40,7 @@ etc.
## Documentation ## Documentation
* Write [remark](https://github.com/remarkjs/remark) markdown style * Write [remark](https://github.com/remarkjs/remark) markdown style.
You can run `npm run lint-docs` to ensure that your documentation changes are You can run `npm run lint-docs` to ensure that your documentation changes are
formatted correctly. formatted correctly.

14
docs/development/debugging-instructions-macos-xcode.md
View file

@ -1,9 +1,9 @@
## Debugging with XCode ## Debugging with XCode
### Build Debug Electron with Release libchromiumcontent ### Build Debug Electron with Release libchromiumcontent
You can create a debug build of electron by following [build instructions for macOS](build-instructions-osx.md). You can create a debug build of Electron by following [build instructions for macOS](build-instructions-osx.md).
The bootstrap process will download Release version of libchromiumcontent by default, The bootstrap process will download Release version of libchromiumcontent by default,
so you will not be able to step through the chromium source. so you will not be able to step through the Chromium source.
### Build Debug Electron with Debug libchromiumcontent ### Build Debug Electron with Debug libchromiumcontent
If you want to debug and step through libchromiumcontent, you will have to run the If you want to debug and step through libchromiumcontent, you will have to run the
@ -25,7 +25,7 @@ Electron debug builds will use this shared library to link against.
```sh ```sh
$ ./script/build.py -c D --libcc $ ./script/build.py -c D --libcc
``` ```
This will build debug electron with debug version of libchromiumcontent. This will build debug Electron with debug version of libchromiumcontent.
### Generate xcode project for debugging sources (cannot build code from xcode) ### Generate xcode project for debugging sources (cannot build code from xcode)
Run the update script with the --xcode argument. Run the update script with the --xcode argument.
@ -37,14 +37,14 @@ to set breakpoints and inspect.
### Debugging and breakpoints ### Debugging and breakpoints
Launch electron app after build. Launch Electron app after build.
You can now open the xcode workspace created above and attach to the electron process You can now open the xcode workspace created above and attach to the Electron process
through the Debug > Attach To Process > Electron debug menu. [Note: If you want to debug through the Debug > Attach To Process > Electron debug menu. [Note: If you want to debug
the renderer process, you need to attach to the Electron Helper as well.] the renderer process, you need to attach to the Electron Helper as well.]
You can now set breakpoints in any of the indexed files. However, you will not be able You can now set breakpoints in any of the indexed files. However, you will not be able
to set breakpoints directly in the chromium source. to set breakpoints directly in the Chromium source.
To set break points in the chromium source, you can choose Debug > Breakpoints > Create To set break points in the Chromium source, you can choose Debug > Breakpoints > Create
Symbolic Breakpoint and set any function name as the symbol. This will set the breakpoint Symbolic Breakpoint and set any function name as the symbol. This will set the breakpoint
for all functions with that name, from all the classes if there are more than one. for all functions with that name, from all the classes if there are more than one.
You can also do this step of setting break points prior to attaching the debugger, You can also do this step of setting break points prior to attaching the debugger,

4
docs/tutorial/application-distribution.md
View file

@ -141,7 +141,7 @@ we appreciate your help.
2. Create a new S3 bucket and create the following empty directory structure: 2. Create a new S3 bucket and create the following empty directory structure:
```sh ```sh
- atom-shell/ - electron/
- symbols/ - symbols/
- dist/ - dist/
``` ```
@ -150,7 +150,7 @@ we appreciate your help.
* `ELECTRON_GITHUB_TOKEN` - a token that can create releases on GitHub * `ELECTRON_GITHUB_TOKEN` - a token that can create releases on GitHub
* `ELECTRON_S3_ACCESS_KEY`, `ELECTRON_S3_BUCKET`, `ELECTRON_S3_SECRET_KEY` - * `ELECTRON_S3_ACCESS_KEY`, `ELECTRON_S3_BUCKET`, `ELECTRON_S3_SECRET_KEY` -
the place where you'll upload node.js headers as well as symbols the place where you'll upload Node.js headers as well as symbols
* `ELECTRON_RELEASE` - Set to `true` and the upload part will run, leave unset * `ELECTRON_RELEASE` - Set to `true` and the upload part will run, leave unset
and `surf-build` will do CI-type checks, appropriate to run for every and `surf-build` will do CI-type checks, appropriate to run for every
pull request. pull request.

2
docs/tutorial/electron-versioning.md
View file

@ -49,7 +49,7 @@ Below is a table explicitly mapping types of changes to their corresponding cate
| Chromium version updates | | fix-related chromium patches | | Chromium version updates | | fix-related chromium patches |
Note that most chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches. Note that most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches.
# Stabilization Branches # Stabilization Branches

2
docs/tutorial/using-selenium-and-webdriver.md
View file

@ -164,7 +164,7 @@ To test your application without rebuilding Electron,
[place](https://github.com/electron/electron/blob/master/docs/tutorial/application-distribution.md) [place](https://github.com/electron/electron/blob/master/docs/tutorial/application-distribution.md)
your app source into Electron's resource directory. your app source into Electron's resource directory.
Alternatively, pass an argument to run with your electron binary that points to Alternatively, pass an argument to run with your Electron binary that points to
your app's folder. This eliminates the need to copy-paste your app into your app's folder. This eliminates the need to copy-paste your app into
Electron's resource directory. Electron's resource directory.