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`] option.)
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. You can also type the text of an element with
202 a hint marker: See the [Hint characters] option for more information.
204 Another way to find links on the page is to use `g/`. It’s like the regular find
205 command (`/`), except that it searches links only.
207 Which elements get hints depends on the command as well:
209 - `f` and `af`: Anything clickable—links, buttons, form controls.
210 - `F`, `et`, `ew` and `ep`: Anything that can be opened in a new tab or
212 - `yf`: Anything that has something useful to copy—links (their URL) and text
214 - `ef`: Anything focusable—links, buttons, form controls, scrollable elements,
216 - `ec`: Most things that have a context menu—images, links, videos and text
217 inputs, but also many textual elements.
218 - `eb`: Browser elements, such as toolbar buttons.
220 It might seem simpler to match the same set of elements for _all_ of the
221 commands. The reason that is not the case is because the fewer elements the
222 shorter the hints. (Also, what should happen if you tried to `F` a button?)
224 (You can also customize [which elements do and don’t get hints][hint-matcher].)
226 Another way to make hints shorter is to assign the same hint to all links with
227 the same URL. So don’t be surprised if you see the same hint repeated several
230 VimFx also tries to give you shorter hints for elements that you are more likely
231 to click. This is done by the surprisingly simple rule: The larger the element,
232 the shorter the hint. To learn more about hint characters and hint length, read
233 about the [Hint characters] option.
235 Hints are added on top of the corresponding element. If they obscure the display
236 too much you can hold down ctrl and shift simultaneously to make them
237 transparent, letting you peek through them. (See [Styling] and the
238 [`hints.peek_through`] option if you’d like to change that.) The hints can also
239 sometimes cover each other. Press `<c-space>` and `<s-space>` to switch which
240 one should be on top.
242 Yet another way to deal with areas crowded with hint markers is to type part of
243 a marker’s element text. That will filter out hint markers whose elements
244 _don’t_ match what you’ve typed. Pagination links are good examples, like these
245 (fake) ones: [1](#1) [2](#2) [3](#3) [4](#4) [5](#5) [6](#6). It’s very hard to
246 tell which hint to use to go to page three. But if you type “3” things will be
247 much clearer. (It might even [auto-activate][Hint auto-activation] the hint
250 When giving a count to a hint command, all markers will be re-shown after you’ve
251 typed the hint characters of one of them, _count_ minus one times. All but the
252 last time, the marker’s link will be opened in a new background tab. The last
253 time the command opens links as normal (in the current tab (`f`) or in a new
254 background (`F`) or foreground tab (`et`)).
256 Note that the hint command adds markers not only to links, but to buttons and
257 form controls as well. What happens the _count_ minus one times then? Buttons,
258 checkboxes and the like are simply clicked, allowing you to quickly check many
259 checkboxes in one go, for example. Text inputs cancel the command.
261 `af` works as if you’d supplied an infinite count to `f`. (In fact, the `af`
262 command is implemented by running the same function as for the `f` command,
263 passing `Infinity` as the `count` argument!) Therefore the `af` command does not
264 accept a count itself.
266 The `et`, `ef`, `yf` and `eb` commands do not accept counts.
268 Press `<up>` to increase the count by one. This is useful when you’ve already
269 entered Hints mode but realize that you want to interact with yet a marker. This
270 can be faster than going into Hints mode once more.
272 If you’ve pressed `f` but realize that you’d rather open a link in a new tab you
273 can hold ctrl while typing the last hint character. This is similar to how you
274 can press `<c-enter>` on a focused link to open it in a new tab (while just
275 `<enter>` would have opened it in the same tab). Hold alt to open in a new
276 foreground tab. In other words, holding ctrl works as if you’d pressed `F` from
277 the beginning, and holding alt works as if you’d pressed `et`.
279 For the `F` and `et` commands, holding ctrl makes them open links in the same
280 tab instead, as if you’d used the `f` command. Holding alt toggles whether to
281 open tabs in the background or foreground—it makes `F` work like `et`, and `et`
282 like `F`. As mentioned in [Hint auto-activation], the best hint is highlighted
283 with a different color, and can be activated by pressing `<enter>`. Holding alt
284 or ctrl works there too: `<c-enter>` toggles same/new tab and `<a-enter>`
285 toggles background/foreground tab.
287 (Also see the advanced options [`hints.toggle_in_tab`] and
288 [`hints.toggle_in_background`].)
290 Finally, if the element you wanted to interact with didn’t get a hint marker you
291 can try pressing `<c-backspace>` while the hints are still shown. That will give
292 hint markers to all _other_ elements. Warning: This can be very slow, and result
293 in an overwhelming amount of hint markers (making it difficult to know which
294 hint to activate sometimes). See this as an escape hatch if you _really_ want to
295 avoid using the mouse at all costs. (Press `<c-backspace>` again to toggle back
296 to the previous hints.)
298 ### Mnemonics and choice of default hint command shortcuts
300 The main command is `f`. It comes from the Vimium and Vimperator extensions. The
301 mnemonic is “<strong>f</strong>ollow link.” It is a good key, because on many
302 keyboard layouts it is located right under where your left index finger rests.
304 The most common variations of `f` are centered around that letter: `F`, `yf` and
305 `af`. (Some users might want to swap `F` and `et`, though.) In Vim, it is not
306 uncommon that an uppercase letter does the same thing as its lowercase
307 counterpart, but with some variation (in this case, `F` opens links in new tabs
308 instead of in the current tab), and `y` usually means “yank” or “copy.” VimFx
309 also has this pattern that `a` means “all.”
311 You can think of the above commands as the “f commands.” That sounds like
312 “eff-commands” when you say it out loud, which is a way of remembering that the
313 rest of the `f` variations are behind the `e` key. That’s also a pretty good
314 key/letter, because it is close to `f` both alphabetically, and physically in
315 many keyboard layouts (and is pretty easy to type).
317 The second key after `e` was chosen based on mnemonics: There’s `et` as in
318 <strong>t</strong>ab, `ew` as in <strong>w</strong>indow, `ep` as in
319 <strong>p</strong>rivate window, `ef` as in <strong>f</strong>ocus, `ec` as in
320 <strong>c</strong>ontext menu and `eb` as in <strong>b</strong>rowser.
322 [`v` commands]: #the-v-commands--caret-mode
323 [hint-matcher]: api.md#vimfxsethintmatcherhintmatcher
324 [Hint characters]: options.md#hint-characters
325 [Hint auto-activation]: options.md#hint-auto-activation
326 [Styling]: styling.md
327 [`hints.peek_through`]: options.md#hints.peek_through
328 [`hints.toggle_in_tab`]: options.md#hints.toggle_in_tab
329 [`hints.toggle_in_background`]: options.md#hints.toggle_in_background
332 ## The `v` commands / Caret mode
334 The point of Caret mode is to copy text from web pages using the keyboard.
336 ### Entering Caret mode
338 Pressing `v` will enter Hints mode with hint markers for all elements with text
339 inside. When activating a marker, its element will get a blinking caret at the
340 beginning of it, and Caret mode will be entered.
342 The `av` command does the same thing as `v`, but instead of placing the caret at
343 the beginning of the element, it selects the entire element (it selects
344 <strong>a</strong>ll of the element).
346 The `yv` command brings up the same hint markers as `av` does, and then takes
347 the text that `av` would have selected and copies it to the clipboard. It does
348 not enter Caret mode at all.
350 The letter `v` was chosen for these shortcuts because that’s what Vim uses to
351 enter its Visual mode, which was an inspiration for VimFx’s Caret mode.
353 ### Caret mode commands
355 Caret mode uses [Firefox’s own Caret mode] under the hood. This means that you
356 can use the arrows keys, `<home>`, `<end>`, `<pageup>` and `<pagedown>`
357 (optionally holding ctrl) to move the caret as usual. Hold shift while moving
358 the caret to select text.
360 In addition to the above, VimFx provides a few commands inspired by Vim.
362 - `h`, `j`, `k`, `l`: Move the caret left, down, up or right, like the arrow
365 - `b`, `w`: Move the caret one word backward or forward, like `<c-left>` and
366 `<c-right>` but a bit “Vim-adjusted” (see the section on Vim below) in order
369 - `0` (or `^`), `$`: Move the caret to the start or end of the line.
371 The above commands (except the ones moving to the start or end of the line)
372 accept a _count._ For example, press `3w` to move three words forward.
374 Press `v` to start selecting text. After doing so, VimFx’s commands for moving
375 the caret select the text instead of just moving the caret. Press `v` again to
376 collapse the selection again. (Note that after pressing `v`, only VimFx’s
377 commands goes into “selection mode,” while Firefox’s work as usual, requiring
378 shift to be held to select text.)
380 `o` moves the caret to the “other end” of the selection. If the caret is at the
381 end of the selection, `o` will move it to the start (while keeping the selection
382 intact), and vice versa. This let’s you adjust the selection in both ends.
384 Finally, `y` is a possibly faster alternative to the good old `<c-c>`. Other
385 than copying the selection to the clipboard, it also exits Caret mode, saving
386 you yet a keystroke. (`<escape>` is unsurprisingly used to exit Caret mode
389 [Firefox’s own Caret mode]: http://kb.mozillazine.org/Accessibility_features_of_Firefox#Allow_text_to_be_selected_with_the_keyboard
393 If you’re lucky, the text you want to copy is located within a single element
394 that contains no other text, such as the text of a link or an inline code
395 snippet. If so, using the `yv` command (which copies an entire element without
396 entering Caret mode) is the fastest.
398 If you want to copy _almost_ all text of an element, or a bit more than it, use
399 the `av` command (which selects an entire element). Then adjust the selection
400 using the various Caret mode commands. Remember that `o` lets you adjust both
401 ends of the selection.
403 In all other cases, use the `v` command to place the caret close to the text you
404 want to copy. Then move the caret in place using the various Caret
405 mode commands, hit `v` to start selecting, and move the again.
407 Use `y` to finish (or `<escape>` to abort). Alternatively, use the `<menu>` key
408 to open the context menu for the selection.
412 As seen above, Caret mode is obviously inspired by Vim’s Visual mode. However,
413 keep in mind that the point of Caret mode is to **copy text using the keyboard,
414 not mimicing Vim’s visual mode.** I’ve found that selecting text for _copying_
415 is different than selecting code for _editing._ Keep that in mind.
417 Working with text selection in webpages using code is a terrible mess full of
418 hacks. New commands will only be added if they _really_ are worth it.
420 A note on VimFx’s `b` and `w`: They work like Vim’s `b` and `w` (but a “word” is
421 according to Firefox’s definition, not Vim’s), except when there is selected
422 text and the caret is at the end of the selection. Then `b` works like Vim’s
423 `ge` and `w` works like Vim’s `e`. The idea is to keep it simple and only
424 provide two commands that do what you want, rather than many just to mimic Vim.
427 ## Ignore mode `<s-f1>`
429 Ignore mode is all about ignoring VimFx commands and sending the keys to the
430 page instead. Sometimes, though, you might want to run some VimFx command even
433 One way of doing that is to press `<s-escape>` to exit Ignore mode, run your
434 command and then enter Ignore mode again using `i`. However, it might be
435 inconvenient having to remember to re-enter Ignore mode, and sometimes that’s
436 not even possible, such as if you ran the `K` command to get to the next tab.
438 Another way is to press `<s-f1>` followed by the Normal mode command you wanted
439 to run. (`<s-f1>` is essentially the inverse of the `I` command, which passes
440 the next keypress on to the page. Internally they’re called “quote” and
441 “unquote.”) This is handy if you’d like to switch away from a [blacklisted]
442 page: Just press for example `<s-f1>K`.
444 `<s-f1>` was chosen as the default shortcut because on a typical keyboard `<f1>`
445 is located just beside `<escape>`, which makes it very similar to `<s-escape>`,
446 which is used to exit Ignore mode. Both of those are uncommonly used by web
447 pages, so they shouldn’t be in the way. If you ever actually do need to send any
448 of those to the page, you can prefix them with `<s-f1>`, because if the key you
449 press after `<s-f1>` is not part of any Normal mode command, the key is sent to
450 the page. (Another way is for example `<s-f1>I<s-escape>`.)
452 [blacklisted]: options.md#blacklist
457 Vim has something called “ex” commands. Want something similar in VimFx? True to
458 its spirit, VimFx embraces a standard Firefox feature for this purpose: The
459 [Developer Toolbar]. That link also includes instructions on how to extend it
460 with your own commands.
462 In the future VimFx might even ship with a few extra “ex” commands by default.
463 We’re open for suggestions!
465 [Developer Toolbar]: https://developer.mozilla.org/en-US/docs/Tools/GCLI