3 This file documents VimFx’s [config file] API.
5 Both `config.js` and `frame.js` have access to a variable called `vimfx`. Note
6 that while the variables have the same name, they are different and provide
12 In `config.js`, the following API is available as the variable `vimfx`.
14 ### `vimfx.get(...)`, `vimfx.getDefault(...)` and `vimfx.set(...)`
16 Gets or sets the (default) value of a VimFx option.
18 You can see all options in [defaults.coffee], or by opening [about:config] and
19 filtering by `extensions.vimfx`. Note that you can also access the [special
20 options], which may not be accessed in [about:config], using `vimfx.get(...)`
21 and `vimfx.set(...)`—in fact, this is the _only_ way of accessing those options.
23 #### `vimfx.get(option)`
25 Gets the value of the VimFx option `option`.
28 // Get the value of the Hint characters option:
29 vimfx.get('hints.chars')
30 // Get all keyboard shortcuts (as a string) for the `f` command:
31 vimfx.get('mode.normal.follow')
34 #### `vimfx.getDefault(option)`
36 Gets the default value of the VimFx option `option`.
38 Useful when you wish to extend a default, rather than replacing it. See below.
40 #### `vimfx.set(option, value)`
42 Sets the value of the VimFx option `option` to `value`.
45 // Set the value of the Hint characters option:
46 vimfx.set('hints.chars', 'abcdefghijklmnopqrstuvwxyz')
47 // Add yet a keyboard shortcut for the `f` command:
48 vimfx.set('mode.normal.follow', vimfx.getDefault('mode.normal.follow') + ' ee')
51 When extending an option (as in the second example above), be sure to use
52 `vimfx.getDefault` rather than `vimfx.get`. Otherwise you get a multiplying
53 effect. In the above example, after starting Firefox a few times the option
54 would be `f e e e e`. Also, if you find that example very verbose: Remember
55 that you’re using a programming language! Write a small helper function that
58 Note: If you produce conflicting keyboard shortcuts, the order of your code does
59 not matter. The command that comes first in VimFx’s options page in the Add-ons
60 Manager (and in the Keyboard Shortcuts help dialog) gets the shortcut; the other
61 one(s) do(es) not. See the notes about order in [mode object], [category object]
62 and [command object] for more information about order.
65 // Even though we set the shortcut for focusing the search bar last, the command
66 // for focusing the location bar “wins”, because it comes first in VimFx’s
67 // options page in the Add-ons Manager.
68 vimfx.set('mode.normal.focus_location_bar', 'ö')
69 vimfx.set('mode.normal.focus_search_bar', 'ö')
71 // Swapping their orders also swaps the “winner”.
72 let {commands} = vimfx.modes.normal
73 ;[commands.focus_location_bar.order, commands.focus_search_bar.order] =
74 [commands.focus_search_bar.order, commands.focus_location_bar.order]
77 ### `vimfx.addCommand(options, fn)`
79 Creates a new command.
83 - name: `String`. The name used when accessing the command via
84 `vimfx.modes[options.mode].commands[options.name]`. It is also used for the
85 option name (preference key) used to store the shortcuts for the command:
86 `` `custom.mode.${options.mode}.${options.name}` ``.
87 - description: `String`. Shown in the Keyboard Shortcuts help dialog and VimFx’s
88 options page in the Add-ons Manager.
89 - mode: `String`. Defaults to `'normal'`. The mode to add the command to. The
90 value has to be one of the keys of [`vimfx.modes`].
91 - category: `String`. Defaults to `'misc'` for Normal mode and `''`
92 (uncategorized) otherwise. The category to add the command to. The
93 value has to be one of the keys of [`vimfx.get('categories')`][categories].
94 - order: `Number`. Defaults to putting the command at the end of the category.
95 The first of the default commands has the order `100` and then they increase
96 by `100` per command. This allows to put new commands between two already
99 `fn` is called when the command is activated. See the [onInput] documentation
100 below for more information.
102 <strong id="custom-command-shortcuts">Note</strong> that you have to give the
103 new command a shortcut in VimFx’s options page in the Add-ons Manager or set
104 one using `vimfx.set(...)` to able to use the new command.
109 description: 'Log Hello World',
111 console.log('Hello World!')
114 vimfx.set('custom.mode.normal.hello', 'gö')
117 ### `vimfx.addOptionOverrides(...)` and `vimfx.addKeyOverrides(...)`
119 These methods take any number of arguments. Each argument is a rule. The rules
120 are added in order. The methods may be run multiple times.
122 A rule is an `Array` of length 2:
124 1. The first item is a function that returns `true` if the rule should be
125 applied and `false` if not. This is called the matching function. The
126 matching function receives a [location object] as its only argument.
127 2. The second item is the value that should be used if the rule is applied. This
128 is called the override.
130 The rules are tried in the same order they were added. When a matching rule is
131 found it is applied. No more rules will be applied.
133 #### `vimfx.addOptionOverrides(...rules)`
135 The rules are matched any time the value of a VimFx option is needed.
137 The override is an object whose keys are VimFx option names and whose values
138 override the option in question. The values should be formatted as in an
142 vimfx.addOptionOverrides(
143 [ ({hostname, pathname, hash}) =>
144 `${hostname}${pathname}${hash}` === 'google.com/',
145 {prevent_autofocus: false}
149 vimfx.addOptionOverrides(
150 [ ({hostname}) => hostname === 'imgur.com',
152 pattern_attrs: ['class'],
153 pattern_selector: 'div.next-prev .btn',
154 prev_patterns: [/\bnavPrev\b/],
155 next_patterns: [/\bnavNext\b/],
161 #### `vimfx.addKeyOverrides(...rules)`
163 The rules are matched any time you press a key that is not part of the tail of a
164 multi-key Normal mode shortcut.
166 The override is an array of keys which should not activate VimFx commands but be
169 This allows to disable commands on specific sites. To _add_ commands on specific
170 sites, add them globally and then disable them on all _other_ sites.
173 vimfx.addKeyOverrides(
174 [ location => location.hostname === 'facebook.com',
180 ### `vimfx.send(vim, message, data = null, callback = null)`
182 Send `message` (a string) to the instance of `frame.js` in the tab managed by
183 [`vim`][vim object], and pass it `data`. `frame.js` uses its
184 [`vimfx.listen(...)`] method to listen for (and optionally respond to)
187 If provided, `callback` must be a function. That function will receive a single
188 argument: The data that `frame.js` responds with.
194 // You get a `vim` instance by using `vimfx.addCommand(...)` or `vimfx.on(...)`.
195 vimfx.send(vim, 'getSelection', {example: 5}, selection => {
196 console.log('Currently selected text:', selection)
202 vimfx.listen('getSelection', ({example}, callback) => {
203 console.log('`example` should be 5:', example)
204 // `content` is basically the same as the `window` of the page.
205 let selection = content.getSelection().toString()
210 What if you want to do it the other way around: Send a message _from_ `frame.js`
211 and listen for it in `config.js`? That’s not the common use case, so VimFx does
212 not provide convenience functions for it. `vimfx.send(...)`, and
213 `vimfx.listen(...)` in `frame.js`, are just light wrappers around the standard
214 Firefox [Message Manager] to make it easier to create custom commands that ask
215 `frame.js` for information about the current web page (as in the above example).
216 If you want to send messages any other way, you’ll need to use the Message
217 Manager directly. See [the `shutdown` event] for an example.
219 (While it would have made sense to provide `vim.send(message, data, callback)`
220 instead of `vimfx.send(vim, message, data, callback)`, the latter was chosen for
221 symmetry between `config.js` and `frame.js`. Use `vimfx.send()` to send
222 messages, and `vimfx.listen()` to listen for them.)
224 ### `vimfx.on(eventName, listener)` and `vimfx.off(eventName, listener)`
226 After calling `vimfx.on(eventName, listener)`, `listener(data)` will be called
227 when `eventName` is fired, where `data` is an object. Which properties `data`
228 has is specific to each event.
230 You may use `vimfx.off(eventName, listener)` if you’d like to remove your
231 added listener for some reason.
233 While [`vimfx.send(...)`] and [`vimfx.listen(...)`] are all about passing
234 messages between `config.js` and `frame.js`, `vimfx.on(...)` is all about doing
235 something whenever VimFx emits internal events.
237 #### The `locationChange` event
239 Occurs when opening a new tab, navigating to a new URL or refreshing the page,
240 causing a full page load.
244 - vim: The current [vim object].
245 - location: A [location object].
247 This event can be used to enter a different mode by default on some pages (which
248 can be used to replace the blacklist option).
251 vimfx.on('locationChange', ({vim, location}) => {
252 if (location.hostname === 'example.com') {
253 vimfx.modes.normal.commands.enter_mode_ignore.run({vim, blacklist: true})
258 #### The `notification` and `hideNotification` events
260 The `notification` event occurs when `vim.notify(message)` is called, and means
261 that `message` should be displayed to the user.
263 The `hideNotification` event occurs when the `vim.hideNotification()` is called,
264 and means that the current notification is requested to be hidden.
268 - vim: The current [vim object].
269 - message: The message that should be notified. Only for the `notification`
272 Both of these events are emitted even if the [`notifications_enabled`] option is
273 disabled, allowing you to display notifications in any way you want.
275 #### The `modeChange` event
277 Occurs whenever the current mode in any tab changes. The initial entering of the
278 default mode in new tabs also counts as a mode change.
282 - vim: The current [vim object].
285 vimfx.on('modeChange', ({vim}) => {
286 let mode = vimfx.modes[vim.mode].name
287 vim.notify(`Entering mode: ${mode}`)
291 #### The `TabSelect` event
293 Occurs whenever any tab in any window is selected. This is also fired when
294 Firefox starts for the currently selected tab.
298 - event: The `event` object passed to the standard Firefox [TabSelect] event.
300 #### The `modeDisplayChange` event
302 This is basically a combination of the `modeChange` and the `TabSelect` events.
303 The event is useful for knowing when to update UI showing the current mode.
307 - vim: The current [vim object].
309 (VimFx itself uses this event to update the toolbar [button], by setting
310 `#main-window[vimfx-mode]` to the current mode. You may use this with custom
313 #### The `focusTypeChange` event
315 Occurs when focusing or blurring any element. See also the [`blur_timeout`]
320 - vim: The current [vim object].
322 `data.vim.focusType` has been updated just before this event fires.
324 (VimFx itself uses this event to update the toolbar [button], by setting
325 `#main-window[vimfx-focus-type]` to the current focus type. You may use this
326 with custom [styling].)
328 #### The `shutdown` event
332 - VimFx shuts down: When Firefox shuts down, when VimFx is disabled or when
334 - When the config file is reloaded using the `gC` command.
336 `data`: No data at all is passed.
338 If you care about that things you do in `config.js` and `frame.js` are undone
339 when any of the above happens, read on.
341 If all you do is using the methods of the `vimfx` object, you shouldn’t need to
342 care about this event.
344 The following methods don’t need any undoing:
347 - `vimfx.getDefault(...)`
351 The following methods are automatically undone when the `shutdown` event fires.
352 This means that if you, for example, add a custom command in `config.js` but
353 then remove it from `config.js` and hit `gC`, the custom command will be gone in
357 - `vimfx.addCommand(...)`
358 - `vimfx.addOptionOverrides(...)`
359 - `vimfx.addKeyOverrides(...)`
362 The following require manual undoing:
364 - `vimfx.mode`. Any changes you do here must be manually undone.
366 If you add event listeners in `frame.js`, here’s an example of how to remove
371 vimfx.on('shutdown', () => {
372 Components.classes['@mozilla.org/globalmessagemanager;1']
373 .getService(Components.interfaces.nsIMessageListenerManager)
374 // Send this message to _all_ frame scripts.
375 .broadcastAsyncMessage('VimFx-config:shutdown')
382 function listen(eventName, listener) {
383 addEventListener(eventName, listener, true)
384 listeners.push([eventName, listener])
387 listen('focus', event => {
388 console.log('focused element', event.target)
391 addMessageListener('VimFx-config:shutdown', () => {
392 listeners.forEach(([eventName, listener]) => {
393 removeMessageListener(eventName, listener, true)
400 An object whose keys are mode names and whose values are [mode object]s.
402 This is a very low-level part of the API. It allows to:
404 - Access all commands and run them. This is the most common thing that a config
405 file user needs it for.
408 let {commands} = vimfx.modes.normal
409 // Inside a custom command:
410 commands.tab_new.run(args)
413 - Adding new commands. It is recommended to use the `vimfx.addCommand(...)`
414 helper instead. It’s easier.
417 vimfx.modes.normal.commands.new_command = {
418 pref: 'extensions.my_extension.mode.normal.new_command',
421 description: translate('mode.normal.new_command'),
422 run: args => console.log('New command! args:', args)
426 - Adding new modes. This is the most advanced customization you can do to VimFx.
427 Expect having to read VimFx’s source code to figure it all out.
430 vimfx.modes.new_mode = {
431 name: translate('mode.new_mode'),
436 onInput(args, match) {
437 switch (match.type) {
439 match.command.run(args)
450 Have a look at [modes.coffee] and [commands.coffee] for more information.
452 ### `vimfx.get('categories')`
454 An object whose keys are category names and whose values are [category object]s.
457 let categories = vimfx.get('categories')
459 // Add a new category.
460 categories.custom = {
461 name: 'Custom commands',
465 // Swap the order of the Location and Tabs categories.
466 ;[commands.focus_location_bar.order, categories.tabs.order] =
467 [categories.tabs.order, commands.focus_location_bar.order]
470 ### Custom hint commands
472 Apart from the standard hint commands, you can create your own.
474 You may run any VimFx command by using the following pattern:
479 name: 'run_other_command_example',
480 description: 'Run other command example',
482 // Replace 'follow' with any command name here:
483 vimfx.modes.normal.commands.follow.run(args)
487 All hint commands (except `eb`) also support `args.callbackOverride`:
492 name: 'custom_hint_command_example',
493 description: 'Custom hint command example',
495 vimfx.modes.normal.commands.follow.run(Object.assign({}, args, {
496 callbackOverride({type, href, id, timesLeft}) {
497 console.log('Marker data:', {type, href, id, timesLeft})
498 return (timesLeft > 1)
504 This lets you piggy-back on one of the existing hint commands by getting the
505 same hints on screen as that command, but then doing something different with
506 the matched hint marker.
508 `callbackOverride` is called with an object with the following properties:
510 - type: `String`. The type of the element of the matched hint marker. See
511 [`vimfx.setHintMatcher(...)`] for all possible values.
513 - href: `String` or `null`. If `type` is `'link'`, then this is the `href`
514 attribute of the element of the matched hint marker.
516 - id: An id that you can pass to [`vimfx.getMarkerElement(...)`] to get the
517 element of the matched hint marker.
519 - timesLeft: `Number`. Calling a hint command with a count means that you want
520 to run it _count_ times in a row. This number tells how many times there are
521 left to run. If you don’t provide a count, the number is `1`.
523 `callbackOverride` should return `true` if you want the hint markers to
524 re-appear on screen after you’ve matched one of them (as in the `af` command),
525 and `false` if you wish to exit Hints mode. If your command ignores counts,
526 simply always return `false`. Otherwise you most likely want to return
529 Here’s an example which adds a silly command for marking links with
530 color—`http://` links with red and all other links with green.
534 let {commands} = vimfx.modes.normal
538 category: 'browsing',
539 description: 'Mark link with red or green',
542 commands.follow_in_tab.run(Object.assign({}, args, {
543 callbackOverride({type, href, id, timesLeft}) {
545 let color = href.startsWith('http://') ? 'red' : 'green'
546 vimfx.send(vim, 'highlight_marker_element', {id, color})
556 vimfx.listen('highlight_marker_element', ({id, color}) => {
557 let element = vimfx.getMarkerElement(id)
559 element.style.backgroundColor = color
566 A mode is an object with the following properties:
568 - name: `String`. A human readable name of the mode used in the Keyboard
569 Shortcuts help dialog and VimFx’s options page in the Add-ons Manager. Config
570 file users adding custom modes could simply use a hard-coded string; extension
571 authors are encouraged to look up the name from a locale file.
572 - order: `Number`. The first of the default modes has the order `100` and then
573 they increase by `100` per mode. This allows to put new modes between two
574 already existing ones.
575 - commands: `Object`. The keys are command names and the values are [command
577 - onEnter(data, ...args): `Function`. Called when the mode is entered.
578 - onLeave(data): `Function`. Called when the mode is left.
579 - onInput(data, match): `Function`. Called when a key is pressed.
581 #### onEnter, onLeave and onInput
583 These methods are called with an object (called `data` above) with the following
586 - vim: The current [vim object].
587 - storage: An object unique to the current [vim object] and to the current mode.
588 Allows to share things between commands of the same mode by getting and
593 This method is called with an object as mentioned above, and after that there
594 may be any number of arguments that the mode is free to do whatever it wants
599 The object passed to this method (see above) also has the following properties:
601 - event: `Event`. The keydown event object.
602 - count: `Number`. The count for the command. `undefined` if no count. (This is
603 simply a copy of `match.count`. `match` is defined below.)
605 The above object should be passed to commands when running them. The mode is
606 free to do whatever it wants with the return value (if any) of the commands it
609 It also receives a [match object] as the second argument.
611 `onInput` should return `true` if the current keypress should not be passed on
612 to the browser and web pages, and `false` otherwise.
616 A category is an object with the following properties:
618 - name: `String`. A human readable name of the category used in the Keyboard
619 Shortcuts help dialog and VimFx’s options page in the Add-ons Manager. Config
620 file users adding custom categories could simply a use hard-coded string;
621 extension authors are encouraged to look up the name from a locale file.
622 - order: `Number`. The first of the default categories is the “uncategorized”
623 category. It has the order `100` and then they increase by `100` per category.
624 This allows to put new categories between two already existing ones.
628 A command is an object with the following properties:
630 - pref: `String`. The option name (preference key) used to store the shortcuts
632 - run(args): `Function`. Called when the command is activated.
633 - description: `String`. A description of the command, shown in the Keyboard
634 Shortcuts help dialog and VimFx’s options page in the Add-ons Manager. Config
635 file users adding custom commands could simply use a hard-coded string;
636 extension authors are encouraged to look up the name from a locale file.
637 - category: `String`. The category to add the command to. The value has to be
638 one of the keys of [`vimfx.get('categories')`][categories].
639 - order: `Number`. The first of the default commands has the order `100` and
640 then they increase by `100` per command. This allows to put new commands
641 between two already existing ones.
645 A `match` object has the following properties:
647 - type: `String`. It has one of the following values:
649 - `'full'`: The current keypress, together with previous keypresses, fully
650 matches a command shortcut.
651 - `'partial'`: The current keypress, together with previous keypresses,
652 partially matches a command shortcut.
653 - `'count'`: The current keypress is not part of a command shortcut, but is a
654 digit and contributes to the count of a future matched command.
655 - `'none'`: The current keypress is not part of a command shortcut and does
656 not contribute to a count.
658 - likelyConflict: `Boolean`. This is `true` if the current keypress is likely to
659 cause conflicts with default Firefox behavior of that key, and `false`
660 otherwise. A mode might not want to run commands and suppress the event if
661 this value is `true`. VimFx uses the current keypress and `vim.focusType` of
662 the current [vim object] to decide if the current keypress is a likely
665 1. If the key is part of the tail of a shortcut, it is never a conflict.
666 2. If `vim.focusType` is `'activatable'` or `'adjustable'` and the key is
667 present in [`activatable_element_keys`] or [`adjustable_element_keys`]
668 (respectively), then it is a likely conflict.
669 3. Finally, unless `vim.focusType` is `'none'`, then it is a likely conflict.
670 This most commonly means that a text input is focused.
672 Note that any VimFx shortcut starting with a keypress involving a modifier is
673 _very_ likely to conflict with either a Firefox default shortcut or a shortcut
674 from some other add-on. This is _not_ attempted to be detected in any way.
675 Instead, VimFx uses no modifiers in any default Normal mode shortcuts, leaving
676 it up to you to choose modifier-shortcuts that work out for you if you want
677 such shortcuts. In other words, for modifier-shortcuts the point of VimFx _is_
678 to conflict (overriding default shortcuts).
680 - command: `null` unless `type` is `'full'`. Then it is the matched command (a
683 The matched command should usually be run at this point. It is suitable to
684 pass on the object passed to [onInput] to the command. Some modes might choose
685 to add extra properties to the object first. (That is favored over passing
686 several arguments, since it makes it easier for the command to in turn pass
687 the same data it got on to another command, if needed.)
689 Usually the return value of the command isn’t used, but that’s up to the mode.
691 - count: `Number`. The count for the command. `undefined` if no count.
693 - specialKeys: `Object`. The keys may be any of the following:
698 If a key exists, its value is always `true`. The keys that exist indicate the
699 [special keys] for the sequence used for the matched command (if any).
701 - keyStr: `String`. The current keypress represented as a string.
703 - unmodifiedKey: `String`. `keyStr` without modifiers.
705 - rawKey: `String`. Unchanged [`event.key`].
707 - rawCode: `String`. Unchanged [`event.code`].
709 - toplevel: `Boolean`. Whether or not the match was a toplevel match in the
710 shortcut key tree. This is `true` unless the match is part of the tail of a
713 - discard(): `Function`. Discards keys pressed so far: If `type` is `'partial'`
714 or `'count'`. For example, if you have typed `12g`, run `match.discard()` and
715 then press `$`, the `$` command will be run instead of `12g$`.
719 There is one `vim` object per tab.
721 A `vim` object has the following properties:
723 - window: [`Window`]. The current Firefox window object. Most commands
724 interacting with Firefox’s UI use this.
726 - browser: [`Browser`]. The `browser` that this vim object handles.
728 - options: `Object`. Provides access to all of VimFx’s options. It is an
731 - mode: `String`. The current mode name.
733 - focusType: `String`. The type of currently focused element. VimFx decides the
734 type based on how it responds to keystorkes. It has one of the following
737 - `'ignore'`: Some kind of Vim-style editor. VimFx automatically
738 enters Ignore mode when this focus type is encountered.
739 - `'editable'`: Some kind of text input, a `<select>` element or a
740 “contenteditable” element.
741 - `'activatable'`: An “activatable” element (link or button).
742 (See also the [`activatable_element_keys`] option.)
743 - `'adjustable'`: An “adjustable” element (form control or video
744 player). (See also the [`adjustable_element_keys`] option.)
745 - `'findbar'`: The findbar text input is focused.
746 - `'none'`: The currently focused element does not appear to respond to
747 keystrokes in any special way.
749 [The `focusTypeChange` event] is fired whenever `focusType` is updated.
751 `match.likelyConflict` of [match object]s depend on `focusType`.
753 - isUIEvent(event): `Function`. Returns `true` if `event` occurred in the
754 browser UI, and `false` otherwise (if it occurred in web page content).
756 - notify(message): `Function`. Display a notification with the text `message`.
758 - hideNotification(): `Function`. Hide the current notification (if any).
760 - markPageInteraction(value=true): `Function`. When `value` is `true` (as it is
761 by default when the argument is omitted), marks that the user has interacted
762 with the page. After that [autofocus prevention] is not done anymore. Commands
763 interacting with web page content might want to do this. If `value` is
764 `false`, the state is reset and autofocus prevention _will_ be done again.
766 **Warning:** There are also properties starting with an underscore on `vim`
767 objects. They are private, and not supposed to be used outside of VimFx’s own
768 source code. They may change at any time.
772 An `options` object provides access to all of VimFx’s options. It is an object
773 whose keys are VimFx option names.
775 Note that the values are not just simply `vimfx.get(option)` for the `option` in
776 question; they are _parsed_ (`parse(vimfx.get(option))`):
778 - Space-separated options are parsed into arrays of strings. For example,
779 `pattern_attrs: ['class']`.
781 - `blacklist`, `prev_patterns` and `next_patterns` are parsed into arrays of
782 regular expressions. For example, `prev_patterns: [/\bnavPrev\b/]`.
784 (See [parse-prefs.coffee] for all details.)
786 Any [option overrides] are automatically taken into account when getting an
789 The [special options] are also available on this object.
794 A location object is very similar to [`window.location`] in web pages.
795 Technically, it is a [`URL`] instance. You can experiment with the current
796 location object by opening the [web console] and entering `location`.
801 In `frame.js`, the following API is available as the variable `vimfx`.
803 ### `vimfx.listen(message, listener)`
805 Listen for `message` (a string) from `config.js`. `listener` will be called with
806 the data sent from `config.js` (if any), and optionally a callback function if
807 `config.js` wants you to respond. If so, call the callback function, optionally
808 with some data to send back to `config.js.` `config.js` uses its
809 [`vimfx.send(...)`] method to send `message` (and optionally some data along
812 See the [`vimfx.send(...)`] method in `config.js` for more information and
815 ### `vimfx.setHintMatcher(hintMatcher)`
817 `hintMatcher` is a function that lets you customize which elements do and don’t
818 get hints. It might help to read about [the hint commands] first.
820 If you call `vimfx.setHintMatcher(hintMatcher)` more than once, only the
821 `hintMatcher` provided the last time will be used.
824 vimfx.setHintMatcher((id, element, type) => {
825 // Inspect `element` and return a different `type` if needed.
830 The arguments passed to the `hintMatcher` function are:
832 - id: `String`. A string identifying which command is used:
834 - `'normal'`: `f` or `af`.
835 - `'tab'`: `F`, `et`, `ew` or `ep`.
839 - `'select'`: `v`, `av` or `yv`.
841 - element: `Element`. One out of all elements currently inside the viewport.
843 - type: `String` or `null`. If a string, it means that `element` should get a
844 hint. If `null`, it won’t. See the available strings below. When a marker
845 is matched, `type` decides what happens to `element`.
847 This parameter tells how VimFx has matched `element`. You have the opportunity
850 The available type strings depend on `id`:
854 - link: A “proper” link (not used as a button with the help of JavaScript),
855 with an `href` attribute.
856 - text: An element that can you can type in, such as text inputs.
857 - clickable: Some clickable element not falling into another category.
858 - clickable-special: Like “clickable,” but uses a different technique to
859 simulate a click on the element. If “clickable” doesn’t work, try this one.
860 - scrollable: A scrollable element.
864 - link: Like “link” when `id` is “normal” (see above).
868 - link: Like “link” when `id` is “normal” (see above).
869 - text: Like “text” when `id` is “normal” (see above), except that in this
870 case “contenteditable” elements are not included.
871 - contenteditable: Elements with “contenteditable” turned on.
875 - focusable: Any focusable element not falling into another category.
876 - scrollable: Like “scrollable” when `id` is “normal” (see above).
880 - context: An element that can have a context menu opened.
884 - selectable: An element with selectable text (but not text inputs).
886 The function must return `null` or a string like the `type` parameter.
888 ### `vimfx.getMarkerElement(id)`
890 Takes an id that has been given to you when creating [custom hint commands] and
891 returns the DOM element associated with that id. If no element can be found,
895 [option overrides]: #vimfxaddoptionoverridesrules
896 [`vimfx.send(...)`]: #vimfxsendvim-message-data--null-callback--null
897 [`vimfx.listen(...)`]: #vimfxlistenmessage-listener
898 [categories]: #vimfxgetcategories
899 [custom hint commands]: #custom-hints-commands
900 [`vimfx.modes`]: #vimfxmodes
902 [mode object]: #mode-object
903 [category object]: #category-object
904 [command object]: #command-object
905 [match object]: #match-object
906 [vim object]: #vim-object
907 [options object]: #options-object
908 [location object]: #location-object
909 [The `focusTypeChange` event]: #the-focustypechange-event
910 [the `shutdown` event]: #the-shutdown-event
911 [`vimfx.setHintMatcher(...)`]: #vimfxsethintmatcherhintmatcher
912 [`vimfx.getMarkerElement(...)`]: #vimfxgetmarkerelementid
914 [blacklisted]: options.md#blacklist
915 [special options]: options.md#special-options
916 [config file]: config-file.md
917 [bootstrap.js]: config-file.md#bootstrapjs
918 [autofocus prevention]: options.md#prevent-autofocus
919 [`activatable_element_keys`]: options.md#activatable_element_keys
920 [`adjustable_element_keys`]: options.md#adjustable_element_keys
921 [`blur_timeout`]: options.md#blur_timeout
922 [`notifications_enabled`]: options.md#notifications_enabled
925 [the hint commands]: commands.md#the-hint-commands--hints-mode
926 [special keys]: shortcuts.md#special-keys
927 [styling]: styling.md
929 [defaults.coffee]: ../extension/lib/defaults.coffee
930 [parse-prefs.coffee]: ../extension/lib/parse-prefs.coffee
931 [modes.coffee]: ../extension/lib/modes.coffee
932 [commands.coffee]: ../extension/lib/commands.coffee
933 [vim.coffee]: ../extension/lib/vim.coffee
935 [`event.key`]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key
936 [`event.code`]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code
937 [`Window`]: https://developer.mozilla.org/en-US/docs/Web/API/Window
938 [`Browser`]: https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XUL/browser
939 [`window.location`]: https://developer.mozilla.org/en-US/docs/Web/API/Location
940 [`URL`]: https://developer.mozilla.org/en-US/docs/Web/API/URL
941 [Message Manager]: https://developer.mozilla.org/en-US/Firefox/Multiprocess_Firefox/Message_Manager
942 [TabSelect]: https://developer.mozilla.org/en-US/docs/Web/Events/TabSelect
943 [web console]: https://developer.mozilla.org/en-US/docs/Tools/Web_Console
944 [about:config]: http://kb.mozillazine.org/About:config