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 (Set the option to `*` to make VimFx start out in Ignore mode _everywhere._)
  72
  73 You might also want to read about the [Ignore mode `<s-f1>` command][s-f1].
  74
  75 [s-f1]: commands.md#ignore-mode-s-f1
  76
  77 ### Prevent autofocus
  78
  79 Many sites autofocus their search box, for example. This might be annoying when
  80 browsing using the keyboard, as you do with VimFx, because it often feels like
  81 VimFx isn’t responding, until you realize that you are typing in a text box—not
  82 running VimFx commands!
  83
  84 For this reason VimFx can prevent autofocus. It’s not enabled by default,
  85 though, since one of VimFx’s key features is to be nice to your browser and your
  86 habits.
  87
  88 If enabled, all focusing that occurs on page load, or after you’ve just switched
  89 back to a tab from another, until you interact with the page is prevented.
  90
  91 #### Technical notes and trivia
  92
  93 Autofocus on page load and when coming back to a tab are the two most common
  94 cases. Some sites, though, automatically focus a text input in other cases as
  95 well. Trying to catch those cases as well, VimFx used to prevent all focusing
  96 that didn’t occur within a fixed number of milliseconds after your last
  97 interaction (click or keypress). However, this proved to be too aggressive,
  98 preventing too much focusing. In other words, the time-based check was not
  99 sufficient to distinguish between intended focusing and automatic unwanted
 100 focusing. It made things worse more than it helped. Since these cases are so
 101 difficult (if not impossible) to detect, it is better to leave them. Thankfully
 102 they are not very common.
 103
 104 On page load or when coming back to a tab, before you have interacted with the
 105 page in any way, we can be _sure_ that any focusing is automatic (not caused by
 106 you), which makes it safe to prevent all focusing in those time spans.
 107
 108 ### Ignore keyboard layout
 109
 110 If you use more than one keyboard layout, you probably want to enable this
 111 option.
 112
 113 People who use a keyboard layout _without_ the letters A–Z usually also use the
 114 standard en-US QWERTY layout as well.
 115
 116 This option makes VimFx ignore your current layout and pretend that the standard
 117 en-US QWERTY layout is _always_ used. This way the default shortcuts work even
 118 if your layout doesn’t contain the letters A–Z and all shortcuts can be typed by
 119 the same physical keys on your keyboard regardless of your current keyboard
 120 layout.
 121
 122 (If you’d like VimFx to pretend that some other keyboard layout than the
 123 standard en-US QWERTY is always used, you may do so with the special option
 124 [`translations`].)
 125
 126 [`translations`]: #translations
 127
 128 ### Timeout
 129
 130 The maximum amount of time (in milliseconds) that may pass between two
 131 keypresses of a shortcut.
 132
 133 It’s easy to press, say, `a` by mistake while browsing. Without a timeout, you
 134 might be surprised that all search results are highlighted when you a bit later
 135 try to search using the `/` command. (That’s what `a/` does.) _With_ a timeout,
 136 the `a` would be cancelled when the timeout has passed.
 137
 138
 139 ## Advanced options
 140
 141 These options are _not_ available in VimFx’s settings page in the Add-ons
 142 Manager. They can only be changed in [about:config] or using the [public API].
 143 They all start with `extensions.VimFx.`.
 144
 145 (There are actually a few more advanced options than those listed here. You can
 146 see them all in [defaults.coffee].)
 147
 148 [about:config]: http://kb.mozillazine.org/About:config
 149 [public API]: api.md
 150 [defaults.coffee]: ../extension/lib/defaults.coffee
 151
 152 ### `notifications_enabled`
 153
 154 Controls whether [notifications] should be shown or not.
 155
 156 You can also choose to show notifications any way you want by listening for the
 157 [the `notification` and `hideNotification` events][notification-events].
 158
 159 [notifications]: notifications.md
 160 [notification-events]: api.md#the-notification-and-hidenotification-events
 161
 162 ### `notify_entered_keys`
 163
 164 If enabled, a [notification] is shown with the keys you have entered so far of
 165 a command. This is only noticeable if you type a multi-key shortcut or use a
 166 count.
 167
 168 [notification]: notifications.md
 169
 170 ### `prevent_target_blank`
 171
 172 You might have noticed that some links open in new tabs when you click them.
 173 That is not the case if you “click” them using VimFx’s `f` command, though. If
 174 you dislike that, disable this option.
 175
 176 ### `counts_enabled`
 177
 178 Controls whether [counts] are enabled or not.
 179
 180 [counts]: commands.md#counts
 181
 182 ### `ignore_ctrl_alt`
 183
 184 This option is enabled by default on Windows, and disabled otherwise.
 185
 186 If enabled, ignores ctrl+alt for printable keys. `<a-c-$>` becomes `$` and
 187 `<a-c-A>` becomes `A`, while `<a-c-enter>` stays the same.
 188
 189 This option is suitable on Windows, which treats [AltGr as
 190 ctrl+alt][wikipedia-altgr]. For example, if a user of the sv-SE layout on
 191 Windows holds AltGr and presses the key labeled `4`, in order to produce a `$`,
 192 the result would be `<a-c-$>` without this option, making it impossible to
 193 trigger a keyboard shortcut containing `$`. _With_ this option the result is
 194 `$`, as expected (and as on GNU/Linux). On the other hand it won’t be possible
 195 to trigger keyboard shortcuts such as `<a-c-a>`, but ctrl+alt keyboard shortcuts
 196 are [discouraged on Windows][wikipedia-altgr] anyway because of this reason.
 197
 198 [wikipedia-altgr]: https://en.wikipedia.org/wiki/AltGr_key#Control_.2B_Alt_as_a_substitute
 199
 200 ### `prevent_autofocus_modes`
 201
 202 Space separated list of modes where `prevent_autofocus` should be used.
 203
 204 ### `hints_timeout`
 205
 206 The number of milliseconds a matched hint marker should stay on screen before
 207 disappearing (or resetting).
 208
 209 ### Scrolling prefs
 210
 211 Apart from its own prefs, VimFx also respects a few built-in Firefox prefs.
 212
 213 #### Smooth scrolling
 214
 215 If you want to customize Firefox’s smooth scrolling, adjusting
 216 `general.smoothScroll.{lines,pages,other}.duration{Min,Max}MS` is the way to
 217 go. VimFx has similar prefs for the scrolling commands, but they work like
 218 `layout.css.scroll-behavior.spring-constant`.
 219
 220 Basically, the higher the value, the faster the scrolling.
 221
 222 These are VimFx’s variants, and the commands they affect:
 223
 224 - `smoothScroll.lines.spring-constant`: `h`, `l`, `j`, `k`
 225 - `smoothScroll.pages.spring-constant`: `d`, `u`, `<space>`, `<s-space>`
 226 - `smoothScroll.other.spring-constant`: `gg`, `G`, `0`, `^`, `$`
 227
 228 Note that the value of these prefs are _strings,_ not numbers!
 229
 230 The Firefox pref `general.smoothScroll` lets you turn off smooth scrolling
 231 entirely, including all of VimFx’s scrolling commands.
 232
 233 `general.smoothScroll.lines`, `general.smoothScroll.pages`, and
 234 `general.smoothScroll.other` lets you selectively disable smooth scrolling.
 235 VimFx’s scrolling commands follow the same “lines,” “pages” and “other”
 236 categorization as in the above list.
 237
 238 #### Scroll step
 239
 240 By default you can scroll using the arrow keys in Firefox. You can control how
 241 much they scroll by adjusting the following prefs:
 242
 243 - `toolkit.scrollbox.horizontalScrollDistance`: `<left>`, `<right>`, `h`, `l`
 244 - `toolkit.scrollbox.verticalScrollDistance`:   `<down>`, `<up>`,    `j`, `k`
 245
 246 (VimFx used to have a `scroll_step` pref, but is has been replaced by the
 247 above.)
 248
 249 #### `scroll.full_page_adjustment` and `scroll.half_page_adjustment`
 250
 251 An important use case for scrolling a full page down is to read an entire page
 252 (a window-full) of text, press `<space>` and then continue reading the next
 253 page. However, if you can only see, say, _half_ of the height the last line,
 254 pressing `<space>` would give you the other half, but reading only the top or
 255 bottom parts of letters is difficult. Even if the lines happen to line up with
 256 the window edge to not be sliced horizontally, it might feel disorienting
 257 pressing `<space>`.
 258
 259 For this reason, both VimFx and Firefox by default scroll _about a line less
 260 than a whole page_ when pressing `<space>`. This solves the sliced-last-line
 261 problem, and provides some context on where you are in the text you’re reading.
 262
 263 These two prefs control how many pixels “about a line” actually means for the
 264 different page scrolling commands.
 265
 266 - `scroll.full_page_adjustment`: `<space>, `<s-space>`
 267 - `scroll.half_page_adjustment`: `d`, `u`
 268
 269 #### `scroll.last_position_mark`
 270
 271 The special mark for the [`` ` ``][scroll-to-mark] command that takes you to the
 272 last position.
 273
 274 [scroll-to-mark]: commands.md#marks-m-and-
 275
 276 ### `pattern_selector`
 277
 278 A CSS selector that targets candidates for a previous/next page link.
 279
 280 ### `pattern_attrs`
 281
 282 A space-separated list of attributes that the previous/next page patterns should
 283 be matched against.
 284
 285 ### `hints_toggle_in_tab`
 286
 287 If the keypress that matched a hint starts with this string, toggle whether to
 288 open the matched link in the current tab or a new tab. See [The `f` commands]
 289 for more information.
 290
 291 ### `hints_toggle_in_background`
 292
 293 If the keypress that matched a hint starts with this string, open the matched
 294 link in a new tab and toggle whether to open that tab in the background or
 295 foreground. See [The `f` commands] for more information.
 296
 297 ### `activatable_element_keys`
 298
 299 Keys that should not trigger VimFx commands but be sent through to the page if
 300 an “activatable” element (link or button) is focused.
 301
 302 ### `adjustable_element_keys`
 303
 304 Keys that should not trigger VimFx commands but be sent through to the page if
 305 an “adjustable” element (form control or video player) is focused.
 306
 307 ### `focus_previous_key` and `focus_next_key`
 308
 309 The default values are `<s-tab` and `<tab>`, respectively. Those keys are
 310 specially handled after focusing a text input using [`gi`]. To disable this
 311 special handling, set the prefs to the empty string.
 312
 313 [`gi`]: commands.md#gi-1
 314
 315
 316 ## Special options
 317
 318 These options are available in neither VimFx’s settings page in the Add-ons
 319 Manager nor in [about:config]. The only way to change them is by using the
 320 [public API].
 321
 322 ### `translations`
 323
 324 See the description of the `translations` option in [vim-like-key-notation].
 325
 326 [vim-like-key-notation]: https://github.com/lydell/vim-like-key-notation#api
 327
 328 ### `categories`
 329
 330 See the documentation for [`vimfx.get('categories')`][categories].
 331
 332 [categories]: api.md#vimfxgetcategories