Lua Reference

Appearance

Class pinnacle.window.WindowHandle ​

A window handle.

This is a handle to an application window that allows manipulation of the window.

If the window is destroyed, the handle will become invalid and may not do what you want it to.

You can retrieve window handles through the various get functions in the Window module.

Fields ​

id ​

id: integer

The unique id of this window.

Functions ​

method close ​

function pinnacle.window.WindowHandle:close()

Sends a close request to this window.

method set_geometry ​

function pinnacle.window.WindowHandle:set_geometry(geo: { x?: integer, y?: integer, width?: integer, height?: integer })

Sets this window's location and/or size.

The coordinate system has the following axes:

       ^ -y
       |
 -x <--+--> +x
       |
       v +y

Tiled windows will not reflect these changes. This method only applies to this window's floating geometry.

Example ​

lua
local focused = Window.get_focused()
if focused then
    focused:set_floating(true)                     -- `set_geometry` only applies to floating geometry.

    focused:set_geometry({ x = 50, y = 300 })      -- Move this window to (50, 300)
    focused:set_geometry({ y = 0, height = 1080 }) -- Move this window to y = 0 and make its height 1080 pixels
    focused:set_geometry({})                       -- Do nothing useful
end

Parameters ​

geo - The new location and/or size
  ┃ { x?: integer, y?: integer, width?: integer, height?: integer }

method resize_tile ​

function pinnacle.window.WindowHandle:resize_tile(dimensions: { left?: integer, right?: integer, top?: integer, bottom?: integer })

If this window is tiled, resizes its tile by shifting the left, right, top, and bottom edges by the provided pixel amounts.

Positive amounts shift edges right/down, while negative amounts shift edges left/up.

If this resizes the tile in a direction that it can no longer resize towards (e.g. it's at the edge of the screen), it will resize in the opposite direction.

Example ​

lua
-- Grow the focused tiled window 10 pixels leftward
Window.get_focused():resize_tile({ left = -10 })

-- Shrink the focused tiled window 10 pixels inward from the right
Window.get_focused():resize_tile({ right = -10 })

-- Grow the focused tiled window 20 pixels centered vertically
Window.get_focused():resize_tile({ top = -10, bottom = 10 })

Parameters ​

dimensions
  ┃ { left?: integer, right?: integer, top?: integer, bottom?: integer }

method set_fullscreen ​

function pinnacle.window.WindowHandle:set_fullscreen(fullscreen: boolean)

Sets this window to fullscreen or not.

Parameters ​

fullscreen
  ┃ boolean

method toggle_fullscreen ​

function pinnacle.window.WindowHandle:toggle_fullscreen()

Toggles this window to and from fullscreen.

method set_maximized ​

function pinnacle.window.WindowHandle:set_maximized(maximized: boolean)

Sets this window to maximized or not.

Parameters ​

maximized
  ┃ boolean

method toggle_maximized ​

function pinnacle.window.WindowHandle:toggle_maximized()

Toggles this window to and from maximized.

method set_floating ​

function pinnacle.window.WindowHandle:set_floating(floating: boolean)

Sets this window to floating or not.

Parameters ​

floating
  ┃ boolean

method toggle_floating ​

function pinnacle.window.WindowHandle:toggle_floating()

Toggles this window to and from floating.

method set_focused ​

function pinnacle.window.WindowHandle:set_focused(focused: boolean)

Focuses or unfocuses this window.

Parameters ​

focused
  ┃ boolean

method toggle_focused ​

function pinnacle.window.WindowHandle:toggle_focused()

Toggles this window to and from focused.

method set_decoration_mode ​

function pinnacle.window.WindowHandle:set_decoration_mode(mode: "client_side" | "server_side")

Sets this window's decoration mode.

If not set, the client is allowed to choose its decoration mode, defaulting to client-side if it doesn't.

Parameters ​

mode - "client_side" to enable CSD, or "server_side" to enable CSD.
  ┃ "client_side" | "server_side"

method move_to_output ​

function pinnacle.window.WindowHandle:move_to_output(output: pinnacle.output.OutputHandle)

Moves this window to the specified output.

This will set the window tags to the output tags, and update the window position.

Parameters ​

output - The output to move this window to.
  ┃ pinnacle.output.OutputHandle

method move_to_tag ​

function pinnacle.window.WindowHandle:move_to_tag(tag: pinnacle.tag.TagHandle)

Moves this window to the specified tag.

This will remove all tags from this window and add the tag tag.

Parameters ​

tag - The tag to move this window to
  ┃ pinnacle.tag.TagHandle

method set_tag ​

function pinnacle.window.WindowHandle:set_tag(tag: pinnacle.tag.TagHandle, set: boolean)

Adds or removes the given tag to or from this window.

Parameters ​

tag - The tag to set or unset
  ┃ pinnacle.tag.TagHandle

set
  ┃ boolean

method toggle_tag ​

function pinnacle.window.WindowHandle:toggle_tag(tag: pinnacle.tag.TagHandle)

Toggles the given tag on this window.

Parameters ​

tag - The tag to toggle
  ┃ pinnacle.tag.TagHandle

method set_tags ​

function pinnacle.window.WindowHandle:set_tags(tags: pinnacle.tag.TagHandle[])

Sets the exact provided tags on this window.

Passing in an empty table will not change the window's tags.

Example ​

lua
-- Sets the focused window's tags to "1" and "3", removing all others
Window.get_focused():set_tags({ Tag.get("1"), Tag.get("2") })

Parameters ​

tags - The tags to set
  ┃ pinnacle.tag.TagHandle[]

method set_vrr_demand ​

function pinnacle.window.WindowHandle:set_vrr_demand(vrr_demand?: "visible" | "fullscreen")

Sets this window's vrr demand.

This works in conjunction with an output with an on-demand vrr state.

Parameters ​

vrr_demand? - The vrr demand, or nil to have none.
  ┃ "visible" - Turns vrr on on an on-demand vrr output when a window is visible.
  ┃ "fullscreen" - Turns vrr on on an on-demand vrr output when a window is both visible and fullscreen.

method raise ​

function pinnacle.window.WindowHandle:raise()

Raises a window.

This will bring the window to the front.

method lower ​

function pinnacle.window.WindowHandle:lower()

Lowers a window.

This will bring the window to the back.

method is_on_active_tag ​

function pinnacle.window.WindowHandle:is_on_active_tag()
    -> boolean

Returns whether or not this window is on an active tag.

Returns ​

  1. boolean

method loc ​

function pinnacle.window.WindowHandle:loc()
    -> { x: integer, y: integer }?

Gets this window's location.

Returns ​

  1. { x: integer, y: integer }

method size ​

function pinnacle.window.WindowHandle:size()
    -> { width: integer, height: integer }?

Gets this window's location.

Returns ​

  1. { width: integer, height: integer }

method app_id ​

function pinnacle.window.WindowHandle:app_id()
    -> string

Gets this window's class.

Returns ​

  1. string

method title ​

function pinnacle.window.WindowHandle:title()
    -> string

Gets this window's title.

Returns ​

  1. string

method focused ​

function pinnacle.window.WindowHandle:focused()
    -> boolean

Gets whether or not this window is focused.

Returns ​

  1. boolean

method output ​

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

Gets this window's output.

This is currently implemented as the output of the first tag on this window.

Returns ​

  1. output: pinnacle.output.OutputHandle | nil - This window's output, or nil if it doesn't exist or it has no tags.

method floating ​

function pinnacle.window.WindowHandle:floating()
    -> boolean

Gets whether or not this window is floating.

Returns ​

  1. boolean

method tiled ​

function pinnacle.window.WindowHandle:tiled()
    -> boolean

Gets whether this window is tiled.

Returns ​

  1. boolean

method spilled ​

function pinnacle.window.WindowHandle:spilled()
    -> boolean

Gets whether this window is spilled from the layout.

A window is spilled when the current layout doesn't contains enough nodes and the compositor cannot assign a geometry to it. In that state, the window behaves as a floating window except that it gets tiled again if the number of nodes become big enough.

Returns ​

  1. boolean

method fullscreen ​

function pinnacle.window.WindowHandle:fullscreen()
    -> boolean

Gets whether this window is fullscreen.

Returns ​

  1. boolean

method maximized ​

function pinnacle.window.WindowHandle:maximized()
    -> boolean

Gets whether this window is maximized.

Returns ​

  1. boolean

method tags ​

function pinnacle.window.WindowHandle:tags()
    -> pinnacle.tag.TagHandle[]

Gets all tags on this window.

Returns ​

  1. pinnacle.tag.TagHandle[]

method in_direction ​

function pinnacle.window.WindowHandle:in_direction(direction: "left" | "right" | "up" | "down")
    -> pinnacle.window.WindowHandle[]

Gets all windows in the provided direction, sorted closest to farthest.

Parameters ​

direction
  ┃ "left" | "right" | "up" | "down"

Returns ​

  1. pinnacle.window.WindowHandle[]

method foreign_toplevel_list_identifier ​

function pinnacle.window.WindowHandle:foreign_toplevel_list_identifier()
    -> identifier: string | nil

Gets this window's ext-foreign-toplevel-list handle identifier.

Returns ​

  1. identifier: string | nil

method swap ​

function pinnacle.window.WindowHandle:swap(target: pinnacle.window.WindowHandle)

Swap position with another window.

Parameters ​

target
  ┃ pinnacle.window.WindowHandle

Last updated: