]> git.gir.st - VimFx.git/blob - documentation/options.md
Show usage of Hints mode modifiers in the help dialog
[VimFx.git] / documentation / options.md
1 <!--
2 This is part of the VimFx documentation.
3 Copyright Simon Lydell 2015, 2016.
4 See the file README.md for copying conditions.
5 -->
6
7 # Options
8
9 VimFx has many options that can be configured, but they all have nice defaults
10 so you shouldn’t need to.
11
12 Advanced users might also be interested in [styling] VimFx and writing a [config
13 file].
14
15 [styling]: styling.md
16 [config file]: config-file.md
17
18
19 ## Regular options
20
21 These options are available in VimFx’s settings page in the Add-ons Manager
22 (where you can also customize [keyboard shortcuts]).
23
24 [keyboard shortcuts]: shortcuts.md
25
26 ### Hint chars
27
28 The characters used for the hints in Hints mode, which can be entered using one
29 of the many [`f` commands] \(and a few `v` commands).
30
31 Quick suggestion: Put more easily reachable keys longer to the left. Put two
32 pretty good (but not the best) keys at the end, after the space.
33
34 Some hint characters are easier to type than others. Many people think that the
35 ones on the home row are the best. VimFx favors keys to the left. That’s why you
36 should put better keys longer to the left.
37
38 The hint characters always contain a single space. This splits them into two
39 groups: _primary_ hint characters (before the space), and _secondary_ hint
40 characters (after the space). Read on to find out why.
41
42 Some markable elements are quicker to find than others. Therefore, VimFx looks
43 for markable elements in two passes for some commands, such as the `f` command.
44 (This is why all hints don’t always appear on screen at the same time). If two
45 passes are used, hints from the _first_ pass can only begin with _primary_ hint
46 characters. In all other cases hints may start with _any_ hint character.
47
48 When choosing how many secondary hint characters you want (there are two by
49 default), think about this: Usually most markable elements are found in the
50 first pass, while fewer are found in the second pass. So it makes sense to have
51 more primary hint characters than secondary. It’s a tradeoff. If you think the
52 hints from the first pass are too long, you probably need more primary hint
53 characters. On the other hand, if you think the hints from the _second_ pass are
54 too long, you might need a few extra secondary hint characters, but remember
55 that it might be at the expense of longer hints in the first pass.
56
57 All of this also help you understand why hints may be slow on some pages:
58
59 - One reason could be that most hints come from a second pass, which are slower
60 to compute (and are worse than first pass hints).
61
62 If a site gets an unusual amount of second pass hints, it might be because the
63 site is badly coded accessibility-wise. If so, consider contacting the site
64 and telling them so, which improves their accessibility for everyone!
65
66 - Another reason could be that a page has a _huge_ amount of links. If that
67 bothers you regularly, feel free to send a pull request with faster code!
68
69 [`f` commands]: commands.md#the-f-commands--hints-mode
70
71 ### “Previous”/“Next” link patterns
72
73 Space separated lists of patterns that match links to the previous/next page.
74 Used by the `[` and `]` commands.
75
76 There is a standardized way for websites to tell browsers the URLs to the
77 previous and next page. VimFx looks for that information in the first place.
78 Unfortunately, many websites don’t provide this information. Then VimFx falls
79 back on looking for links on the page that seem to go to the previous/next page
80 using patterns.
81
82 The patterns are matched at the beginning and end of link text (and the
83 attributes defined by the advanced setting [`pattern_attrs`]). The patterns do
84 not match in the middle of words, so “previous” does not match “previously”.
85 The matching is case <strong>in</strong>sensitive.
86
87 Actually, the patterns are regular expressions. If you do not know what a
88 regular expression is, that’s fine. You can type simple patterns like the
89 default ones without problems. If you do know what it is, though, you have the
90 possibility to create more advanced patterns if needed.
91
92 Some of the default patterns are English words. You might want to add
93 alternatives in your own language.
94
95 Note: If you need to include a space in your pattern, use `\s`. For example:
96 `next\spage`.
97
98 [`pattern_attrs`]: #pattern_attrs
99
100 ### Blacklist
101
102 Space separated list of URLs where VimFx should automatically enter Ignore mode.
103 Example:
104
105 *example.com* http://example.org/editor/*
106
107 Note that the URLs in the list must match the current URL _entirely_ for it to
108 apply. Therefore it is easiest to always use the `*` wildcard (which matches
109 zero or more characters).
110
111 Set the option to `*` to make VimFx start out in Ignore mode _everywhere._
112
113 When you’re done editing the blacklist, go to one of the pages you intend to
114 match. If you already have a tab open for that page, reload it. Then look at
115 VimFx’s [button] to see if your edits work out.
116
117 Note that when Ignore mode is automatically entered because of the blacklist, it
118 is also automatically exited (returning to Normal mode) if you go to a
119 non-blacklisted page in the same tab. On the other hand, if you entered Ignore
120 mode by pressing `i`, you’ll stay in Ignore mode in that tab until you exit it,
121 even if you navigate to another page.
122
123 You might also want to read about the [Ignore mode `<s-f1>` command][s-f1].
124
125 [button]: button.md
126 [s-f1]: commands.md#ignore-mode-s-f1
127
128 #### Blacklisting specific elements
129
130 VimFx automatically enters Ignore mode while Vim-style editors are focused, such
131 as the [wasavi] extension and [CodeMirror editors in Vim mode][codemirror-vim].
132
133 By default, VimFx lets you press `<escape>` to blur text inputs. Also by
134 default, Vim-style editors use `<escape>` to exit from their Insert mode to
135 their Normal mode. In other words, there is a keyboard shortcut conflict here.
136
137 It makes the most sense to let the Vim-style editor “win.” That’s why VimFx
138 (temporarily) enters Ignore mode when focusing such an editor. In Insert mode,
139 there is no `<escape>` shortcut (by default), and thus no conflict. Instead,
140 there’s `<s-escape>` to blur the current element and exit Ignore mode.
141 `<s-escape>` was chosen because it is very unlikely to cause conflicts. If it
142 ever does, there’s the [`<s-f1>`] command to the rescue.
143
144 There is currently no way of specifying your own elements to be blacklisted, but
145 such a feature could be added if there’s demand for it.
146
147 [wasavi]: http://appsweets.net/wasavi/
148 [codemirror-vim]: https://codemirror.net/demo/vim.html
149 [`<s-f1>`]: commands.md#ignore-mode-s-f1
150
151 ### Prevent autofocus
152
153 Many sites autofocus their search box, for example. This might be annoying when
154 browsing using the keyboard, as you do with VimFx, because it often feels like
155 VimFx isn’t responding, until you realize that you are typing in a text box—not
156 running VimFx commands!
157
158 For this reason VimFx can prevent autofocus. It’s not enabled by default,
159 though, since one of VimFx’s key features is to be nice to your browser and your
160 habits.
161
162 If enabled, all focusing that occurs on page load, or after you’ve just switched
163 back to a tab from another, until you interact with the page is prevented.
164
165 #### Technical notes and trivia
166
167 Autofocus on page load and when coming back to a tab are the two most common
168 cases. Some sites, though, automatically focus a text input in other cases as
169 well. Trying to catch those cases as well, VimFx used to prevent all focusing
170 that didn’t occur within a fixed number of milliseconds after your last
171 interaction (click or keypress). However, this proved to be too aggressive,
172 preventing too much focusing. In other words, the time-based check was not
173 sufficient to distinguish between intended focusing and automatic unwanted
174 focusing. It made things worse more than it helped. Since these cases are so
175 difficult (if not impossible) to detect, it is better to leave them. Thankfully
176 they are not very common.
177
178 On page load or when coming back to a tab, before you have interacted with the
179 page in any way, we can be _sure_ that any focusing is automatic (not caused by
180 you), which makes it safe to prevent all focusing in those time spans.
181
182 ### Ignore keyboard layout
183
184 If you use more than one keyboard layout, you probably want to enable this
185 option.
186
187 People who use a keyboard layout _without_ the letters A–Z usually also use the
188 standard en-US QWERTY layout as well.
189
190 This option makes VimFx ignore your current layout and pretend that the standard
191 en-US QWERTY layout is _always_ used. This way the default shortcuts work even
192 if your layout doesn’t contain the letters A–Z and all shortcuts can be typed by
193 the same physical keys on your keyboard regardless of your current keyboard
194 layout.
195
196 (If you’d like VimFx to pretend that some other keyboard layout than the
197 standard en-US QWERTY is always used, you may do so with the special option
198 [`translations`].)
199
200 [`translations`]: #translations
201
202 ### Timeout
203
204 The maximum amount of time (in milliseconds) that may pass between two
205 keypresses of a shortcut.
206
207 It’s easy to press, say, `a` by mistake while browsing. Without a timeout, you
208 might be surprised that all search results are highlighted when you a bit later
209 try to search using the `/` command. (That’s what `a/` does.) _With_ a timeout,
210 the `a` would be cancelled when the timeout has passed.
211
212
213 ## Advanced options
214
215 These options are _not_ available in VimFx’s settings page in the Add-ons
216 Manager. They can only be changed in [about:config] or using a [config file].
217 They all start with `extensions.VimFx.`.
218
219 (There are actually a few more advanced options than those listed here. You can
220 see them all in [defaults.coffee].)
221
222 [about:config]: http://kb.mozillazine.org/About:config
223 [config file]: config-file.md
224 [defaults.coffee]: ../extension/lib/defaults.coffee
225
226 ### `notifications_enabled`
227
228 Controls whether [notifications] should be shown or not.
229
230 You can also choose to show notifications any way you want by listening for the
231 [the `notification` and `hideNotification` events][notification-events].
232
233 [notifications]: notifications.md
234 [notification-events]: api.md#the-notification-and-hidenotification-events
235
236 ### `notify_entered_keys`
237
238 If enabled, a [notification] is shown with the keys you have entered so far of
239 a command. This is only noticeable if you type a multi-key shortcut or use a
240 count.
241
242 [notification]: notifications.md
243
244 ### `prevent_target_blank`
245
246 You might have noticed that some links open in new tabs when you click them.
247 That is not the case if you “click” them using VimFx’s `f` command, though. If
248 you dislike that, disable this option.
249
250 ### `counts_enabled`
251
252 Controls whether [counts] are enabled or not.
253
254 [counts]: commands.md#counts
255
256 ### `find_from_top_of_viewport`
257
258 Toggles whether the various find commands are Vim-style or Firefox
259 default-style.
260
261 Disable this pref if you want `/` to work more like `<c-f>` and `n`/`N` to work
262 more like `<f3>`/`<s-f3>`.
263
264 If there is selected text on the page, Firefox starts searching after that.
265 VimFx does so too, but only if the selection is currently _visible_ (inside the
266 current viewport).
267
268 If there _isn’t_ selected text on the page, Firefox starts searching from the
269 top of the page. VimFx instead starts searching from the top of the current
270 viewport.
271
272 The VimFx behavior is designed to be less disorienting. It is also similar to
273 how searching in Vim works. Again, you can return to the Firefox default
274 behavior (if you prefer that) by disabling this pref.
275
276 One of the main benefits of the VimFx behavior is that you can scroll past a
277 block of the text with lots of search matches and then continue going through
278 matches with `n` after that block, without having to spam `n` lots and lots of
279 times.
280
281 ### `ignore_ctrl_alt`
282
283 This option is enabled by default on Windows, and disabled otherwise.
284
285 If enabled, ignores ctrl+alt for printable keys. `<a-c-$>` becomes `$` and
286 `<a-c-A>` becomes `A`, while `<a-c-enter>` stays the same.
287
288 This option is suitable on Windows, which treats [AltGr as
289 ctrl+alt][wikipedia-altgr]. For example, if a user of the sv-SE layout on
290 Windows holds AltGr and presses the key labeled `4`, in order to produce a `$`,
291 the result would be `<a-c-$>` without this option, making it impossible to
292 trigger a keyboard shortcut containing `$`. _With_ this option the result is
293 `$`, as expected (and as on GNU/Linux). On the other hand it won’t be possible
294 to trigger keyboard shortcuts such as `<a-c-a>`, but ctrl+alt keyboard shortcuts
295 are [discouraged on Windows][wikipedia-altgr] anyway because of this reason.
296
297 [wikipedia-altgr]: https://en.wikipedia.org/wiki/AltGr_key#Control_.2B_Alt_as_a_substitute
298
299 ### `prevent_autofocus_modes`
300
301 Space separated list of modes where `prevent_autofocus` should be used.
302
303 ### `config_file_directory`
304
305 VimFx can optionally be customized using a [config file]. If you want to that,
306 you need to tell VimFx where that file is. That’s what this pref is for.
307
308 By default this pref is blank (the empty string), which means that no config
309 file should be loaded.
310
311 If non-blank, it should be the path to the directory where the config file
312 exists. See the [config file] documentation for more information.
313
314 [config file]: config-file.md
315
316 ### `blur_timeout`
317
318 The number of milliseconds VimFx should wait after an element has been blurred
319 before checking if you’re inside a text input or not.
320
321 Some sites with fancy text inputs (such as twitter) blur the text input for a
322 split second and then re-focus it again while typing (for some reason). If you
323 happen to press a key during that split second, that key might trigger a VimFx
324 shortcut instead of typing into the text input, which can be quite annoying. To
325 avoid the problem, VimFx waits a bit before checking if you have left the text
326 input.
327
328 ### `hints_timeout`
329
330 The number of milliseconds a matched hint marker should stay on screen before
331 disappearing (or resetting).
332
333 ### `hints_sleep`
334
335 In Hints mode, VimFx continually checks if the element for a hint marker has
336 moved. If so, the marker is moved as well. This pref controls how many
337 milliseconds VimFx should “sleep” between each check. The shorter, the more CPU
338 usage, the longer, the more stuttery marker movement.
339
340 The default value should work fine, but if you have a low-performing computer
341 and you notice bothering CPU usage during Hints mode you might want to raise the
342 sleep time.
343
344 Set it to -1 to disable the marker movement feature entirely.
345
346 ### Scrolling prefs
347
348 Apart from its own prefs, VimFx also respects a few built-in Firefox prefs.
349
350 #### Smooth scrolling
351
352 If you want to customize Firefox’s smooth scrolling, adjusting
353 `general.smoothScroll.{lines,pages,other}.duration{Min,Max}MS` is the way to
354 go. VimFx has similar prefs for the scrolling commands, but they work like
355 `layout.css.scroll-behavior.spring-constant`.
356
357 Basically, the higher the value, the faster the scrolling.
358
359 These are VimFx’s variants, and the commands they affect:
360
361 - `smoothScroll.lines.spring-constant`: `h`, `l`, `j`, `k`
362 - `smoothScroll.pages.spring-constant`: `d`, `u`, `<space>`, `<s-space>`
363 - `smoothScroll.other.spring-constant`: `gg`, `G`, `0`, `^`, `$`, `` ` ``
364
365 Note that the value of these prefs are _strings,_ not numbers!
366
367 Unfortunately, Firefox provides no way for code to tell which “spring constant”
368 it wants when scrolling smoothly. All VimFx can do is to temporarily set
369 Firefox’s `layout.css.scroll-behavior.spring-constant` pref. It is reset again
370 after one second (by default). If that doesn’t work out for you, you can
371 customize that timeout using the `scroll.reset_timeout` pref.
372
373 The Firefox pref `general.smoothScroll` lets you turn off smooth scrolling
374 entirely, including all of VimFx’s scrolling commands.
375
376 `general.smoothScroll.lines`, `general.smoothScroll.pages`, and
377 `general.smoothScroll.other` lets you selectively disable smooth scrolling.
378 VimFx’s scrolling commands follow the same “lines,” “pages” and “other”
379 categorization as in the above list.
380
381 #### Scroll step
382
383 By default you can scroll using the arrow keys in Firefox. You can control how
384 much they scroll by adjusting the following prefs:
385
386 - `toolkit.scrollbox.horizontalScrollDistance`: `<left>`, `<right>`, `h`, `l`
387 - `toolkit.scrollbox.verticalScrollDistance`: `<down>`, `<up>`, `j`, `k`
388
389 (VimFx used to have a `scroll_step` pref, but is has been replaced by the
390 above.)
391
392 #### `scroll.full_page_adjustment` and `scroll.half_page_adjustment`
393
394 An important use case for scrolling a full page down is to read an entire page
395 (a window-full) of text, press `<space>` and then continue reading the next
396 page. However, if you can only see, say, _half_ of the height the last line,
397 pressing `<space>` would give you the other half, but reading only the top or
398 bottom parts of letters is difficult. Even if the lines happen to line up with
399 the window edge to not be sliced horizontally, it might feel disorienting
400 pressing `<space>`.
401
402 For this reason, both VimFx and Firefox by default scroll _about a line less
403 than a whole page_ when pressing `<space>`. This solves the sliced-last-line
404 problem, and provides some context on where you are in the text you’re reading.
405
406 These two prefs control how many pixels “about a line” actually means for the
407 different page scrolling commands.
408
409 - `scroll.full_page_adjustment`: `<space>, `<s-space>`
410 - `scroll.half_page_adjustment`: `d`, `u`
411
412 #### `scroll.last_position_mark`
413
414 The special mark for the [`` ` ``][scroll-to-mark] command that takes you to the
415 last position.
416
417 [scroll-to-mark]: commands.md#marks-m-and-
418
419 ### `pattern_selector`
420
421 A CSS selector that targets candidates for a previous/next page link.
422
423 ### `pattern_attrs`
424
425 A space-separated list of attributes that the [“Previous”/“Next” link patterns]
426 should be matched against.
427
428 [“Previous”/“Next” link patterns]: #previousnext-link-patterns
429
430 ### `hints_peek_through`
431
432 This pref doesn’t do much. If you’ve used custom [styling] to change which
433 modifier lets you peek through markers in [Hints mode], you might want to change
434 this pref as well. Otherwise VimFx’s Keyboard Shortcuts dialog will still tell
435 you to press shift for this task.
436
437 [styling]: styling.md
438 [Hints mode]: commands.md#the-f-commands--hints-mode
439
440 ### `hints_toggle_in_tab`
441
442 If the keypress that matched a hint starts with this string, toggle whether to
443 open the matched link in the current tab or a new tab. See [The `f` commands]
444 for more information.
445
446 ### `hints_toggle_in_background`
447
448 If the keypress that matched a hint starts with this string, open the matched
449 link in a new tab and toggle whether to open that tab in the background or
450 foreground. See [The `f` commands] for more information.
451
452 ### `activatable_element_keys`
453
454 Keys that should not trigger VimFx commands but be sent through to the page if
455 an “activatable” element (link or button) is focused.
456
457 ### `adjustable_element_keys`
458
459 Keys that should not trigger VimFx commands but be sent through to the page if
460 an “adjustable” element (form control or video player) is focused.
461
462 ### `focus_previous_key` and `focus_next_key`
463
464 The default values are `<s-tab` and `<tab>`, respectively. Those keys are
465 specially handled after focusing a text input using [`gi`]. To disable this
466 special handling, set the prefs to the empty string.
467
468 [`gi`]: commands.md#gi-1
469
470
471 ## Special options
472
473 These options are available in neither VimFx’s settings page in the Add-ons
474 Manager nor in [about:config]. The only way to change them is by using the
475 a [config file].
476
477 ### `translations`
478
479 See the description of the `translations` option in [vim-like-key-notation].
480
481 [vim-like-key-notation]: https://github.com/lydell/vim-like-key-notation#api
482
483 ### `categories`
484
485 See the documentation for [`vimfx.get('categories')`][categories].
486
487 [categories]: api.md#vimfxgetcategories
Imprint / Impressum