c83f836faf
* docs: add references to app.whenReady() in isReady
* refactor: prefer app.whenReady()
In the docs, specs, and lib, replace instances of `app.once('ready')`
(seen occasionally) and `app.on('ready')` (extremely common) with
`app.whenReady()`.
It's better to encourage users to use whenReady():
1. it handles the edge case of registering for 'ready' after it's fired
2. it avoids the minor wart of leaving an active listener alive for
an event that wll never fire again
92 lines
2.8 KiB
Markdown
92 lines
2.8 KiB
Markdown
# Keyboard Shortcuts
|
|
|
|
> Configure local and global keyboard shortcuts
|
|
|
|
## Local Shortcuts
|
|
|
|
You can use the [Menu] module to configure keyboard shortcuts that will
|
|
be triggered only when the app is focused. To do so, specify an
|
|
[`accelerator`] property when creating a [MenuItem].
|
|
|
|
```js
|
|
const { Menu, MenuItem } = require('electron')
|
|
const menu = new Menu()
|
|
|
|
menu.append(new MenuItem({
|
|
label: 'Print',
|
|
accelerator: 'CmdOrCtrl+P',
|
|
click: () => { console.log('time to print stuff') }
|
|
}))
|
|
```
|
|
|
|
You can configure different key combinations based on the user's operating system.
|
|
|
|
```js
|
|
{
|
|
accelerator: process.platform === 'darwin' ? 'Alt+Cmd+I' : 'Ctrl+Shift+I'
|
|
}
|
|
```
|
|
|
|
## Global Shortcuts
|
|
|
|
You can use the [globalShortcut] module to detect keyboard events even when
|
|
the application does not have keyboard focus.
|
|
|
|
```js
|
|
const { app, globalShortcut } = require('electron')
|
|
|
|
app.whenReady().then(() => {
|
|
globalShortcut.register('CommandOrControl+X', () => {
|
|
console.log('CommandOrControl+X is pressed')
|
|
})
|
|
})
|
|
```
|
|
|
|
## Shortcuts within a BrowserWindow
|
|
|
|
If you want to handle keyboard shortcuts for a [BrowserWindow], you can use the `keyup` and `keydown` event listeners on the window object inside the renderer process.
|
|
|
|
```js
|
|
window.addEventListener('keyup', doSomething, true)
|
|
```
|
|
|
|
Note the third parameter `true` which means the listener will always receive key presses before other listeners so they can't have `stopPropagation()` called on them.
|
|
|
|
The [`before-input-event`](../api/web-contents.md#event-before-input-event) event
|
|
is emitted before dispatching `keydown` and `keyup` events in the page. It can
|
|
be used to catch and handle custom shortcuts that are not visible in the menu.
|
|
|
|
If you don't want to do manual shortcut parsing there are libraries that do advanced key detection such as [mousetrap].
|
|
|
|
```js
|
|
Mousetrap.bind('4', () => { console.log('4') })
|
|
Mousetrap.bind('?', () => { console.log('show shortcuts!') })
|
|
Mousetrap.bind('esc', () => { console.log('escape') }, 'keyup')
|
|
|
|
// combinations
|
|
Mousetrap.bind('command+shift+k', () => { console.log('command shift k') })
|
|
|
|
// map multiple combinations to the same callback
|
|
Mousetrap.bind(['command+k', 'ctrl+k'], () => {
|
|
console.log('command k or control k')
|
|
|
|
// return false to prevent default behavior and stop event from bubbling
|
|
return false
|
|
})
|
|
|
|
// gmail style sequences
|
|
Mousetrap.bind('g i', () => { console.log('go to inbox') })
|
|
Mousetrap.bind('* a', () => { console.log('select all') })
|
|
|
|
// konami code!
|
|
Mousetrap.bind('up up down down left right left right b a enter', () => {
|
|
console.log('konami code')
|
|
})
|
|
```
|
|
|
|
[Menu]: ../api/menu.md
|
|
[MenuItem]: ../api/menu-item.md
|
|
[globalShortcut]: ../api/global-shortcut.md
|
|
[`accelerator`]: ../api/accelerator.md
|
|
[BrowserWindow]: ../api/browser-window.md
|
|
[mousetrap]: https://github.com/ccampbell/mousetrap
|