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.
57 Note that unread tabs are never considered _visited._ See the `gL` command
62 Selects the _count_ oldest unread tab.
64 Unread tabs are tabs opened in the background, for example by using the `F`
65 command, that you have not yet visited.
67 Tip: It might help to make unread tabs visually different through custom
68 [styling]. The following makes the tab titles of unread tabs italic:
71 .tabbrowser-tab[unread]:not(#override) {
72 font-style: italic !important;
80 Moves the current tab _count_ tabs forward/backward.
82 As opposed to `J` and `K`, pinned and non-pinned tabs are handled separately.
83 The first non-pinned tab wraps to the last tab, and the last tab wraps to the
84 first non-pinned tab, and vice versa for non-pinned tabs. Use `gp` to move a tab
85 between the pinned and non-pinned parts of the tab bar.
87 Other than the above, the count and wrap semantics work like `J` and `K`.
91 `g0` selects the tab at index _count,_ counting from the start.
93 `g^` selects the tab at index _count,_ counting from the first non-pinned tab.
95 `g$` selects the tab at index _count,_ counting from the end.
99 Closes the current tab and _count_ minus one of the following tabs.
103 Restores the _count_ last closed tabs.
107 Passes on the next _count_ keypresses to the page, without activating VimFx
112 Explained in the their own section below.
116 Explained in its own section below.
119 ## Scrolling commands
121 Firefox lets you scroll with the arrow keys, page down, page up, home, end and
122 space by default. VimFx provides similar scrolling commands (and actually
123 overrides `<space>`), but they work a little bit differently.
125 They scroll _the currently focused element._ If the currently focused element
126 isn’t scrollable, the largest scrollable element on the page (if any, and
127 including the entire page itself) is scrolled.
129 You can focus scrollable elements using the `zf` command (or the `f` command).
130 Scrollable browser elements, such as in the dev tools, can be focused using the
131 `zF` command. The right border of hint markers for scrollable elements is styled
132 to remind of a scroll bar, making them easier to recognize among hints for
135 Note that `zf` and `f` do _not_ add a hint marker for the _largest_ scrollable
136 element (such as the entire page). There’s no need to focus that element, since
137 it is scrolled by default if no other scrollable element is focused, as
138 explained above. (This prevents the largest scrollable element from likely
139 eating your best hint char on most pages; see [The `f` commands]).
141 [The `f` commands]: #the-f-commands--hints-mode
143 ### Marks: `m` and `` ` ``
145 Other than traditional scrolling, VimFx has _marks._ Press `m` followed by a
146 letter to associate the current scroll position with that letter. For example,
147 press `ma` to save the position into mark _a._ Then you can return to that
148 position by pressing `` ` `` followed by the same letter, e.g. `` `a ``.
150 One mark is special: `` ` ``. Pressing ``` `` ``` takes you to the scroll
151 position before the last `gg`, `G`, `0`, `$`, `/`, `n`, `N` or `` ` ``. (You can
152 change this mark using the [`scroll.last_position_mark`] pref.)
154 [`scroll.last_position_mark`]: options.md#scroll.last_position_mark
158 Unlike Vim, you may press _any_ key after `m`, and the scroll position will be
159 associated with that key (Vim allows only a–z, roughly).
161 Unlike Vim and Vimium, VimFx has no global marks. The reason is that they would
162 be a lot more complicated to implement and do not seem useful enough to warrant
165 As mentioned above, `m` stores the _current scroll position._ Specifically, that
166 means the scroll position of the element that would be scrolled if the active
167 element isn’t scrollable; see [Scrolling commands] above.
169 [Scrolling commands]: #scrolling-commands-1
174 `gi` focuses the text input you last used, or the first one on the page. Note
175 that a [prevented autofocus] still counts as having focused and used a text
176 input. This allows you to have your cake and eat it too: You can enable
177 autofocus prevention, and type `gi` when you wish you hadn’t.
179 `gi` takes a count. It then selects the `counth` text input on the page. Note
180 that `gi` and `1gi` are different: The latter _always_ focuses the first input
181 of the page, regradless of which input you used last.
183 After having focused a text input using `gi`, `<tab>` and `<s-tab>` will _only
184 cycle between text inputs,_ instead of moving the focus between _all_ focusable
185 elements as they usually do. (See also the [`focus_previous_key` and
186 `focus_next_key`] advanced options.)
188 [prevented autofocus]: options.md#prevent-autofocus
189 [`focus_previous_key` and `focus_next_key`]: options.md#focus_previous_key-and-focus_next_key
192 ## The `f` commands / Hints mode
194 When invoking one of the `f` commands you enter Hints mode. In Hints mode,
195 markers with hints are shown for some elements. By typing the letters of a hint
196 something is done to that element, depending on the command.
198 Another way to find links on the page is to use `g/`. It’s like the regular find
199 command (`/`), except that it searches links only.
201 Which elements get hints depends on the command as well:
203 - `f` and `af`: Anything clickable—links, buttons, form controls.
204 - `F`, `gf` and `gF`: Anything that can be opened in a new tab or window—links.
205 - `yf`: Anything that has something useful to copy—links (their URL) and text
207 - `zf`: Anything focusable—links, buttons, form controls, scrollable elements,
209 - `zF`: Browser elements, such as toolbar buttons.
211 It might seem simpler to match the same set of elements for _all_ of the
212 commands. The reason that is not the case is because the fewer elements the
213 shorter the hints. (Also, what should happen if you tried to `F` a button?)
215 (You can also customize [which elements do and don’t get hints][hint-matcher].)
217 Another way to make hints shorter is to assign the same hint to all links with
218 the same URL. So don’t get surprised if you see the same hint repeated several
221 VimFx also tries to give you shorter hints for elements that you are more likely
222 to click. This is done by the surprisingly simple rule: The larger the element,
223 the shorter the hint.
225 There are standardized elements which are always clickable—_semantically_
226 clickable elements. Unfortunately, many sites use unclickable elements and then
227 make them clickable using JavaScript—<em>un</em>semantically clickable elements.
228 Such elements are difficult to find. VimFx has a few techniques for doing so,
229 which works many times but not always, but unfortunately they sometimes produce
230 false positives. Many times those false positives are pretty large elements,
231 which according to the last paragraph would give them really short hints, making
232 other more important elements suffer by getting longer ones. Therefore VimFx
233 favors semantic elements over unsemantic ones and takes that into account when
234 deciding the hint length for elements.
236 Some hint characters are easier to type than others. The ones on the home row
237 are of course the best. When customizing the [hint chars] option you should put
238 the best keys to the left and the worst ones to the right. VimFx favors keys to
239 the left, so that should give you the optimal hints.
241 Hints are added on top of the corresponding element. If they obscure the display
242 too much you can hold shift to make them transparent. (See [Styling] if you’d
243 like to change that.) The hints can also sometimes cover each other. Press
244 `<space>` and `<s-space>` to switch which one should be on top.
246 When giving a count to an `f` command, all markers will be re-shown after you’ve
247 typed the hint characters of one of them, _count_ minus one times. All but the
248 last time, the marker’s link will be opened in a new background tab. The last
249 time the command opens links as normal (in the current tab (`f`) or in a new
250 background (`F`) or foreground tab (`gf`)).
252 Note that the `f` command adds markers not only to links, but to buttons and
253 form controls as well. What happens the _count_ minus one times then? Buttons,
254 checkboxes and the like are simply clicked, allowing you to quickly check many
255 checkboxes in one go, for example. Text inputs cancel the command.
257 `af` works as if you’d supplied an infinite count to `f`. (In fact, the `af`
258 command is implemented by running the same function as for the `f` command,
259 passing `Infinity` as the `count` argument!) Therefore the `af` command does not
260 accept a count itself.
262 The `gF`, `zf`, `yf` and `zF` commands do not accept counts.
264 Press `<enter>` to increase the count by one. This is useful when you’ve already
265 entered Hints mode but realize that you want to interact with yet a marker. This
266 can be faster than going into Hints mode once more.
268 If you’ve pressed `f` but realize that you’d rather open a link in a new tab you
269 can hold ctrl while typing the last hint character. This is similar to how you
270 can press `<c-enter>` on a focused link to open it in a new tab (while just
271 `<enter>` would have opened it in the same tab). Hold alt to open in a new
272 foreground tab. In other words, holding ctrl works as if you’d pressed `F` from
273 the beginning, and holding alt works as if you’d pressed `gf`.
275 For the `F` and `gf` commands, holding ctrl makes them open links in the same
276 tab instead, as if you’d used the `f` command. Holding alt toggles whether to
277 open tabs in the background or foreground—it makes `F` work like `gf`, and `gf`
280 (Also see the advanced prefs [hints\_toggle\_in\_tab] and
281 [hints\_toggle\_in\_background].)
283 [hint-matcher]: api.md#vimfxhintmatcher
284 [hint chars]: options.md#hint-chars
285 [Styling]: styling.md
286 [hints\_toggle\_in\_tab]: options.md#hints_toggle_in_tab
287 [hints\_toggle\_in\_background]: options.md#hints_toggle_in_background
290 ## Ignore mode `<s-f1>`
292 Ignore mode is all about ignoring VimFx commands and sending the keys to the
293 page instead. Sometimes, though, you might want to run some VimFx command even
296 One way of doing that is to press `<s-escape>` to exit Ignore mode, run your
297 command and then enter Ignore mode again using `i`. However, it might be
298 inconvenient having to remember to re-enter Ignore mode, and sometimes that’s
299 not even possible, such as if you ran the `K` command to get to the next tab.
301 Another way is to press `<s-f1>` followed by the Normal mode command you wanted
302 to run. (`<s-f1>` is essentially the inverse of the `I` command, which passes
303 the next keypress on to the page. Internally they’re called “quote” and
304 “unquote.”) This is handy if you’d like to switch away from a [blacklisted]
305 page: Just press for example `<s-f1>K`.
307 `<s-f1>` was chosen as the default shortcut because on a typical keyboard `<f1>`
308 is located just beside `<escape>`, which makes it very similar to `<s-escape>`,
309 which is used to exit Ignore mode. Both of those are uncommonly used by web
310 pages, so they shouldn’t be in the way. If you ever actually do need to send any
311 of those to the page, you can prefix them with `<s-f1>`, because if the key you
312 press after `<s-f1>` is not part of any Normal mode command, the key is sent to
313 the page. (Another way is for example `<s-f1>I<s-escape>`.)
315 [blacklisted]: options.md#blacklist
320 Vim has something called “ex” commands. Want something similar in VimFx? True to
321 its spirit, VimFx embraces a standard Firefox feature for this purpose: The
322 [Developer Toolbar]. That link also includes instructions on how to extend it
323 with your own commands.
325 In the future VimFx might even ship with a few extra “ex” commands by default.
326 We’re open for suggestions!
328 [Developer Toolbar]: https://developer.mozilla.org/en-US/docs/Tools/GCLI