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