Lua Reference

Appearance

Class Input ​

Input management.

This module provides utilities to set key- and mousebinds as well as change keyboard settings.

Fields ​

mouse_button_values ​

mouse_button_values: table

key ​

key = require("pinnacle.input.keys")

Functions ​

function keybind ​

function Input.keybind(mods: Modifier[], key: Key | string, action: fun(), keybind_info?: KeybindInfo)

Set a keybind. If called with an already existing keybind, it gets replaced.

You must provide three arguments:

  • mods: An array of Modifiers. If you don't want any, provide an empty table.
  • key: The key that will trigger action. You can provide three types of key:
    • Something from the Key table in Input.key, which lists every xkbcommon key. The naming pattern is the xkbcommon key without the KEY_ prefix, unless that would make it start with a number or the reserved lua keyword function, in which case the KEY_ prefix is included.
    • A single character representing your key. This can be something like "g", "$", "~", "1", and so on.
    • A string of the key's name. This is the name of the xkbcommon key without the KEY_ prefix.
  • action: The function that will be run when the keybind is pressed.

It is important to note that "a" is different than "A". Similarly, key.a is different than key.A. Usually, it's best to use the non-modified key to prevent confusion and unintended behavior.

lua
Input.keybind({ "shift" }, "a", function() end) -- This is preferred
Input.keybind({ "shift" }, "A", function() end) -- over this

 -- This keybind will only work with capslock on.
Input.keybind({}, "A", function() end)

 -- This keybind won't work at all because to get `@` you need to hold shift,
 -- which this keybind doesn't accept.
Input.keybind({ "ctrl" }, "@", function() end)

Example ​

lua
 -- Set `super + Return` to open Alacritty
Input.keybind({ "super" }, Input.key.Return, function()
    Process.spawn("alacritty")
end)

Parameters ​

mods: Modifier[] - The modifiers that need to be held down for the bind to trigger
key: Key | string - The key used to trigger the bind
action: fun() - The function to run when the bind is triggered
keybind_info?: KeybindInfo

function mousebind ​

function Input.mousebind(mods: Modifier[], button: MouseButton, edge: MouseEdge, action: fun())

Set a mousebind. If called with an already existing mousebind, it gets replaced.

You must specify whether the keybind happens on button press or button release.

Example ​

lua
 -- Set `super + left mouse button` to move a window on press
Input.mousebind({ "super" }, "btn_left", "press", function()
    Window.begin_move("btn_left")
end)

Parameters ​

mods: Modifier[] - The modifiers that need to be held down for the bind to trigger
button: MouseButton - The mouse button used to trigger the bind
edge: MouseEdge - "press" or "release" to trigger on button press or release
action: fun() - The function to run when the bind is triggered

function keybind_descriptions ​

function Input.keybind_descriptions()
    -> KeybindDescription[]

Get all keybinds along with their descriptions

Returns ​

  1. KeybindDescription[]

function set_xkb_config ​

function Input.set_xkb_config(xkb_config: XkbConfig)

Set the xkbconfig for your keyboard.

Fields not present will be set to their default values.

Read xkeyboard-config(7) for more information.

Example ​

lua
Input.set_xkb_config({
    layout = "us,fr,ge",
    options = "ctrl:swapcaps,caps:shift"
})

Parameters ​

xkb_config: XkbConfig - The new xkbconfig

function set_repeat_rate ​

function Input.set_repeat_rate(rate: integer, delay: integer)

Set the keyboard's repeat rate and delay.

Example ​

lua
Input.set_repeat_rate(100, 1000) -- Key must be held down for 1 second, then repeats 10 times per second.

Parameters ​

rate: integer - The time between repeats in milliseconds
delay: integer - The duration a key needs to be held down before repeating starts in milliseconds

function set_libinput_settings ​

function Input.set_libinput_settings(settings: LibinputSettings)

Set a libinput setting.

This includes settings for pointer devices, like acceleration profiles, natural scroll, and more.

Example ​

lua
Input.set_libinput_settings({
    accel_profile = "flat",
    natural_scroll = true,
})

Parameters ​

settings: LibinputSettings

function set_xcursor_theme ​

function Input.set_xcursor_theme(theme: string)

Sets the current xcursor theme.

Pinnacle reads $XCURSOR_THEME on startup to set the theme. This allows you to set it at runtime.

Parameters ​

theme: string

function set_xcursor_size ​

function Input.set_xcursor_size(size: integer)

Sets the current xcursor size.

Pinnacle reads $XCURSOR_SIZE on startup to set the cursor size. This allows you to set it at runtime.

Parameters ​

size: integer