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 ## Regular options
  10
  11 These options are available in VimFx’s settings page in the Add-ons Manager.
  12
  13 ### Hint chars
  14
  15 The characters used for the hints in Hints mode, which can be entered using one
  16 of the many `f` commands.
  17
  18 ### Previous/Next page patterns
  19
  20 Space separated lists of patterns that match links to the previous/next page.
  21 Used by the `[` and `]` commands.
  22
  23 There is a standardized way for websites to tell browsers the URLs to the
  24 previous and next page. VimFx looks for that information in the first place.
  25 Unfortunately, many websites don’t provide this information. Then VimFx falls
  26 back on looking for links on the page that seem to go to the previous/next page
  27 using patterns.
  28
  29 The patterns are matched at the beginning and end of link text (and the
  30 attributes defined by the advanced setting [`pattern_attrs`]). The patterns do
  31 not match in the middle of words, so “previous” does not match “previously”.
  32 The matching is case <strong>in</strong>sensitive.
  33
  34 Actually, the patterns are regular expressions. If you do not know what a
  35 regular expression is, that’s fine. You can type simple patterns like the
  36 default ones without problems. If you do know what it is, though, you have the
  37 possibility to create more advanced patterns if needed.
  38
  39 Some of the default patterns are English words. You might want to add
  40 alternatives in your own language.
  41
  42 Note: If you need to include a space in your pattern, use `\s`. For example:
  43 `next\spage`.
  44
  45 [`pattern_attrs`]: #pattern_attrs
  46
  47 ### Blacklist
  48
  49 Space separated list of URLs where VimFx should automatically enter Insert mode.
  50
  51 Note that the URLs in the list must match the current URL _entirely_ for it to
  52 apply. Therefore it is easiest to always use the `*` wildcard (which matches
  53 zero or more characters).
  54
  55 ### Prevent autofocus
  56
  57 Many sites autofocus their search box, for example. This might be annoying when
  58 browsing using the keyboard, as you do with VimFx, because it often feels like
  59 VimFx isn’t responding, until you realize that you are typing in a text box—not
  60 running VimFx commands!
  61
  62 For this reason VimFx prevents autofocus. If you dislike that, or think the
  63 prevention is too aggressive, you may disable it, returning to the standard
  64 behavior.
  65
  66 What is meant by “aggressive”? Well, in fact it is very hard to tell if a focus
  67 was an “autofocus” or a “regular focus” caused by you. VimFx prevents all
  68 focusing that doesn’t happen reasonably close (200ms by default) to an
  69 interaction by you (such as clicking something or using one of the `f`
  70 commands). (You may change what “reasonably close” means through the advanced
  71 setting [`autofocus_limit`]).
  72
  73 [`autofocus_limit`]: #autofocus_limit
  74
  75 ### Ignore keyboard layout
  76
  77 If you use more than one keyboard layout, you probably want to enable this
  78 option.
  79
  80 People who use a keyboard layout without the letters A-Z usually also use the
  81 standard en-US QWERTY layout as well.
  82
  83 This option makes VimFx ignore your current layout and pretend that the standard
  84 en-US QWERTY layout is always used. This way the default shortcuts work even if
  85 your layout doesn’t contain the letters A-Z and all shorcuts can be typed by the
  86 same physical keys on your keyboard regardless of your current keyboard layout.
  87
  88 (If you’d like VimFx to pretend that some other keyboard layout than the
  89 standard en-US QWERTY is always used, you may do so with the special option
  90 [`translations`].)
  91
  92 [`translations`]: #translations
  93
  94 ### Timeout
  95
  96 The maximum amount of time (in milliseconds) that may pass between two
  97 keypresses of a shortcut.
  98
  99 It’s easy to press, say, `a` by mistake while browsing. Without a timeout, you
 100 might be surprised that all search results are highlighted when you a bit later
 101 try to search using the `/` command. (That’s what `a/` does.) _With_ a timeout,
 102 the `a` would be cancelled when the timeout has passed.
 103
 104
 105 ## Advanced options
 106
 107 These options are _not_ available in VimFx’s settings page in the Add-ons
 108 Manager. They can only be changed in [about:config] or using the [public API].
 109 They all start with `extensions.VimFx.`.
 110
 111 (There are actually a few more advanced options than those listed here. You can
 112 see them all in [defaults.coffee].)
 113
 114 [about:config]: http://kb.mozillazine.org/About:config
 115 [public API]: api.md
 116 [defaults.coffee]: ../extension/lib/defaults.coffee
 117
 118 ### `prevent_target_blank`
 119
 120 You might have noticed that some links open in new tabs when you click them.
 121 That is not the case if you “click” them using VimFx’s `f` command, though. If
 122 you dislike that, disable this option.
 123
 124 ### `autofocus_limit`
 125
 126 If `prevent_autofocus` is enabled, all focus events except those that occur
 127 within this number of milliseconds after a user interaction are suppressed.
 128
 129 ### `hints_timeout`
 130
 131 The number of milliseconds a matched hint marker should stay on screen before
 132 disappearing (or resetting).
 133
 134 ### Scrolling prefs
 135
 136 If you want to customize Firefox’s smooth scrolling, adjusting
 137 `general.smoothScroll.{lines,pages,other}.duration{Min,Max}MS` is the way to
 138 go. VimFx has similar prefs for the scrolling commands, but they work like
 139 `layout.css.scroll-behavior.spring-constant`.
 140
 141 Basically, the higher the value, the faster the scrolling.
 142
 143 These are VimFx’s variants, and the commands they affect:
 144
 145 - `smoothScroll.lines.spring-constant`: `h`, `l`, `j`, `k`
 146 - `smoothScroll.pages.spring-constant`: `d`, `u`, `<space>`, `<s-space>`
 147 - `smoothScroll.other.spring-constant`: `gg`, `G`, `0`, `^`, `$`
 148
 149 Note that the value of these prefs are _strings,_ not numbers!
 150
 151 VimFx’s scrolling commands also respect a few built-in Firefox prefs.
 152
 153 `general.smoothScroll` lets you turn off smooth scrolling entirely, including
 154 all of VimFx’s scrolling commands.
 155
 156 `general.smoothScroll.lines`, `general.smoothScroll.pages`, and
 157 `general.smoothScroll.other` lets you selectively disable smooth scrolling.
 158 VimFx’s scrolling commands follow the same “lines,” “pages” and “other”
 159 categorization as in the above list.
 160
 161 By default you can scroll using the arrow keys in Firefox. You can control how
 162 much they scroll by adjusting the following prefs:
 163
 164 - `toolkit.scrollbox.horizontalScrollDistance`: `<left>`, `<right>`, `h`, `l`
 165 - `toolkit.scrollbox.verticalScrollDistance`:   `<down>`, `<up>`,    `j`, `k`
 166
 167 (VimFx used to have a `scroll_step` pref, but is has been replaced by the
 168 above.)
 169
 170 ### `pattern_selector`
 171
 172 A CSS selector that targets candidates for a previous/next page link.
 173
 174 ### `pattern_attrs`
 175
 176 A space-separated list of attributes that the previous/next page patterns should
 177 be matched against.
 178
 179 ### `activatable_element_keys`
 180
 181 Keys that should not trigger VimFx commands but be sent through to the page if
 182 an “activatable” element (link or button) is focused.
 183
 184 ### `adjustable_element_keys`
 185
 186 Keys that should not trigger VimFx commands but be sent through to the page if
 187 an “adjustable” element (form control or video player) is focused.
 188
 189
 190 ## Special options
 191
 192 These options are available in neither VimFx’s settings page in the Add-ons
 193 Manager nor in [about:config]. The only way to change them is by using the
 194 [public API].
 195
 196 ### `translations`
 197
 198 See the description of the `translations` option in [vim-like-key-notation].
 199
 200 [vim-like-key-notation]: https://github.com/lydell/vim-like-key-notation#api