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

Merge branch 'master' into native-window-open

Browse source
This commit is contained in:
Ryohei Ikegami 2017-05-11 13:51:43 +09:00
commit 7ac93045b7
157 changed files with 2239 additions and 1058 deletions
Download patch file Download diff file Expand all files Collapse all files

1
docs/README.md
View file

@ -40,6 +40,7 @@ an issue:
* [Desktop Environment Integration](tutorial/desktop-environment-integration.md)
* [Online/Offline Event Detection](tutorial/online-offline-events.md)
* [REPL](tutorial/repl.md)
* [Native Notifications](tutorial/notifications.md)
## API References

4
docs/api/app.md
View file

@ -760,6 +760,10 @@ Disables hardware acceleration for current app.
This method can only be called before app is ready.
### `app.getAppMemoryInfo()`
Returns [ProcessMemoryInfo[]](structures/process-memory-info.md): Array of `ProcessMemoryInfo` objects that correspond to memory usage statistics of all the processes associated with the app.
### `app.setBadgeCount(count)` _Linux_ _macOS_
* `count` Integer

10
docs/api/browser-view.md
View file

@ -44,7 +44,7 @@ Objects created with `new BrowserView` have the following properties:
#### `view.webContents` _Experimental_
A [`webContents`](web-contents.md) object owned by this view.
A [`WebContents`](web-contents.md) object owned by this view.
#### `win.id` _Experimental_
@ -57,10 +57,10 @@ Objects created with `new BrowserWindow` have the following instance methods:
#### `win.setAutoResize(options)` _Experimental_
* `options` Object
* `width`: If `true`, the view's width will grow and shrink together with
the window. `false` by default.
* `height`: If `true`, the view's height will grow and shrink together with
the window. `false` by default.
* `width` Boolean - If `true`, the view's width will grow and shrink together
with the window. `false` by default.
* `height` Boolean - If `true`, the view's height will grow and shrink
together with the window. `false` by default.
#### `win.setBounds(bounds)` _Experimental_

16
docs/api/dialog.md
View file

@ -176,7 +176,7 @@ it is usually used to report errors in early stage of startup. If called
before the app `ready`event on Linux, the message will be emitted to stderr,
and no GUI dialog will appear.
### `dialog.showCertificateTrustDialog([browserWindow, ]options, callback)` _macOS_
### `dialog.showCertificateTrustDialog([browserWindow, ]options, callback)` _macOS_ _Windows_
* `browserWindow` BrowserWindow (optional)
* `options` Object
@ -184,11 +184,17 @@ and no GUI dialog will appear.
* `message` String - The message to display to the user.
* `callback` Function
Displays a modal dialog that shows a message and certificate information, and
gives the user the option of trusting/importing the certificate.
On macOS, this displays a modal dialog that shows a message and certificate
information, and gives the user the option of trusting/importing the
certificate. If you provide a `browserWindow` argument the dialog will be
attached to the parent window, making it modal.
The `browserWindow` argument allows the dialog to attach itself to a parent
window, making it modal.
On Windows the options are more limited, due to the Win32 APIs used:
- The `message` argument is not used, as the OS provides its own confirmation
dialog.
- The `browserWindow` argument is ignored since it is not possible to make
this confirmation dialog modal.
## Sheets

4
docs/api/ipc-main.md
View file

@ -16,8 +16,8 @@ It is also possible to send messages from the main process to the renderer
process, see [webContents.send][web-contents-send] for more information.
* When sending a message, the event name is the `channel`.
* To reply a synchronous message, you need to set `event.returnValue`.
* To send an asynchronous back to the sender, you can use
* To reply to a synchronous message, you need to set `event.returnValue`.
* To send an asynchronous message back to the sender, you can use
`event.sender.send(...)`.
An example of sending and handling messages between the render and main

147
docs/api/locales.md
View file

@ -8,132 +8,135 @@ values are listed below:
| Language Code | Language Name |
|---------------|---------------|
| af | Afrikaans |
| an | Aragonese |
| ar-AE | Arabic (U.A.E.) |
| ar-IQ | Arabic (Iraq) |
| ar | Arabic (Standard) |
| ar-BH | Arabic (Bahrain) |
| ar-DZ | Arabic (Algeria) |
| ar-EG | Arabic (Egypt) |
| ar-JO | Arabic (Jordan) |
| ar-KW | Arabic (Kuwait) |
| ar-LB | Arabic (Lebanon) |
| ar-LY | Arabic (Libya) |
| ar-MA | Arabic (Morocco) |
| ar-OM | Arabic (Oman) |
| ar-QA | Arabic (Qatar) |
| ar-SA | Arabic (Saudi Arabia) |
| ar-SY | Arabic (Syria) |
| ar-TN | Arabic (Tunisia) |
| ar-YE | Arabic (Yemen) |
| as | Assamese |
| ast | Asturian |
| am | Amharic |
| ar | Arabic |
| az | Azerbaijani |
| be | Belarusian |
| bg | Bulgarian |
| bg | Bulgarian |
| bh | Bihari |
| bn | Bengali |
| br | Breton |
| bs | Bosnian |
| ca | Catalan |
| ce | Chechen |
| ch | Chamorro |
| co | Corsican |
| cr | Cree |
| cs | Czech |
| cv | Chuvash |
| cy | Welsh |
| da | Danish |
| de | German (Standard) |
| de | German |
| de-AT | German (Austria) |
| de-CH | German (Switzerland) |
| de-DE | German (Germany) |
| de-LI | German (Liechtenstein) |
| de-LU | German (Luxembourg) |
| el | Greek |
| en-AU | English (Australia) |
| en-BZ | English (Belize) |
| en | English |
| en-AU | English (Australia) |
| en-CA | English (Canada) |
| en-GB | English (United Kingdom) |
| en-IE | English (Ireland) |
| en-JM | English (Jamaica) |
| en-GB | English (UK) |
| en-NZ | English (New Zealand) |
| en-PH | English (Philippines) |
| en-TT | English (Trinidad & Tobago) |
| en-US | English (United States) |
| en-US | English (US) |
| en-ZA | English (South Africa) |
| en-ZW | English (Zimbabwe) |
| eo | Esperanto |
| es | Spanish |
| es-419 | Spanish (Latin America) |
| et | Estonian |
| eu | Basque |
| fa | Persian |
| fa | Farsi |
| fa-IR | Persian/Iran |
| fi | Finnish |
| fj | Fijian |
| fo | Faeroese |
| fil | Filipino |
| fo | Faroese |
| fr | French |
| fr-CA | French (Canada) |
| fr-CH | French (Switzerland) |
| fr-FR | French (France) |
| fr-LU | French (Luxembourg) |
| fr-MC | French (Monaco) |
| fr | French (Standard) |
| fr-BE | French (Belgium) |
| fr-CA | French (Canada) |
| fur | Friulian |
| fy | Frisian |
| ga | Irish |
| gd-IE | Gaelic (Irish) |
| gd | Gaelic (Scots) |
| gl | Galacian |
| gu | Gujurati |
| gd | Scots Gaelic |
| gl | Galician |
| gn | Guarani |
| gu | Gujarati |
| ha | Hausa |
| haw | Hawaiian |
| he | Hebrew |
| hi | Hindi |
| hr | Croatian |
| ht | Haitian |
| hu | Hungarian |
| hy | Armenian |
| ia | Interlingua |
| id | Indonesian |
| is | Icelandic |
| it | Italian |
| it-CH | Italian (Switzerland) |
| it | Italian (Standard) |
| iu | Inuktitut |
| it-IT | Italian (Italy) |
| ja | Japanese |
| jw | Javanese |
| ka | Georgian |
| kk | Kazakh |
| km | Khmer |
| km | Cambodian |
| kn | Kannada |
| ko | Korean |
| ko-KP | Korean (North Korea) |
| ko-KR | Korean (South Korea) |
| ks | Kashmiri |
| ky | Kirghiz |
| ku | Kurdish |
| ky | Kyrgyz |
| la | Latin |
| lb | Luxembourgish |
| ln | Lingala |
| lo | Laothian |
| lt | Lithuanian |
| lv | Latvian |
| mi | Maori |
| mk | FYRO Macedonian |
| mk | Macedonian |
| ml | Malayalam |
| mn | Mongolian |
| mo | Moldavian |
| mr | Marathi |
| ms | Malay |
| mt | Maltese |
| my | Burmese |
| nb | Norwegian (Bokmal) |
| ne | Nepali |
| ng | Ndonga |
| nl | Dutch (Standard) |
| nl-BE | Dutch (Belgian) |
| nl | Dutch |
| nn | Norwegian (Nynorsk) |
| no | Norwegian |
| nv | Navajo |
| oc | Occitan |
| om | Oromo |
| or | Oriya |
| pa | Punjabi |
| pl | Polish |
| ps | Pashto |
| pt | Portuguese |
| pt-BR | Portuguese (Brazil) |
| pt-PT | Portuguese (Portugal) |
| qu | Quechua |
| rm | Romansh |
| ro | Romanian |
| ru | Russian |
| sd | Sindhi |
| sh | Serbo-Croatian |
| si | Sinhalese |
| sk | Slovak |
| sl | Slovenian |
| sn | Shona |
| so | Somali |
| sq | Albanian |
| tlh | Klingon |
| zh-TW | Chinese (Taiwan) |
| sr | Serbian |
| st | Sesotho |
| su | Sundanese |
| sv | Swedish |
| sw | Swahili |
| ta | Tamil |
| te | Telugu |
| tg | Tajik |
| th | Thai |
| ti | Tigrinya |
| tk | Turkmen |
| to | Tonga |
| tr | Turkish |
| tt | Tatar |
| tw | Twi |
| ug | Uighur |
| uk | Ukrainian |
| ur | Urdu |
| uz | Uzbek |
| vi | Vietnamese |
| xh | Xhosa |
| yi | Yiddish |
| yo | Yoruba |
| zh | Chinese |
| zh-CN | Chinese (PRC) |
| zh-HK | Chinese (Hong Kong) |
| zh-SG | Chinese (Singapore) |
| zh-CN | Chinese (Simplified) |
| zh-TW | Chinese (Traditional) |
| zu | Zulu |

2
docs/api/menu.md
View file

@ -241,7 +241,7 @@ Linux. Here are some notes on making your app's menu more native-like.
On macOS there are many system-defined standard menus, like the `Services` and
`Windows` menus. To make your menu a standard menu, you should set your menu's
`role` to one of following and Electron will recognize them and make them
`role` to one of the following and Electron will recognize them and make them
become standard menus:
* `window`

12
docs/api/process.md
View file

@ -116,3 +116,15 @@ Returns `Object`:
Returns an object giving memory usage statistics about the entire system. Note
that all statistics are reported in Kilobytes.
### `process.getCPUUsage()`
Returns:
* `CPUUsage` [CPUUsage](structures/cpu-usage.md)
### `process.getIOCounters()` _Windows_ _Linux_
Returns:
* `IOCounters` [IOCounters](structures/io-counters.md)

6
docs/api/structures/cpu-usage.md Normal file
View file

@ -0,0 +1,6 @@
# CPUUsage Object
* `percentCPUUsage` Number - Percentage of CPU used since the last call to getCPUUsage.
First call returns 0.
* `idleWakeupsPerSecond` Number - The number of average idle cpu wakeups per second
since the last call to getCPUUsage. First call returns 0.

8
docs/api/structures/io-counters.md Normal file
View file

@ -0,0 +1,8 @@
# IOCounters Object
* `readOperationCount` Number - The number of I/O read operations.
* `writeOperationCount` Number - The number of I/O write operations.
* `otherOperationCount` Number - Then number of I/O other operations.
* `readTransferCount` Number - The number of I/O read transfers.
* `writeTransferCount` Number - The number of I/O write transfers.
* `otherTransferCount` Number - Then number of I/O other transfers.

12
docs/api/structures/memory-info.md Normal file
View file

@ -0,0 +1,12 @@
# MemoryInfo Object
* `pid` Integer - Process id of the process.
* `workingSetSize` Integer - The amount of memory currently pinned to actual physical RAM.
* `peakWorkingSetSize` Integer - The maximum amount of memory that has ever been pinned
to actual physical RAM.
* `privateBytes` Integer - The amount of memory not shared by other processes, such as
JS heap or HTML content.
* `sharedBytes` Integer - The amount of memory shared between processes, typically
memory consumed by the Electron code itself
Note that all statistics are reported in Kilobytes.

4
docs/api/structures/process-memory-info.md Normal file
View file

@ -0,0 +1,4 @@
# ProcessMemoryInfo Object
* `pid` Integer - Process id of the process.
* `memory` [MemoryInfo](memory-info.md) - Memory information of the process.

11
docs/api/touch-bar-segmented-control.md
View file

@ -21,10 +21,15 @@ Process: [Main](../tutorial/quick-start.md#main-process)
* `small-square` - The control is displayed using the small square style.
* `separated` - The segments in the control are displayed very close to each
other but not touching.
* `segments` [SegmentedControlSegment[]](structures/segmented-control-segment.md) - An array of segments to place in this control
* `selectedIndex` Integer (Optional) - The index of the currently selected segment, will update automatically with user interaction
* `mode` String - (Optional) The selection mode of the control:
* `single` - Default. One item selected at a time, selecting one deselects the previously selected item.
* `multiple` - Multiple items can be selected at a time.
* `buttons` - Make the segments act as buttons, each segment can be pressed and released but never marked as active.
* `segments` [SegmentedControlSegment[]](structures/segmented-control-segment.md) - An array of segments to place in this control.
* `selectedIndex` Integer (Optional) - The index of the currently selected segment, will update automatically with user interaction. When the mode is multiple it will be the last selected item.
* `change` Function - Called when the user selects a new segment
* `selectedIndex` Integer - The index of the segment the user selected
* `selectedIndex` Integer - The index of the segment the user selected.
* `isSelected` Boolean - Whether as a result of user selection the segment is selected or not.
### Instance Properties

10
docs/api/touch-bar.md
View file

@ -138,3 +138,13 @@ app.once('ready', () => {
window.setTouchBar(touchBar)
})
```
### Running the above example
To run the example above, you'll need to (assuming you've got a terminal open in the dirtectory you want to run the example):
1. Save the above file to your computer as `touchbar.js`
2. Install Electron via `npm install electron`
3. Run the example inside Electron: `./node_modules/.bin/electron touchbar.js`
You should then see a new Electron window and the app running in your touch bar (or touch bar emulator).

2
docs/glossary.md
View file

@ -127,7 +127,7 @@ available in "core".
### V8
V8 is Google's open source JavaScript engine. It is written in C++ and is
used in Google Chrome, the open source browser from Google. V8 can run
used in Google Chrome. V8 can run
standalone, or can be embedded into any C++ application.
### webview

50
docs/tutorial/desktop-environment-integration.md
View file

@ -8,55 +8,9 @@ applications can put a custom menu in the dock menu.
This guide explains how to integrate your application into those desktop
environments with Electron APIs.
## Notifications (Windows, Linux, macOS)
## Notifications
All three operating systems provide means for applications to send notifications
to the user. Electron conveniently allows developers to send notifications with
the [HTML5 Notification API](https://notifications.spec.whatwg.org/), using
the currently running operating system's native notification APIs to display it.
**Note:** Since this is an HTML5 API it is only available in the renderer process.
```javascript
let myNotification = new Notification('Title', {
body: 'Lorem Ipsum Dolor Sit Amet'
})
myNotification.onclick = () => {
console.log('Notification clicked')
}
```
While code and user experience across operating systems are similar, there
are fine differences.
### Windows
* On Windows 10, notifications "just work".
* On Windows 8.1 and Windows 8, a shortcut to your app, with a [Application User
Model ID][app-user-model-id], must be installed to the Start screen. Note,
however, that it does not need to be pinned to the Start screen.
* On Windows 7, notifications work via a custom implemetation which visually
resembles the native one on newer systems.
Furthermore, the maximum length for the notification body is 250 characters,
with the Windows team recommending that notifications should be kept to 200
characters.
### Linux
Notifications are sent using `libnotify`, it can show notifications on any
desktop environment that follows [Desktop Notifications
Specification][notification-spec], including Cinnamon, Enlightenment, Unity,
GNOME, KDE.
### macOS
Notifications are straight-forward on macOS, you should however be aware of
[Apple's Human Interface guidelines regarding notifications](https://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/OSXHIGuidelines/NotificationCenter.html).
Note that notifications are limited to 256 bytes in size - and will be truncated
if you exceed that limit.
See [Notifications](notifications.md)
## Recent documents (Windows & macOS)

85
docs/tutorial/notifications.md Normal file
View file

@ -0,0 +1,85 @@
# Notifications (Windows, Linux, macOS)
All three operating systems provide means for applications to send notifications
to the user. Electron conveniently allows developers to send notifications with
the [HTML5 Notification API](https://notifications.spec.whatwg.org/), using
the currently running operating system's native notification APIs to display it.
**Note:** Since this is an HTML5 API it is only available in the renderer process.
```javascript
let myNotification = new Notification('Title', {
body: 'Lorem Ipsum Dolor Sit Amet'
})
myNotification.onclick = () => {
console.log('Notification clicked')
}
```
While code and user experience across operating systems are similar, there
are subtle differences.
## Windows
* On Windows 10, notifications "just work".
* On Windows 8.1 and Windows 8, a shortcut to your app, with an [Application User
Model ID][app-user-model-id], must be installed to the Start screen. Note,
however, that it does not need to be pinned to the Start screen.
* On Windows 7, notifications work via a custom implementation which visually
resembles the native one on newer systems.
Furthermore, in Windows 8, the maximum length for the notification body is 250
characters, with the Windows team recommending that notifications should be kept
to 200 characters. That said, that limitation has been removed in Windows 10, with
the Windows team asking developers to be reasonable. Attempting to send gigantic
amounts of text to the API (thousands of characters) might result in instability.
### Advanced Notifications
Later versions of Windows allow for advanced notifications, with custom templates,
images, and other flexible elements. To send those notifications (from either the
main process or the renderer process), use the userland module
[electron-windows-notifications](https://github.com/felixrieseberg/electron-windows-notifications),
which uses native Node addons to send `ToastNotification` and `TileNotification` objects.
While notifications including buttons work with just `electron-windows-notifications`,
handling replies requires the use of [`electron-windows-interactive-notifications`](https://github.com/felixrieseberg/electron-windows-interactive-notifications), which
helps with registering the required COM components and calling your Electron app with
the entered user data.
### Quiet Hours / Presentation Mode
To detect whether or not you're allowed to send a notification, use the userland module
[electron-notification-state](https://github.com/felixrieseberg/electron-notification-state).
This allows you to determine ahead of time whether or not Windows will silently throw
the notification away.
## macOS
Notifications are straight-forward on macOS, but you should be aware of
[Apple's Human Interface guidelines regarding notifications](https://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/OSXHIGuidelines/NotificationCenter.html).
Note that notifications are limited to 256 bytes in size and will be truncated
if you exceed that limit.
### Advanced Notifications
Later versions of macOS allow for notifications with an input field, allowing the user
to quickly reply to a notification. In order to send notifications with an input field,
use the userland module [node-mac-notifier](https://github.com/CharlieHess/node-mac-notifier).
### Do not disturb / Session State
To detect whether or not you're allowed to send a notification, use the userland module
[electron-notification-state](https://github.com/felixrieseberg/electron-notification-state).
This will allow you to detect ahead of time whether or not the notification will be displayed.
## Linux
Notifications are sent using `libnotify` which can show notifications on any
desktop environment that follows [Desktop Notifications
Specification][notification-spec], including Cinnamon, Enlightenment, Unity,
GNOME, KDE.

8
docs/tutorial/quick-start.md
View file

@ -192,10 +192,10 @@ $ .\node_modules\.bin\electron .
If you downloaded Electron manually, you can also use the included
binary to execute your app directly.
#### Windows
#### macOS
```bash
$ .\electron\electron.exe your-app\
$ ./Electron.app/Contents/MacOS/Electron your-app/
```
#### Linux
@ -204,10 +204,10 @@ $ .\electron\electron.exe your-app\
$ ./electron/electron your-app/
```
#### macOS
#### Windows
```bash
$ ./Electron.app/Contents/MacOS/Electron your-app/
$ .\electron\electron.exe your-app\
```
`Electron.app` here is part of the Electron's release package, you can download