documentation/options.md

   1 <!--
   2 This is part of the VimFx documentation.
   3 Copyright Simon Lydell 2015.
   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 You might also be interested [styling] VimFx and writing a [config file].
  13
  14 [styling]: styling.md
  15 [config file]: config-file.md
  16
  17
  18 ## Regular options
  19
  20 These options are available in VimFx’s settings page in the Add-ons Manager.
  21
  22 ### Hint chars
  23
  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].
  26
  27 [The `f` commands]: commands.md#the-f-commands-1
  28
  29 ### Previous/Next page patterns
  30
  31 Space separated lists of patterns that match links to the previous/next page.
  32 Used by the `[` and `]` commands.
  33
  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
  38 using patterns.
  39
  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.
  44
  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.
  49
  50 Some of the default patterns are English words. You might want to add
  51 alternatives in your own language.
  52
  53 Note: If you need to include a space in your pattern, use `\s`. For example:
  54 `next\spage`.
  55
  56 [`pattern_attrs`]: #pattern_attrs
  57
  58 ### Blacklist
  59
  60 Space separated list of URLs where VimFx should automatically enter Ignore mode.
  61
  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).
  65
  66 You might also want to read about the [Ignore mode `<s-f1>` command][s-f1].
  67
  68 [s-f1]: commands.md#ignore-mode-s-f1
  69
  70 ### Prevent autofocus
  71
  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!
  76
  77 For this reason VimFx can prevent autofocus. It’s not enabled by default,
  78 though, since one of VimFx’s key features is to be nice to your browser and your
  79 habits.
  80
  81 If enabled, all focusing that occurs on page load, or after you’ve just switched
  82 back to a tab from another, until you interact with the page is prevented.
  83
  84 #### Technical notes and trivia
  85
  86 Autofocus on page load and when coming back to a tab are the two most common
  87 cases. Some sites, though, automatically focus a text input in other cases as
  88 well. Trying to catch those cases as well, VimFx used to prevent all focusing
  89 that didn’t occur within a fixed number of milliseconds after your last
  90 interaction (click or keypress). However, this proved to be too aggressive,
  91 preventing too much focusing. In other words, the time-based check was not
  92 sufficent to distinguish between inteded focusing and automatic unwanted
  93 focusing. It made things worse more than it helped. Since these cases are so
  94 difficult (if not impossible) to detect, it is better to leave them. Thankfully
  95 they are not very common.
  96
  97 On page load or when coming back to a tab, before you have interacted with the
  98 page in any way, we can be _sure_ that any focusing is automatic (not caused by
  99 you), which makes it safe to prevent all focusing in those time spans.
 100
 101 ### Ignore keyboard layout
 102
 103 If you use more than one keyboard layout, you probably want to enable this
 104 option.
 105
 106 People who use a keyboard layout without the letters A-Z usually also use the
 107 standard en-US QWERTY layout as well.
 108
 109 This option makes VimFx ignore your current layout and pretend that the standard
 110 en-US QWERTY layout is always used. This way the default shortcuts work even if
 111 your layout doesn’t contain the letters A-Z and all shorcuts can be typed by the
 112 same physical keys on your keyboard regardless of your current keyboard layout.
 113
 114 (If you’d like VimFx to pretend that some other keyboard layout than the
 115 standard en-US QWERTY is always used, you may do so with the special option
 116 [`translations`].)
 117
 118 [`translations`]: #translations
 119
 120 ### Timeout
 121
 122 The maximum amount of time (in milliseconds) that may pass between two
 123 keypresses of a shortcut.
 124
 125 It’s easy to press, say, `a` by mistake while browsing. Without a timeout, you
 126 might be surprised that all search results are highlighted when you a bit later
 127 try to search using the `/` command. (That’s what `a/` does.) _With_ a timeout,
 128 the `a` would be cancelled when the timeout has passed.
 129
 130
 131 ## Advanced options
 132
 133 These options are _not_ available in VimFx’s settings page in the Add-ons
 134 Manager. They can only be changed in [about:config] or using the [public API].
 135 They all start with `extensions.VimFx.`.
 136
 137 (There are actually a few more advanced options than those listed here. You can
 138 see them all in [defaults.coffee].)
 139
 140 [about:config]: http://kb.mozillazine.org/About:config
 141 [public API]: api.md
 142 [defaults.coffee]: ../extension/lib/defaults.coffee
 143
 144 ### `prevent_target_blank`
 145
 146 You might have noticed that some links open in new tabs when you click them.
 147 That is not the case if you “click” them using VimFx’s `f` command, though. If
 148 you dislike that, disable this option.
 149
 150 ### `prevent_autofocus_modes`
 151
 152 Space separated list of modes where `prevent_autofocus` should be used.
 153
 154 ### `hints_timeout`
 155
 156 The number of milliseconds a matched hint marker should stay on screen before
 157 disappearing (or resetting).
 158
 159 ### Scrolling prefs
 160
 161 If you want to customize Firefox’s smooth scrolling, adjusting
 162 `general.smoothScroll.{lines,pages,other}.duration{Min,Max}MS` is the way to
 163 go. VimFx has similar prefs for the scrolling commands, but they work like
 164 `layout.css.scroll-behavior.spring-constant`.
 165
 166 Basically, the higher the value, the faster the scrolling.
 167
 168 These are VimFx’s variants, and the commands they affect:
 169
 170 - `smoothScroll.lines.spring-constant`: `h`, `l`, `j`, `k`
 171 - `smoothScroll.pages.spring-constant`: `d`, `u`, `<space>`, `<s-space>`
 172 - `smoothScroll.other.spring-constant`: `gg`, `G`, `0`, `^`, `$`
 173
 174 Note that the value of these prefs are _strings,_ not numbers!
 175
 176 VimFx’s scrolling commands also respect a few built-in Firefox prefs.
 177
 178 `general.smoothScroll` lets you turn off smooth scrolling entirely, including
 179 all of VimFx’s scrolling commands.
 180
 181 `general.smoothScroll.lines`, `general.smoothScroll.pages`, and
 182 `general.smoothScroll.other` lets you selectively disable smooth scrolling.
 183 VimFx’s scrolling commands follow the same “lines,” “pages” and “other”
 184 categorization as in the above list.
 185
 186 By default you can scroll using the arrow keys in Firefox. You can control how
 187 much they scroll by adjusting the following prefs:
 188
 189 - `toolkit.scrollbox.horizontalScrollDistance`: `<left>`, `<right>`, `h`, `l`
 190 - `toolkit.scrollbox.verticalScrollDistance`:   `<down>`, `<up>`,    `j`, `k`
 191
 192 (VimFx used to have a `scroll_step` pref, but is has been replaced by the
 193 above.)
 194
 195 ### `pattern_selector`
 196
 197 A CSS selector that targets candidates for a previous/next page link.
 198
 199 ### `pattern_attrs`
 200
 201 A space-separated list of attributes that the previous/next page patterns should
 202 be matched against.
 203
 204 ### `hints_toggle_in_tab`
 205
 206 If the keypress that matched a hint starts with this string, toggle whether to
 207 open the matched link in the current tab or a new tab. See [The `f` commands]
 208 for more information.
 209
 210 ### `hints_toggle_in_background`
 211
 212 If the keypress that matched a hint starts with this string, open the matched
 213 link in a new tab and toggle whether to open that tab in the background or
 214 foreground. See [The `f` commands] for more information.
 215
 216 ### `activatable_element_keys`
 217
 218 Keys that should not trigger VimFx commands but be sent through to the page if
 219 an “activatable” element (link or button) is focused.
 220
 221 ### `adjustable_element_keys`
 222
 223 Keys that should not trigger VimFx commands but be sent through to the page if
 224 an “adjustable” element (form control or video player) is focused.
 225
 226
 227 ## Special options
 228
 229 These options are available in neither VimFx’s settings page in the Add-ons
 230 Manager nor in [about:config]. The only way to change them is by using the
 231 [public API].
 232
 233 ### `translations`
 234
 235 See the description of the `translations` option in [vim-like-key-notation].
 236
 237 [vim-like-key-notation]: https://github.com/lydell/vim-like-key-notation#api
 238
 239 ### `categories`
 240
 241 See the documentation for [`vimfx.get('categories')`][categories].
 242
 243 [categories]: api.md#vimfxgetcategories