Devilspie2's lua type annotation

types.d.lua

---@meta devilspie2

-- SPDX-License-Identifier: 0BSD

-- If index = 0 then the ‘current’ monitor (with the window's centre point)
-- is used (falling back on then the first monitor showing part of the
-- window then the first monitor).
--
-- If index = -1 then all monitors are treated as one large virtual monitor.
--
-- If index is out of range then the first monitor is used.
---@alias MonitorIndex -1|integer

---@alias WindowType "WINDOW_TYPE_NORMAL"
---| "WINDOW_TYPE_DESKTOP"
---| "WINDOW_TYPE_DOCK"
---| "WINDOW_TYPE_DIALOG"
---| "WINDOW_TYPE_TOOLBAR"
---| "WINDOW_TYPE_MENU"
---| "WINDOW_TYPE_UTILITY"
---| "WINDOW_TYPE_SPLASHSCREEN"
---| "WINDOW_TYPE_UNRECOGNIZED"
---| "WINDOW_ERROR"

---@alias NET_WM_WINDOW_TYPE "_NET_WM_WINDOW_TYPE_NORMAL"
---| "_NET_WM_WINDOW_TYPE_DESKTOP"
---| "_NET_WM_WINDOW_TYPE_DOCK"
---| "_NET_WM_WINDOW_TYPE_TOOLBAR"
---| "_NET_WM_WINDOW_TYPE_MENU"
---| "_NET_WM_WINDOW_TYPE_UTILITY"
---| "_NET_WM_WINDOW_TYPE_SPLASH"
---| "_NET_WM_WINDOW_TYPE_DIALOG"

-- If direction begins with 'H', the window is horizontally centred *only*.
---@alias Horizontal "H"|"h"

-- If direction begins with 'V', the window is vertically centred *only*.
---@alias Vertical "V"|"v"

---@alias AlignAxis ""|Horizontal|Vertical

-- returns a string containing the name of the current window.
---@return string name window name from `wnck_window_get_name()`
function get_window_name() end

-- (Available from v0.20)
--
-- return true or false depending on if the window has a name or not
---@return boolean exists true if window has a name
function get_window_has_name() end

-- Set the position of a window.
--
-- If index is specified then the co-ordinates are relative to a corner of
-- the specified monitor (counting from 1) on the current workspace. Which
-- corner is determined by the co-ordinates' signs:
--    +ve X ⇒ left, -ve X ⇒ right;
--    +ve Y ⇒ top,  -ve Y ⇒ bottom.
--
-- NOTE: since -0 would have a use here but is equal to +0, ~ (bitwise NOT)
-- is used. To put the window 60px from the right or bottom, use ~60 or -61.
--
-- If index = 0 then the ‘current’ monitor (with the window's centre point)
-- is used (falling back on then the first monitor showing part of the
-- window then the first monitor).
--
-- If index = -1 then all monitors are treated as one large virtual monitor.
---@see set_window_position2
---@param x integer
---@param y integer
---@param index? MonitorIndex
---@return boolean success true if the window was moved
function set_window_position(x, y, index) end

-- (Available from v0.21)
--
-- Set the position of a window - Compared to set_window_position, this
-- function uses XMoveWindow instead of wnck_window_set_geometry which
-- gives a slightly different result.
---@see set_window_position
---@param x integer
---@param y integer
function set_window_position2(x, y) end

-- Sets the size of a window
---@param width integer
---@param height integer
function set_window_size(width, height) end

-- (Available from v0.32)
--
-- Set the reserved area at the borders of the desktop for a docking area such
-- as a taskbar or a panel.
---@param left integer
---@param right integer
---@param top integer
---@param bottom integer
function set_window_strut(left, right, top, bottom) end

-- Sets both size and position of a window in one command.
---@see set_window_geometry2
---@param x integer
---@param y integer
---@param width integer
---@param height integer
function set_window_geometry(x, y, width, height) end

-- (Available from v0.21)
--
-- Sets the window geometry just as set_window_geometry, using
-- `XMoveResizeWindow` instead of its libwnck alternative. This results in
-- different coordinates than the set_window_geometry function, and results
-- are more similar to the results of the original devilspie geometry function.
---@see set_window_geometry
---@param x integer
---@param y integer
---@param width integer
---@param height integer
function set_window_geometry2(x, y, width, height) end

-- returns the application name of the current window.
---@return string name application name from `wnck_application_get_name()`
function get_application_name() end

-- Debug helper that prints a string to stdout. The string is only printed to
-- stdout if devilspie2 is run with the `--debug` option, otherwise nothing will
-- be printed.
---@param ... any
function debug_print(...) end

-- "Shades" a window, showing only the title-bar.
---@see unshade
function shade() end

-- Unshades a window - the opposite of "shade"
---@see shade
function unshade() end

-- (-ise available from v0.45)
--
-- maximises a window
function maximize() end
maximise = maximize

-- (-ise available from 0.45)
--
-- maximises the current window horizontally.
function maximize_horizontally() end
maximise_horizontally = maximize_horizontally

-- (-ise available from v0.45)
--
-- maximises the current window vertically.
function maximize_vertically() end
maximise_vertically = maximize_vertically

-- (-ise available from v0.45)
--
-- unmaximises a window
function unmaximize() end
unmaximise = unmaximize

-- (-ise available from v0.45)
--
-- minimises a window
function minimize() end
minimise = minimize

-- (-ise available from v0.45)
--
-- unminimises a window, that is bringing it back to screen from the
-- minimised position/size.
function unminimize() end
unminimise = unminimize

-- Shows all window decoration.
---@see undecorate_window
---@return boolean result
function decorate_window() end

-- Removes all window decorations.
---@see decorate_window
---@return boolean result
function undecorate_window() end

-- Moves a window to another workspace. The number variable starts counting
-- at 1.
---@param number integer
---@return boolean result
function set_window_workspace(number) end

-- Changes the current workspace to another. The number variable starts
-- counting at 1.
---@param number integer
---@return boolean result
function change_workspace(number) end

-- (Available from v0.27)
--
-- Return the number of workspaces available.
---@return integer
function get_workspace_count() end

-- asks the window manager to put the window on all workspaces.
---@see unpin_window
function pin_window() end

-- Asks the window manager to put window only in the currently active workspace.
---@see pin_window
function unpin_window() end

-- Asks the window manager to keep the window's position fixed on the screen,
-- even when the workspace or viewport scrolls.
---@see unstick_window
function stick_window() end

-- Asks the window manager to not have window's position fixed on the screen
-- when the workspace or viewport scrolls.
---@see stick_window
function unstick_window() end

-- (Available from v0.31)
--
-- Closes the window.
function close_window() end

-- (Available from v0.45)
--
-- Allow for situations where moving or resizing the window is done
-- incorrectly, i.e.
-- ```lua
-- set_window_position(0,0)
-- ```
-- results in the window decoration being taken into account twice, i.e.
-- the window (including decoration) is offset from the top left corner by
-- the width of the left side decoration and the height of the title bar.
--
-- This is currently off by default, and is sticky: if you do not explicitly
-- set it in your script, its current value is retained.
--
-- If used, it should be used at the start of the script.
--
-- This affects the following functions:
---@see set_window_geometry
---@see set_window_position
---@see set_window_size
---@see xy
---@see xywh
---@param adjust boolean?
function set_adjust_for_decoration(adjust) end

-- (Available from v0.16)
--
-- Returns the window geometry as four numbers - x-position, y-position,
-- width and height.
-- For example you can do something like this:
-- ```lua
-- x, y, width, height = get_window_geometry()
-- print("X: "..x..", Y: "..y..", width: "..width..", height: "..height)
-- ```
---@return integer x, integer y, integer width, integer height
function get_window_geometry() end

-- (Available from v0.16)
--
-- returns the window geometry excluding the window manager borders as four
-- numbers, x-position, y-position, width and height.
---@see get_window_geometry
---@return integer x, integer y, integer width, integer height
function get_window_client_geometry() end

-- (Available from v0.16)
--
-- Set this to true if you would like the window to skip listing in your
-- tasklist.
---@param skip boolean
function set_skip_tasklist(skip) end

-- (Available from v0.16)
--
-- Set this to true if you would like the window to skip listing in your pager.
---@param skip boolean
function set_skip_pager(skip) end

-- (Available from v0.21)
-- (-ise available from v0.45)
--
-- Returns true if the window is maximised, false otherwise.
---@return boolean state
function get_window_is_maximized() end
get_window_is_maximised = get_window_is_maximized

-- (Available from v0.21)
-- (-ise available from v0.45)
--
-- Returns true if the window is vertically maximised, false otherwise.
---@return boolean state
function get_window_is_maximized_vertically() end
get_window_is_maximised_vertically = get_window_is_maximized_vertically

-- (Available from v0.21)
-- (-ise available from v0.45)
--
-- Returns true if the window is vertically maximised, false otherwise.
---@return boolean state
function get_window_is_maximized_horizontally() end
get_window_is_maximised_horizontally = get_window_is_maximized_horizontally

-- (Available from v0.44)
--
-- Returns true if the window is pinned, false otherwise.
---@return boolean state
function get_window_is_pinned() end

-- (Available from v0.44)
--
-- Returns true if the window is decorated, false otherwise.
---@return boolean state
function get_window_is_decorated() end

-- (Available from v0.21)
--
-- Set the current window below all normal windows.
---@param state boolean? defaults to true
function set_window_below(state) end

-- (Available from v0.21)
--
-- Set the current window above all normal windows.
---@param state boolean? defaults to true
function set_window_above(state) end

-- Same as `set_window_above(true)`
---@see set_window_above
function make_always_on_top()
	set_window_above(true)
end

-- (Available from v0.24)
--
-- Asks the window manager to set the fullscreen state of the window.
---@param state boolean
function set_window_fullscreen(state) end

-- (Available from v0.45)
--
-- Sets a window on top of the others.
-- Unlike `set_window_above`, it doesn't lock the window in this position.
-- As of v0.45, the window's layer (above, between, below) is
-- maintained.
---@see set_window_above
function set_on_top() end

-- (Available from v0.45)
--
-- Sets a window below the others.
-- Unlike `set_window_below`, it doesn't lock the window in this position.
-- As of v0.45, the window's layer (above, between, below) is
-- maintained.
---@see set_window_below
function set_on_bottom() end

-- (Available from v0.21)
--
-- Returns the type of the window.
---@return WindowType
function get_window_type() end

-- (Available from v0.21)
--
-- Returns the window property described in the property string. For a list of
-- available properties, you should see the page
-- <https://standards.freedesktop.org/wm-spec/wm-spec-latest.html>
---@param property string
---@return string result
function get_window_property(property) end

-- Returns a string describing the current window role of the matched window as
-- defined by it's WM_WINDOW_ROLE hint.
---@return string role
function get_window_role() end

-- Returns the X window id of the current window.
---@return integer xid
function get_window_xid() end

-- Returns a string representing the class of the current window.
---@return string class
function get_window_class() end

-- (Available from v0.44)
--
-- Set a property of a window to a string or a cardinal (32-bit integer or
-- boolean).
---@param property string
---@param value string|integer|boolean
function set_window_property(property, value) end

-- (Available from v0.44)
--
-- Remove a property from a window.
---@param property string
function delete_window_property(property) end

---@overload fun(viewport: integer)
-- (Available from v0.25)
--
-- Moves the window to the requested viewport.
-- Counting starts at number 1.
---@overload fun(x: integer, y: integer)
-- (Available from v0.40)
--
-- If you are using two indata to the set_viewport function, you can decide
-- where in the viewport the window will be placed.
function set_viewport() end

-- (Available without parameters from v0.26)
-- (Parameters and `centre` available from v0.44)
--
-- If centring only along one axis, the window may be moved along the other
-- axis to ensure that it is on the specified monitor.
--
---@param index MonitorIndex defaults to all monitors
---@param direction AlignAxis defaults to both axes
---@overload fun()
-- With no parameters, centres the current window on the current workspace.
-- May place the window across multiple monitors.
function center(index, direction) end
centre = center

-- (Available from v0.28, set_window_opacity from v0.29)
--
-- Sets the window opacity, takes a float value, `1.0` = completely opaque,
-- `0.0`, completely see-through. Both `set_opacity` and `set_window_opacity`
-- will do the same thing.
---@param value number opacity value between `0.0` and `1.0`
function set_opacity(value) end
set_window_opacity = set_opacity

-- (Available from v0.28)
--
-- Sets the window type, according to _NET_WM_WINDOW_TYPE. The allowed types
-- are the standard _NET_WM ones (formatted as a string),
-- or shorter versions of the same values.
---@see NET_WM_WINDOW_TYPE
---@see WindowType
---@type WindowType
---@param type NET_WM_WINDOW_TYPE|WindowType
function set_window_type(type) end

-- (Available from v0.29)
--
-- Returns the screen geometry for the screen of the current window.
---@return integer width, integer height
function get_screen_geometry() end

-- (Available from v0.44)
---@return boolean state
function get_window_fullscreen() end
get_fullscreen = get_window_fullscreen

-- Gets the class instance name from the WM_CLASS Property for the current
-- window. Only available on libwnck 3+, and in devilspie2 version 0.21 or
-- later.
---@return string instance
function get_class_instance_name() end

-- Gets the class group name from the WM_CLASS Property for the current
-- window. Only available on libwnck 3+, and in devilspie2 version 0.45 or
-- later.
---@return string group
function get_class_group_name() end

-- Focus the current window.
function focus() end
focus_window = focus

-- (Available from v0.44)
--
-- Returns the index of the monitor containing the window centre (or some
-- part of the window).
function get_monitor_index() end

-- (Available from v0.44)
--
---@return integer x, integer y, integer width, integer height
function get_monitor_geometry() end

-- Set the position of a window.
---@param x integer
---@param y integer
---@overload fun(): x: integer, y: integer
-- if you don't give any input, get the position of a window
function xy(x, y) end
-- Set the position and size of a window
---@param x integer
---@param y integer
---@param width integer
---@param height integer
---@overload fun(): x: integer, y: integer, width: integer, height: integer
-- if you don't give any input, get the position and size of a window.
function xywh(x, y, width, height) end

---@param callback fun()
function on_geometry_changed(callback) end

-- (Available from v0.44)
--
-- Returns the name of the process owning the current window.
--
-- On (at least) Linux, the process name is read from `/proc/<pid>/comm`. If
-- that's not possible, `ps` is launched in a shell. For this reason, you
-- should avoid calling `get_process_name()` more than necessary.
--
-- WARN: This function is not compatible with busybox ps.
function get_process_name() end

-- If there is a file named devilspie2.lua in config folder, it is read and
-- it is searched for a global variable named either `scripts_window_close`,
-- `scripts_window_focus` or `scripts_window_blur`.
--
-- The filenames in the strings in this table will be called when windows are
-- closed, focused or blurred respectively. If these variables isn't present in
-- this file, it will be called as a devilspie2 script file like any other.
--
-- For example:
-- ```lua
-- scripts_window_close = {
--    "file1.lua",
--    "file2.lua"
-- }
-- ```
-- This would make the files file1.lua and file2.lua interpreted when windows are
-- closing instead of when windows are opening.
---@alias CallbackScripts string[]

---@type CallbackScripts
scripts_window_close = {}

---@type CallbackScripts
scripts_window_focus = {}

---@type CallbackScripts
scripts_window_blur = {}