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