Lua Reference

Appearance

Class pinnacle.window ​

Window management.

This module helps you deal with setting windows to fullscreen and maximized, setting their size, moving them between tags, and various other actions.

Functions ​

function get_all ​

function pinnacle.window.get_all()
    -> windows: pinnacle.window.WindowHandle[]

Gets all windows.

Returns ​

  1. windows: pinnacle.window.WindowHandle[] - Handles to all windows

function get_focused ​

function pinnacle.window.get_focused()
    -> window: pinnacle.window.WindowHandle | nil

Gets the currently focused window.

Returns ​

  1. window: pinnacle.window.WindowHandle | nil - A handle to the currently focused window

function begin_move ​

function pinnacle.window.begin_move(button: pinnacle.input.MouseButton)

Begins moving this window using the specified mouse button.

The button must be pressed at the time this method is called. If the button is lifted, the move will end.

Example ​

lua
Input.mousebind({ "super" }, "btn_left", function()
    Window.begin_move("btn_left")
end)

Parameters ​

button: pinnacle.input.MouseButton - The button that will initiate the move

function begin_resize ​

function pinnacle.window.begin_resize(button: pinnacle.input.MouseButton)

Begins resizing this window using the specified mouse button.

The button must be pressed at the time this method is called. If the button is lifted, the resize will end.

Example ​

lua
Input.mousebind({ "super" }, "btn_right", function()
    Window.begin_resize("btn_right")
end)

Parameters ​

button: pinnacle.input.MouseButton - The button that will initiate the resize

function connect_signal ​

function pinnacle.window.connect_signal(signals: pinnacle.window.WindowSignal)
    -> signal_handles: pinnacle.signal.SignalHandles

Connects to a window 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
Window.connect_signal({
    pointer_enter = function(window)
        print("Pointer entered", window:app_id())
    end
})

Parameters ​

signals: pinnacle.window.WindowSignal - 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 ​

function add_window_rule ​

function pinnacle.window.add_window_rule(rule: fun(window: pinnacle.window.WindowHandle))

Adds a window rule.

Instead of using a declarative window rule system with match conditions, you supply a closure that acts on a newly opened window. You can use standard if statements and apply properties using the same methods that are used everywhere else in this API.

Note: this function is special in that if it is called, Pinnacle will wait for the provided closure to finish running before it sends windows an initial configure event. Do not block here. At best, short blocks will increase the time it takes for a window to open. At worst, a complete deadlock will prevent windows from opening at all.

Example ​

lua
Window.add_window_rule(function(window)
    if window:app_id() == "Alacritty" then
        window:set_tag(Tag.get("Terminal"), true)
    end
end)

Parameters ​

rule: fun(window: pinnacle.window.WindowHandle)