Master Key

Appearance

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 a variable storing the pending key sequence. 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 (via runCommands)

Arguments

  • flag: If present, transiently sets the given flag to true. See also setFlag
  • cursor: Transiently change the cursor shape until the last key in a multi-key sequence is pressed

Example ​

The tab prefix is documented in the Larkin bindings as follows

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

These prefixes may be explicitly specified in this way so they can be documented. When users do not provide an explicit prefix, Master key explicitly creates these bindings by itself, but without documentation. As such, all of the bindings written in a keybinding.json file have just a single key press, with some conditioned on the specific prefix that must occur beforehand. This is so that master key can explicitly manage state across the key presses of a multi-key sequence keybinding.

Prefix Format ​

The prefix state is stored under 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).

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 not reset any previously set transient state (e.g. from previous calls to prefix or transient setFlag). 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

toml
[[bind]]
key = "shift+;"
name = "suggest"
finalKey = false
hideInPalette = true
prefixes = "{{all_prefixes}}"
mode = ["!capture", "!insert"]
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.commandSuggestions"

A few things are going on here:

  1. The binding applies regardless of the current prefix (`prefixes = "{{all_prefixes}}").
  2. This calls a command that lists possible keys that can be pressed given the current prefix (command = "master-key.commandSuggestions"). 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")
  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.