]> git.gir.st - VimFx.git/blob - documentation/commands.md
Prevent autofocus after re-selecting a tab
[VimFx.git] / documentation / commands.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 # Commands
8
9 Most of VimFx’s commands are straight-forward enough to not need any
10 documentation. For some commands, though, there is a bit more to know.
11
12 ## Counts
13
14 Some commands support _counts._ That means that you can type a number before a
15 command and it will change its behavior based on that number—the count. For
16 example, typing `12x` would close 12 tabs.
17
18 (As opposed to vim, you may only supply a count _before_ a command, not in the
19 middle of one. This is because VimFx’s commands are simple sequences, while
20 vim’s are operators and motions.)
21
22 ### `gu`
23
24 Goes _count_ levels up in the URL hierarchy.
25
26 ### `H` and `L`
27
28 Goes _count_ pages backward/forward in history.
29
30 ### Scrolling commands
31
32 Specifying a count make them scroll _count_ times as far.
33
34 ### `J`, `K`
35
36 Selects the tab _count_ tabs backward/forward.
37
38 If the count is greater than one they don’t wrap around when reaching the ends
39 of the tab bar.
40
41 ### `gJ`, `gK`
42
43 Moves the current tab _count_ tabs forward/backward.
44
45 If the count is greater than one they don’t wrap around when reaching the ends
46 of the tab bar.
47
48 ### `x`
49
50 Closes the current tab and _count_ minus one of the following tabs.
51
52 ### `X`
53
54 Restores the _count_ last closed tabs.
55
56 ### `I`
57
58 Passes on the next _count_ keypresses to the page, without activating VimFx
59 commands.
60
61 ### The `f` commands
62
63 Explained in the their own section below.
64
65 ### `gi`
66
67 Explained in its own section below.
68
69
70 ## `<force>` commands
71
72 By putting the special “key” `<force>` at the beginning of a shortcut the
73 shortcut will work exactly as it would without `<force>`, except that it will
74 also be available in text inputs.
75
76 VimFx enters a kind of “automatic insert mode” when you focus a text input,
77 allowing you to type text into it without triggering VimFx commands. The `esc`
78 command, however, is still available, allowing you to blur the text input by
79 pressing `<escape>`. The reason it is available is because the default shortcut
80 is `<force><escape>`.
81
82 Using `<force>` allows you to run other commands in text inputs as well. For
83 example, you could use `<force><a-j>` and `<force><a-k>` to be able to select
84 tab backward and forward regardless if you happen to be in a text input or not.
85
86
87 ## Scrolling commands
88
89 Firefox lets you scroll with the arrow keys, page down, page up, home, end and
90 space by default. VimFx provides similar scrolling commands (and actually
91 overrides space), but they work a little bit differently.
92
93 They scroll _the currently focused element._ If the currently focused element
94 isn’t scrollable, or there is no (apparent) currently focused element, the
95 entire page is scrolled.
96
97 You can focus scrollable elements using the `zf` command.
98
99
100 ## `gi`
101
102 `gi` focuses the text input you last used, or the first one on the page. Note
103 that a [prevented autofocus] still counts as having focused and used a text
104 input. This allows you to have your cake and eat it too: You can enable
105 autofocus prevention, and type `gi` when you wish you hadn’t.
106
107 `gi` takes a count. It then selects the `counth` text input on the page. Note
108 that `gi` and `1gi` are different: The latter _always_ focuses the first input
109 of the page, regradless of which input you used last.
110
111 [prevented autofocus]: options.md#prevent-autofocus
112
113
114 ## Focus next/previous element
115
116 The default shorcuts are `<tab>` and `<s-tab>`, respectively. They work just
117 like `<tab>` works normally, except that if you focused a text input using the
118 `gi` command they will only switch between text inputs on thee page, as opposed
119 to between all focusable elements (such as links, buttons and checkboxes) as
120 they do otherwise.
121
122
123 ## The `f` commands
124
125 When invoking one of the `f` commands you enter Hints mode. In Hints mode,
126 markers with hints are shown for some elements. By typing the letters of a hint
127 something is done to that element, depending on the command.
128
129 Which elements get hints depends on the command as well:
130
131 - `f` and `af`: Anything clickable—links, buttons, form controls.
132 - `F` and `gf`: Anything that can be opened in a new tabs—links.
133 - `yf`: Anything that has something useful to copy—links (their URL) and text
134 inputs (their text).
135 - `zf`: Anything focusable—links, buttons, form controls, scrollable elements,
136 frames.
137
138 It might seem simpler to match the same set of elements for _all_ of the
139 commands. The reason that is not the case is because the fewer elements the
140 shorter the hints. (Also, what should happen if you tried to `F` a button?)
141
142 Another way to make hints shorter is to assign the same hint to all links with
143 the same URL. So don’t get surprised if you see the same hint repeated several
144 times.
145
146 VimFx also tries to give you shorter hints for elements that you are more likely
147 to click. This is done by the surprisingly simple rule: The larger the element,
148 the shorter the hint.
149
150 There are standardized elements which are always clickable—_semantically_
151 clickable elements. Unfortunately, many sites use unclickable elements and then
152 make them clickable using JavaScript—<em>un</em>semantically clickable elements.
153 Such elements are difficult to find. VimFx has a few techniques for doing so,
154 which works many times but not always, but unfortunately they sometimes produce
155 false positives. Many times those false positives are pretty large elements,
156 which according to the last paragraph would give them really short hints, making
157 other more important elements suffer by getting longer ones. Therefore VimFx
158 favors semantic elements over unsemantic ones and takes that into account when
159 deciding the hint length for elements.
160
161 Some hint characters are easier to type than others. The ones on the home row
162 are of course the best. When customizing the [hint chars] option you should put
163 the best keys to the left and the worst ones to the right. VimFx favors keys to
164 the left, so that should give you the optimal hints.
165
166 Hints are added on top of the corresponding element. If they obscure the display
167 too much you can hold shift to make them transparent. (See [Styling] if you’d
168 like to change that.) The hints can also sometimes cover each other. Press
169 `<space>` and `<s-space>` to switch which one should be on top.
170
171 When giving a count to an `f` command, all markers will be re-shown after you’ve
172 typed the hint characters of one of them, _count_ minus one times. All but the
173 last time, the marker’s link will be opened in a new background tab. The last
174 time the command opens links as normal (in the current tab (`f`) or in a new
175 background (`F`) or foreground tab (`gf`)).
176
177 Note that the `f` command adds markers not only to links, but to buttons and
178 form controls as well. What happens the _count_ minus one times then? Buttons,
179 checkboxes and the like are simply clicked, allowing you to quickly check many
180 checkboxes in one go, for example. Text inputs cancel the command.
181
182 `af` works as if you’d supplied an infinite count to `f`. (In fact, the `af`
183 command is implemented by running the same function as for the `f` command,
184 passing `Infinity` as the `count` argument!) Therefore the `af` command does not
185 accept a count itself.
186
187 The `zf` and `yf` commands do not accept counts.
188
189 Press `<enter>` to increase the count by one. This is useful when you’ve already
190 entered Hints mode but realize that you want to interact with yet a marker. This
191 can be faster than going into Hints mode once more.
192
193 If you’ve pressed `f` but realize that you’d rather open a link in a new tab you
194 can hold ctrl while typing the last hint character. This is similar to how you
195 can press `<c-enter>` on a focused link to open it in a new tab (while just
196 `<enter>` would have opened it in the same tab). Hold alt to open in a new
197 foreground tab. In other words, holding ctrl works as if you’d pressed `F` from
198 the beginning, and holding alt works as if you’d pressed `gf`.
199
200 For the `F` and `gf` commands, holding ctrl makes them open links in the same
201 tab instead, as if you’d used the `f` command. Holding alt toggles whether to
202 open tabs in the background or foreground—it makes `F` work like `gf`, and `gf`
203 like `F`.
204
205 [hint chars]: options.md#hint-chars
206 [Styling]: styling.md
207
208
209 ## Ignore mode `<s-f1>`
210
211 Ignore mode is all about ignoring VimFx commands and sending the keys to the
212 page instead. Sometimes, though, you might want to run some VimFx command even
213 when in Insert mode.
214
215 One way of doing that is to press `<s-escape>` to exit Ignore mode, run your
216 command and then enter Ignore mode again using `i`. However, it might be
217 inconvenient having to remember to re-enter Ignore mode, and sometimes that’s
218 not even possible, such as if you ran the `K` command to get to the next tab.
219
220 Another way is to press `<s-f1>` followed by the Normal mode command you wanted
221 to run. (`<s-f1>` is essentially the inverse of the `I` command, which passes
222 the next keypress on to the page. Internally they’re called “quote” and
223 “unquote.”) This is handy if you’d like to switch away from a [blacklisted]
224 page: Just press for example `<s-f1>K`.
225
226 `<s-f1>` was chosen as the default shortcut because on a typical keyboard `<f1>`
227 is located just beside `<escape>`, which makes it very similar to `<s-escape>`,
228 which is used to exit Ignore mode. Both of those are uncommonly used by web
229 pages, so they shouldn’t be in the way. If you ever actually do need to send any
230 of those to the page, you can prefix them with `<s-f1>`, because if the key you
231 press after `<s-f1>` is not part of any Normal mode command, the key is sent to
232 the page. (Another way is for example `<s-f1>I<s-escape>`.)
233
234 [blacklisted]: options.md#blacklist
235
236
237 ## Ex commands
238
239 vim has something called “ex” commands. Want something similar in VimFx? True to
240 its spirit, VimFx embraces a standard Firefox feature for this purpose: The
241 [Developer Toolbar]. That link also includes instructions on how to extend it
242 with your own commands.
243
244 In the future VimFx might even ship with a few extra “ex” commands by default.
245 We’re open for suggestions!
246
247 [Developer Toolbar]: https://developer.mozilla.org/en-US/docs/Tools/GCLI
Imprint / Impressum