master-key.prefix

This command is used to implement multi-key sequence bindings in master key. It causes the current key press to be appended to the variable key.prefix. This prefix shows up in the status bar in VSCode. It can also be used explicitly within a binding file for a few purposes:

• provide helpful documentation for a given key prefix.
• define a command that has several possible follow-up key presses (such as operators in vim).
• execute commands in addition to updating the prefix (see running multiple commands)

Arguments

• cursor: Transiently change the cursor shape until the last key in a multi-key sequence is pressed. Valid values are:
  • 'Line',
  • 'Block',
  • 'Underline',
  • 'LineThin',
  • 'BlockOutline',
  • 'UnderlineThin',

Example

The tab prefix is documented in the Larkin bindings as follows

[[bind]]
defaults = "util"
name = "utility"
key = "tab"
description = """
utility related commands: file opening, window manipulation, debugging etc...
"""
command = "master-key.prefix"

The prefix command is used here so that this prefix binding is well documented.

Prefix Format

The prefix state is stored under key.prefix (when evaluating an expression) and under master-key.prefix in a when clause (though it should rarely be necessary to access the prefix explicitly in a when clause). It is stored as a space delimited sequence of keybindings in the same form that the key field is specified (which is the same as the binding format for any VSCode keybinding). It is displayed in the status bar in a stylized fashion: e.g. Ctrl+J becomes ^J.

Transient State

A binding that includes a prefix command has finalKey set to false. Whereas, without a prefix command present, the default is true. When finalKey is false master key does not reset any previously set transient state (e.g. from previous calls to prefix or updateCount). When finalKey is true any transient state is returned to a default, unset state.

In most circumstances you do not want to set finalKey to false without using master-key.prefix, but there are exceptions. In this situation the key's commands will be executed but the key the user pressed will not update the prefix state. For example, pressing "shift+;" in Larkin displays a menu of possible key suffixes. This command is implemented as follows

[[bind]]
key = "shift+;"
doc.name = "suggest"
finalKey = false
doc.hideInPalette = true
prefixes.any = true
mode = '{{not_modes(["insert"])}}'
doc.description = """
show command suggestions within the context of the current mode and keybinding prefix
(if any). E.g. `TAB, ⇧;` in `normal` mode will show all `normal` command suggestions
that start with `TAB`.
"""
command = "master-key.toggleSuggestions"

A few things are going on here:

1. The binding applies regardless of the current prefix (prefixes.any = true).
2. This calls a command that lists possible keys that can be pressed given the current prefix (command = "master-key.toggleSuggestions"). master-key.prefix is not called, so the press of shift+; will not update to the current sequence of keys that have been pressed. It's "invisible" as far as the sequence of a multi-key binding is concerned.
3. The binding does not reset the prefixes state since finalKey = false, so master key will continue to wait for additional key presses that can occur for the given keybinding prefix.

In this way the user can ask for help regarding which keys they can press next, without resetting the state.