Lua Reference

Appearance

Class pinnacle.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 pinnacle.input.keybind(mods: pinnacle.input.Mod[], key: pinnacle.input.Key | string, on_press: fun(), bind_info?: { group: string, description: string })

Sets a keybind.

This function can be called in two ways:

  1. As Input.keybind(mods, key, on_press, bind_info?)
  2. As Input.keybind(<Keybind table>)

Calling this with a Keybind table gives you more options, including the ability to assign a bind layer to the keybind or set it to happen on release instead of press.

When calling using the first way, 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.
  • on_press: 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.

Similar principles apply when calling with a Keybind table.

Ignoring Modifiers ​

Normally, modifiers that are not specified will require the bind to not have them held down. You can ignore this by adding the corresponding "ignore_*" modifier.

Descriptions ​

You can specify a group and description for the bind. This will be used to categorize the bind in the bind overlay and provide a description.

Example ​

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

Parameters ​

mods: pinnacle.input.Mod[] - The modifiers that need to be held down for the bind to trigger
key: pinnacle.input.Key | string - The key used to trigger the bind
on_press: fun() - The function to run when the bind is triggered
bind_info?: { group: string, description: string }

function mousebind ​

function pinnacle.input.mousebind(mods: pinnacle.input.Mod[], button: pinnacle.input.MouseButton, on_press: fun(), bind_info?: { group: string, description: string })

Sets a mousebind.

This function can be called in two ways:

  1. As Input.mousebind(mods, button, on_press, bind_info?)
  2. As Input.mousebind(<Mousebind table>)

Calling this with a Mousebind table gives you more options, including the ability to assign a bind layer to the keybind or set it to happen on release instead of press.

When calling using the first way, you must provide three arguments:

  • mods: An array of Modifiers. If you don't want any, provide an empty table.
  • button: The mouse button.
  • on_press: The function that will be run when the button is pressed.

Ignoring Modifiers ​

Normally, modifiers that are not specified will require the bind to not have them held down. You can ignore this by adding the corresponding "ignore_*" modifier.

Descriptions ​

You can specify a group and description for the bind. This will be used to categorize the bind in the bind overlay and provide a description.

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: pinnacle.input.Mod[] - The modifiers that need to be held down for the bind to trigger
button: pinnacle.input.MouseButton - The mouse button used to trigger the bind
on_press: fun() - The function to run when the bind is triggered
bind_info?: { group: string, description: string }

function enter_bind_layer ​

function pinnacle.input.enter_bind_layer(layer?: string)

Enters the bind layer layer, or the default layer if layer is nil.

Parameters ​

layer?: string

function bind_infos ​

function pinnacle.input.bind_infos()
    -> pinnacle.input.BindInfo[]

Gets all binds and their information.

Returns ​

  1. pinnacle.input.BindInfo[]

function set_xkb_config ​

function pinnacle.input.set_xkb_config(xkb_config: pinnacle.input.XkbConfig)

Sets the xkbconfig for your keyboard.

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: pinnacle.input.XkbConfig - The new xkbconfig

function set_repeat_rate ​

function pinnacle.input.set_repeat_rate(rate: integer, delay: integer)

Sets 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_xcursor_theme ​

function pinnacle.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 pinnacle.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

function connect_signal ​

function pinnacle.input.connect_signal(signals: pinnacle.input.InputSignal)
    -> signal_handles: pinnacle.signal.SignalHandles

Connects to an input signal.

signals is a table containing the signal(s) you want to connect to along with a corresponding callback that will be called when the signal is signalled.

This function returns a table of signal handles with each handle stored at the same key used to connect to the signal. See SignalHandles for more information.

Example ​

lua
Input.connect_signal({
    device_added = function(device)
        print("Device connected", device:name())
    end
})

Parameters ​

signals: pinnacle.input.InputSignal - The signal you want to connect to

Returns ​

  1. signal_handles: pinnacle.signal.SignalHandles - Handles to every signal you connected to wrapped in a table, with keys being the same as the connected signal.

See also ​