From 6b5f2677c5bcc01f0a39d18facedb87779cf9209 Mon Sep 17 00:00:00 2001 From: Simon Lydell Date: Sat, 20 Aug 2016 10:39:48 +0200 Subject: [PATCH] Change default shortcuts for some hint commands Many of the old ones were difficult to remember, and there was no space for adding new ones. Refs. #788. --- documentation/api.md | 38 +++++----- documentation/commands.md | 76 +++++++++++++------ .../handy-standard-firefox-features.md | 2 +- documentation/modes.md | 6 +- documentation/options.md | 10 +-- documentation/questions-and-answers.md | 2 +- documentation/shortcuts.md | 2 +- extension/lib/defaults.coffee | 10 +-- extension/lib/markable-elements.coffee | 2 +- 9 files changed, 87 insertions(+), 61 deletions(-) diff --git a/documentation/api.md b/documentation/api.md index 7408be6..a7e4837 100644 --- a/documentation/api.md +++ b/documentation/api.md @@ -51,7 +51,7 @@ Sets the value of the VimFx pref `pref` to `value`. // Set the value of the Hint chars option: vimfx.set('hint_chars', 'abcdefghijklmnopqrstuvwxyz') // Add yet a keyboard shortcut for the `f` command: -vimfx.set('mode.normal.follow', vimfx.getDefault('mode.normal.follow') + ' e') +vimfx.set('mode.normal.follow', vimfx.getDefault('mode.normal.follow') + ' ee') ``` When extending a pref (as in the second example above), be sure to use @@ -458,9 +458,9 @@ categories.custom = { [categories.tabs.order, commands.focus_location_bar.order] ``` -### Custom hints commands +### Custom hint commands -Apart from the standard `f` commands, you can create your own. +Apart from the standard hint commands, you can create your own. You may run any VimFx command by using the following pattern: @@ -475,13 +475,13 @@ vimfx.addCommand({ }) ``` -All `f` commands (except `zF`) also support `args.callbackOverride`: +All hint commands (except `eb`) also support `args.callbackOverride`: ```js // config.js vimfx.addCommand({ - name: 'custom_hints_command_example', - description: 'Custom hints command example', + name: 'custom_hint_command_example', + description: 'Custom hint command example', }, (args) => { vimfx.modes.normal.commands.follow.run(Object.assign({}, args, { callbackOverride({type, href, id, timesLeft}) { @@ -492,9 +492,9 @@ vimfx.addCommand({ }) ``` -This lets you piggy-back on one of the existing `f` commands by getting the same -hints on screen as that command, but then doing something different with the -matched hint marker. +This lets you piggy-back on one of the existing hint commands by getting the +same hints on screen as that command, but then doing something different with +the matched hint marker. `callbackOverride` is called with an object with the following properties: @@ -507,9 +507,9 @@ matched hint marker. - id: An id that you can pass to [`vimfx.getMarkerElement(...)`] to get the element of the matched hint marker. -- timesLeft: `Number`. Calling an `f` command means that you want to run it - _count_ times in a row. This number tells how many times there are left to - run. If you don’t provide a count, the number is `1`. +- timesLeft: `Number`. Calling a hint command with a count means that you want + to run it _count_ times in a row. This number tells how many times there are + left to run. If you don’t provide a count, the number is `1`. `callbackOverride` should return `true` if you want the hint markers to re-appear on screen after you’ve matched one of them (as in the `af` command), @@ -803,7 +803,7 @@ examples. ### `vimfx.setHintMatcher(hintMatcher)` `hintMatcher` is a function that lets you customize which elements do and don’t -get hints. It might help to read about [the `f` commands] first. +get hints. It might help to read about [the hint commands] first. If you call `vimfx.setHintMatcher(hintMatcher)` more than once, only the `hintMatcher` provided the last time will be used. @@ -820,10 +820,10 @@ The arguments passed to the `hintMatcher` function are: - id: `String`. A string identifying which command is used: - `'normal'`: `f` or `af`. - - `'tab'`: `F`, `gf` or `gF`. + - `'tab'`: `F`, `et` or `ew`. - `'copy'`: `yf`. - - `'focus'`: `zf`. - - `'select'`: `v`, `zv` or `yv`. + - `'focus'`: `ef`. + - `'select'`: `v`, `av` or `yv`. - element: `Element`. One out of all elements currently inside the viewport. @@ -870,7 +870,7 @@ The function must return `null` or a string like the `type` parameter. ### `vimfx.getMarkerElement(id)` -Takes an id that has been given to you when creating [custom hints commands] and +Takes an id that has been given to you when creating [custom hint commands] and returns the DOM element associated with that id. If no element can be found, `null` is returned. @@ -889,7 +889,7 @@ backwards compatibility will be a priority and won’t be broken until VimFx [`vimfx.send(...)`]: #vimfxsendvim-message-data--null-callback--null [`vimfx.listen(...)`]: #vimfxlistenmessage-listener [categories]: #vimfxgetcategories -[custom hints commands]: #custom-hints-commands +[custom hint commands]: #custom-hints-commands [`vimfx.modes`]: #vimfxmodes [onInput]: #oninput [mode object]: #mode-object @@ -915,7 +915,7 @@ backwards compatibility will be a priority and won’t be broken until VimFx [`notifications_enabled`]: options.md#notifications_enabled [button]: button.md -[the `f` commands]: commands.md#the-f-commands--hints-mode +[the hint commands]: commands.md#the-hint-commands--hints-mode [special keys]: shortcuts.md#special-keys [styling]: styling.md diff --git a/documentation/commands.md b/documentation/commands.md index c17b72a..7d61370 100644 --- a/documentation/commands.md +++ b/documentation/commands.md @@ -108,7 +108,7 @@ Restores the _count_ last closed tabs. Passes on the next _count_ keypresses to the page, without activating VimFx commands. -### The `f` commands +### The hint commands Explained in the their own section below. @@ -127,19 +127,19 @@ They scroll _the currently focused element._ If the currently focused element isn’t scrollable, the largest scrollable element on the page (if any, and including the entire page itself) is scrolled. -You can focus scrollable elements using the `zf` command (or the `f` command). +You can focus scrollable elements using the `ef` command (or the `f` command). Scrollable browser elements, such as in the dev tools, can be focused using the -`zF` command. The right border of hint markers for scrollable elements is styled +`eb` command. The right border of hint markers for scrollable elements is styled to remind of a scroll bar, making them easier to recognize among hints for links. -Note that `zf` and `f` do _not_ add a hint marker for the _largest_ scrollable +Note that `ef` and `f` do _not_ add a hint marker for the _largest_ scrollable element (such as the entire page). There’s no need to focus that element, since it is scrolled by default if no other scrollable element is focused, as explained above. (This prevents the largest scrollable element from likely -eating your best hint char on most pages; see [The `f` commands]). +eating your best hint char on most pages; see [The hint commands]). -[The `f` commands]: #the-f-commands--hints-mode +[The hint commands]: #the-hint-commands--hints-mode ### Marks: `m` and `` ` `` @@ -190,11 +190,12 @@ elements as they usually do. (See also the [`focus_previous_key` and [`focus_previous_key` and `focus_next_key`]: options.md#focus_previous_key-and-focus_next_key -## The `f` commands / Hints mode +## The hint commands / Hints mode -When invoking one of the `f` commands you enter Hints mode. In Hints mode, -markers with hints are shown for some elements. By typing the letters of a hint -something is done to that element, depending on the command. +When invoking one of the hint commands (such as `f`, `et` or one of the [`v` +commands]) you enter Hints mode. In Hints mode, markers with hints are shown for +some elements. By typing the letters of a hint something is done to that +element, depending on the command. Another way to find links on the page is to use `g/`. It’s like the regular find command (`/`), except that it searches links only. @@ -202,12 +203,12 @@ command (`/`), except that it searches links only. Which elements get hints depends on the command as well: - `f` and `af`: Anything clickable—links, buttons, form controls. -- `F`, `gf` and `gF`: Anything that can be opened in a new tab or window—links. +- `F`, `et` and `ew`: Anything that can be opened in a new tab or window—links. - `yf`: Anything that has something useful to copy—links (their URL) and text inputs (their text). -- `zf`: Anything focusable—links, buttons, form controls, scrollable elements, +- `ef`: Anything focusable—links, buttons, form controls, scrollable elements, frames. -- `zF`: Browser elements, such as toolbar buttons. +- `eb`: Browser elements, such as toolbar buttons. It might seem simpler to match the same set of elements for _all_ of the commands. The reason that is not the case is because the fewer elements the @@ -230,13 +231,13 @@ them. (See [Styling] and the [hints\_peek\_through] pref if you’d like to chan that.) The hints can also sometimes cover each other. Press `` and `` to switch which one should be on top. -When giving a count to an `f` command, all markers will be re-shown after you’ve +When giving a count to a hint command, all markers will be re-shown after you’ve typed the hint characters of one of them, _count_ minus one times. All but the last time, the marker’s link will be opened in a new background tab. The last time the command opens links as normal (in the current tab (`f`) or in a new -background (`F`) or foreground tab (`gf`)). +background (`F`) or foreground tab (`et`)). -Note that the `f` command adds markers not only to links, but to buttons and +Note that the hint command adds markers not only to links, but to buttons and form controls as well. What happens the _count_ minus one times then? Buttons, checkboxes and the like are simply clicked, allowing you to quickly check many checkboxes in one go, for example. Text inputs cancel the command. @@ -246,7 +247,7 @@ command is implemented by running the same function as for the `f` command, passing `Infinity` as the `count` argument!) Therefore the `af` command does not accept a count itself. -The `gF`, `zf`, `yf` and `zF` commands do not accept counts. +The `et`, `ef`, `yf` and `eb` commands do not accept counts. Press `` to increase the count by one. This is useful when you’ve already entered Hints mode but realize that you want to interact with yet a marker. This @@ -257,11 +258,11 @@ can hold ctrl while typing the last hint character. This is similar to how you can press `` on a focused link to open it in a new tab (while just `` would have opened it in the same tab). Hold alt to open in a new foreground tab. In other words, holding ctrl works as if you’d pressed `F` from -the beginning, and holding alt works as if you’d pressed `gf`. +the beginning, and holding alt works as if you’d pressed `et`. -For the `F` and `gf` commands, holding ctrl makes them open links in the same +For the `F` and `et` commands, holding ctrl makes them open links in the same tab instead, as if you’d used the `f` command. Holding alt toggles whether to -open tabs in the background or foreground—it makes `F` work like `gf`, and `gf` +open tabs in the background or foreground—it makes `F` work like `et`, and `et` like `F`. (Also see the advanced prefs [hints\_toggle\_in\_tab] and @@ -275,6 +276,30 @@ hint to activate sometimes). See this as an escape hatch if you _really_ want to avoid using the mouse at all costs. (Press `` again to toggle back to the previous hints.) +### Mnemonics and choice of default hint command shortcuts + +The main command is `f`. It comes from the Vimium and Vimperator extensions. The +mnemonic is “follow link.” It is a good key, because on many +keyboard layouts it is located right under where your left index finger rests. + +The most common variations of `f` are centered around that letter: `F`, `yf` and +`af`. (Some users might want to swap `F` and `et`, though.) In Vim, it is not +uncommon that an uppercase letter does the same thing as its lowercase +counterpart, but with some variation (in this case, `F` opens links in new tabs +instead of in the current tab), and `y` usually means “yank” or “copy.” VimFx +also has this pattern that `a` means “all.” + +You can think of the above commands as the “f commands.” That sounds like +“eff-commands” when you say it out loud, which is a way of remembering that the +rest of the `f` variations are behind the `e` key. That’s also a pretty good +key/letter, because it is close to `f` both alphabetically, and physically in +many keyboard layouts (and is pretty easy to type). + +The second key after `e` was chosen based on mnemonics: There’s `et` as in +tab, `ew` as in window, `ef` as in +focus and `eb` as in bbrowser. + +[`v` commands]: #the-v-commands-caret-mode [hint-matcher]: api.md#vimfxhintmatcher [hint chars]: options.md#hint-chars [Styling]: styling.md @@ -293,11 +318,12 @@ Pressing `v` will enter Hints mode with hint markers for all elements with text inside. When activating a marker, its element will get a blinking caret at the beginning of it, and Caret mode will be entered. -The `zv` command does the same thing as `v`, but instead of placing the caret at -the beginning of the element, it selects the entire element. +The `av` command does the same thing as `v`, but instead of placing the caret at +the beginning of the element, it selects the entire element (it selects +all of the element). -The `yv` command brings up the same hint markers as `zv` does, and then takes -the text that `zv` would have selected and copies it to the clipboard. It does +The `yv` command brings up the same hint markers as `av` does, and then takes +the text that `av` would have selected and copies it to the clipboard. It does not enter Caret mode at all. The letter `v` was chosen for these shortcuts because that’s what Vim uses to @@ -349,7 +375,7 @@ snippet. If so, using the `yv` command (which copies an entire element without entering Caret mode) is the fastest. If you want to copy _almost_ all text of an element, or a bit more than it, use -the `zv` command (which selects an entire element). Then adjust the selection +the `av` command (which selects an entire element). Then adjust the selection using the various Caret mode commands. Remember that `o` lets you adjust both ends of the selection. diff --git a/documentation/handy-standard-firefox-features.md b/documentation/handy-standard-firefox-features.md index f0f564d..b2bb59f 100644 --- a/documentation/handy-standard-firefox-features.md +++ b/documentation/handy-standard-firefox-features.md @@ -46,7 +46,7 @@ This is true for most programs, not just Firefox. Here are two examples where the above comes especially in handy for VimFx: -- You can use the `zf` command to focus a link or video (or anything) and then +- You can use the `ef` command to focus a link or video (or anything) and then press the `` key to open the context menu, providing you a plethora of things to do with the focused target. For videos, the access key for the “Play/Pause” menu item is often `p`. This allows you, for example, to control diff --git a/documentation/modes.md b/documentation/modes.md index 5bfc200..b4234d8 100644 --- a/documentation/modes.md +++ b/documentation/modes.md @@ -32,7 +32,7 @@ These are the modes of VimFx: make sense to [enter Ignore mode by default][blacklist] and stay in Ignore mode most of the time, occasionally popping into Normal mode. -- Hints mode. Entered when using the [`f` commands][f-commands] and lets you +- Hints mode. Entered when using the [hint commands][hint-commands] and lets you click things by typing the letters of hint markers. - Caret mode. Entered when using some of the [`v` commands][v-commands] and lets @@ -52,7 +52,7 @@ A mode does three things. - It decides what happens when you press keys on your keyboard. If your key press is part of the [shortcut] for a command, it is usually consumed by VimFx. If not, Normal mode and Ignore mode pass the key press on (letting it - behave as if VimFx wasn’t even installed), while in [Hints mode][f-commands] + behave as if VimFx wasn’t even installed), while in [Hints mode][hint-commands] _all_ key presses are captured, allowing you to type the letters of a hint marker. @@ -70,6 +70,6 @@ Note that the mode is per tab, not global. [blacklist]: options.md#blacklist [autofocus prevention]: options.md#prevent-autofocus [shortcut]: shortcuts.md -[f-commands]: commands.md#the-f-commands--hints-mode +[hint-commands]: commands.md#the-hint-commands--hints-mode [v-commands]: commands.md#the-v-commands--caret-mode [button]: button.md diff --git a/documentation/options.md b/documentation/options.md index 6daa70c..8293b89 100644 --- a/documentation/options.md +++ b/documentation/options.md @@ -26,7 +26,7 @@ These options are available in VimFx’s settings page in the Add-ons Manager ### Hint chars The characters used for the hints in Hints mode, which can be entered using one -of the many [`f` commands] \(and a few `v` commands). +of the many [hint commands]. Quick suggestion: Put more easily reachable keys longer to the left. Put two pretty good (but not the best) keys at the end, after the space. @@ -66,7 +66,7 @@ All of this also help you understand why hints may be slow on some pages: - Another reason could be that a page has a _huge_ amount of links. If that bothers you regularly, feel free to send a pull request with faster code! -[`f` commands]: commands.md#the-f-commands--hints-mode +[hint commands]: commands.md#the-hint-commands--hints-mode ### “Previous”/“Next” link patterns @@ -435,19 +435,19 @@ this pref as well. Otherwise VimFx’s Keyboard Shortcuts dialog will still tell you to press shift for this task. [styling]: styling.md -[Hints mode]: commands.md#the-f-commands--hints-mode +[Hints mode]: commands.md#the-hint-commands--hints-mode ### `hints_toggle_in_tab` If the keypress that matched a hint starts with this string, toggle whether to -open the matched link in the current tab or a new tab. See [The `f` commands] +open the matched link in the current tab or a new tab. See [The hint commands] for more information. ### `hints_toggle_in_background` If the keypress that matched a hint starts with this string, open the matched link in a new tab and toggle whether to open that tab in the background or -foreground. See [The `f` commands] for more information. +foreground. See [The hint commands] for more information. ### `activatable_element_keys` diff --git a/documentation/questions-and-answers.md b/documentation/questions-and-answers.md index ee04e34..1d33b83 100644 --- a/documentation/questions-and-answers.md +++ b/documentation/questions-and-answers.md @@ -82,7 +82,7 @@ which is specialized at searching your keyboard shortcuts. No, but clicking on any command in it opens VimFx’s settings page in the Add-ons Manager and automatically selects the text input for that command. Tip: Use the -`zF` command to click without using the mouse. +`eb` command to click without using the mouse. ## Will VimFx provide advanced Find features? diff --git a/documentation/shortcuts.md b/documentation/shortcuts.md index e5f92d8..3bde866 100644 --- a/documentation/shortcuts.md +++ b/documentation/shortcuts.md @@ -12,7 +12,7 @@ defaults and trying things out. If not, read on. In VimFx’s Keyboard Shortcuts help dialog (which can be opened by pressing `?`) you can click any command to open VimFx’s settings page in the Add-ons Manager -and automatically select the text input for that command. Tip: Use the `zF` +and automatically select the text input for that command. Tip: Use the `eb` command to click without using the mouse. Shortcuts tell which keys to press to activate a command. A command may have diff --git a/extension/lib/defaults.coffee b/extension/lib/defaults.coffee index e49c9ff..1d4e6c5 100644 --- a/extension/lib/defaults.coffee +++ b/extension/lib/defaults.coffee @@ -83,17 +83,17 @@ shortcuts = 'browsing': 'f': 'follow' 'F': 'follow_in_tab' - 'gf': 'follow_in_focused_tab' - 'gF': 'follow_in_window' + 'et': 'follow_in_focused_tab' + 'ew': 'follow_in_window' 'af': 'follow_multiple' 'yf': 'follow_copy' - 'zf': 'follow_focus' - 'zF': 'click_browser_element' + 'ef': 'follow_focus' + 'eb': 'click_browser_element' '[': 'follow_previous' ']': 'follow_next' 'gi': 'focus_text_input' 'v': 'element_text_caret' - 'zv': 'element_text_select' + 'av': 'element_text_select' 'yv': 'element_text_copy' 'find': diff --git a/extension/lib/markable-elements.coffee b/extension/lib/markable-elements.coffee index e4ddbbc..027daaa 100644 --- a/extension/lib/markable-elements.coffee +++ b/extension/lib/markable-elements.coffee @@ -82,7 +82,7 @@ getAllElements = (document, selector) -> # Ideally we should find a way to find all elements without duplicates. elements = new Set() getAllRegular = (element) -> - # The first time `zF` is run `.getElementsByTagName('*')` may oddly include + # The first time `eb` is run `.getElementsByTagName('*')` may oddly include # `undefined` in its result! Filter those out. (Also, `selector` is ignored # here since it doesn’t make sense in XUL documents because of all the # trickery around anonymous elements.) -- 2.39.3