Lua Reference

Appearance

Class 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

Functions ​

method close ​

function WindowHandle:close()

Send a close request to this window.

Example ​

lua
local focused = Window.get_focused()
if focused then focused:close() end

method set_geometry ​

function WindowHandle:set_geometry(geo: { x: integer, y: integer, width: integer, height: integer })

Set 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: { x: integer, y: integer, width: integer, height: integer } - The new location and/or size

method set_fullscreen ​

function WindowHandle:set_fullscreen(fullscreen: boolean)

Set this window to fullscreen or not.

Example ​

lua
local focused = Window.get_focused()
if focused then
    focused:set_fullscreen(true)
    focused:set_fullscreen(false)
end

Parameters ​

fullscreen: boolean

method toggle_fullscreen ​

function WindowHandle:toggle_fullscreen()

Toggle this window to and from fullscreen.

Example ​

lua
local focused = Window.get_focused()
if focused then
    focused:toggle_fullscreen()
end

method set_maximized ​

function WindowHandle:set_maximized(maximized: boolean)

Set this window to maximized or not.

Example ​

lua
local focused = Window.get_focused()
if focused then
    focused:set_maximized(true)
    focused:set_maximized(false)
end

Parameters ​

maximized: boolean

method toggle_maximized ​

function WindowHandle:toggle_maximized()

Toggle this window to and from maximized.

Example ​

lua
local focused = Window.get_focused()
if focused then
    focused:toggle_maximized()
end

method set_floating ​

function WindowHandle:set_floating(floating: boolean)

Set this window to floating or not.

Example ​

lua
local focused = Window.get_focused()
if focused then
    focused:set_floating(true)
    focused:set_floating(false)
end

Parameters ​

floating: boolean

method toggle_floating ​

function WindowHandle:toggle_floating()

Toggle this window to and from floating.

Example ​

lua
local focused = Window.get_focused()
if focused then
    focused:toggle_floating()
end

method set_focused ​

function WindowHandle:set_focused(focused: boolean)

Focus or unfocus this window.

Example ​

lua
local focused = Window.get_focused()
if focused then
    focused:set_focused(false)
end

Parameters ​

focused: boolean

method toggle_focused ​

function WindowHandle:toggle_focused()

Toggle this window to and from focused.

Example ​

lua
local focused = Window.get_focused()
if focused then
    focused:toggle_focused()
end

method move_to_tag ​

function WindowHandle:move_to_tag(tag: TagHandle)

Move this window to the specified tag.

This will remove all tags from this window and tag it with tag.

Example ​

lua
 -- Assume the focused output has the tag "Tag"
local focused = Window.get_focused()
if focused then
    focused:move_to_tag(Tag.get("Tag"))
end

Parameters ​

tag: TagHandle - The tag to move this window to

method set_tag ​

function WindowHandle:set_tag(tag: TagHandle, set: boolean)

Tag or untag the given tag on this window.

Example ​

lua
 -- Assume the focused output has the tag "Tag"
local focused = Window.get_focused()
if focused then
    local tag = Tag.get("Tag")

    focused:set_tag(tag, true)
    -- `focused` now has tag "Tag"
    focused:set_tag(tag, false)
    -- `focused` no longer has tag "Tag"
end

Parameters ​

tag: TagHandle - The tag to set or unset
set: boolean

method toggle_tag ​

function WindowHandle:toggle_tag(tag: TagHandle)

Toggle the given tag on this window.

Example ​

lua
 -- Assume the focused output has the tag "Tag"
local focused = Window.get_focused()
if focused then
    local tag = Tag.get("Tag")
    focused:set_tag(tag, false)

    focused:toggle_tag(tag)
    -- `focused` now has tag "Tag"
    focused:toggle_tag(tag)
    -- `focused` no longer has tag "Tag"
end

Parameters ​

tag: TagHandle - The tag to toggle

method raise ​

function WindowHandle:raise()

Raise a window.

This will raise a window all the way to the top of the z-stack.

Example ​

lua
local focused = Window.get_focused()
if focused then
    focused:raise()
end

method is_on_active_tag ​

function WindowHandle:is_on_active_tag()
    -> boolean

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

Returns ​

  1. boolean

method props ​

function WindowHandle:props()
    -> WindowProperties

Get all the properties of this window.

Returns ​

  1. WindowProperties

method geometry ​

function WindowHandle:geometry()
    -> { x: integer, y: integer, width: integer, height: integer }

Get this window's location and size.

Shorthand for handle:props().geometry.

Returns ​

  1. { x: integer, y: integer, width: integer, height: integer }

method class ​

function WindowHandle:class()
    -> string

Get this window's class.

Shorthand for handle:props().class.

Returns ​

  1. string

method title ​

function WindowHandle:title()
    -> string

Get this window's title.

Shorthand for handle:props().title.

Returns ​

  1. string

method focused ​

function WindowHandle:focused()
    -> boolean

Get whether or not this window is focused.

Shorthand for handle:props().focused.

Returns ​

  1. boolean

method floating ​

function WindowHandle:floating()
    -> boolean

Get whether or not this window is floating.

Shorthand for handle:props().floating.

Returns ​

  1. boolean

method tiled ​

function WindowHandle:tiled()
    -> boolean

Get whether this window is tiled.

Returns ​

  1. boolean

method fullscreen ​

function WindowHandle:fullscreen()
    -> boolean

Get whether this window is fullscreen.

Returns ​

  1. boolean

method maximized ​

function WindowHandle:maximized()
    -> boolean

Get whether this window is maximized.

Returns ​

  1. boolean

method fullscreen_or_maximized ​

function WindowHandle:fullscreen_or_maximized()
    -> FullscreenOrMaximized

Deprecated; use the fullscreen or maximized methods instead.

Get whether this window is fullscreen, maximized, or neither.

Shorthand for handle:props().fullscreen_or_maximized.

Returns ​

  1. FullscreenOrMaximized

method tags ​

function WindowHandle:tags()
    -> TagHandle[]

Get all tags on this window.

Shorthand for handle:props().tags.

Returns ​

  1. TagHandle[]