metis.input.keybinding

A system for handling keyboard shortcuts. Given a table of keybindings and their corresponding action, metis.input.keybinding will process events and invoke the appropriate action when a key is pressed.

Keybinding syntax

Keybindings are written in an Emacs-esque notation, specifying the modifier keys and then the actual key. For instance, C-M-underscore means the "Control", "Meta" (or "Alt") and "underscore" keys must be pressed.

Usage

• local kb = require "metis.input.keybinding".create {
    ["C-M-x"] = function() print("Pressed Ctrl, Alt and 'x'") end,
    char = function(c) print("Typed character " .. c) end,
  }
  
  while true do kb:event(os.pullEvent()) end

create_keymap(...)Source

Create a new keymap.

Parameters

1. ... { [string] = function } | Keymap

   One or more tables of key bindings. These can either be:

   • An existing Keymap instance or.
   • A mapping of keybinding names (as described in the module description) to functions. The special name "char" may be used when a character is typed.

   Later keybindings override existing ones.

Or

1. ... Keymap An existing keymap which this one will extend.

Returns

1. Keymap The constructed keymap handler.

create([keymap])Source

Create a new group of keybindings.

Parameters

1. keymap? Keymap | { [string] = function } The keymap to use for this instance. Can be changed later with Keybindings:set_keymap.

Returns

1. Keybindings The constructed keybinding handler.

Types

Keybindings

The keybinding processor. This accepts events, determines what keys are pressed, and dispatches the appropriate action.

Keybindings.char(chr, ...)Source

Process a char event.

Parameters

1. chr string The character which has been typed.
2. ... Additional arguments which will be passed to the associated action.

Returns

1. The result of the associated keybinding's action, or nil.

Keybindings.key(key, ...)Source

Process a key event.

Parameters

1. key number The key which has been pressed.
2. ... Additional arguments which will be passed to the associated action.

Returns

1. The result of the associated keybinding's action, or nil.

Keybindings.key_up(key)Source

Process a key_up event.

Parameters

1. key number The key which has been released.

Keybindings.event(event, ...)Source

Process an event. This dispatches to the Keybindings:key, Keybindings:key_up or Keybindings:char as appropriate.

Repeat key events will be passed to Keybindings:key by default. If this is not desired, your keybindings should either check if this event is a repeat (the first argument will be true) or roll your own version of event.

Parameters

1. event string The name of the event.
2. ... Additional event arguments.

Usage

• kb:event(os.pullEvent())

Keybindings.set_keymap(keymap)Source

Update the underlying Keymap of this keybindings instance.

Parameters

1. keymap Keymap | { [string] = function } The keymap to use for this instance.

Keybindings:reset()Source

Reset the set of pressed keys within the keybinding manager. This may be used if a window becomes unfocused, and so key_up events will no longer be sent to it.

Keymap

A mapping of various key combinations to functions.

This is used by a Keybindings instance to dispatch

See also

• create_keymap to create a new Keymap.