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 ## Counts
  13
  14 Some commands support _counts._ That means that you can type a number before a
  15 command and it will change its behavior based on that number—the count. For
  16 example, typing `12x` would close 12 tabs.
  17
  18 (As opposed to vim, you may only supply a count _before_ a command, not in the
  19 middle of one. This is because VimFx’s commands are simple sequences, while
  20 vim’s are operators and motions.)
  21
  22 ### `gu`
  23
  24 Goes _count_ levels up in the URL hierarchy.
  25
  26 ### `H` and `L`
  27
  28 Goes _count_ pages backward/forward in history.
  29
  30 ### Scrolling commands
  31
  32 Specifying a count make them scroll _count_ times as far.
  33
  34 ### `J`, `K`
  35
  36 Selects the tab _count_ tabs backward/forward.
  37
  38 If the count is greater than one they don’t wrap around when reaching the ends
  39 of the tab bar.
  40
  41 ### `gJ`, `gK`
  42
  43 Moves the current tab _count_ tabs forward/backward.
  44
  45 If the count is greater than one they don’t wrap around when reaching the ends
  46 of the tab bar.
  47
  48 ### `x`
  49
  50 Closes the current tab and _count_ minus one of the following tabs.
  51
  52 ### `X`
  53
  54 Restores the _count_ last closed tabs.
  55
  56 ### `q`
  57
  58 Passes on the next _count_ keypresses to the page, without activating VimFx
  59 commands.
  60
  61 ### The `f` commands
  62
  63 Explained in the their own section below.
  64
  65 ### `gi`
  66
  67 Explained in its own section below.
  68
  69
  70 ## `<force>` commands
  71
  72 By putting the special “key” `<force>` at the beginning of a shortcut the
  73 shortcut will work exactly as it would without `<force>`, except that it will
  74 also be available in text inputs.
  75
  76 VimFx enters a kind of “automatic insert mode” when you focus a text input,
  77 allowing you to type text into it without triggering VimFx commands. The `esc`
  78 command, however, is still available, allowing you to blur the text input by
  79 pressing `<escape>`. The reason it is available is because the default shortcut
  80 is `<force><escape>`.
  81
  82 Using `<force>` allows you to run other commands in text inputs as well. For
  83 example, you could use `<force><a-j>` and `<force><a-k>` to be able to select
  84 tab backward and forward regardless if you happen to be in a text input or not.
  85
  86
  87 ## Scrolling commands
  88
  89 Firefox lets you scroll with the arrow keys, page down, page up, home, end and
  90 space by default. VimFx provides similar scrolling commands (and actually
  91 overrides space), but they work a little bit differently.
  92
  93 They scroll _the currently focused element._ If the currently focused element
  94 isn’t scrollable, or there are no (apparent) currently focused element, the
  95 entire page is scrolled.
  96
  97 You can focus scrollable elements using the `vf` command.
  98
  99
 100 ## `gi`—Text Input mode
 101
 102 `gi` focuses the text input you last used, or the first one on the page. Note
 103 that a [prevented autofocus] still counts as having focused and used a text
 104 input. This allows you to have your cake and eat it too: You can enable
 105 autofocus prevention, and type `gi` when you wish you hadn’t.
 106
 107 `gi` takes a count. It then selects the `counth` text input on the page. Note
 108 that `gi` and `1gi` are different: The latter _always_ focuses the first input
 109 of the page, regradless of which input you used last.
 110
 111 Typing `gi` also enters Text Input mode. That’s mostly an implementation detail.
 112 What it means is that `<tab>` will only switch between text inputs on the page,
 113 as opposed to between all focusable elements (such as links, buttons and
 114 checkboxes) as it does otherwise.
 115
 116 [prevented autofocus]: options.md#prevent-autofocus
 117
 118
 119 ## The `f` commands
 120
 121 When invoking one of the `f` commands you enter Hints mode. In Hints mode,
 122 markers with hints are shown for some elements. By typing the letters of a hint
 123 something is done to that element, depending on the command.
 124
 125 Which elements get hints depends on the command as well:
 126
 127 - `f` and `af`: Anything clickable—links, buttons, form controls.
 128 - `F` and `gf`: Anything that can be opened in a new tabs—links.
 129 - `yf`: Anything that has something useful to copy—links (their URL) and text
 130   inputs (their text).
 131 - `vf`: Anything focusable—links, buttons, form controls, scrollable elements,
 132   frames.
 133
 134 It might seem simpler to match the same set of elements for _all_ of the
 135 commands. The reason that is not the case is because the fewer elements the
 136 shorter the hints. (Also, what should happen if you tried to `F` a button?)
 137
 138 Another way to make hints shorter is to assign the same hint to all links with
 139 the same URL. So don’t get surprised if you see the same hint repeated several
 140 times.
 141
 142 VimFx also tries to give you shorter hints for elements that you are more likely
 143 to click. This is done by the surprisingly simple rule: The larger the element,
 144 the shorter the hint.
 145
 146 There are standardized elements which are always clickable—_semantically_
 147 clickable elements. Unfortunately, many sites use unclickable elements and then
 148 make them clickable using JavaScript—<em>un</em>semantically clickable elements.
 149 Such elements are difficult to find. VimFx has a few techniques for doing so,
 150 which works many times but not always, but unfortunately they sometimes produce
 151 false positives. Many times those false positives are pretty large elements,
 152 which according to the last paragraph would give them really short hints, making
 153 other more important elements suffer by getting longer ones. Therefore VimFx
 154 favors semantic elements over unsemantic ones and takes that into account when
 155 deciding the hint length for elements.
 156
 157 One more thing about hints: Some hint characters are easier to type than others.
 158 The ones on the home row are of course the best. When customizing the [hint
 159 chars] option you should put the best keys to the left and the worst ones to the
 160 right. VimFx favors keys to the left, so that should give you the optimal hints.
 161
 162 When giving a count to an `f` command, all markers will be re-shown after you’ve
 163 typed the hint characters of one of them, _count_ minus one times. All but the
 164 last time, the marker’s link will be opened in a new background tab. The last
 165 time the command opens links as normal (in the current tab (`f`) or in a new
 166 background (`F`) or foreground tab (`gf`)).
 167
 168 Note that the `f` command adds markers not only to links, but to buttons and
 169 form controls as well. What happens the _count_ minus one times then? Buttons,
 170 checkboxes and the like are simply clicked, allowing you to quickly check many
 171 checkboxes in one go, for example. Text inputs cancel the command.
 172
 173 `af` works as if you’d supplied an infinite count to `f`. (In fact, the `af`
 174 command is implemented by running the same function as for the `f` command,
 175 passing `Infinity` as the `count` argument!) Therefore the `af` command does not
 176 accept a count itself.
 177
 178 The `vf` and `yf` commands do not accept counts.
 179
 180 [hint chars]: options.md#hint-chars
 181
 182
 183 ## Ex commands
 184
 185 vim has something called “ex” commands. Want something similar in VimFx? True to
 186 its spirit, VimFx embraces a standard Firefox feature for this purpose: The
 187 [Developer Toolbar]. That link also includes instructions on how to extend it
 188 with your own commands.
 189
 190 In the future VimFx might even ship with a few extra “ex” commands by default.
 191 We’re open for suggestions!
 192
 193 [Developer Toolbar]: https://developer.mozilla.org/en-US/docs/Tools/GCLI