documentation/shortcuts.md

   1 <!--
   2 This is part of the VimFx documentation.
   3 Copyright Simon Lydell 2015, 2016.
   4 See the file README.md for copying conditions.
   5 -->
   6
   7 # Shortcuts
   8
   9 All of VimFx’s keyboard shortcuts can be customized in VimFx’s options page in
  10 the Add-ons Manager. Doing so is really easy. You get far just by looking at the
  11 defaults and trying things out. If not, read on.
  12
  13 In VimFx’s Keyboard Shortcuts help dialog (which can be opened by pressing `?`)
  14 you can click any command to open VimFx’s options page in the Add-ons Manager
  15 and automatically select the text input for that command. Tip: Use the `eb`
  16 command to click without using the mouse.
  17
  18 Shortcuts tell which keys to press to activate a command. A command may have
  19 several different shortcuts. Read about [modes] for more information.
  20
  21 This file documents how the shortcuts work in general, not the [default
  22 shortcuts] or details on what the [_command_][commands] for a shortcut does.
  23
  24 [modes]: modes.md
  25 [default shortcuts]: https://github.com/akhodakivskiy/VimFx/blob/master/extension/lib/defaults.coffee
  26 [commands]: commands.md
  27
  28
  29 ## Key notation
  30
  31 VimFx’s key notation is inspired by Vim’s key notation.
  32
  33 Here is an example of what you can type into a text input for a command in
  34 VimFx’s options page in the Add-ons Manager:
  35
  36     J  <c-s-tab>  <c-j>  gT  g<left>
  37
  38 The above defines five alternative shortcuts for the same command. The first
  39 three consist of one key each, while the rest consist of two. Letters can be
  40 written as they are, while non-letter keys like Tab and the arrow keys need to
  41 be put inside `<` and `>`. If you want to specify a modifier, then letters need
  42 to be put inside `<` and `>` as well (as in the `<c-j>` example, which might be
  43 notated as “CTRL+J” in some other programs.)
  44
  45 If you’re usure on how to express a key press you’d like to use as part of a
  46 shortcut, press `<c-q>` while inside one of the text inputs for a command and
  47 then press your desired key (optionally holding modifier keys). That will paste
  48 the key notation for that particular key press into the text input. `<c-d>`
  49 pastes the default shortcut(s), and `<c-r>` resets the text input to the default
  50 entirely. You can of course use the standard `<c-z>` to undo.
  51
  52 You can specify any number of shortcuts for every command. Separate them from
  53 each other by one or more spaces.
  54
  55 Here is a more formal description of all of the above:
  56
  57 A _shortcut_ consists of one or more _keys_ that you need to press in order to
  58 activate the command. (See also the [timeout] option.)
  59
  60 A _key_ corresponds to pressing a single key on your keyboard, optionally while
  61 holding one or more _modifiers._ The following modifiers are recognized:
  62
  63 - a: alt
  64 - c: control (also known as ctrl)
  65 - m: meta
  66 - s: shift
  67
  68 (Which of the above you can actually use depends on your operating system.)
  69
  70 If you’d like to know even more about the key notation, see
  71 [vim-like-key-notation].
  72
  73 [timeout]: options.md#timeout
  74 [vim-like-key-notation]: https://github.com/lydell/vim-like-key-notation
  75
  76
  77 ## Tips
  78
  79 If you use more than one keyboard layout, remember to check out the [Ignore
  80 keyboard layout] option.
  81
  82 If you’d like see what VimFx interprets a key stroke as, you can (ab)use the
  83 [`m`] command. Press `m` followed by your desired key stroke. A [notification]
  84 will appear, including the interpreted key notation for that key press.
  85
  86 [Ignore keyboard layout]: options.md#ignore-keyboard-layout
  87 [`m`]: commands.md#marks-m-and-
  88 [notification]: notifications.md
  89
  90
  91 ## Special keys
  92
  93 Just like Vim, VimFx has a few “special keys:”
  94
  95 - [`<force>`]
  96 - [`<late>`]
  97
  98 No keyboard (or keyboard layout) can produce those (in practise). As a
  99 consequence, putting one of those “keys” in a shortcut would normally make it
 100 impossible to trigger. However, that is not the case for special keys.
 101
 102 By putting a special key at the beginning of a shortcut, the shortcut will work
 103 exactly as it would without the special key, except that some behavior of the
 104 shortcut is changed (depending on the special key used). Special keys specify an
 105 _option_ for the shortcut rather than a key to press in order to activate the
 106 command.
 107
 108 Each special key is described below.
 109
 110 [`<force>`]: #force
 111 [`<late>`]: #late
 112
 113 ### `<force>`
 114
 115 The `<force>` special key makes the shortcut in question available in text
 116 inputs.
 117
 118 VimFx enters a kind of “automatic insert mode” when you focus a text input,
 119 allowing you to type text into it without triggering VimFx commands. The `esc`
 120 command, however, is still available, allowing you to blur the text input by
 121 pressing `<escape>`. The reason it is available is because the default shortcut
 122 is `<force><escape>`.
 123
 124 Using `<force>` allows you to run other commands in text inputs as well. For
 125 example, you could use `<force><a-j>` and `<force><a-k>` to be able to select
 126 tab backward and forward regardless if you happen to be in a text input or not.
 127
 128 Notice that VimFx’s [button] turns grey when you’re in this “automatic insert
 129 mode.”
 130
 131 [button]: button.md
 132
 133 ### `<late>`
 134
 135 The `<late>` special key makes the shortcut in question run _after_ the handling
 136 of key presses in the current page, allowing the current page to override it.
 137
 138 Normally, all of VimFx’s shortcuts are triggered _before_ the current page gets
 139 the key presses. This makes the VimFx shortcuts work consistently regardless of
 140 what the current page happens to be up to.
 141
 142 Sometimes, though, it is useful to let the page override a shortcut. For
 143 example, if you plan to use the arrow keys for VimFx’s scrolling commands, while
 144 still being able to move the focus in the custom menus some sites use.