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")

Keycodes for every key.

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

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

Parameters

mods - The modifiers that need to be held down for the bind to trigger
  ┃ pinnacle.input.Mod[]

key - The key used to trigger the bind
  ┃ pinnacle.input.Key | string

on_press - The function to run when the bind is triggered
  ┃ fun()

bind_info - An optional group and description that is displayed in the bind overlay.
  ┃ { 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

 -- 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 - The modifiers that need to be held down for the bind to trigger
  ┃ pinnacle.input.Mod[]

button - The mouse button used to trigger the bind
  ┃ pinnacle.input.MouseButton

on_press - The function to run when the bind is triggered
  ┃ fun()

bind_info - An optional group and description that will be displayed in the bind overlay.
  ┃ { 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 - The bind 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

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

Parameters

xkb_config - The new xkbconfig
  ┃ pinnacle.input.XkbConfig

function set_repeat_rate

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

Sets the keyboard's repeat rate and delay.

Example

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

Parameters

rate - The time between repeats in milliseconds
  ┃ integer

delay - The duration a key needs to be held down before repeating starts in milliseconds
  ┃ integer

function set_xkb_keymap

function pinnacle.input.set_xkb_keymap(keymap: string)

Sets the XKB keymap.

Examples

Input.set_xkb_keymap("keymap here...")

-- From a file
Input.set_xkb_keymap(io.open("/path/to/keymap.xkb"):read("*a"))

Parameters

keymap - The keymap to set.
  ┃ string

function cycle_xkb_layout_forward

function pinnacle.input.cycle_xkb_layout_forward()

Cycles the current XKB layout forward.

function cycle_xkb_layout_backward

function pinnacle.input.cycle_xkb_layout_backward()

Cycles the current XKB layout backward.

function switch_xkb_layout

function pinnacle.input.switch_xkb_layout(index: integer)

Switches the current XKB layout to the one at the provided index.

Fails if the index is out of bounds.

Parameters

index - The index of the layout to switch to.
  ┃ integer

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 - The name of the xcursor 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 - The new size of the cursor.
  ┃ 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

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

Parameters

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

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

• pinnacle.signal.SignalHandles.disconnect_all: - To disconnect from these signals