2 This is part of the VimFx documentation.
3 Copyright Simon Lydell 2015.
4 See the file README.md for copying conditions.
9 VimFx has many options that can be configured, but they all have nice defaults
10 so you shouldn’t need to.
12 You might also be interested [styling] VimFx and writing a [config file].
15 [config file]: config-file.md
20 These options are available in VimFx’s settings page in the Add-ons Manager.
24 The characters used for the hints in Hints mode, which can be entered using one
25 of the many `f` commands. See also [The `f` commands].
27 [The `f` commands]: commands.md#the-f-commands-1
29 ### Previous/Next page patterns
31 Space separated lists of patterns that match links to the previous/next page.
32 Used by the `[` and `]` commands.
34 There is a standardized way for websites to tell browsers the URLs to the
35 previous and next page. VimFx looks for that information in the first place.
36 Unfortunately, many websites don’t provide this information. Then VimFx falls
37 back on looking for links on the page that seem to go to the previous/next page
40 The patterns are matched at the beginning and end of link text (and the
41 attributes defined by the advanced setting [`pattern_attrs`]). The patterns do
42 not match in the middle of words, so “previous” does not match “previously”.
43 The matching is case <strong>in</strong>sensitive.
45 Actually, the patterns are regular expressions. If you do not know what a
46 regular expression is, that’s fine. You can type simple patterns like the
47 default ones without problems. If you do know what it is, though, you have the
48 possibility to create more advanced patterns if needed.
50 Some of the default patterns are English words. You might want to add
51 alternatives in your own language.
53 Note: If you need to include a space in your pattern, use `\s`. For example:
56 [`pattern_attrs`]: #pattern_attrs
60 Space separated list of URLs where VimFx should automatically enter Ignore mode.
62 Note that the URLs in the list must match the current URL _entirely_ for it to
63 apply. Therefore it is easiest to always use the `*` wildcard (which matches
64 zero or more characters).
66 You might also want to read about the [Ignore mode `<s-f1>` command][s-f1].
68 [s-f1]: commands.md#ignore-mode-s-f1
72 Many sites autofocus their search box, for example. This might be annoying when
73 browsing using the keyboard, as you do with VimFx, because it often feels like
74 VimFx isn’t responding, until you realize that you are typing in a text box—not
75 running VimFx commands!
77 For this reason VimFx prevents autofocus. If you dislike that, or think the
78 prevention is too aggressive, you may disable it, returning to the standard
81 What is meant by “aggressive”? Well, in fact it is very hard to tell if a focus
82 was an “autofocus” or a “regular focus” caused by you. VimFx prevents all
83 focusing that doesn’t happen reasonably close (200ms by default) to an
84 interaction by you (such as clicking something or using one of the `f`
85 commands). (You may change what “reasonably close” means through the advanced
86 setting [`autofocus_limit`]).
88 [`autofocus_limit`]: #autofocus_limit
90 ### Ignore keyboard layout
92 If you use more than one keyboard layout, you probably want to enable this
95 People who use a keyboard layout without the letters A-Z usually also use the
96 standard en-US QWERTY layout as well.
98 This option makes VimFx ignore your current layout and pretend that the standard
99 en-US QWERTY layout is always used. This way the default shortcuts work even if
100 your layout doesn’t contain the letters A-Z and all shorcuts can be typed by the
101 same physical keys on your keyboard regardless of your current keyboard layout.
103 (If you’d like VimFx to pretend that some other keyboard layout than the
104 standard en-US QWERTY is always used, you may do so with the special option
107 [`translations`]: #translations
111 The maximum amount of time (in milliseconds) that may pass between two
112 keypresses of a shortcut.
114 It’s easy to press, say, `a` by mistake while browsing. Without a timeout, you
115 might be surprised that all search results are highlighted when you a bit later
116 try to search using the `/` command. (That’s what `a/` does.) _With_ a timeout,
117 the `a` would be cancelled when the timeout has passed.
122 These options are _not_ available in VimFx’s settings page in the Add-ons
123 Manager. They can only be changed in [about:config] or using the [public API].
124 They all start with `extensions.VimFx.`.
126 (There are actually a few more advanced options than those listed here. You can
127 see them all in [defaults.coffee].)
129 [about:config]: http://kb.mozillazine.org/About:config
131 [defaults.coffee]: ../extension/lib/defaults.coffee
133 ### `prevent_target_blank`
135 You might have noticed that some links open in new tabs when you click them.
136 That is not the case if you “click” them using VimFx’s `f` command, though. If
137 you dislike that, disable this option.
139 ### `autofocus_limit`
141 If `prevent_autofocus` is enabled, all focus events except those that occur
142 within this number of milliseconds after a user interaction are suppressed.
144 If you set i to 0, _all_ programmaticly invoked focus events in web pages will
145 be prevented. Only focus events as the result of you clicking or pressing a key
146 are allowed. Some sites automatically focuses inputs after clicking some button,
147 which might make this undesireable.
149 Setting it to a very large value basically has the same effact as turning of
152 ### `prevent_autofocus_modes`
154 Space separated list of modes where `prevent_autofocus` should be used.
158 The number of milliseconds a matched hint marker should stay on screen before
159 disappearing (or resetting).
163 If you want to customize Firefox’s smooth scrolling, adjusting
164 `general.smoothScroll.{lines,pages,other}.duration{Min,Max}MS` is the way to
165 go. VimFx has similar prefs for the scrolling commands, but they work like
166 `layout.css.scroll-behavior.spring-constant`.
168 Basically, the higher the value, the faster the scrolling.
170 These are VimFx’s variants, and the commands they affect:
172 - `smoothScroll.lines.spring-constant`: `h`, `l`, `j`, `k`
173 - `smoothScroll.pages.spring-constant`: `d`, `u`, `<space>`, `<s-space>`
174 - `smoothScroll.other.spring-constant`: `gg`, `G`, `0`, `^`, `$`
176 Note that the value of these prefs are _strings,_ not numbers!
178 VimFx’s scrolling commands also respect a few built-in Firefox prefs.
180 `general.smoothScroll` lets you turn off smooth scrolling entirely, including
181 all of VimFx’s scrolling commands.
183 `general.smoothScroll.lines`, `general.smoothScroll.pages`, and
184 `general.smoothScroll.other` lets you selectively disable smooth scrolling.
185 VimFx’s scrolling commands follow the same “lines,” “pages” and “other”
186 categorization as in the above list.
188 By default you can scroll using the arrow keys in Firefox. You can control how
189 much they scroll by adjusting the following prefs:
191 - `toolkit.scrollbox.horizontalScrollDistance`: `<left>`, `<right>`, `h`, `l`
192 - `toolkit.scrollbox.verticalScrollDistance`: `<down>`, `<up>`, `j`, `k`
194 (VimFx used to have a `scroll_step` pref, but is has been replaced by the
197 ### `pattern_selector`
199 A CSS selector that targets candidates for a previous/next page link.
203 A space-separated list of attributes that the previous/next page patterns should
206 ### `hints_toggle_in_tab`
208 If the keypress that matched a hint starts with this string, toggle whether to
209 open the matched link in the current tab or a new tab. See [The `f` commands]
210 for more information.
212 ### `hints_toggle_in_background`
214 If the keypress that matched a hint starts with this string, open the matched
215 link in a new tab and toggle whether to open that tab in the background or
216 foreground. See [The `f` commands] for more information.
218 ### `activatable_element_keys`
220 Keys that should not trigger VimFx commands but be sent through to the page if
221 an “activatable” element (link or button) is focused.
223 ### `adjustable_element_keys`
225 Keys that should not trigger VimFx commands but be sent through to the page if
226 an “adjustable” element (form control or video player) is focused.
231 These options are available in neither VimFx’s settings page in the Add-ons
232 Manager nor in [about:config]. The only way to change them is by using the
237 See the description of the `translations` option in [vim-like-key-notation].
239 [vim-like-key-notation]: https://github.com/lydell/vim-like-key-notation#api
243 See the documentation for [`vimfx.get('categories')`][categories].
245 [categories]: api.md#vimfxgetcategories