2 This is part of the VimFx documentation.
3 Copyright Simon Lydell 2015, 2016.
4 See the file README.md for copying conditions.
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.
12 In this document, many commands are referred to by their default shortcut. You
13 can of course [change those] if you like. (Read about [modes] to tell the
14 difference between _commands_ and _shortcuts._)
16 [change those]: shortcuts.md
21 Some commands support _counts._ That means that you can type a number before a
22 command and it will change its behavior based on that number—the count. For
23 example, typing `12x` would close 12 tabs.
25 (As opposed to Vim, you may only supply a count _before_ a command, not in the
26 middle of one. That’s because VimFx’s commands are simple sequences, while Vim’s
27 are operators and motions.)
31 Goes _count_ levels up in the URL hierarchy.
35 Goes _count_ pages backward/forward in history.
37 ### Scrolling commands
39 Specifying a count make them scroll _count_ times as far.
43 Selects the tab _count_ tabs backward/forward.
45 If the count is greater than one they don’t wrap around when reaching the ends
46 of the tab bar, unless:
48 - the first tab is selected and `J` is used.
49 - the last tab is selected and `K` is used.
51 They only wrap around _once._
55 Selects the _count_ most recently visited tab.
59 Selects the _count_ oldest unvisited tab.
61 Tip: It might help to make “unread” tabs visually different through custom
65 // Unread, unvisited tabs (opened in the background). These are the ones that
66 // can be selected using `gL`.
67 .tabbrowser-tab[unread]:not([VimFx-visited]):not(#override) {
68 font-style: italic !important;
71 // Unread but previously selected tabs (that have changed since last select).
72 .tabbrowser-tab[unread][VimFx-visited]:not(#override) {
73 font-weight: bold !important;
81 Moves the current tab _count_ tabs forward/backward.
83 As opposed to `J` and `K`, pinned and non-pinned tabs are handled separately.
84 The first non-pinned tab wraps to the last tab, and the last tab wraps to the
85 first non-pinned tab, and vice versa for non-pinned tabs. Use `gp` to move a tab
86 between the pinned and non-pinned parts of the tab bar.
88 Other than the above, the count and wrap semantics work like `J` and `K`.
92 `g0` selects the tab at index _count,_ counting from the start.
94 `g^` selects the tab at index _count,_ counting from the first non-pinned tab.
96 `g$` selects the tab at index _count,_ counting from the end.
100 Closes the current tab and _count_ minus one of the following tabs.
104 Restores the _count_ last closed tabs.
108 Passes on the next _count_ keypresses to the page, without activating VimFx
111 ### The hint commands
113 Explained in the their own section below.
117 Explained in its own section below.
120 ## Scrolling commands
122 Firefox lets you scroll with the arrow keys, page down, page up, home, end and
123 space by default. VimFx provides similar scrolling commands (and actually
124 overrides `<space>`), but they work a little bit differently.
126 They scroll _the currently focused element._ If the currently focused element
127 isn’t scrollable, the largest scrollable element on the page (if any, and
128 including the entire page itself) is scrolled.
130 You can focus scrollable elements using the `ef` command (or the `f` command).
131 Scrollable browser elements, such as in the dev tools, can be focused using the
132 `eb` command. The right border of hint markers for scrollable elements is styled
133 to remind of a scroll bar, making them easier to recognize among hints for
136 Note that `ef` and `f` do _not_ add a hint marker for the _largest_ scrollable
137 element (such as the entire page). There’s no need to focus that element, since
138 it is scrolled by default if no other scrollable element is focused, as
139 explained above. (This prevents the largest scrollable element from likely
140 eating your best hint char on most pages; see [The hint commands]).
142 [The hint commands]: #the-hint-commands--hints-mode
144 ### Marks: `m` and `'`
146 Other than traditional scrolling, VimFx has _marks._ Press `m` followed by a
147 letter to associate the current scroll position with that letter. For example,
148 press `ma` to save the position into mark _a._ Then you can return to that
149 position by pressing `'` followed by the same letter, e.g. `'a`.
151 One mark is special: `'`. Pressing `''` takes you to the scroll position before
152 the last `gg`, `G`, `0`, `$`, `/`, `n`, `N` or `'`. (You can change this mark
153 using the [`scroll.last_position_mark`] pref.)
155 Note: Firefox has a `'` shortcut by default. It opens the Quick Find bar. VimFx
156 provides the `g/` shortcut instead.
158 [`scroll.last_position_mark`]: options.md#scroll.last_position_mark
162 Unlike Vim, you may press _any_ key after `m`, and the scroll position will be
163 associated with that key (Vim allows only a–z, roughly).
165 Unlike Vim and Vimium, VimFx has no global marks. The reason is that they would
166 be a lot more complicated to implement and do not seem useful enough to warrant
169 As mentioned above, `m` stores the _current scroll position._ Specifically, that
170 means the scroll position of the element that would be scrolled if the active
171 element isn’t scrollable; see [Scrolling commands] above.
173 [Scrolling commands]: #scrolling-commands-1
178 `gi` focuses the text input you last used, or the first one on the page. Note
179 that a [prevented autofocus] still counts as having focused and used a text
180 input. This allows you to have your cake and eat it too: You can enable
181 autofocus prevention, and type `gi` when you wish you hadn’t.
183 `gi` takes a count. It then selects the `counth` text input on the page. Note
184 that `gi` and `1gi` are different: The latter _always_ focuses the first input
185 of the page, regradless of which input you used last.
187 After having focused a text input using `gi`, `<tab>` and `<s-tab>` will _only
188 cycle between text inputs,_ instead of moving the focus between _all_ focusable
189 elements as they usually do. (See also the [`focus_previous_key` and
190 `focus_next_key`] advanced options.)
192 [prevented autofocus]: options.md#prevent-autofocus
193 [`focus_previous_key` and `focus_next_key`]: options.md#focus_previous_key-and-focus_next_key
196 ## The hint commands / Hints mode
198 When invoking one of the hint commands (such as `f`, `et` or one of the [`v`
199 commands]) you enter Hints mode. In Hints mode, markers with hints are shown for
200 some elements. By typing the letters of a hint something is done to that
201 element, depending on the command.
203 Another way to find links on the page is to use `g/`. It’s like the regular find
204 command (`/`), except that it searches links only.
206 Which elements get hints depends on the command as well:
208 - `f` and `af`: Anything clickable—links, buttons, form controls.
209 - `F`, `et`, `ew` and `ep`: Anything that can be opened in a new tab or
211 - `yf`: Anything that has something useful to copy—links (their URL) and text
213 - `ef`: Anything focusable—links, buttons, form controls, scrollable elements,
215 - `ec`: Most things that have a context menu—images, links, videos and text
216 inputs, but also many textual elements.
217 - `eb`: Browser elements, such as toolbar buttons.
219 It might seem simpler to match the same set of elements for _all_ of the
220 commands. The reason that is not the case is because the fewer elements the
221 shorter the hints. (Also, what should happen if you tried to `F` a button?)
223 (You can also customize [which elements do and don’t get hints][hint-matcher].)
225 Another way to make hints shorter is to assign the same hint to all links with
226 the same URL. So don’t be surprised if you see the same hint repeated several
229 VimFx also tries to give you shorter hints for elements that you are more likely
230 to click. This is done by the surprisingly simple rule: The larger the element,
231 the shorter the hint. To learn more about hint characters and hint length, read
232 about the [hint chars] option.
234 Hints are added on top of the corresponding element. If they obscure the display
235 too much you can hold shift to make them transparent, letting you peek through
236 them. (See [Styling] and the [hints\_peek\_through] pref if you’d like to change
237 that.) The hints can also sometimes cover each other. Press `<space>` and
238 `<s-space>` to switch which one should be on top.
240 When giving a count to a hint command, all markers will be re-shown after you’ve
241 typed the hint characters of one of them, _count_ minus one times. All but the
242 last time, the marker’s link will be opened in a new background tab. The last
243 time the command opens links as normal (in the current tab (`f`) or in a new
244 background (`F`) or foreground tab (`et`)).
246 Note that the hint command adds markers not only to links, but to buttons and
247 form controls as well. What happens the _count_ minus one times then? Buttons,
248 checkboxes and the like are simply clicked, allowing you to quickly check many
249 checkboxes in one go, for example. Text inputs cancel the command.
251 `af` works as if you’d supplied an infinite count to `f`. (In fact, the `af`
252 command is implemented by running the same function as for the `f` command,
253 passing `Infinity` as the `count` argument!) Therefore the `af` command does not
254 accept a count itself.
256 The `et`, `ef`, `yf` and `eb` commands do not accept counts.
258 Press `<enter>` to increase the count by one. This is useful when you’ve already
259 entered Hints mode but realize that you want to interact with yet a marker. This
260 can be faster than going into Hints mode once more.
262 If you’ve pressed `f` but realize that you’d rather open a link in a new tab you
263 can hold ctrl while typing the last hint character. This is similar to how you
264 can press `<c-enter>` on a focused link to open it in a new tab (while just
265 `<enter>` would have opened it in the same tab). Hold alt to open in a new
266 foreground tab. In other words, holding ctrl works as if you’d pressed `F` from
267 the beginning, and holding alt works as if you’d pressed `et`.
269 For the `F` and `et` commands, holding ctrl makes them open links in the same
270 tab instead, as if you’d used the `f` command. Holding alt toggles whether to
271 open tabs in the background or foreground—it makes `F` work like `et`, and `et`
274 (Also see the advanced prefs [hints\_toggle\_in\_tab] and
275 [hints\_toggle\_in\_background].)
277 Finally, if the element you wanted to interact with didn’t get a hint marker you
278 can try pressing `<c-enter>` while the hints are still shown. That will give
279 hint markers to all _other_ elements. Warning: This can be very slow, and result
280 in an overwhelming amount of hint markers (making it difficult to know which
281 hint to activate sometimes). See this as an escape hatch if you _really_ want to
282 avoid using the mouse at all costs. (Press `<c-enter>` again to toggle back to
285 ### Mnemonics and choice of default hint command shortcuts
287 The main command is `f`. It comes from the Vimium and Vimperator extensions. The
288 mnemonic is “<strong>f</strong>ollow link.” It is a good key, because on many
289 keyboard layouts it is located right under where your left index finger rests.
291 The most common variations of `f` are centered around that letter: `F`, `yf` and
292 `af`. (Some users might want to swap `F` and `et`, though.) In Vim, it is not
293 uncommon that an uppercase letter does the same thing as its lowercase
294 counterpart, but with some variation (in this case, `F` opens links in new tabs
295 instead of in the current tab), and `y` usually means “yank” or “copy.” VimFx
296 also has this pattern that `a` means “all.”
298 You can think of the above commands as the “f commands.” That sounds like
299 “eff-commands” when you say it out loud, which is a way of remembering that the
300 rest of the `f` variations are behind the `e` key. That’s also a pretty good
301 key/letter, because it is close to `f` both alphabetically, and physically in
302 many keyboard layouts (and is pretty easy to type).
304 The second key after `e` was chosen based on mnemonics: There’s `et` as in
305 <strong>t</strong>ab, `ew` as in <strong>w</strong>indow, `ep` as in
306 <strong>p</strong>rivate window, `ef` as in <strong>f</strong>ocus, `ec` as in
307 <strong>c</strong>ontext menu and `eb` as in <strong>b</strong>rowser.
309 [`v` commands]: #the-v-commands--caret-mode
310 [hint-matcher]: api.md#vimfxsethintmatcherhintmatcher
311 [hint chars]: options.md#hint-chars
312 [Styling]: styling.md
313 [hints\_peek\_through]: options.md#hints_peek_through
314 [hints\_toggle\_in\_tab]: options.md#hints_toggle_in_tab
315 [hints\_toggle\_in\_background]: options.md#hints_toggle_in_background
318 ## The `v` commands / Caret mode
320 The point of Caret mode is to copy text from web pages using the keyboard.
322 ### Entering Caret mode
324 Pressing `v` will enter Hints mode with hint markers for all elements with text
325 inside. When activating a marker, its element will get a blinking caret at the
326 beginning of it, and Caret mode will be entered.
328 The `av` command does the same thing as `v`, but instead of placing the caret at
329 the beginning of the element, it selects the entire element (it selects
330 <strong>a</strong>ll of the element).
332 The `yv` command brings up the same hint markers as `av` does, and then takes
333 the text that `av` would have selected and copies it to the clipboard. It does
334 not enter Caret mode at all.
336 The letter `v` was chosen for these shortcuts because that’s what Vim uses to
337 enter its Visual mode, which was an inspiration for VimFx’s Caret mode.
339 ### Caret mode commands
341 Caret mode uses [Firefox’s own Caret mode] under the hood. This means that you
342 can use the arrows keys, `<home>`, `<end>`, `<pageup>` and `<pagedown>`
343 (optionally holding ctrl) to move the caret as usual. Hold shift while moving
344 the caret to select text.
346 In addition to the above, VimFx provides a few commands inspired by Vim.
348 - `h`, `j`, `k`, `l`: Move the caret left, down, up or right, like the arrow
351 - `b`, `w`: Move the caret one word backward or forward, like `<c-left>` and
352 `<c-right>` but a bit “Vim-adjusted” (see the section on Vim below) in order
355 - `0` (or `^`), `$`: Move the caret to the start or end of the line.
357 The above commands (except the ones moving to the start or end of the line)
358 accept a _count._ For example, press `3w` to move three words forward.
360 Press `v` to start selecting text. After doing so, VimFx’s commands for moving
361 the caret select the text instead of just moving the caret. Press `v` again to
362 collapse the selection again. (Note that after pressing `v`, only VimFx’s
363 commands goes into “selection mode,” while Firefox’s work as usual, requiring
364 shift to be held to select text.)
366 `o` moves the caret to the “other end” of the selection. If the caret is at the
367 end of the selection, `o` will move it to the start (while keeping the selection
368 intact), and vice versa. This let’s you adjust the selection in both ends.
370 Finally, `y` is a possibly faster alternative to the good old `<c-c>`. Other
371 than copying the selection to the clipboard, it also exits Caret mode, saving
372 you yet a keystroke. (`<escape>` is unsurprisingly used to exit Caret mode
375 [Firefox’s own Caret mode]: http://kb.mozillazine.org/Accessibility_features_of_Firefox#Allow_text_to_be_selected_with_the_keyboard
379 If you’re lucky, the text you want to copy is located within a single element
380 that contains no other text, such as the text of a link or an inline code
381 snippet. If so, using the `yv` command (which copies an entire element without
382 entering Caret mode) is the fastest.
384 If you want to copy _almost_ all text of an element, or a bit more than it, use
385 the `av` command (which selects an entire element). Then adjust the selection
386 using the various Caret mode commands. Remember that `o` lets you adjust both
387 ends of the selection.
389 In all other cases, use the `v` command to place the caret close to the text you
390 want to copy. Then move the caret in place using the various Caret
391 mode commands, hit `v` to start selecting, and move the again.
393 Use `y` to finish (or `<escape>` to abort). Alternatively, use the `<menu>` key
394 to open the context menu for the selection.
398 As seen above, Caret mode is obviously inspired by Vim’s Visual mode. However,
399 keep in mind that the point of Caret mode is to **copy text using the keyboard,
400 not mimicing Vim’s visual mode.** I’ve found that selecting text for _copying_
401 is different than selecting code for _editing._ Keep that in mind.
403 Working with text selection in webpages using code is a terrible mess full of
404 hacks. New commands will only be added if they _really_ are worth it.
406 A note on VimFx’s `b` and `w`: They work like Vim’s `b` and `w` (but a “word” is
407 according to Firefox’s definition, not Vim’s), except when there is selected
408 text and the caret is at the end of the selection. Then `b` works like Vim’s
409 `ge` and `w` works like Vim’s `e`. The idea is to keep it simple and only
410 provide two commands that do what you want, rather than many just to mimic Vim.
413 ## Ignore mode `<s-f1>`
415 Ignore mode is all about ignoring VimFx commands and sending the keys to the
416 page instead. Sometimes, though, you might want to run some VimFx command even
419 One way of doing that is to press `<s-escape>` to exit Ignore mode, run your
420 command and then enter Ignore mode again using `i`. However, it might be
421 inconvenient having to remember to re-enter Ignore mode, and sometimes that’s
422 not even possible, such as if you ran the `K` command to get to the next tab.
424 Another way is to press `<s-f1>` followed by the Normal mode command you wanted
425 to run. (`<s-f1>` is essentially the inverse of the `I` command, which passes
426 the next keypress on to the page. Internally they’re called “quote” and
427 “unquote.”) This is handy if you’d like to switch away from a [blacklisted]
428 page: Just press for example `<s-f1>K`.
430 `<s-f1>` was chosen as the default shortcut because on a typical keyboard `<f1>`
431 is located just beside `<escape>`, which makes it very similar to `<s-escape>`,
432 which is used to exit Ignore mode. Both of those are uncommonly used by web
433 pages, so they shouldn’t be in the way. If you ever actually do need to send any
434 of those to the page, you can prefix them with `<s-f1>`, because if the key you
435 press after `<s-f1>` is not part of any Normal mode command, the key is sent to
436 the page. (Another way is for example `<s-f1>I<s-escape>`.)
438 [blacklisted]: options.md#blacklist
443 Vim has something called “ex” commands. Want something similar in VimFx? True to
444 its spirit, VimFx embraces a standard Firefox feature for this purpose: The
445 [Developer Toolbar]. That link also includes instructions on how to extend it
446 with your own commands.
448 In the future VimFx might even ship with a few extra “ex” commands by default.
449 We’re open for suggestions!
451 [Developer Toolbar]: https://developer.mozilla.org/en-US/docs/Tools/GCLI