From 32f44d79176c6ed3650939e4070313400b3d0496 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Sat, 25 Feb 2017 18:59:13 -0800 Subject: [PATCH 1/5] add a guide to keyboard shortcuts --- docs/tutorial/shortcuts.md | 65 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/tutorial/shortcuts.md diff --git a/docs/tutorial/shortcuts.md b/docs/tutorial/shortcuts.md new file mode 100644 index 000000000000..215a6d47eb25 --- /dev/null +++ b/docs/tutorial/shortcuts.md @@ -0,0 +1,65 @@ +# Keyboard Shortcuts + +> Configure local and global keyboard shortcuts + +## 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.on('ready', () => { + globalShortcut.register('CommandOrControl+X', () => { + console.log('CommandOrControl+X is pressed') + }) +}) +``` + +## 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') } +})) +``` + +It's easy to configure different key combinations based on the user's operating system. + +```js +{ + accelerator: process.platform === 'darwin' ? 'Alt+Cmd+I' : 'Ctrl+Shift+I' +} +``` + + +## Local Shortcuts without a Menu + +If you want to configure a local keyboard shortcut to trigger an action that +_does not_ have a corresponding menu item, you can use the +[electron-localshortcut] npm module. + +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. + +[Menu]: ../api/menu.md +[MenuItem]: ../api/menu-item.md +[globalShortcut]: ../api/global-shortcut.md +[`accelerator`]: ../api/accelerator.md +[electron-localshortcut]: http://ghub.io/electron-localshortcut +[BrowserWindow]: ../api/browser-window.md From 5c6407503232f05f8819df2bea9df00cba605069 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Sat, 25 Feb 2017 19:07:09 -0800 Subject: [PATCH 2/5] add section for browser window events --- docs/tutorial/shortcuts.md | 35 ++++++++++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/docs/tutorial/shortcuts.md b/docs/tutorial/shortcuts.md index 215a6d47eb25..48caebd67255 100644 --- a/docs/tutorial/shortcuts.md +++ b/docs/tutorial/shortcuts.md @@ -42,13 +42,12 @@ It's easy to configure different key combinations based on the user's operating } ``` - -## Local Shortcuts without a Menu - If you want to configure a local keyboard shortcut to trigger an action that _does not_ have a corresponding menu item, you can use the [electron-localshortcut] npm module. +## 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 @@ -57,9 +56,39 @@ 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. +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', function () { console.log('4')}) +Mousetrap.bind('?', function () { console.log('show shortcuts!')}) +Mousetrap.bind('esc', function () { console.log('escape')}, 'keyup') + +// combinations +Mousetrap.bind('command+shift+k', function () { console.log('command shift k')}) + +// map multiple combinations to the same callback +Mousetrap.bind(['command+k', 'ctrl+k'], function () { + console.log('command k or control k') + + // return false to prevent default browser behavior + // and stop event from bubbling + return false +}) + +// gmail style sequences +Mousetrap.bind('g i', function () { console.log('go to inbox')}) +Mousetrap.bind('* a', function () { console.log('select all')}) + +// konami code! +Mousetrap.bind('up up down down left right left right b a enter', function () { + console.log('konami code') +}) +``` + [Menu]: ../api/menu.md [MenuItem]: ../api/menu-item.md [globalShortcut]: ../api/global-shortcut.md [`accelerator`]: ../api/accelerator.md [electron-localshortcut]: http://ghub.io/electron-localshortcut [BrowserWindow]: ../api/browser-window.md +[mousetrap]: https://github.com/ccampbell/mousetrap From ba4a2d7c307cc5fe9e57aab898f6b619babc1f81 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Sat, 25 Feb 2017 19:21:33 -0800 Subject: [PATCH 3/5] describe local shortcuts before global --- docs/tutorial/shortcuts.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/tutorial/shortcuts.md b/docs/tutorial/shortcuts.md index 48caebd67255..131406a98e7e 100644 --- a/docs/tutorial/shortcuts.md +++ b/docs/tutorial/shortcuts.md @@ -2,21 +2,6 @@ > Configure local and global keyboard shortcuts -## 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.on('ready', () => { - globalShortcut.register('CommandOrControl+X', () => { - console.log('CommandOrControl+X is pressed') - }) -}) -``` - ## Local Shortcuts You can use the [Menu] module to configure keyboard shortcuts that will @@ -46,6 +31,21 @@ If you want to configure a local keyboard shortcut to trigger an action that _does not_ have a corresponding menu item, you can use the [electron-localshortcut] npm module. +## 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.on('ready', () => { + 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. From f774ea857e7ee838f88460cc2ff35b1e6605f66a Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Mon, 27 Feb 2017 08:20:23 -0800 Subject: [PATCH 4/5] remove electron-localshortcut recommendation --- docs/tutorial/shortcuts.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/tutorial/shortcuts.md b/docs/tutorial/shortcuts.md index 131406a98e7e..dee0e10e177b 100644 --- a/docs/tutorial/shortcuts.md +++ b/docs/tutorial/shortcuts.md @@ -27,10 +27,6 @@ It's easy to configure different key combinations based on the user's operating } ``` -If you want to configure a local keyboard shortcut to trigger an action that -_does not_ have a corresponding menu item, you can use the -[electron-localshortcut] npm module. - ## Global Shortcuts You can use the [globalShortcut] module to detect keyboard events even when @@ -89,6 +85,5 @@ Mousetrap.bind('up up down down left right left right b a enter', function () { [MenuItem]: ../api/menu-item.md [globalShortcut]: ../api/global-shortcut.md [`accelerator`]: ../api/accelerator.md -[electron-localshortcut]: http://ghub.io/electron-localshortcut [BrowserWindow]: ../api/browser-window.md [mousetrap]: https://github.com/ccampbell/mousetrap From 250c656aa760fc8aa1d7ce315dd8664b1aefa3e6 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Mon, 27 Feb 2017 09:34:35 -0800 Subject: [PATCH 5/5] lint --- docs/tutorial/shortcuts.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/tutorial/shortcuts.md b/docs/tutorial/shortcuts.md index dee0e10e177b..9b20d23f6d6f 100644 --- a/docs/tutorial/shortcuts.md +++ b/docs/tutorial/shortcuts.md @@ -14,7 +14,7 @@ const menu = new Menu() menu.append(new MenuItem({ label: 'Print', - accelerator: 'CmdOrCtrl+P' + accelerator: 'CmdOrCtrl+P', click: () => { console.log('time to print stuff') } })) ``` @@ -55,28 +55,27 @@ Note the third parameter `true` which means the listener will always receive key 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', function () { console.log('4')}) -Mousetrap.bind('?', function () { console.log('show shortcuts!')}) -Mousetrap.bind('esc', function () { console.log('escape')}, 'keyup') +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', function () { console.log('command shift k')}) +Mousetrap.bind('command+shift+k', () => { console.log('command shift k') }) // map multiple combinations to the same callback -Mousetrap.bind(['command+k', 'ctrl+k'], function () { +Mousetrap.bind(['command+k', 'ctrl+k'], () => { console.log('command k or control k') - // return false to prevent default browser behavior - // and stop event from bubbling + // return false to prevent default behavior and stop event from bubbling return false }) // gmail style sequences -Mousetrap.bind('g i', function () { console.log('go to inbox')}) -Mousetrap.bind('* a', function () { console.log('select all')}) +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', function () { +Mousetrap.bind('up up down down left right left right b a enter', () => { console.log('konami code') }) ```