diff options
Diffstat (limited to 'doc/development/fe_guide/keyboard_shortcuts.md')
-rw-r--r-- | doc/development/fe_guide/keyboard_shortcuts.md | 63 |
1 files changed, 44 insertions, 19 deletions
diff --git a/doc/development/fe_guide/keyboard_shortcuts.md b/doc/development/fe_guide/keyboard_shortcuts.md index e50e9ec65df..aab252da305 100644 --- a/doc/development/fe_guide/keyboard_shortcuts.md +++ b/doc/development/fe_guide/keyboard_shortcuts.md @@ -33,9 +33,10 @@ Mousetrap.bind(keysFor(TOGGLE_PERFORMANCE_BAR), togglePerformanceBar); ## Shortcut customization `keybindings.js` stores keyboard shortcut customizations as a JSON string in -`localStorage`. When `keybindings.js` is first imported, it fetches any -customizations from `localStorage` and merges these customizations into the -default set of keybindings. There is no UI to edit these customizations. +`localStorage`. When `keysFor` is called, it uses the provided command object's +`id` to lookup any customizations found in `localStorage` and returns the custom +keybindings, or the default keybindings if the command has not been customized. +There is no UI to edit these customizations. ## Adding new shortcuts @@ -44,27 +45,33 @@ developers are encouraged to build _lots_ of keyboard shortcuts into GitLab. Shortcuts that are less likely to be used should be [disabled](#disabling-shortcuts) by default. -To add a new shortcut, define and export a new command string in +To add a new shortcut, define and export a new command object in `keybindings.js`: ```javascript -export const MAKE_COFFEE = 'foodAndBeverage.makeCoffee'; +export const MAKE_COFFEE = { + id: 'foodAndBeverage.makeCoffee', + description: s__('KeyboardShortcuts|Make coffee'), + defaultKeys: ['mod+shift+c'], +}; ``` -Next, add a new command definition under the appropriate group in the -`keybindingGroups` array: +Next, add a new command to the appropriate keybinding group object: ```javascript -{ - description: s__('KeyboardShortcuts|Make coffee'), - command: MAKE_COFFEE, - defaultKeys: ['mod+shift+c'], - customKeys: customizations[MAKE_COFFEE], +const COFFEE_GROUP = { + id: 'foodAndBeverage', + name: s__('KeyboardShortcuts|Food and Beverage'), + keybindings: [ + MAKE_ESPRESSO, + MAKE_LATTE, + MAKE_COFFEE + ]; } ``` Finally, in the application code, import the `keysFor` function and the new -command and bind the shortcut to the handler using Mousetrap: +command object and bind the shortcut to the handler using Mousetrap: ```javascript import { keysFor, MAKE_COFFEE } from '~/behaviors/shortcuts/keybindings' @@ -81,16 +88,34 @@ shortcut to an empty array `[]`. For example, to introduce a new shortcut that is disabled by default, a command can be defined like this: ```javascript -export const MAKE_MOCHA = 'foodAndBeverage.makeMocha'; - -{ +export const MAKE_MOCHA = { + id: 'foodAndBeverage.makeMocha', description: s__('KeyboardShortcuts|Make a mocha'), - command: MAKE_MOCHA, defaultKeys: [], - customKeys: customizations[MAKE_MOCHA], -} +}; ``` +## Making shortcuts non-customizable + +Occasionally, it's important that a keyboard shortcut _not_ be customizable +(although this should be a rare occurrence). + +In this case, a shortcut can be defined with `customizable: false`, which +disables customization of the keybinding: + +```javascript +export const MAKE_AMERICANO = { + id: 'foodAndBeverage.makeAmericano', + description: s__('KeyboardShortcuts|Make an Americano'), + defaultKeys: ['mod+shift+a'], + + // this disables customization of this shortcut + customizable: false +}; +``` + +This shortcut will always be bound to its `defaultKeys`. + ## Make cross-platform shortcuts It's difficult to make shortcuts that work well in all platforms and browsers. |