Miroirs/pinnacle
1
0
Fork 0
mirror of https://github.com/pinnacle-comp/pinnacle.git synced 2025-01-14 08:01:14 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Rename API modules and classes internally

Browse source
This commit is contained in:
Ottatop 2023-10-18 03:44:42 -05:00
parent 5b026b63f1
commit ed5447d5b6
5 changed files with 360 additions and 348 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

258
api/lua/output.lua
View file

@ -7,40 +7,40 @@
---An output is what you would call a monitor. It presents windows, your cursor, and other UI elements. ---An output is what you would call a monitor. It presents windows, your cursor, and other UI elements.
--- ---
---Outputs are uniquely identified by their name, a.k.a. the name of the connector they're plugged in to. ---Outputs are uniquely identified by their name, a.k.a. the name of the connector they're plugged in to.
---@class OutputModule ---@class Output
local output_module = {}
---An output object.
---
---This is a representation of your actual output to the config process.
---It serves to make it easier to deal with your outputs, defining methods for getting properties and
---helpers for things like positioning multiple monitors.
---
---This can be retrieved through that various `get` functions in the `OutputModule`.
---@classmod
---@class Output A display.
---@field private _name string The name of this output (or rather, of its connector).
local output = {} local output = {}
---@param params Output|string ---An output handle.
---@return Output|nil ---
---This is a handle to one of your monitors.
---It serves to make it easier to deal with them, defining methods for getting properties and
---helpers for things like positioning multiple monitors.
---
---This can be retrieved through the various `get` functions in the `Output` module.
---@classmod
---@class OutputHandle A handle to a display.
---@field private _name string The name of this output (or rather, of its connector).
local output_handle = {}
---@param params OutputHandle|string
---@return OutputHandle|nil
local function create_output_from_params(params) local function create_output_from_params(params)
if type(params) == "table" then if type(params) == "table" then
return params return params
end end
return output_module.get_by_name(params --[[@as string]]) return output.get_by_name(params --[[@as string]])
end end
---Create a new output object from a name. ---Create a new output handle from a name.
---The name is the unique identifier for each output. ---The name is the unique identifier for each output.
---@param name string ---@param name string
---@return Output ---@return OutputHandle
local function create_output(name) local function create_output(name)
---@type Output ---@type OutputHandle
local o = { _name = name } local o = { _name = name }
-- Copy functions over -- Copy functions over
for k, v in pairs(output) do for k, v in pairs(output_handle) do
o[k] = v o[k] = v
end end
@ -49,73 +49,73 @@ end
---Get this output's name. This is something like "eDP-1" or "HDMI-A-0". ---Get this output's name. This is something like "eDP-1" or "HDMI-A-0".
---@return string ---@return string
function output:name() function output_handle:name()
return self._name return self._name
end end
---Get all tags on this output. ---Get all tags on this output.
---@return Tag[] ---@return TagHandle[]
---@see OutputModule.tags — The corresponding module function ---@see Output.tags — The corresponding module function
function output:tags() function output_handle:tags()
return output_module.tags(self) return output.tags(self)
end end
---Add tags to this output. ---Add tags to this output.
---@param ... string The names of the tags you want to add. You can also pass in a table. ---@param ... string The names of the tags you want to add. You can also pass in a table.
---@overload fun(self: self, tag_names: string[]) ---@overload fun(self: self, tag_names: string[])
---@see OutputModule.add_tags — The corresponding module function ---@see Output.add_tags — The corresponding module function
function output:add_tags(...) function output_handle:add_tags(...)
output_module.add_tags(self, ...) output.add_tags(self, ...)
end end
---Get this output's make. ---Get this output's make.
---@return string|nil ---@return string|nil
---@see OutputModule.make — The corresponding module function ---@see Output.make — The corresponding module function
function output:make() function output_handle:make()
return output_module.make(self) return output.make(self)
end end
---Get this output's model. ---Get this output's model.
---@return string|nil ---@return string|nil
---@see OutputModule.model — The corresponding module function ---@see Output.model — The corresponding module function
function output:model() function output_handle:model()
return output_module.model(self) return output.model(self)
end end
---Get this output's location in the global space, in pixels. ---Get this output's location in the global space, in pixels.
---@return { x: integer, y: integer }|nil ---@return { x: integer, y: integer }|nil
---@see OutputModule.loc — The corresponding module function ---@see Output.loc — The corresponding module function
function output:loc() function output_handle:loc()
return output_module.loc(self) return output.loc(self)
end end
---Get this output's resolution in pixels. ---Get this output's resolution in pixels.
---@return { w: integer, h: integer }|nil ---@return { w: integer, h: integer }|nil
---@see OutputModule.res — The corresponding module function ---@see Output.res — The corresponding module function
function output:res() function output_handle:res()
return output_module.res(self) return output.res(self)
end end
---Get this output's refresh rate in millihertz. ---Get this output's refresh rate in millihertz.
---For example, 60Hz will be returned as 60000. ---For example, 60Hz will be returned as 60000.
---@return integer|nil ---@return integer|nil
---@see OutputModule.refresh_rate — The corresponding module function ---@see Output.refresh_rate — The corresponding module function
function output:refresh_rate() function output_handle:refresh_rate()
return output_module.refresh_rate(self) return output.refresh_rate(self)
end end
---Get this output's physical size in millimeters. ---Get this output's physical size in millimeters.
---@return { w: integer, h: integer }|nil ---@return { w: integer, h: integer }|nil
---@see OutputModule.physical_size — The corresponding module function ---@see Output.physical_size — The corresponding module function
function output:physical_size() function output_handle:physical_size()
return output_module.physical_size(self) return output.physical_size(self)
end end
---Get whether or not this output is focused. This is currently defined as having the cursor on it. ---Get whether or not this output is focused. This is currently defined as having the cursor on it.
---@return boolean|nil ---@return boolean|nil
---@see OutputModule.focused — The corresponding module function ---@see Output.focused — The corresponding module function
function output:focused() function output_handle:focused()
return output_module.focused(self) return output.focused(self)
end end
---Set this output's location. ---Set this output's location.
@ -139,8 +139,8 @@ end
---dp2:set_loc({ x = 2560, y = 1440 - 1080 }) ---dp2:set_loc({ x = 2560, y = 1440 - 1080 })
---``` ---```
---@param loc { x: integer?, y: integer? } ---@param loc { x: integer?, y: integer? }
function output:set_loc(loc) function output_handle:set_loc(loc)
output_module.set_loc(self, loc) output.set_loc(self, loc)
end end
-- TODO: move this into own file or something --------------------------------------------- -- TODO: move this into own file or something ---------------------------------------------
@ -155,8 +155,8 @@ end
---| "center" Center the outputs vertically ---| "center" Center the outputs vertically
---| "right" Align the right edges of the outputs ---| "right" Align the right edges of the outputs
---@param op1 Output ---@param op1 OutputHandle
---@param op2 Output ---@param op2 OutputHandle
---@param left_or_right "left" | "right" ---@param left_or_right "left" | "right"
---@param alignment AlignmentVertical? How you want to align the `self` output. Defaults to `top`. ---@param alignment AlignmentVertical? How you want to align the `self` output. Defaults to `top`.
local function set_loc_horizontal(op1, op2, left_or_right, alignment) local function set_loc_horizontal(op1, op2, left_or_right, alignment)
@ -179,11 +179,11 @@ local function set_loc_horizontal(op1, op2, left_or_right, alignment)
end end
if alignment == "top" then if alignment == "top" then
output_module.set_loc(op1, { x = x, y = other_loc.y }) output.set_loc(op1, { x = x, y = other_loc.y })
elseif alignment == "center" then elseif alignment == "center" then
output_module.set_loc(op1, { x = x, y = other_loc.y + (other_res.h - self_res.h) // 2 }) output.set_loc(op1, { x = x, y = other_loc.y + (other_res.h - self_res.h) // 2 })
elseif alignment == "bottom" then elseif alignment == "bottom" then
output_module.set_loc(op1, { x = x, y = other_loc.y + (other_res.h - self_res.h) }) output.set_loc(op1, { x = x, y = other_loc.y + (other_res.h - self_res.h) })
end end
end end
@ -198,10 +198,10 @@ end
--- └────────┘ └────────┘ └────────┴──────┘ --- └────────┘ └────────┘ └────────┴──────┘
---``` ---```
---This will fail if `op` is an invalid output. ---This will fail if `op` is an invalid output.
---@param op Output ---@param op OutputHandle
---@param alignment AlignmentVertical? How you want to align the `self` output. Defaults to `top`. ---@param alignment AlignmentVertical? How you want to align the `self` output. Defaults to `top`.
---@see Output.set_loc if you need more granular control ---@see OutputHandle.set_loc if you need more granular control
function output:set_loc_right_of(op, alignment) function output_handle:set_loc_right_of(op, alignment)
set_loc_horizontal(self, op, "right", alignment) set_loc_horizontal(self, op, "right", alignment)
end end
@ -216,15 +216,15 @@ end
--- └────────┘ └────────┘ └──────┴────────┘ --- └────────┘ └────────┘ └──────┴────────┘
---``` ---```
---This will fail if `op` is an invalid output. ---This will fail if `op` is an invalid output.
---@param op Output ---@param op OutputHandle
---@param alignment AlignmentVertical? How you want to align the `self` output. Defaults to `top`. ---@param alignment AlignmentVertical? How you want to align the `self` output. Defaults to `top`.
---@see Output.set_loc if you need more granular control ---@see OutputHandle.set_loc if you need more granular control
function output:set_loc_left_of(op, alignment) function output_handle:set_loc_left_of(op, alignment)
set_loc_horizontal(self, op, "left", alignment) set_loc_horizontal(self, op, "left", alignment)
end end
---@param op1 Output ---@param op1 OutputHandle
---@param op2 Output ---@param op2 OutputHandle
---@param top_or_bottom "top" | "bottom" ---@param top_or_bottom "top" | "bottom"
---@param alignment AlignmentHorizontal? How you want to align the `self` output. Defaults to `top`. ---@param alignment AlignmentHorizontal? How you want to align the `self` output. Defaults to `top`.
local function set_loc_vertical(op1, op2, top_or_bottom, alignment) local function set_loc_vertical(op1, op2, top_or_bottom, alignment)
@ -247,11 +247,11 @@ local function set_loc_vertical(op1, op2, top_or_bottom, alignment)
end end
if alignment == "left" then if alignment == "left" then
output_module.set_loc(op1, { x = other_loc.x, y = y }) output.set_loc(op1, { x = other_loc.x, y = y })
elseif alignment == "center" then elseif alignment == "center" then
output_module.set_loc(op1, { x = other_loc.x + (other_res.w - self_res.w) // 2, y = y }) output.set_loc(op1, { x = other_loc.x + (other_res.w - self_res.w) // 2, y = y })
elseif alignment == "right" then elseif alignment == "right" then
output_module.set_loc(op1, { x = other_loc.x + (other_res.w - self_res.w), y = y }) output.set_loc(op1, { x = other_loc.x + (other_res.w - self_res.w), y = y })
end end
end end
@ -267,10 +267,10 @@ end
--- └────────┘ └────────┘ └────────┘ --- └────────┘ └────────┘ └────────┘
---``` ---```
---This will fail if `op` is an invalid output. ---This will fail if `op` is an invalid output.
---@param op Output ---@param op OutputHandle
---@param alignment AlignmentHorizontal? How you want to align the `self` output. Defaults to `left`. ---@param alignment AlignmentHorizontal? How you want to align the `self` output. Defaults to `left`.
---@see Output.set_loc if you need more granular control ---@see OutputHandle.set_loc if you need more granular control
function output:set_loc_top_of(op, alignment) function output_handle:set_loc_top_of(op, alignment)
set_loc_vertical(self, op, "top", alignment) set_loc_vertical(self, op, "top", alignment)
end end
@ -286,10 +286,10 @@ end
--- left center right --- left center right
---``` ---```
---This will fail if `op` is an invalid output. ---This will fail if `op` is an invalid output.
---@param op Output ---@param op OutputHandle
---@param alignment AlignmentHorizontal? How you want to align the `self` output. Defaults to `left`. ---@param alignment AlignmentHorizontal? How you want to align the `self` output. Defaults to `left`.
---@see Output.set_loc if you need more granular control ---@see OutputHandle.set_loc if you need more granular control
function output:set_loc_bottom_of(op, alignment) function output_handle:set_loc_bottom_of(op, alignment)
set_loc_vertical(self, op, "bottom", alignment) set_loc_vertical(self, op, "bottom", alignment)
end end
@ -307,8 +307,8 @@ end
---print(monitor:name()) -- should print `DP-1` ---print(monitor:name()) -- should print `DP-1`
---``` ---```
---@param name string The name of the output. ---@param name string The name of the output.
---@return Output|nil output The output, or nil if none have the provided name. ---@return OutputHandle|nil output The output, or nil if none have the provided name.
function output_module.get_by_name(name) function output.get_by_name(name)
local response = Request("GetOutputs") local response = Request("GetOutputs")
local output_names = response.RequestResponse.response.Outputs.output_names local output_names = response.RequestResponse.response.Outputs.output_names
@ -321,17 +321,20 @@ function output_module.get_by_name(name)
return nil return nil
end end
---Note: This may or may not be what is reported by other monitor listing utilities. Pinnacle currently fails to pick up one of my monitors' models when it is correctly picked up by tools like wlr-randr. I'll fix this in the future.
---
---Get outputs by their model. ---Get outputs by their model.
---
---Note: This may or may not be what is reported by other monitor listing utilities.
---Pinnacle currently fails to pick up one of my monitor's models when it is correctly
---picked up by tools like wlr-randr. I'll fix this in the future.
---
---This is something like "DELL E2416H" or whatever gibberish monitor manufacturers call their displays. ---This is something like "DELL E2416H" or whatever gibberish monitor manufacturers call their displays.
---@param model string The model of the output(s). ---@param model string The model of the output(s).
---@return Output[] outputs All outputs with this model. ---@return OutputHandle[] outputs All outputs with this model.
function output_module.get_by_model(model) function output.get_by_model(model)
local response = Request("GetOutputs") local response = Request("GetOutputs")
local output_names = response.RequestResponse.response.Outputs.output_names local output_names = response.RequestResponse.response.Outputs.output_names
---@type Output[] ---@type OutputHandle[]
local outputs = {} local outputs = {}
for _, output_name in pairs(output_names) do for _, output_name in pairs(output_names) do
local o = create_output(output_name) local o = create_output(output_name)
@ -347,13 +350,13 @@ end
--- ---
---@param width integer The width of the outputs, in pixels. ---@param width integer The width of the outputs, in pixels.
---@param height integer The height of the outputs, in pixels. ---@param height integer The height of the outputs, in pixels.
---@return Output[] outputs All outputs with this resolution. ---@return OutputHandle[] outputs All outputs with this resolution.
function output_module.get_by_res(width, height) function output.get_by_res(width, height)
local response = Request("GetOutputs") local response = Request("GetOutputs")
local output_names = response.RequestResponse.response.Outputs.output_names local output_names = response.RequestResponse.response.Outputs.output_names
---@type Output[] ---@type OutputHandle[]
local outputs = {} local outputs = {}
for _, output_name in pairs(output_names) do for _, output_name in pairs(output_names) do
local o = create_output(output_name) local o = create_output(output_name)
@ -384,8 +387,8 @@ end
---```lua ---```lua
---local tags = output.get_focused():tags() -- will NOT warn for nil ---local tags = output.get_focused():tags() -- will NOT warn for nil
---``` ---```
---@return Output|nil output The output, or nil if none are focused. ---@return OutputHandle|nil output The output, or nil if none are focused.
function output_module.get_focused() function output.get_focused()
local response = Request("GetOutputs") local response = Request("GetOutputs")
local output_names = response.RequestResponse.response.Outputs.output_names local output_names = response.RequestResponse.response.Outputs.output_names
@ -410,9 +413,10 @@ end
---This is intended to prevent duplicate setup. ---This is intended to prevent duplicate setup.
--- ---
---Please note: this function will be run *after* Pinnacle processes your entire config. ---Please note: this function will be run *after* Pinnacle processes your entire config.
---For example, if you define tags in `func` but toggle them directly after `connect_for_all`, nothing will happen as the tags haven't been added yet. ---For example, if you define tags in `func` but toggle them directly after `connect_for_all`,
---@param func fun(output: Output) The function that will be run. ---nothing will happen as the tags haven't been added yet.
function output_module.connect_for_all(func) ---@param func fun(output: OutputHandle) The function that will be run.
function output.connect_for_all(func)
---@param args Args ---@param args Args
table.insert(CallbackTable, function(args) table.insert(CallbackTable, function(args)
local args = args.ConnectForAllOutputs local args = args.ConnectForAllOutputs
@ -426,11 +430,11 @@ function output_module.connect_for_all(func)
end end
---Get the output the specified tag is on. ---Get the output the specified tag is on.
---@param tag Tag ---@param tag TagHandle
---@return Output|nil ---@return OutputHandle|nil
---@see TagModule.output — A global method for fully qualified syntax (for you Rustaceans out there) ---@see Tag.output — A global method for fully qualified syntax (for you Rustaceans out there)
---@see Tag.output — The corresponding object method ---@see TagHandle.output — The corresponding object method
function output_module.get_for_tag(tag) function output.get_for_tag(tag)
local response = Request({ local response = Request({
GetTagProps = { GetTagProps = {
tag_id = tag:id(), tag_id = tag:id(),
@ -448,10 +452,10 @@ end
---------Fully-qualified functions ---------Fully-qualified functions
---Get the specified output's make. ---Get the specified output's make.
---@param op Output|string The name of the output or an output object. ---@param op OutputHandle|string The name of the output or an output handle.
---@return string|nil ---@return string|nil
---@see Output.make — The corresponding object method ---@see OutputHandle.make — The corresponding object method
function output_module.make(op) function output.make(op)
local op = create_output_from_params(op) local op = create_output_from_params(op)
if op == nil then if op == nil then
@ -468,10 +472,10 @@ function output_module.make(op)
end end
---Get the specified output's model. ---Get the specified output's model.
---@param op Output|string The name of the output or an output object. ---@param op OutputHandle|string The name of the output or an output object.
---@return string|nil ---@return string|nil
---@see Output.model — The corresponding object method ---@see OutputHandle.model — The corresponding object method
function output_module.model(op) function output.model(op)
local op = create_output_from_params(op) local op = create_output_from_params(op)
if op == nil then if op == nil then
@ -488,10 +492,10 @@ function output_module.model(op)
end end
---Get the specified output's location in the global space, in pixels. ---Get the specified output's location in the global space, in pixels.
---@param op Output|string The name of the output or an output object. ---@param op OutputHandle|string The name of the output or an output object.
---@return { x: integer, y: integer }|nil ---@return { x: integer, y: integer }|nil
---@see Output.loc — The corresponding object method ---@see OutputHandle.loc — The corresponding object method
function output_module.loc(op) function output.loc(op)
local op = create_output_from_params(op) local op = create_output_from_params(op)
if op == nil then if op == nil then
@ -512,10 +516,10 @@ function output_module.loc(op)
end end
---Get the specified output's resolution in pixels. ---Get the specified output's resolution in pixels.
---@param op Output|string The name of the output or an output object. ---@param op OutputHandle|string The name of the output or an output object.
---@return { w: integer, h: integer }|nil ---@return { w: integer, h: integer }|nil
---@see Output.res — The corresponding object method ---@see OutputHandle.res — The corresponding object method
function output_module.res(op) function output.res(op)
local op = create_output_from_params(op) local op = create_output_from_params(op)
if op == nil then if op == nil then
@ -537,10 +541,10 @@ end
---Get the specified output's refresh rate in millihertz. ---Get the specified output's refresh rate in millihertz.
---For example, 60Hz will be returned as 60000. ---For example, 60Hz will be returned as 60000.
---@param op Output|string The name of the output or an output object. ---@param op OutputHandle|string The name of the output or an output object.
---@return integer|nil ---@return integer|nil
---@see Output.refresh_rate — The corresponding object method ---@see OutputHandle.refresh_rate — The corresponding object method
function output_module.refresh_rate(op) function output.refresh_rate(op)
local op = create_output_from_params(op) local op = create_output_from_params(op)
if op == nil then if op == nil then
@ -557,10 +561,10 @@ function output_module.refresh_rate(op)
end end
---Get the specified output's physical size in millimeters. ---Get the specified output's physical size in millimeters.
---@param op Output|string The name of the output or an output object. ---@param op OutputHandle|string The name of the output or an output object.
---@return { w: integer, h: integer }|nil ---@return { w: integer, h: integer }|nil
---@see Output.physical_size — The corresponding object method ---@see OutputHandle.physical_size — The corresponding object method
function output_module.physical_size(op) function output.physical_size(op)
local op = create_output_from_params(op) local op = create_output_from_params(op)
if op == nil then if op == nil then
@ -581,10 +585,10 @@ function output_module.physical_size(op)
end end
---Get whether or not the specified output is focused. This is currently defined as having the cursor on it. ---Get whether or not the specified output is focused. This is currently defined as having the cursor on it.
---@param op Output|string The name of the output or an output object. ---@param op OutputHandle|string The name of the output or an output object.
---@return boolean|nil ---@return boolean|nil
---@see Output.focused — The corresponding object method ---@see OutputHandle.focused — The corresponding object method
function output_module.focused(op) function output.focused(op)
local op = create_output_from_params(op) local op = create_output_from_params(op)
if op == nil then if op == nil then
@ -601,11 +605,11 @@ function output_module.focused(op)
end end
---Get the specified output's tags. ---Get the specified output's tags.
---@param op Output|string The name of the output or an output object. ---@param op OutputHandle|string The name of the output or an output object.
---@return Tag[] ---@return TagHandle[]
---@see TagModule.get_on_output — The called function ---@see Tag.get_on_output — The called function
---@see Output.tags — The corresponding object method ---@see OutputHandle.tags — The corresponding object method
function output_module.tags(op) function output.tags(op)
local op = create_output_from_params(op) local op = create_output_from_params(op)
if op == nil then if op == nil then
@ -616,12 +620,12 @@ function output_module.tags(op)
end end
---Add tags to the specified output. ---Add tags to the specified output.
---@param op Output|string The name of the output or an output object. ---@param op OutputHandle|string The name of the output or an output object.
---@param ... string The names of the tags you want to add. You can also pass in a table. ---@param ... string The names of the tags you want to add. You can also pass in a table.
---@overload fun(op: Output|string, tag_names: string[]) ---@overload fun(op: OutputHandle|string, tag_names: string[])
---@see TagModule.add — The called function ---@see Tag.add — The called function
---@see Output.add_tags — The corresponding object method ---@see OutputHandle.add_tags — The corresponding object method
function output_module.add_tags(op, ...) function output.add_tags(op, ...)
local op = create_output_from_params(op) local op = create_output_from_params(op)
if op == nil then if op == nil then
@ -651,9 +655,9 @@ end
---output.set_loc(dp1, { x = 0, y = 0 }) ---output.set_loc(dp1, { x = 0, y = 0 })
---output.set_loc(dp2, { x = 2560, y = 1440 - 1080 }) ---output.set_loc(dp2, { x = 2560, y = 1440 - 1080 })
---``` ---```
---@param op Output|string The name of the output or an output object. ---@param op OutputHandle|string The name of the output or an output object.
---@param loc { x: integer?, y: integer? } ---@param loc { x: integer?, y: integer? }
function output_module.set_loc(op, loc) function output.set_loc(op, loc)
local op = create_output_from_params(op) local op = create_output_from_params(op)
if op == nil then if op == nil then
@ -669,4 +673,4 @@ function output_module.set_loc(op, loc)
}) })
end end
return output_module return output

8
api/lua/pinnacle.lua
View file

@ -72,7 +72,7 @@ local function read_exact(socket_fd, count)
return data return data
end end
---@class PinnacleModule ---@class Pinnacle
---The entry point to all configuration. ---The entry point to all configuration.
local pinnacle = { local pinnacle = {
---Key and mouse binds ---Key and mouse binds
@ -92,9 +92,11 @@ function pinnacle.quit()
SendMsg("Quit") SendMsg("Quit")
end end
---Configure Pinnacle. You should put mostly eveything into the config_func to avoid invalid state. ---Configure Pinnacle. You should put mostly everything into the config_func to avoid invalid state.
---The function takes one argument: the `PinnacleModule` table, which is how you'll access all of the available config options. ---The function takes one argument: the `PinnacleModule` table, which is how you'll access all of the available config options.
---@param config_func fun(pinnacle: PinnacleModule) ---
---You can also just `require` all the individual modules, but hey, they're all passed in anyway; might as well use them!
---@param config_func fun(pinnacle: Pinnacle)
function pinnacle.setup(config_func) function pinnacle.setup(config_func)
---@type integer ---@type integer
local socket_fd = assert(socket.socket(socket.AF_UNIX, socket.SOCK_STREAM, 0), "Failed to create socket") local socket_fd = assert(socket.socket(socket.AF_UNIX, socket.SOCK_STREAM, 0), "Failed to create socket")

195
api/lua/tag.lua
View file

@ -17,22 +17,22 @@
--- This is helpful if you, say, want to reference a browser window while coding; you toggle your --- This is helpful if you, say, want to reference a browser window while coding; you toggle your
--- browser's tag and temporarily reference it while you work without having to change screens. --- browser's tag and temporarily reference it while you work without having to change screens.
--- ---
---Many of the functions in this module take Tag|TagTable|TagTableNamed|string. ---Many of the functions in this module take `TagConstructor`.
---This is a convenience so you don't have to get a tag object every time you want to do ---This is a convenience so you don't have to get a tag handle every time you want to do
---something with tags. ---something with tags.
--- ---
---Instead, you can pass in either: ---Instead, you can pass in either:
--- ---
--- - A string of the tag's name (ex. "1") --- - A string of the tag's name (ex. "1")
--- - This will get the first tag with that name on the focused output. --- - This will get the first tag with that name on the focused output.
--- - A table where [1] is the name and [2] is the output (or its name) (ex. { "1", output.get_by_name("DP-1") }) --- - A table where `name` is the name and `output` is the output (or its name) (ex. { name = "1", output = "DP-1" })
--- - This will get the first tag with that name on the specified output. --- - This will get the first tag with that name on the specified output.
--- - The same table as above, but keyed with `name` and `output` (ex. { name = "1", output = "DP-1" }) --- - A tag handle itself
--- - This is simply for those who want more clarity in their config. --- - If you already have a tag handle, it will be used directly.
--- ---
---If you need to get tags beyond the first with the same name, use a `get` function and find what you need. ---If you need to get tags beyond the first with the same name, use a `get` function and find what you need.
---@class TagModule ---@class Tag
local tag_module = {} local tag = {}
---@alias Layout ---@alias Layout
---| "MasterStack" # One master window on the left with all other windows stacked to the right. ---| "MasterStack" # One master window on the left with all other windows stacked to the right.
@ -43,27 +43,29 @@ local tag_module = {}
---| "CornerBottomLeft" # One main corner window in the bottom left with a column of windows on the right and a row on the top. ---| "CornerBottomLeft" # One main corner window in the bottom left with a column of windows on the right and a row on the top.
---| "CornerBottomRight" # One main corner window in the bottom right with a column of windows on the left and a row on the top. ---| "CornerBottomRight" # One main corner window in the bottom right with a column of windows on the left and a row on the top.
---@alias TagTable { name: string, output: (string|Output)? } ---@alias TagTable { name: string, output: (string|OutputHandle)? }
---@alias TagConstructor Tag|TagTable|string ---@alias TagConstructor TagHandle|TagTable|string
---A tag object. ---A tag handle.
--- ---
---This can be retrieved through the various `get` functions in the `TagModule`. ---This is a handle to a tag that can be passed to windows and such.
---
---This can be retrieved through the various `get` functions in the `Tag` module.
---@classmod ---@classmod
---@class Tag ---@class TagHandle
---@field private _id integer The internal id of this tag. ---@field private _id integer The internal id of this tag.
local tag = {} local tag_handle = {}
---Create a tag from an id. ---Create a tag from an id.
---The id is the unique identifier for each tag. ---The id is the unique identifier for each tag.
---@param id TagId ---@param id TagId
---@return Tag ---@return TagHandle
local function create_tag(id) local function create_tag(id)
---@type Tag ---@type TagHandle
local t = { _id = id } local t = { _id = id }
-- Copy functions over -- Copy functions over
for k, v in pairs(tag) do for k, v in pairs(tag_handle) do
t[k] = v t[k] = v
end end
@ -73,48 +75,48 @@ end
---Get this tag's internal id. ---Get this tag's internal id.
---***You probably won't need to use this.*** ---***You probably won't need to use this.***
---@return integer ---@return integer
function tag:id() function tag_handle:id()
return self._id return self._id
end end
---Get this tag's active status. ---Get this tag's active status.
---@return boolean|nil active `true` if the tag is active, `false` if not, and `nil` if the tag doesn't exist. ---@return boolean|nil active `true` if the tag is active, `false` if not, and `nil` if the tag doesn't exist.
---@see TagModule.active — The corresponding module function ---@see Tag.active — The corresponding module function
function tag:active() function tag_handle:active()
return tag_module.active(self) return tag.active(self)
end end
---Get this tag's name. ---Get this tag's name.
---@return string|nil name The name of this tag, or nil if it doesn't exist. ---@return string|nil name The name of this tag, or nil if it doesn't exist.
---@see TagModule.name — The corresponding module function ---@see Tag.name — The corresponding module function
function tag:name() function tag_handle:name()
return tag_module.name(self) return tag.name(self)
end end
---Get this tag's output. ---Get this tag's output.
---@return Output|nil output The output this tag is on, or nil if the tag doesn't exist. ---@return OutputHandle|nil output The output this tag is on, or nil if the tag doesn't exist.
---@see TagModule.output — The corresponding module function ---@see Tag.output — The corresponding module function
function tag:output() function tag_handle:output()
return tag_module.output(self) return tag.output(self)
end end
---Switch to this tag. ---Switch to this tag.
---@see TagModule.switch_to — The corresponding module function ---@see Tag.switch_to — The corresponding module function
function tag:switch_to() function tag_handle:switch_to()
tag_module.switch_to(self) tag.switch_to(self)
end end
---Toggle this tag. ---Toggle this tag.
---@see TagModule.toggle — The corresponding module function ---@see Tag.toggle — The corresponding module function
function tag:toggle() function tag_handle:toggle()
tag_module.toggle(self) tag.toggle(self)
end end
---Set this tag's layout. ---Set this tag's layout.
---@param layout Layout ---@param layout Layout
---@see TagModule.set_layout — The corresponding module function ---@see Tag.set_layout — The corresponding module function
function tag:set_layout(layout) function tag_handle:set_layout(layout)
tag_module.set_layout(self, layout) tag.set_layout(self, layout)
end end
----------------------------------------------------------- -----------------------------------------------------------
@ -127,16 +129,16 @@ end
---if op ~= nil then ---if op ~= nil then
--- tag.add(op, "1", "2", "3", "4", "5") -- Add tags with names 1-5 --- tag.add(op, "1", "2", "3", "4", "5") -- Add tags with names 1-5
---end ---end
-- ---
--- -- You can also pass in a table. --- -- You can also pass in a table.
---local tags = {"Terminal", "Browser", "Code", "Potato", "Email"} ---local tags = {"Terminal", "Browser", "Code", "Potato", "Email"}
---tag.add(op, tags) ---tag.add(op, tags)
---``` ---```
---@param output Output The output you want these tags to be added to. ---@param output OutputHandle The output you want these tags to be added to.
---@param ... string The names of the new tags you want to add. ---@param ... string The names of the new tags you want to add.
---@overload fun(output: Output, tag_names: string[]) ---@overload fun(output: OutputHandle, tag_names: string[])
---@see Output.add_tags — The corresponding object method ---@see OutputHandle.add_tags — The corresponding object method
function tag_module.add(output, ...) function tag.add(output, ...)
local varargs = { ... } local varargs = { ... }
if type(varargs[1]) == "string" then if type(varargs[1]) == "string" then
local tag_names = varargs local tag_names = varargs
@ -172,14 +174,14 @@ end
---tag.toggle({ name = "1", output = "DP-1" }) -- Toggle tag 1 on "DP-1" ---tag.toggle({ name = "1", output = "DP-1" }) -- Toggle tag 1 on "DP-1"
---tag.toggle({ name = "1", output = op }) -- Same as above ---tag.toggle({ name = "1", output = op }) -- Same as above
--- ---
--- -- Using a tag object --- -- Using a tag handle
---local t = tag.get_by_name("1")[1] -- `t` is the first tag with the name "1" ---local t = tag.get("1") -- `t` is the tag with the name "1" on the focused output
---tag.toggle(t) ---tag.toggle(t)
---``` ---```
---@param t TagConstructor ---@param t TagConstructor
---@see Tag.toggle — The corresponding object method ---@see TagHandle.toggle — The corresponding object method
function tag_module.toggle(t) function tag.toggle(t)
local t = tag_module.get(t) local t = tag.get(t)
if t then if t then
SendMsg({ SendMsg({
@ -204,14 +206,14 @@ end
---tag.switch_to({ name = "1", output = "DP-1" }) -- Switch to tag 1 on "DP-1" ---tag.switch_to({ name = "1", output = "DP-1" }) -- Switch to tag 1 on "DP-1"
---tag.switch_to({ name = "1", output = op }) -- Same as above ---tag.switch_to({ name = "1", output = op }) -- Same as above
--- ---
--- -- Using a tag object --- -- Using a tag handle
---local t = tag.get_by_name("1")[1] -- `t` is the first tag with the name "1" ---local t = tag.get_by_name("1")[1] -- `t` is the first tag with the name "1"
---tag.switch_to(t) ---tag.switch_to(t)
---``` ---```
---@param t TagConstructor ---@param t TagConstructor
---@see Tag.switch_to — The corresponding object method ---@see TagHandle.switch_to — The corresponding object method
function tag_module.switch_to(t) function tag.switch_to(t)
local t = tag_module.get(t) local t = tag.get(t)
if t then if t then
SendMsg({ SendMsg({
@ -233,16 +235,16 @@ end
---tag.set_layout({ name = "1", output = "DP-1" }, "Dwindle") -- Set tag 1 on "DP-1" to "Dwindle" ---tag.set_layout({ name = "1", output = "DP-1" }, "Dwindle") -- Set tag 1 on "DP-1" to "Dwindle"
---tag.set_layout({ name = "1", output = op }, "Dwindle") -- Same as above ---tag.set_layout({ name = "1", output = op }, "Dwindle") -- Same as above
--- ---
--- -- Using a tag object --- -- Using a tag handle
---local t = tag.get_by_name("1")[1] -- `t` is the first tag with the name "1" ---local t = tag.get_by_name("1")[1] -- `t` is the first tag with the name "1"
---tag.set_layout(t, "Dwindle") ---tag.set_layout(t, "Dwindle")
---``` ---```
--- ---
---@param t TagConstructor ---@param t TagConstructor
---@param layout Layout The layout. ---@param layout Layout The layout.
---@see Tag.set_layout — The corresponding object method ---@see TagHandle.set_layout — The corresponding object method
function tag_module.set_layout(t, layout) function tag.set_layout(t, layout)
local t = tag_module.get(t) local t = tag.get(t)
if t then if t then
SendMsg({ SendMsg({
@ -265,7 +267,6 @@ end
---### Examples ---### Examples
---```lua ---```lua
---local t = tag.get("1") ---local t = tag.get("1")
---local t = tag.get({ name = "3" })
---local t = tag.get({ name = "1", output = "HDMI-A-0" }) ---local t = tag.get({ name = "1", output = "HDMI-A-0" })
--- ---
---local op = output.get_by_name("DP-2") ---local op = output.get_by_name("DP-2")
@ -274,15 +275,15 @@ end
---end ---end
---``` ---```
---@param params TagConstructor ---@param params TagConstructor
---@return Tag|nil ---@return TagHandle|nil
--- ---
---@see TagModule.get_on_output ---@see Tag.get_on_output — Get all tags on an output
---@see TagModule.get_by_name ---@see Tag.get_by_name — Get all tags with some name
---@see TagModule.get_all ---@see Tag.get_all — Get all tags
function tag_module.get(params) function tag.get(params)
-- If creating from a tag object, just return the obj -- If creating from a tag object, just return the obj
if params.id then if params.id then
return params --[[@as Tag]] return params --[[@as TagHandle]]
end end
-- string passed in -- string passed in
@ -292,7 +293,7 @@ function tag_module.get(params)
return nil return nil
end end
local tags = tag_module.get_by_name(params) local tags = tag.get_by_name(params)
for _, t in pairs(tags) do for _, t in pairs(tags) do
if t:output() and t:output():name() == op:name() then if t:output() and t:output():name() == op:name() then
return t return t
@ -321,7 +322,7 @@ function tag_module.get(params)
op = o op = o
end end
local tags = tag_module.get_by_name(tag_name) local tags = tag.get_by_name(tag_name)
for _, t in pairs(tags) do for _, t in pairs(tags) do
if t:output() and t:output():name() == op:name() then if t:output() and t:output():name() == op:name() then
return t return t
@ -340,11 +341,11 @@ end
--- local tags = tag.get_on_output(op) -- All tags on the focused output --- local tags = tag.get_on_output(op) -- All tags on the focused output
---end ---end
---``` ---```
---@param output Output ---@param output OutputHandle
---@return Tag[] ---@return TagHandle[]
--- ---
---@see Output.tags — The corresponding object method ---@see Output.tags — The corresponding object method
function tag_module.get_on_output(output) function tag.get_on_output(output)
local response = Request({ local response = Request({
GetOutputProps = { GetOutputProps = {
output_name = output:name(), output_name = output:name(),
@ -353,7 +354,7 @@ function tag_module.get_on_output(output)
local tag_ids = response.RequestResponse.response.OutputProps.tag_ids local tag_ids = response.RequestResponse.response.OutputProps.tag_ids
---@type Tag[] ---@type TagHandle[]
local tags = {} local tags = {}
if tag_ids == nil then if tag_ids == nil then
@ -378,11 +379,11 @@ end
--- -- ...will have `no_tags` be empty. --- -- ...will have `no_tags` be empty.
---``` ---```
---@param name string The name of the tag(s) you want. ---@param name string The name of the tag(s) you want.
---@return Tag[] ---@return TagHandle[]
function tag_module.get_by_name(name) function tag.get_by_name(name)
local t_s = tag_module.get_all() local t_s = tag.get_all()
---@type Tag[] ---@type TagHandle[]
local tags = {} local tags = {}
for _, t in pairs(t_s) do for _, t in pairs(t_s) do
@ -402,13 +403,13 @@ end
---local tags = tag.get_all() ---local tags = tag.get_all()
--- -- ...`tags` should have 10 tags, with 5 pairs of those names across both outputs. --- -- ...`tags` should have 10 tags, with 5 pairs of those names across both outputs.
---``` ---```
---@return Tag[] ---@return TagHandle[]
function tag_module.get_all() function tag.get_all()
local response = Request("GetTags") local response = Request("GetTags")
local tag_ids = response.RequestResponse.response.Tags.tag_ids local tag_ids = response.RequestResponse.response.Tags.tag_ids
---@type Tag[] ---@type TagHandle[]
local tags = {} local tags = {}
for _, tag_id in pairs(tag_ids) do for _, tag_id in pairs(tag_ids) do
@ -426,10 +427,10 @@ end
---print(tag.name(tag.get_by_name("Terminal")[1])) ---print(tag.name(tag.get_by_name("Terminal")[1]))
--- -- ...should print `Terminal`. --- -- ...should print `Terminal`.
---``` ---```
---@param t Tag ---@param t TagHandle
---@return string|nil ---@return string|nil
---@see Tag.name — The corresponding object method ---@see TagHandle.name — The corresponding object method
function tag_module.name(t) function tag.name(t)
local response = Request({ local response = Request({
GetTagProps = { GetTagProps = {
tag_id = t:id(), tag_id = t:id(),
@ -440,10 +441,10 @@ function tag_module.name(t)
end end
---Get whether or not the specified tag is active. ---Get whether or not the specified tag is active.
---@param t Tag ---@param t TagHandle
---@return boolean|nil ---@return boolean|nil
---@see Tag.active — The corresponding object method ---@see TagHandle.active — The corresponding object method
function tag_module.active(t) function tag.active(t)
local response = Request({ local response = Request({
GetTagProps = { GetTagProps = {
tag_id = t:id(), tag_id = t:id(),
@ -454,34 +455,36 @@ function tag_module.active(t)
end end
---Get the output the specified tag is on. ---Get the output the specified tag is on.
---@param t Tag ---@param t TagHandle
---@return Output|nil ---@return OutputHandle|nil
---@see OutputModule.get_for_tag — The called function ---@see Output.get_for_tag — The called function
---@see Tag.output — The corresponding object method ---@see TagHandle.output — The corresponding object method
function tag_module.output(t) function tag.output(t)
return require("output").get_for_tag(t) return require("output").get_for_tag(t)
end end
---@class LayoutCycler ---@class LayoutCycler
---@field next fun(output: (Output|OutputName)?) Change the first active tag on `output` to its next layout. If `output` is empty, the focused output is used. ---@field next fun(output: (OutputHandle|OutputName)?) Change the first active tag on `output` to its next layout. If `output` is empty, the focused output is used.
---@field prev fun(output: (Output|OutputName)?) Change the first active tag on `output` to its previous layout. If `output` is empty, the focused output is used. ---@field prev fun(output: (OutputHandle|OutputName)?) Change the first active tag on `output` to its previous layout. If `output` is empty, the focused output is used.
---Given an array of layouts, this will create two functions; one will cycle forward the layout ---Create a `LayoutCycler` to cycle layouts on tags.
---for the provided tag, and one will cycle backward. ---
---Given an array of layouts, this will create a table with two functions;
---one will cycle forward the layout for the active tag, and one will cycle backward.
--- ---
--- ### Example --- ### Example
---```lua ---```lua
---local layout_cycler = tag.layout_cycler({ "Dwindle", "Spiral", "MasterStack" }) ---local layout_cycler = tag.layout_cycler({ "Dwindle", "Spiral", "MasterStack" })
--- ---
---layout_cycler.next() -- Go to the next layout on the first tag of the focused output ---layout_cycler.next() -- Go to the next layout on the first active tag of the focused output
---layout_cycler.prev() -- Go to the previous layout on the first tag of the focused output ---layout_cycler.prev() -- Go to the previous layout on the first active tag of the focused output
--- ---
---layout_cycler.next("DP-1") -- Do the above but on "DP-1" instead ---layout_cycler.next("DP-1") -- Do the above but on "DP-1" instead
---layout_cycler.prev(output.get_by_name("DP-1")) -- With an output object ---layout_cycler.prev(output.get_by_name("DP-1")) -- With an output handle
---``` ---```
---@param layouts Layout[] The available layouts. ---@param layouts Layout[] The available layouts.
---@return LayoutCycler layout_cycler A table with the functions `next` and `prev`, which will cycle layouts for the given tag. ---@return LayoutCycler layout_cycler A table with the functions `next` and `prev`, which will cycle layouts for the given tag.
function tag_module.layout_cycler(layouts) function tag.layout_cycler(layouts)
local indices = {} local indices = {}
-- Return empty functions if layouts is empty -- Return empty functions if layouts is empty
@ -493,7 +496,7 @@ function tag_module.layout_cycler(layouts)
end end
return { return {
---@param output (Output|OutputName)? ---@param output (OutputHandle|OutputName)?
next = function(output) next = function(output)
if type(output) == "string" then if type(output) == "string" then
output = require("output").get_by_name(output) output = require("output").get_by_name(output)
@ -531,7 +534,7 @@ function tag_module.layout_cycler(layouts)
end end
end, end,
---@param output (Output|OutputName)? ---@param output (OutputHandle|OutputName)?
prev = function(output) prev = function(output)
if type(output) == "string" then if type(output) == "string" then
output = require("output").get_by_name(output) output = require("output").get_by_name(output)
@ -571,4 +574,4 @@ function tag_module.layout_cycler(layouts)
} }
end end
return tag_module return tag

245
api/lua/window.lua
View file

@ -4,29 +4,32 @@
--- ---
---This module helps you deal with setting windows to fullscreen and maximized, setting their size, ---This module helps you deal with setting windows to fullscreen and maximized, setting their size,
---moving them between tags, and various other actions. ---moving them between tags, and various other actions.
---@class WindowModule ---@class Window
local window_module = { local window = {
---Window rules. ---Window rules.
rules = require("window_rules"), rules = require("window_rules"),
} }
---A window object. ---A window handle.
--- ---
---This is a representation of an application window to the config process. ---This is a handle to an application window that allows manipulation of the window.
--- ---
---You can retrieve windows through the various `get` function in the `WindowModule`. ---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.
---@classmod ---@classmod
---@class Window ---@class WindowHandle
---@field private _id integer The internal id of this window ---@field private _id integer The internal id of this window
local window = {} local window_handle = {}
---@param window_id WindowId ---@param window_id WindowId
---@return Window ---@return WindowHandle
local function create_window(window_id) local function create_window(window_id)
---@type Window ---@type WindowHandle
local w = { _id = window_id } local w = { _id = window_id }
-- Copy functions over -- Copy functions over
for k, v in pairs(window) do for k, v in pairs(window_handle) do
w[k] = v w[k] = v
end end
@ -37,39 +40,39 @@ end
--- ---
---***You will probably not need to use this.*** ---***You will probably not need to use this.***
---@return WindowId ---@return WindowId
function window:id() function window_handle:id()
return self._id return self._id
end end
---Set this window's size. ---Set this window's size.
--- ---
---See `WindowModule.set_size` for examples. ---See `Window.set_size` for examples.
--- ---
---@param size { w: integer?, h: integer? } ---@param size { w: integer?, h: integer? }
---@see WindowModule.set_size — The corresponding module function ---@see Window.set_size — The corresponding module function
function window:set_size(size) function window_handle:set_size(size)
window_module.set_size(self, size) window.set_size(self, size)
end end
---Move this window to a tag, removing all other ones. ---Move this window to a tag, removing all other ones.
--- ---
---See `WindowModule.move_to_tag` for examples. ---See `Window.move_to_tag` for examples.
--- ---
---@param t TagConstructor ---@param t TagConstructor
---@see WindowModule.move_to_tag — The corresponding module function ---@see Window.move_to_tag — The corresponding module function
function window:move_to_tag(t) function window_handle:move_to_tag(t)
window_module.move_to_tag(self, t) window.move_to_tag(self, t)
end end
---Toggle the specified tag for this window. ---Toggle the specified tag for this window.
--- ---
---Note: toggling off all tags currently makes a window not respond to layouting. ---Note: toggling off all tags currently makes a window not respond to layouting.
--- ---
---See `WindowModule.toggle_tag` for examples. ---See `Window.toggle_tag` for examples.
---@param t TagConstructor ---@param t TagConstructor
---@see WindowModule.toggle_tag — The corresponding module function ---@see Window.toggle_tag — The corresponding module function
function window:toggle_tag(t) function window_handle:toggle_tag(t)
window_module.toggle_tag(self, t) window.toggle_tag(self, t)
end end
---Close this window. ---Close this window.
@ -77,19 +80,19 @@ end
---This only sends a close *event* to the window and is the same as just clicking the X button in the titlebar. ---This only sends a close *event* to the window and is the same as just clicking the X button in the titlebar.
---This will trigger save prompts in applications like GIMP. ---This will trigger save prompts in applications like GIMP.
--- ---
---See `WindowModule.close` for examples. ---See `Window.close` for examples.
---@see WindowModule.close — The corresponding module function ---@see Window.close — The corresponding module function
function window:close() function window_handle:close()
window_module.close(self) window.close(self)
end end
---Get this window's size. ---Get this window's size.
--- ---
---See `WindowModule.size` for examples. ---See `Window.size` for examples.
---@return { w: integer, h: integer }|nil size The size of the window, or nil if it doesn't exist. ---@return { w: integer, h: integer }|nil size The size of the window, or nil if it doesn't exist.
---@see WindowModule.size — The corresponding module function ---@see Window.size — The corresponding module function
function window:size() function window_handle:size()
return window_module.size(self) return window.size(self)
end end
---Get this window's location in the global space. ---Get this window's location in the global space.
@ -100,50 +103,50 @@ end
---If you don't set the location of your monitors, they will start at (0, 0) ---If you don't set the location of your monitors, they will start at (0, 0)
---and extend rightward with their tops aligned. ---and extend rightward with their tops aligned.
--- ---
---See `WindowModule.loc` for examples. ---See `Window.loc` for examples.
---@return { x: integer, y: integer }|nil loc The location of the window, or nil if it's not on-screen or alive. ---@return { x: integer, y: integer }|nil loc The location of the window, or nil if it's not on-screen or alive.
---@see WindowModule.loc — The corresponding module function ---@see Window.loc — The corresponding module function
function window:loc() function window_handle:loc()
return window_module.loc(self) return window.loc(self)
end end
---Get this window's class. This is usually the name of the application. ---Get this window's class. This is usually the name of the application.
--- ---
---See `WindowModule.class` for examples. ---See `Window.class` for examples.
---@return string|nil class This window's class, or nil if it doesn't exist. ---@return string|nil class This window's class, or nil if it doesn't exist.
---@see WindowModule.class — The corresponding module function ---@see Window.class — The corresponding module function
function window:class() function window_handle:class()
return window_module.class(self) return window.class(self)
end end
---Get this window's title. ---Get this window's title.
--- ---
---See `WindowModule.title` for examples. ---See `Window.title` for examples.
---@return string|nil title This window's title, or nil if it doesn't exist. ---@return string|nil title This window's title, or nil if it doesn't exist.
---@see WindowModule.title — The corresponding module function ---@see Window.title — The corresponding module function
function window:title() function window_handle:title()
return window_module.title(self) return window.title(self)
end end
---Get this window's floating status. ---Get this window's floating status.
---@return boolean|nil ---@return boolean|nil
---@see WindowModule.floating — The corresponding module function ---@see Window.floating — The corresponding module function
function window:floating() function window_handle:floating()
return window_module.floating(self) return window.floating(self)
end end
---Get this window's fullscreen status. ---Get this window's fullscreen status.
---@return boolean|nil ---@return boolean|nil
---@see WindowModule.fullscreen — The corresponding module function ---@see Window.fullscreen — The corresponding module function
function window:fullscreen() function window_handle:fullscreen()
return window_module.fullscreen(self) return window.fullscreen(self)
end end
---Get this window's maximized status. ---Get this window's maximized status.
---@return boolean|nil ---@return boolean|nil
---@see WindowModule.maximized — The corresponding module function ---@see Window.maximized — The corresponding module function
function window:maximized() function window_handle:maximized()
return window_module.maximized(self) return window.maximized(self)
end end
---Toggle this window's floating status. ---Toggle this window's floating status.
@ -152,8 +155,8 @@ end
--- ---
---When used on a fullscreen or maximized window, this will still change its ---When used on a fullscreen or maximized window, this will still change its
---underlying floating/tiled status. ---underlying floating/tiled status.
function window:toggle_floating() function window_handle:toggle_floating()
window_module.toggle_floating(self) window.toggle_floating(self)
end end
---Toggle this window's fullscreen status. ---Toggle this window's fullscreen status.
@ -162,8 +165,8 @@ end
---floating or tiled. ---floating or tiled.
--- ---
---When used on a non-fullscreen window, it becomes fullscreen. ---When used on a non-fullscreen window, it becomes fullscreen.
function window:toggle_fullscreen() function window_handle:toggle_fullscreen()
window_module.toggle_fullscreen(self) window.toggle_fullscreen(self)
end end
---Toggle this window's maximized status. ---Toggle this window's maximized status.
@ -172,28 +175,28 @@ end
---floating or tiled. ---floating or tiled.
--- ---
---When used on a non-maximized window, it becomes maximized. ---When used on a non-maximized window, it becomes maximized.
function window:toggle_maximized() function window_handle:toggle_maximized()
window_module.toggle_maximized(self) window.toggle_maximized(self)
end end
---Get whether or not this window is focused. ---Get whether or not this window is focused.
--- ---
---See `WindowModule.focused` for examples. ---See `Window.focused` for examples.
---@return boolean|nil ---@return boolean|nil
---@see WindowModule.focused — The corresponding module function ---@see Window.focused — The corresponding module function
function window:focused() function window_handle:focused()
return window_module.focused(self) return window.focused(self)
end end
------------------------------------------------------------------- -------------------------------------------------------------------
---Get all windows with the specified class (usually the name of the application). ---Get all windows with the specified class (usually the name of the application).
---@param class string The class. For example, Alacritty's class is "Alacritty". ---@param class string The class. For example, Alacritty's class is "Alacritty".
---@return Window[] ---@return WindowHandle[]
function window_module.get_by_class(class) function window.get_by_class(class)
local windows = window_module.get_all() local windows = window.get_all()
---@type Window[] ---@type WindowHandle[]
local windows_ret = {} local windows_ret = {}
for _, w in pairs(windows) do for _, w in pairs(windows) do
if w:class() == class then if w:class() == class then
@ -206,11 +209,11 @@ end
---Get all windows with the specified title. ---Get all windows with the specified title.
---@param title string The title. ---@param title string The title.
---@return Window[] ---@return WindowHandle[]
function window_module.get_by_title(title) function window.get_by_title(title)
local windows = window_module.get_all() local windows = window.get_all()
---@type Window[] ---@type WindowHandle[]
local windows_ret = {} local windows_ret = {}
for _, w in pairs(windows) do for _, w in pairs(windows) do
if w:title() == title then if w:title() == title then
@ -222,10 +225,10 @@ function window_module.get_by_title(title)
end end
---Get the currently focused window. ---Get the currently focused window.
---@return Window|nil ---@return WindowHandle|nil
function window_module.get_focused() function window.get_focused()
-- TODO: get focused on output -- TODO: get focused on output
local windows = window_module.get_all() local windows = window.get_all()
for _, w in pairs(windows) do for _, w in pairs(windows) do
if w:focused() then if w:focused() then
@ -237,11 +240,11 @@ function window_module.get_focused()
end end
---Get all windows. ---Get all windows.
---@return Window[] ---@return WindowHandle[]
function window_module.get_all() function window.get_all()
local window_ids = Request("GetWindows").RequestResponse.response.Windows.window_ids local window_ids = Request("GetWindows").RequestResponse.response.Windows.window_ids
---@type Window[] ---@type WindowHandle[]
local windows = {} local windows = {}
for _, window_id in pairs(window_ids) do for _, window_id in pairs(window_ids) do
@ -253,10 +256,10 @@ end
---Toggle the tag with the given name and (optional) output for the specified window. ---Toggle the tag with the given name and (optional) output for the specified window.
--- ---
---@param w Window ---@param w WindowHandle
---@param t TagConstructor ---@param t TagConstructor
---@see Window.toggle_tag — The corresponding object method ---@see WindowHandle.toggle_tag — The corresponding object method
function window_module.toggle_tag(w, t) function window.toggle_tag(w, t)
local t = require("tag").get(t) local t = require("tag").get(t)
if t then if t then
@ -271,10 +274,10 @@ end
---Move the specified window to the tag with the given name and (optional) output. ---Move the specified window to the tag with the given name and (optional) output.
--- ---
---@param w Window ---@param w WindowHandle
---@param t TagConstructor ---@param t TagConstructor
---@see Window.move_to_tag — The corresponding object method ---@see WindowHandle.move_to_tag — The corresponding object method
function window_module.move_to_tag(w, t) function window.move_to_tag(w, t)
local t = require("tag").get(t) local t = require("tag").get(t)
if t then if t then
@ -293,8 +296,8 @@ end
--- ---
---When used on a fullscreen or maximized window, this will still change its ---When used on a fullscreen or maximized window, this will still change its
---underlying floating/tiled status. ---underlying floating/tiled status.
---@param win Window ---@param win WindowHandle
function window_module.toggle_floating(win) function window.toggle_floating(win)
SendMsg({ SendMsg({
ToggleFloating = { ToggleFloating = {
window_id = win:id(), window_id = win:id(),
@ -308,8 +311,8 @@ end
---floating or tiled. ---floating or tiled.
--- ---
---When used on a non-fullscreen window, it becomes fullscreen. ---When used on a non-fullscreen window, it becomes fullscreen.
---@param win Window ---@param win WindowHandle
function window_module.toggle_fullscreen(win) function window.toggle_fullscreen(win)
SendMsg({ SendMsg({
ToggleFullscreen = { ToggleFullscreen = {
window_id = win:id(), window_id = win:id(),
@ -323,8 +326,8 @@ end
---floating or tiled. ---floating or tiled.
--- ---
---When used on a non-maximized window, it becomes maximized. ---When used on a non-maximized window, it becomes maximized.
---@param win Window ---@param win WindowHandle
function window_module.toggle_maximized(win) function window.toggle_maximized(win)
SendMsg({ SendMsg({
ToggleMaximized = { ToggleMaximized = {
window_id = win:id(), window_id = win:id(),
@ -343,10 +346,10 @@ end
--- window.set_size(win, {}) -- do absolutely nothing useful --- window.set_size(win, {}) -- do absolutely nothing useful
---end ---end
---``` ---```
---@param win Window ---@param win WindowHandle
---@param size { w: integer?, h: integer? } ---@param size { w: integer?, h: integer? }
---@see Window.set_size — The corresponding object method ---@see WindowHandle.set_size — The corresponding object method
function window_module.set_size(win, size) function window.set_size(win, size)
SendMsg({ SendMsg({
SetWindowSize = { SetWindowSize = {
window_id = win:id(), window_id = win:id(),
@ -368,9 +371,9 @@ end
--- window.close(win) -- close the currently focused window --- window.close(win) -- close the currently focused window
---end ---end
---``` ---```
---@param win Window ---@param win WindowHandle
---@see Window.close — The corresponding object method ---@see WindowHandle.close — The corresponding object method
function window_module.close(win) function window.close(win)
SendMsg({ SendMsg({
CloseWindow = { CloseWindow = {
window_id = win:id(), window_id = win:id(),
@ -386,10 +389,10 @@ end
---local size = window.size(win) ---local size = window.size(win)
--- -- ...should have size equal to `{ w = 3840, h = 2160 }`. --- -- ...should have size equal to `{ w = 3840, h = 2160 }`.
---``` ---```
---@param win Window ---@param win WindowHandle
---@return { w: integer, h: integer }|nil size The size of the window, or nil if it doesn't exist. ---@return { w: integer, h: integer }|nil size The size of the window, or nil if it doesn't exist.
---@see Window.size — The corresponding object method ---@see WindowHandle.size — The corresponding object method
function window_module.size(win) function window.size(win)
local response = Request({ local response = Request({
GetWindowProps = { GetWindowProps = {
window_id = win:id(), window_id = win:id(),
@ -421,10 +424,10 @@ end
---local loc = window.loc(win) ---local loc = window.loc(win)
--- -- ...should have loc equal to `{ x = 1920, y = 0 }`. --- -- ...should have loc equal to `{ x = 1920, y = 0 }`.
---``` ---```
---@param win Window ---@param win WindowHandle
---@return { x: integer, y: integer }|nil loc The location of the window, or nil if it's not on-screen or alive. ---@return { x: integer, y: integer }|nil loc The location of the window, or nil if it's not on-screen or alive.
---@see Window.loc — The corresponding object method ---@see WindowHandle.loc — The corresponding object method
function window_module.loc(win) function window.loc(win)
local response = Request({ local response = Request({
GetWindowProps = { GetWindowProps = {
window_id = win:id(), window_id = win:id(),
@ -452,10 +455,10 @@ end
---end ---end
--- -- ...should print "Alacritty". --- -- ...should print "Alacritty".
---``` ---```
---@param win Window ---@param win WindowHandle
---@return string|nil class This window's class, or nil if it doesn't exist. ---@return string|nil class This window's class, or nil if it doesn't exist.
---@see Window.class — The corresponding object method ---@see WindowHandle.class — The corresponding object method
function window_module.class(win) function window.class(win)
local response = Request({ local response = Request({
GetWindowProps = { GetWindowProps = {
window_id = win:id(), window_id = win:id(),
@ -476,10 +479,10 @@ end
---end ---end
--- -- ...should print the directory Alacritty is in or what it's running (what's in its title bar). --- -- ...should print the directory Alacritty is in or what it's running (what's in its title bar).
---``` ---```
---@param win Window ---@param win WindowHandle
---@return string|nil title This window's title, or nil if it doesn't exist. ---@return string|nil title This window's title, or nil if it doesn't exist.
---@see Window.title — The corresponding object method ---@see WindowHandle.title — The corresponding object method
function window_module.title(win) function window.title(win)
local response = Request({ local response = Request({
GetWindowProps = { GetWindowProps = {
window_id = win:id(), window_id = win:id(),
@ -490,10 +493,10 @@ function window_module.title(win)
end end
---Get this window's floating status. ---Get this window's floating status.
---@param win Window ---@param win WindowHandle
---@return boolean|nil ---@return boolean|nil
---@see Window.floating — The corresponding object method ---@see WindowHandle.floating — The corresponding object method
function window_module.floating(win) function window.floating(win)
local response = Request({ local response = Request({
GetWindowProps = { GetWindowProps = {
window_id = win:id(), window_id = win:id(),
@ -504,10 +507,10 @@ function window_module.floating(win)
end end
---Get this window's fullscreen status. ---Get this window's fullscreen status.
---@param win Window ---@param win WindowHandle
---@return boolean|nil ---@return boolean|nil
---@see Window.fullscreen — The corresponding object method ---@see WindowHandle.fullscreen — The corresponding object method
function window_module.fullscreen(win) function window.fullscreen(win)
local response = Request({ local response = Request({
GetWindowProps = { GetWindowProps = {
window_id = win:id(), window_id = win:id(),
@ -518,10 +521,10 @@ function window_module.fullscreen(win)
end end
---Get this window's maximized status. ---Get this window's maximized status.
---@param win Window ---@param win WindowHandle
---@return boolean|nil ---@return boolean|nil
---@see Window.maximized — The corresponding object method ---@see WindowHandle.maximized — The corresponding object method
function window_module.maximized(win) function window.maximized(win)
local response = Request({ local response = Request({
GetWindowProps = { GetWindowProps = {
window_id = win:id(), window_id = win:id(),
@ -540,10 +543,10 @@ end
--- print(window.focused(win)) -- Should print `true` --- print(window.focused(win)) -- Should print `true`
---end ---end
---``` ---```
---@param win Window ---@param win WindowHandle
---@return boolean|nil ---@return boolean|nil
---@see Window.focused — The corresponding object method ---@see WindowHandle.focused — The corresponding object method
function window_module.focused(win) function window.focused(win)
local response = Request({ local response = Request({
GetWindowProps = { GetWindowProps = {
window_id = win:id(), window_id = win:id(),
@ -558,7 +561,7 @@ end
---This will start a window move grab with the provided button on the window the pointer ---This will start a window move grab with the provided button on the window the pointer
---is currently hovering over. Once `button` is let go, the move will end. ---is currently hovering over. Once `button` is let go, the move will end.
---@param button MouseButton The button you want to trigger the move. ---@param button MouseButton The button you want to trigger the move.
function window_module.begin_move(button) function window.begin_move(button)
SendMsg({ SendMsg({
WindowMoveGrab = { WindowMoveGrab = {
button = button, button = button,
@ -571,7 +574,7 @@ end
---This will start a window resize grab with the provided button on the window the ---This will start a window resize grab with the provided button on the window the
---pointer is currently hovering over. Once `button` is let go, the resize will end. ---pointer is currently hovering over. Once `button` is let go, the resize will end.
---@param button MouseButton ---@param button MouseButton
function window_module.begin_resize(button) function window.begin_resize(button)
SendMsg({ SendMsg({
WindowResizeGrab = { WindowResizeGrab = {
button = button, button = button,
@ -579,4 +582,4 @@ function window_module.begin_resize(button)
}) })
end end
return window_module return window

2
api/lua/window_rules.lua
View file

@ -220,7 +220,7 @@ function window_rules.add(...)
if rule.rule.output and type(rule.rule.output) == "table" then if rule.rule.output and type(rule.rule.output) == "table" then
rule.rule.output = rule rule.rule.output = rule
.rule .rule
.output--[[@as Output]] .output--[[@as OutputHandle]]
:name() :name()
end end