documentation/commands.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 # Commands
   8
   9 Most of VimFx’s commands are straight-forward enough to not need any
  10 documentation. For some commands, though, there is a bit more to know.
  11
  12 In this document, many commands are referred to by their default shortcut. You
  13 can of course [change those] if you like.
  14
  15 [change those]: shortcuts.md
  16
  17 ## Counts
  18
  19 Some commands support _counts._ That means that you can type a number before a
  20 command and it will change its behavior based on that number—the count. For
  21 example, typing `12x` would close 12 tabs.
  22
  23 (As opposed to vim, you may only supply a count _before_ a command, not in the
  24 middle of one. This is because VimFx’s commands are simple sequences, while
  25 vim’s are operators and motions.)
  26
  27 ### `gu`
  28
  29 Goes _count_ levels up in the URL hierarchy.
  30
  31 ### `H` and `L`
  32
  33 Goes _count_ pages backward/forward in history.
  34
  35 ### Scrolling commands
  36
  37 Specifying a count make them scroll _count_ times as far.
  38
  39 ### `J`, `K`
  40
  41 Selects the tab _count_ tabs backward/forward.
  42
  43 If the count is greater than one they don’t wrap around when reaching the ends
  44 of the tab bar.
  45
  46 ### `gJ`, `gK`
  47
  48 Moves the current tab _count_ tabs forward/backward.
  49
  50 If the count is greater than one they don’t wrap around when reaching the ends
  51 of the tab bar.
  52
  53 ### `g0`, `g^`, `g$`
  54
  55 `g0` selects the tab at index _count,_ counting from the start.
  56
  57 `g^` selects the tab at index _count,_ counting from the first non-pinned tab.
  58
  59 `g$` selects the tab at index _count,_ counting from the end.
  60
  61 ### `x`
  62
  63 Closes the current tab and _count_ minus one of the following tabs.
  64
  65 ### `X`
  66
  67 Restores the _count_ last closed tabs.
  68
  69 ### `I`
  70
  71 Passes on the next _count_ keypresses to the page, without activating VimFx
  72 commands.
  73
  74 ### The `f` commands
  75
  76 Explained in the their own section below.
  77
  78 ### `gi`
  79
  80 Explained in its own section below.
  81
  82
  83 ## Scrolling commands
  84
  85 Firefox lets you scroll with the arrow keys, page down, page up, home, end and
  86 space by default. VimFx provides similar scrolling commands (and actually
  87 overrides `<space>`), but they work a little bit differently.
  88
  89 They scroll _the currently focused element._ If the currently focused element
  90 isn’t scrollable, or there is no (apparent) currently focused element, the
  91 entire page is scrolled. Finally, if the entire page isn’t scrollable, the
  92 largest scrollable element on the page (if any) is scrolled.
  93
  94 You can focus scrollable elements using the `zf` command (or the `f` command).
  95 The right border of hint markers for scrollable elements is styled to remind of
  96 a scroll bar, making them easier to recognize among hints for links.
  97
  98
  99 ## `gi`
 100
 101 `gi` focuses the text input you last used, or the first one on the page. Note
 102 that a [prevented autofocus] still counts as having focused and used a text
 103 input. This allows you to have your cake and eat it too: You can enable
 104 autofocus prevention, and type `gi` when you wish you hadn’t.
 105
 106 `gi` takes a count. It then selects the `counth` text input on the page. Note
 107 that `gi` and `1gi` are different: The latter _always_ focuses the first input
 108 of the page, regradless of which input you used last.
 109
 110 [prevented autofocus]: options.md#prevent-autofocus
 111
 112
 113 ## Focus next/previous element
 114
 115 The default shorcuts are `<tab>` and `<s-tab>`, respectively (to be precise,
 116 they also include [special keys]). They work just like `<tab>` works normally,
 117 except that if you focused a text input using the `gi` command they will only
 118 switch between text inputs on thee page, as opposed to between all focusable
 119 elements (such as links, buttons and checkboxes) as they do otherwise.
 120
 121 [special keys]: shortcuts.md#special-keys
 122
 123
 124 ## The `f` commands
 125
 126 When invoking one of the `f` commands you enter Hints mode. In Hints mode,
 127 markers with hints are shown for some elements. By typing the letters of a hint
 128 something is done to that element, depending on the command.
 129
 130 Which elements get hints depends on the command as well:
 131
 132 - `f` and `af`: Anything clickable—links, buttons, form controls.
 133 - `F` and `gf`: Anything that can be opened in a new tabs—links.
 134 - `yf`: Anything that has something useful to copy—links (their URL) and text
 135   inputs (their text).
 136 - `zf`: Anything focusable—links, buttons, form controls, scrollable elements,
 137   frames.
 138
 139 It might seem simpler to match the same set of elements for _all_ of the
 140 commands. The reason that is not the case is because the fewer elements the
 141 shorter the hints. (Also, what should happen if you tried to `F` a button?)
 142
 143 Another way to make hints shorter is to assign the same hint to all links with
 144 the same URL. So don’t get surprised if you see the same hint repeated several
 145 times.
 146
 147 VimFx also tries to give you shorter hints for elements that you are more likely
 148 to click. This is done by the surprisingly simple rule: The larger the element,
 149 the shorter the hint.
 150
 151 There are standardized elements which are always clickable—_semantically_
 152 clickable elements. Unfortunately, many sites use unclickable elements and then
 153 make them clickable using JavaScript—<em>un</em>semantically clickable elements.
 154 Such elements are difficult to find. VimFx has a few techniques for doing so,
 155 which works many times but not always, but unfortunately they sometimes produce
 156 false positives. Many times those false positives are pretty large elements,
 157 which according to the last paragraph would give them really short hints, making
 158 other more important elements suffer by getting longer ones. Therefore VimFx
 159 favors semantic elements over unsemantic ones and takes that into account when
 160 deciding the hint length for elements.
 161
 162 Some hint characters are easier to type than others. The ones on the home row
 163 are of course the best. When customizing the [hint chars] option you should put
 164 the best keys to the left and the worst ones to the right. VimFx favors keys to
 165 the left, so that should give you the optimal hints.
 166
 167 Hints are added on top of the corresponding element. If they obscure the display
 168 too much you can hold shift to make them transparent. (See [Styling] if you’d
 169 like to change that.) The hints can also sometimes cover each other. Press
 170 `<space>` and `<s-space>` to switch which one should be on top.
 171
 172 When giving a count to an `f` command, all markers will be re-shown after you’ve
 173 typed the hint characters of one of them, _count_ minus one times. All but the
 174 last time, the marker’s link will be opened in a new background tab. The last
 175 time the command opens links as normal (in the current tab (`f`) or in a new
 176 background (`F`) or foreground tab (`gf`)).
 177
 178 Note that the `f` command adds markers not only to links, but to buttons and
 179 form controls as well. What happens the _count_ minus one times then? Buttons,
 180 checkboxes and the like are simply clicked, allowing you to quickly check many
 181 checkboxes in one go, for example. Text inputs cancel the command.
 182
 183 `af` works as if you’d supplied an infinite count to `f`. (In fact, the `af`
 184 command is implemented by running the same function as for the `f` command,
 185 passing `Infinity` as the `count` argument!) Therefore the `af` command does not
 186 accept a count itself.
 187
 188 The `zf` and `yf` commands do not accept counts.
 189
 190 Press `<enter>` to increase the count by one. This is useful when you’ve already
 191 entered Hints mode but realize that you want to interact with yet a marker. This
 192 can be faster than going into Hints mode once more.
 193
 194 If you’ve pressed `f` but realize that you’d rather open a link in a new tab you
 195 can hold ctrl while typing the last hint character. This is similar to how you
 196 can press `<c-enter>` on a focused link to open it in a new tab (while just
 197 `<enter>` would have opened it in the same tab). Hold alt to open in a new
 198 foreground tab. In other words, holding ctrl works as if you’d pressed `F` from
 199 the beginning, and holding alt works as if you’d pressed `gf`.
 200
 201 For the `F` and `gf` commands, holding ctrl makes them open links in the same
 202 tab instead, as if you’d used the `f` command. Holding alt toggles whether to
 203 open tabs in the background or foreground—it makes `F` work like `gf`, and `gf`
 204 like `F`.
 205
 206 (Also see the advanced prefs [hints\_toggle\_in\_tab] and
 207 [hints\_toggle\_in\_background].)
 208
 209 [hint chars]: options.md#hint-chars
 210 [Styling]: styling.md
 211 [hints\_toggle\_in\_tab]: options.md#hints_toggle_in_tab
 212 [hints\_toggle\_in\_background]: options.md#hints_toggle_in_background
 213
 214
 215 ## Ignore mode `<s-f1>`
 216
 217 Ignore mode is all about ignoring VimFx commands and sending the keys to the
 218 page instead. Sometimes, though, you might want to run some VimFx command even
 219 when in Insert mode.
 220
 221 One way of doing that is to press `<s-escape>` to exit Ignore mode, run your
 222 command and then enter Ignore mode again using `i`. However, it might be
 223 inconvenient having to remember to re-enter Ignore mode, and sometimes that’s
 224 not even possible, such as if you ran the `K` command to get to the next tab.
 225
 226 Another way is to press `<s-f1>` followed by the Normal mode command you wanted
 227 to run. (`<s-f1>` is essentially the inverse of the `I` command, which passes
 228 the next keypress on to the page. Internally they’re called “quote” and
 229 “unquote.”) This is handy if you’d like to switch away from a [blacklisted]
 230 page: Just press for example `<s-f1>K`.
 231
 232 `<s-f1>` was chosen as the default shortcut because on a typical keyboard `<f1>`
 233 is located just beside `<escape>`, which makes it very similar to `<s-escape>`,
 234 which is used to exit Ignore mode. Both of those are uncommonly used by web
 235 pages, so they shouldn’t be in the way. If you ever actually do need to send any
 236 of those to the page, you can prefix them with `<s-f1>`, because if the key you
 237 press after `<s-f1>` is not part of any Normal mode command, the key is sent to
 238 the page. (Another way is for example `<s-f1>I<s-escape>`.)
 239
 240 [blacklisted]: options.md#blacklist
 241
 242
 243 ## Ex commands
 244
 245 vim has something called “ex” commands. Want something similar in VimFx? True to
 246 its spirit, VimFx embraces a standard Firefox feature for this purpose: The
 247 [Developer Toolbar]. That link also includes instructions on how to extend it
 248 with your own commands.
 249
 250 In the future VimFx might even ship with a few extra “ex” commands by default.
 251 We’re open for suggestions!
 252
 253 [Developer Toolbar]: https://developer.mozilla.org/en-US/docs/Tools/GCLI