documentation/shortcuts.md

   1 <!--
   2 This is part of the VimFx documentation.
   3 Copyright Simon Lydell 2015.
   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 settings 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 ## Key notation
  14
  15 VimFx’s key notation is inspired by Vim’s key notation. An example:
  16
  17     J  gT  <c-s-tab>  g<left>  <c-j>
  18
  19 The above defines five alternative shortcuts. The odd ones consist of one key
  20 each, while the even ones consist of two. Letters can be written as they are,
  21 while non-letter keys like Tab and the arrow keys need to be put inside `<` and
  22 `>`. Letters also need to be put inside `<` and `>` if you want to specify a
  23 modifier (as in the `<c-j>` example, which might be notated as “CTRL+J” in some
  24 other programs.)
  25
  26 If you’re usure on how to express a key press you’d like to use as part of a
  27 shortcut, press `<c-q>` while inside one of the text inputs for a command and
  28 then press your desired key (optionally holding modifier keys). That will paste
  29 the key notation for that particular key press into the text input. `<c-d>`
  30 pastes the default shortcut(s), and `<c-r>` resets the text input to the default
  31 entirely. You can of course use the standard `<c-z>` to undo.
  32
  33 You can specify any number of shortcuts for every command. Separate them from
  34 each other by one or more spaces.
  35
  36 A _shortcut_ consists of one or more _keys_ that you need to press in order to
  37 activate the command. (See also the [timeout] option.)
  38
  39 A _key_ corresponds to pressing a single key on your keyboard, optionally while
  40 holding one or more _modifiers._ The following modifiers are recognized:
  41
  42 - a: alt
  43 - c: control (also known as ctrl)
  44 - m: meta
  45 - s: shift
  46
  47 (Which of the above you can actually use depends on your operating system.)
  48
  49 If you’d like to know even more about the key notation, see
  50 [vim-like-key-notation].
  51
  52 [timeout]: options.md#timeout
  53 [vim-like-key-notation]: https://github.com/lydell/vim-like-key-notation
  54
  55 ## Special keys
  56
  57 Just like Vim, VimFx has a few “special keys:”
  58
  59 - [`<force>`]
  60 - [`<late>`]
  61
  62 No keyboard (or keyboard layout) can produce those (in practise). As a
  63 consequence, putting one of those “keys” in a shortcut would normally make it
  64 impossible to trigger. However, that is not the case for special keys.
  65
  66 By putting a special key at the beginning of a shortcut, the shortcut will work
  67 exactly as it would without the special key, except that some behavior of the
  68 shortcut is changed (depending on the special key used). Special keys specify an
  69 _option_ for the shortcut rather than a key to press in order to activate the
  70 command.
  71
  72 Each special key is described below.
  73
  74 [`<force>`]: #force
  75 [`<late>`]: #late
  76
  77 ### `<force>`
  78
  79 The `<force>` special key makes the shortcut in question available in text
  80 inputs.
  81
  82 VimFx enters a kind of “automatic insert mode” when you focus a text input,
  83 allowing you to type text into it without triggering VimFx commands. The `esc`
  84 command, however, is still available, allowing you to blur the text input by
  85 pressing `<escape>`. The reason it is available is because the default shortcut
  86 is `<force><escape>`.
  87
  88 Using `<force>` allows you to run other commands in text inputs as well. For
  89 example, you could use `<force><a-j>` and `<force><a-k>` to be able to select
  90 tab backward and forward regardless if you happen to be in a text input or not.
  91
  92 ### `late`
  93
  94 The `<late>` special key makes the shortcut in question run _after_ the handling
  95 of key presses in the current page, allowing the current page to override it.
  96
  97 Normally, all of VimFx’s shortcuts are triggered _before_ the current page gets
  98 the key presses. This makes the VimFx shortcuts work consistently regardless of
  99 what the current page happens to be up to.
 100
 101 Sometimes, though, it is useful to let the page override a shortcut. For
 102 example, the [focus next/previous element] commands, use `<late>` in their
 103 default shorcuts: `<force><late><tab>` and `<force><late><s-tab>`, respectively.
 104 `<force>` is there so that you can press `<tab>` inside a text input to get to
 105 the next one; `<late>` lets the page offer tab completion instead, for example.
 106
 107 `<late>` is also useful if you plan to use the arrow keys for VimFx’s scrolling
 108 commands, while still being able to move the focus in the custom menus some
 109 sites use.
 110
 111 [focus next/previous element]: commands.md#focus-nextprevious-element