documentation/shortcuts.md

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