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 Insert 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 ### Prevent autofocus
  67
  68 Many sites autofocus their search box, for example. This might be annoying when
  69 browsing using the keyboard, as you do with VimFx, because it often feels like
  70 VimFx isn’t responding, until you realize that you are typing in a text box—not
  71 running VimFx commands!
  72
  73 For this reason VimFx prevents autofocus. If you dislike that, or think the
  74 prevention is too aggressive, you may disable it, returning to the standard
  75 behavior.
  76
  77 What is meant by “aggressive”? Well, in fact it is very hard to tell if a focus
  78 was an “autofocus” or a “regular focus” caused by you. VimFx prevents all
  79 focusing that doesn’t happen reasonably close (200ms by default) to an
  80 interaction by you (such as clicking something or using one of the `f`
  81 commands). (You may change what “reasonably close” means through the advanced
  82 setting [`autofocus_limit`]).
  83
  84 [`autofocus_limit`]: #autofocus_limit
  85
  86 ### Ignore keyboard layout
  87
  88 If you use more than one keyboard layout, you probably want to enable this
  89 option.
  90
  91 People who use a keyboard layout without the letters A-Z usually also use the
  92 standard en-US QWERTY layout as well.
  93
  94 This option makes VimFx ignore your current layout and pretend that the standard
  95 en-US QWERTY layout is always used. This way the default shortcuts work even if
  96 your layout doesn’t contain the letters A-Z and all shorcuts can be typed by the
  97 same physical keys on your keyboard regardless of your current keyboard layout.
  98
  99 (If you’d like VimFx to pretend that some other keyboard layout than the
 100 standard en-US QWERTY is always used, you may do so with the special option
 101 [`translations`].)
 102
 103 [`translations`]: #translations
 104
 105 ### Timeout
 106
 107 The maximum amount of time (in milliseconds) that may pass between two
 108 keypresses of a shortcut.
 109
 110 It’s easy to press, say, `a` by mistake while browsing. Without a timeout, you
 111 might be surprised that all search results are highlighted when you a bit later
 112 try to search using the `/` command. (That’s what `a/` does.) _With_ a timeout,
 113 the `a` would be cancelled when the timeout has passed.
 114
 115
 116 ## Advanced options
 117
 118 These options are _not_ available in VimFx’s settings page in the Add-ons
 119 Manager. They can only be changed in [about:config] or using the [public API].
 120 They all start with `extensions.VimFx.`.
 121
 122 (There are actually a few more advanced options than those listed here. You can
 123 see them all in [defaults.coffee].)
 124
 125 [about:config]: http://kb.mozillazine.org/About:config
 126 [public API]: api.md
 127 [defaults.coffee]: ../extension/lib/defaults.coffee
 128
 129 ### `prevent_target_blank`
 130
 131 You might have noticed that some links open in new tabs when you click them.
 132 That is not the case if you “click” them using VimFx’s `f` command, though. If
 133 you dislike that, disable this option.
 134
 135 ### `autofocus_limit`
 136
 137 If `prevent_autofocus` is enabled, all focus events except those that occur
 138 within this number of milliseconds after a user interaction are suppressed.
 139
 140 If you set i to 0, _all_ programmaticly invoked focus events in web pages will
 141 be prevented. Only focus events as the result of you clicking or pressing a key
 142 are allowed. Some sites automatically focuses inputs after clicking some button,
 143 which might make this undesireable.
 144
 145 Setting it to a very large value basically has the same effact as turning of
 146 `prevent_autofocus`.
 147
 148 ### `prevent_autofocus_modes`
 149
 150 Space separated list of modes where `prevent_autofocus` should be used.
 151
 152 ### `hints_timeout`
 153
 154 The number of milliseconds a matched hint marker should stay on screen before
 155 disappearing (or resetting).
 156
 157 ### Scrolling prefs
 158
 159 If you want to customize Firefox’s smooth scrolling, adjusting
 160 `general.smoothScroll.{lines,pages,other}.duration{Min,Max}MS` is the way to
 161 go. VimFx has similar prefs for the scrolling commands, but they work like
 162 `layout.css.scroll-behavior.spring-constant`.
 163
 164 Basically, the higher the value, the faster the scrolling.
 165
 166 These are VimFx’s variants, and the commands they affect:
 167
 168 - `smoothScroll.lines.spring-constant`: `h`, `l`, `j`, `k`
 169 - `smoothScroll.pages.spring-constant`: `d`, `u`, `<space>`, `<s-space>`
 170 - `smoothScroll.other.spring-constant`: `gg`, `G`, `0`, `^`, `$`
 171
 172 Note that the value of these prefs are _strings,_ not numbers!
 173
 174 VimFx’s scrolling commands also respect a few built-in Firefox prefs.
 175
 176 `general.smoothScroll` lets you turn off smooth scrolling entirely, including
 177 all of VimFx’s scrolling commands.
 178
 179 `general.smoothScroll.lines`, `general.smoothScroll.pages`, and
 180 `general.smoothScroll.other` lets you selectively disable smooth scrolling.
 181 VimFx’s scrolling commands follow the same “lines,” “pages” and “other”
 182 categorization as in the above list.
 183
 184 By default you can scroll using the arrow keys in Firefox. You can control how
 185 much they scroll by adjusting the following prefs:
 186
 187 - `toolkit.scrollbox.horizontalScrollDistance`: `<left>`, `<right>`, `h`, `l`
 188 - `toolkit.scrollbox.verticalScrollDistance`:   `<down>`, `<up>`,    `j`, `k`
 189
 190 (VimFx used to have a `scroll_step` pref, but is has been replaced by the
 191 above.)
 192
 193 ### `pattern_selector`
 194
 195 A CSS selector that targets candidates for a previous/next page link.
 196
 197 ### `pattern_attrs`
 198
 199 A space-separated list of attributes that the previous/next page patterns should
 200 be matched against.
 201
 202 ### `activatable_element_keys`
 203
 204 Keys that should not trigger VimFx commands but be sent through to the page if
 205 an “activatable” element (link or button) is focused.
 206
 207 ### `adjustable_element_keys`
 208
 209 Keys that should not trigger VimFx commands but be sent through to the page if
 210 an “adjustable” element (form control or video player) is focused.
 211
 212
 213 ## Special options
 214
 215 These options are available in neither VimFx’s settings page in the Add-ons
 216 Manager nor in [about:config]. The only way to change them is by using the
 217 [public API].
 218
 219 ### `translations`
 220
 221 See the description of the `translations` option in [vim-like-key-notation].
 222
 223 [vim-like-key-notation]: https://github.com/lydell/vim-like-key-notation#api