Master Key

Appearance

Binding Field bind ​

Example

toml
[[bind]]
name = "left"
key = "h"
mode = "normal"
command = "cursorLeft"

The bind element has two categories of fields: functional and documenting.

Functional Fields ​

The functional fields determine what the keybinding does. Required fields are marked with a *.

  • command*: A string denoting the command to execute. This is a command defined by VSCode or an extension thereof. See finding commands. This field has special behavior for the command runCommands (see running multiple commands).

  • args: The arguments to directly pass to the command, these are static values.

  • computedArgs: Like args except that each value is a string that is evaluated as an expression.

  • key*: the keybinding that triggers command.

  • when: A when clause context under which the binding will be active. Also see Master Key's available contexts

  • mode: The mode during which the binding will be active. The default mode is used when this field is not specified (either directly or via the defaults field)

  • priority: The ordering of the keybinding relative to others; determines which bindings take precedence. Defaults to 0.

  • defaults: the hierarchy of defaults applied to this binding, see default for more details.

  • foreach: Allows parametric definition of multiple keybindings, see foreach clauses.

  • prefixes: (array of strings or the string {{all_prefixes}}). Determines one or more unresolved key sequences that can have occurred before typing this key. See master-key.prefix for details. Defaults to "" (a.k.a. no prefix is allowed). This can be set to {{all_prefixes}}, if you wish to allow the key binding to work regardless of any unresolved key sequence that has been pressed (e.g. this is used for the "escape" key binding in Larkin).

  • finalKey: (boolean, default=true) Whether this key should clear any transient state associated with the pending keybinding prefix. See master-key.prefix for details.

  • computedRepeat: This is an expression. It is expected to evaluate to the number of times to repeat the command. Defaults to zero: one repeat means the command is run twice.

  • command will be repeated the given number of times.

  • whenComputed: an expression that, if evaluated to false, the command will not execute. Favor when clauses over whenComputed. The whenComputed field is distinct from the when clause because it uses the scope of expressions rather than when clause statements. Furthermore, even if the whenComputed is false, the binding is still considered to have triggered, and now downstream keybindings will be triggered. It is most useful in conjunction with runCommands or storeCommand.

Documenting Fields ​

The documenting fields determine how the keybinding is documented. They are all optional.

  • name: A very description for the command; this must fit in the visual documentation so it shouldn't be much longer than five characters for most keys. Favor unicode symbols such as → and ← over text.

  • description: A longer description of what the command does. Shouldn't be much longer than a single sentence for most keys. Save more detailed descriptions for the literate comments.

  • hideInPalette/hideInDocs: whether to show the keys in the popup suggestions and the documentation. These both default to false.

  • combinedName/combinedKey/combinedDescription: in the suggestion palette and textual documentation, keys that have the same combinedName will be represented as single entry, using the combinedKey and combinedDescription instead of key and description. The combinedKey for a multi-key sequence should only include the suffix key. All but the first key's combinedKey and combinedDescription are ignored.

  • kind: The broad cagegory of commands this binding falls under. There should be no more than 4-5 of these. Each kind here should have a corresponding entry in the top-level kind array.

Finding Commands ​

You can find commands in a few ways:

  • Find command you want to use from the command palette, and click on the gear (⚙︎) symbol to copy the command string to your clipboard
  • Review the list of built-in commands
  • Run the command Preferences: Open Default Keyboard Shortcuts (JSON) to get a list of built-in commands and extension commands already associated with a keybinding

Furthermore, you can also use:

Selection Utilities is a complimentary extension used extensively by the Larkin preset.

Running Multiple Commands ​

When command is set to runCommands, you can run multiple commands with a signle key press. Theargs.commands list can be:

  • an array of strings listing the commands
  • an array of objects with command, args computedWhen and computedArgs fields, defined in the same way as the top-level bind fields of the same names are defined. You cannot have nested calls to "runCommands".
  • an object with the field defined set to a command object defined under a define field.

Available when Contexts ​

Each keybinding can make use of any context defined in VSCode across any extension. Master Key adds the follow contexts:

  • All variables available in expression, prefixed with master-key.
  • master-key.keybindingPaletteBindingMode: true when the suggestion palette accepts keybinding key presses, false it accepts a string to search the descriptions of said keybindings
  • master-key.keybindingPaletteOpen: true when the suggestion palette is open

foreach Clauses ​

The foreach clause of a keybinding can be used to generate many bindings from one entry. Each field under foreach is looped through exhaustively. On each iteration, any string values that contain {{[var]}} where [var] is a foreach field, is replaced with that fields value for the given iteration. For example, the following defines 9 bindings:

toml
[[bind]]
foreach.a = [1,2,3]
foreach.b = [1,2,3]
key = "ctrl+; {{a}} {{b}}"
command = "type"
args.text = "{{a-b}}"

Furthermore, if the value {{key: [regex]}} is included in a foreach field, it is expanded to all keybindings that match the given regular expression. For example, the following definition is used in Larkin to allow the numeric keys to be used as count prefix for motions.

toml
[[bind]]
foreach.num = ['{{key: [0-9]}}']
name = "count {{num}}"
key = "{{num}}"
command = "master-key.updateCount"
description = "Add digit {{num}} to the count argument of a command"
args.value = "{{num}}"
# etc...