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