keyboard

A userdata representing a physical keyboard.

Under the hood, catnip uses xkbcommon for keymap support.

local catnip = require('catnip')

for keyboard in catnip.keyboards do
    print(keyboard.id)
end

Fields

Events

Fields

keyboard.id

---@class CatnipKeyboard
...
---@field id number (readonly)
...

The keyboard ID. This is a unique number assigned to each keyboard that persists across reloads.

keyboard.data

---@class CatnipKeyboard
...
---@field data table (readonly)
...

A table for users to attach custom data to the keyboard.

The table contents are never touched by catnip itself and completely defined by the user.

This field is readonly in the sense that users are not allowed to reassign data itself (for example, keyboard.data = 34). This is to ensure consistency in case external libraries, plugins, etc are expecting this field to be a table.

keyboard.name

---@class CatnipKeyboard
...
---@field name string (readonly)
...

The name of the keyboard.

keyboard.xkb_rules

---@class CatnipKeyboard
...
---@field xkb_rules string
...

The xkbcommon rules for the current keymap.

keyboard.xkb_model

---@class CatnipKeyboard
...
---@field xkb_model string
...

The xkbcommon model for the current keymap.

keyboard.xkb_layout

---@class CatnipKeyboard
...
---@field xkb_layout string
...

The xkbcommon layout for the current keymap.

keyboard.xkb_variant

---@class CatnipKeyboard
...
---@field xkb_variant string
...

The xkbcommon variant for the current keymap.

keyboard.xkb_options

---@class CatnipKeyboard
...
---@field xkb_options string
...

The xkbcommon options for the current keymap.

keyboard:subscribe(event, callback)

Similar to catnip.subscribe(event, callback) but for events published on the keyboard itself.

keyboard:unsubscribe(event, callback)

Similar to catnip.unsubscribe(event, callback) but for events published on the keyboard itself.

keyboard:publish(event, ...)

Publishes a keyboard event.

This publishes a local event where callbacks registered via keyboard:subscribe(event, callback) are run.

This also publishes a global event via catnip.publish(event, ...), where the event is prefixed w/ keyboard:: and the keyboard itself is provided as the first argument to the callback, followed by the given varargs.

local catnip = require('catnip')

-- local event
my_keyboard:subscribe('greet', function(name)
    print('hello ' .. name)
end)

-- global event
catnip.subscribe('keyboard::greet', function(keyboard, name)
    print(keyboard.id .. 'says: hello ' .. name)
end)

my_keyboard:publish('greet', 'world')

Events

Keyboard events are published both as local events and global events.

When published as a global event, events are prefixed w/ keyboard:: and the keyboard is passed as the first argument to the callback.

local catnip = require('catnip')

-- local event
my_keyboard:subscribe('destroy', function()
    print('destroy ' .. my_keyboard.id)
end)

-- global event
catnip.subscribe('keyboard::destroy', function(keyboard)
    print('destroy ' .. keyboard.id)
end)

create

Published when a new keyboard has been created (connected). This is also published after (re)loading the user config for any existing keyboards.

destroy

Published when a keyboard has been destroyed (disconnected).

keypress

---@param event CatnipKeyEvent

---@class (exact) CatnipKeyEvent
---(readonly) The [xkbcommon keysym](https://xkbcommon.org/doc/current/group__keysyms.html#ga79e604a22703391bdfe212cfc10ea007).
---@field code number
---(readonly) An [xkbcommon key name](https://xkbcommon.org/doc/current/xkbcommon-keysyms_8h.html) with the `XKB_KEY_` prefix stripped.
---@field name string
---(readonly) A [UTF-8](https://en.wikipedia.org/wiki/UTF-8) string representation of the key.
---@field utf8 string
---(readonly) Whether the shift modifier is active.
---@field shift boolean
---(readonly) Whether the control modifier is active.
---@field ctrl boolean
---(readonly) Whether the mod1 modifier is active.
---@field mod1 boolean
---(readonly) Whether the mod2 modifier is active.
---@field mod2 boolean
---(readonly) Whether the mod3 modifier is active.
---@field mod3 boolean
---(readonly) Whether the mod4 modifier is active.
---@field mod4 boolean
---(readonly) Whether the mod5 modifier is active.
---@field mod5 boolean
---Controls whether to notify the currently focused window about this key event.
---@field prevent_notify boolean

Published whenever a key on the keyboard is pressed.

keyrelease

---@param event CatnipKeyEvent

---@class (exact) CatnipKeyEvent
---(readonly) The [xkbcommon keysym](https://xkbcommon.org/doc/current/group__keysyms.html#ga79e604a22703391bdfe212cfc10ea007).
---@field code number
---(readonly) An [xkbcommon key name](https://xkbcommon.org/doc/current/xkbcommon-keysyms_8h.html) with the `XKB_KEY_` prefix stripped.
---@field name string
---(readonly) A [UTF-8](https://en.wikipedia.org/wiki/UTF-8) string representation of the key.
---@field utf8 string
---(readonly) Whether the shift modifier is active.
---@field shift boolean
---(readonly) Whether the control modifier is active.
---@field ctrl boolean
---(readonly) Whether the mod1 modifier is active.
---@field mod1 boolean
---(readonly) Whether the mod2 modifier is active.
---@field mod2 boolean
---(readonly) Whether the mod3 modifier is active.
---@field mod3 boolean
---(readonly) Whether the mod4 modifier is active.
---@field mod4 boolean
---(readonly) Whether the mod5 modifier is active.
---@field mod5 boolean
---Controls whether to notify the currently focused window about this key event.
---@field prevent_notify boolean

Published whenever a key on the keyboard is released.