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

Merge pull request #61 from Ottatop/improve_api

Browse source 
Improve Lua API
This commit is contained in:
Ottatop 2023-08-28 21:22:40 -05:00 • committed by GitHub
commit 1e9f640884
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
16 changed files with 381 additions and 1077 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
.github/workflows/ldoc.yml vendored
View file

@ -24,6 +24,11 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Get ldoc_gen
uses: actions/checkout@v3
with:
repository: Ottatop/ldoc_gen
path: ./ldoc_gen
- name: Setup Lua
uses: leafo/gh-actions-lua@v8
with:
@ -32,12 +37,14 @@ jobs:
uses: leafo/gh-actions-luarocks@v4
- name: Setup dependencies
run: luarocks install ldoc
- name: Generate LDoc compatible code
run: cd ./ldoc_gen && cargo run -- -p ../api/lua
- name: Build docs
run: cd ./api/lua/doc && ldoc . && cd ../../..
run: cd ./ldoc_gen/.ldoc_gen && cp ../../api/lua/ldoc.css ../../api/lua/config.ld . && ldoc . && cd ../..
- name: Deploy
if: ${{ github.event_name == 'push' || github.event_name == 'pull_request' }}
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./api/lua/doc/doc
publish_dir: ./ldoc_gen/.ldoc_gen/doc
destination_dir: ${{ env.BRANCH_NAME }}

14
CONTRIBUTING.md
View file

@ -47,15 +47,6 @@ as well as documentation that follows the following format:
> ---@and_other_appropriate_annotations
> function thingy(param1, param2, ...) end
> ````
- You will also need to duplicate documentation for LDoc. This is unfortunate, but Lua LS documentation
exporting *really* isn't that great, and I haven't gotten around to finding a way to make it better.
- Place dummy functions of the same names in a respective file in the [`api/lua/doc`](api/lua/doc) folder.
- You can follow the above format with some minor changes:
- Replace `@param` with `@tparam` and swap the parameter name and type.
- Replace `@return` with `@treturn`.
- Instead of an H3 markdown section for examples, place them in `@usage` without the fences
(you may need to add a space between the beginning 3 dashes and any start-of-the-line comments).
- LDoc documentation will then be auto-generated on pull request.
- Format Rust code using [rustfmt](https://github.com/rust-lang/rustfmt) and the provided
[rustfmt.toml](rustfmt.toml) file.
- Format Lua code with [StyLua](https://github.com/JohnnyMorganz/StyLua) and the provided
@ -132,7 +123,7 @@ This includes the following:
> #### Important:
> **If you have a log, config, or similar that is over 50 lines, please either upload it to
> a place like [pastebin](https://pastebin.com/) and link to it or place the text in the
> a place like [pastebin](https://pastebin.com/) and link to it, attach a file, or place the text in the
> `<details>` tag, as shown below. The whitespace lines and indentation are important.**
> This helps both desktop and mobile users not have to scroll several miles to reach the next comment.
> > ````md
@ -170,8 +161,7 @@ If there are other labels you feel are appropriate, like https://github.com/Otta
for XWayland issues, add them as well. These labels help us filter out issues reliably.
### 5. Smash that `Submit new issue` button!
Congrats! You've helped Pinnacle move one step closer towards the summit!
Don't forget to ~~like and comment~~ star and watch the repo! :thumbsup:
We'll get to work on it soon (hopefully).
## Questions
Have a question about the future of the project? Perhaps you're writing your own

3
README.md
View file

@ -147,6 +147,9 @@ Lua = {
### API Documentation
You can find online documentation for the Lua API [here](https://ottatop.github.io/pinnacle/main).
This documentation is auto-generated from the provided LuaLS annotation through
[ldoc_gen](https://github.com/Ottatop/ldoc_gen), so there may be some errors as I work the kinks out.
Note that there are some missing things like the `Keys` table and `Layout` enum
as well as any function overloads, but these should be autocompleted through the language server.

1
api/lua/doc/config.ld → api/lua/config.ld
View file

@ -1,7 +1,6 @@
project = "Pinnacle"
format = "markdown"
description = "A very, VERY WIP Smithay-based Wayland compositor"
boilerplate = true
multimodule = true
no_space_before_args = true
style = true -- Use the ldoc.css in the current dir

17
api/lua/doc/input.lua
View file

@ -1,17 +0,0 @@
-- SPDX-License-Identifier: GPL-3.0-or-later
---Input and keybinds
---@module InputModule
local input_module = {}
---Set a keybind. If called with an already existing keybind, it gets replaced.
---
---### Example
--- -- Set `Super + Return` to open Alacritty
--- input.keybind({ "Super" }, input.keys.Return, function()
--- process.spawn("Alacritty")
--- end)
---@tparam Modifier[] modifiers Which modifiers need to be pressed for the keybind to trigger.
---@tparam Keys key The key for the keybind.
---@tparam function action What to do.
function input_module.keybind(modifiers, key, action) end

283
api/lua/doc/output.lua
View file

@ -1,283 +0,0 @@
-- SPDX-License-Identifier: GPL-3.0-or-later
---Output management
---@module OutputModule
local output_module = {}
---Get an output by its name.
---
---"Name" in this sense does not mean its model or manufacturer;
---rather, "name" is the name of the connector the output is connected to.
---This should be something like "HDMI-A-0", "eDP-1", or similar.
---
---@usage
---local monitor = output.get_by_name("DP-1")
---print(monitor.name) -- should print `DP-1`
---@tparam string name The name of the output.
---@treturn Output|nil output The output, or nil if none have the provided name.
function output_module.get_by_name(name) 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.
---This is something like "DELL E2416H" or whatever gibberish monitor manufacturers call their displays.
---@tparam string model The model of the output(s).
---@treturn Output[] outputs All outputs with this model.
function output_module.get_by_model(model) end
---Get outputs by their resolution.
---
---@tparam integer width The width of the outputs, in pixels.
---@tparam integer height The height of the outputs, in pixels.
---@treturn Output[] outputs All outputs with this resolution.
function output_module.get_by_res(width, height) end
---Get the currently focused output. This is currently implemented as the one with the cursor on it.
---
---This function may return nil, which means you may get a warning if you try to use it without checking for nil.
---Usually this function will not be nil unless you unplug all monitors, so instead of checking,
---you can ignore the warning by either forcing the type to be non-nil with an inline comment:
--- local op = output.get_focused() --[[@as Output]]
---or by disabling nil check warnings for the line:
--- local op = output.get_focused()
--- ---@diagnostic disable-next-line:need-check-nil
--- local tags_on_output = op:tags()
---Type checking done by Lua LS isn't perfect.
---Note that directly using the result of this function inline will *not* raise a warning, so be careful.
--- local tags = output.get_focused():tags() -- will NOT warn for nil
---@treturn Output|nil output The output, or nil if none are focused.
function output_module.get_focused() end
---Connect a function to be run on all current and future outputs.
---
---When called, `connect_for_all` will immediately run `func` with all currently connected outputs.
---If a new output is connected, `func` will also be called with it.
---
---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.
---@tparam function func The function that will be run. This takes an `Output` object.
function output_module.connect_for_all(func) end
---Get the output the specified tag is on.
---@tparam Tag tag
---@treturn Output|nil
---@see TagModule.output
---@see Tag.output
function output_module.get_for_tag(tag) end
---Get the specified output's make.
---@tparam Output op
---@treturn string|nil
---@see Output.make
function output_module.make(op) end
---Get the specified output's model.
---@tparam Output op
---@treturn string|nil
---@see Output.model
function output_module.model(op) end
---Get the specified output's location in the global space, in pixels.
---@tparam Output op
---@treturn table|nil { x: integer, y: integer }
---@see Output.loc
function output_module.loc(op) end
---Get the specified output's resolution in pixels.
---@tparam Output op
---@treturn table|nil { w: integer, h: integer }
---@see Output.res
function output_module.res(op) end
---Get the specified output's refresh rate in millihertz.
---For example, 60Hz will be returned as 60000.
---@tparam Output op
---@treturn integer|nil
---@see Output.refresh_rate
function output_module.refresh_rate(op) end
---Get the specified output's physical size in millimeters.
---@tparam Output op
---@treturn table|nil { w: integer, h: integer }
---@see Output.physical_size
function output_module.physical_size(op) end
---Get whether or not the specified output is focused. This is currently defined as having the cursor on it.
---@tparam Output op
---@treturn boolean|nil
---@see Output.focused
function output_module.focused(op) end
---Get the specified output's tags.
---@tparam Output op
---@see TagModule.get_on_output
---@see Output.tags
function output_module.tags(op) end
---Add tags to the specified output.
---@tparam Output op
---@tparam string ... The names of the tags you want to add. You can also pass in a table.
---@see TagModule.add
---@see Output.add_tags
function output_module.add_tags(op, ...) end
---Set the specified output's location.
---
---@usage
----- Assuming DP-1 is 2560x1440 and DP-2 is 1920x1080...
---local dp1 = output.get_by_name("DP-1")
---local dp2 = output.get_by_name("DP-2")
---
----- Place DP-2 to the left of DP-1, top borders aligned
---output.set_loc(dp1, { x = 1920, y = 0 })
---output.set_loc(dp2, { x = 0, y = 0 })
---
----- Do the same as above, with a different origin
---output.set_loc(dp1, { x = 0, y = 0 })
---output.set_loc(dp2, { x = -1920, y = 0 })
---
----- Place DP-2 to the right of DP-1, bottom borders aligned
---output.set_loc(dp1, { x = 0, y = 0 })
---output.set_loc(dp2, { x = 2560, y = 1440 - 1080 })
---@tparam Output op
---@tparam table loc A table of the form `{ x: integer?, y: integer? }`
function output_module.set_loc(op, loc) end
----------------------------------------------------------
---The output object.
---@classmod Output
local output = {}
---Get this output's name. This is something like "eDP-1" or "HDMI-A-0".
---@treturn string
function output:name() end
---Get all tags on this output.
---@treturn Tag[]
---@see OutputModule.tags
function output:tags() end
---Add tags to this output.
---@tparam string ... The names of the tags you want to add. You can also pass in a table.
---@see OutputModule.add_tags
function output:add_tags(...) end
---Get this output's make.
---@treturn string|nil
---@see OutputModule.make
function output:make() end
---Get this output's model.
---@treturn string|nil
---@see OutputModule.model
function output:model() end
---Get this output's location in the global space, in pixels.
---@treturn table|nil { x: integer, y: integer }
---@see OutputModule.loc
function output:loc() end
---Get this output's resolution in pixels.
---@treturn table|nil { w: integer, h: integer }
---@see OutputModule.res
function output:res() end
---Get this output's refresh rate in millihertz.
---For example, 60Hz will be returned as 60000.
---@treturn integer|nil
---@see OutputModule.refresh_rate
function output:refresh_rate() end
---Get this output's physical size in millimeters.
---@treturn table|nil { w: integer, h: integer }
---@see OutputModule.physical_size
function output:physical_size() end
---Get whether or not this output is focused. This is currently defined as having the cursor on it.
---@treturn boolean|nil
---@see OutputModule.focused
function output:focused() end
---Set this output's location.
---
---@usage
--- -- Assuming DP-1 is 2560x1440 and DP-2 is 1920x1080...
---local dp1 = output.get_by_name("DP-1")
---local dp2 = output.get_by_name("DP-2")
---
--- -- Place DP-2 to the left of DP-1, top borders aligned
---dp1:set_loc({ x = 1920, y = 0 })
---dp2:set_loc({ x = 0, y = 0 })
---
--- -- Do the same as above, with a different origin
---dp1:set_loc({ x = 0, y = 0 })
---dp2:set_loc({ x = -1920, y = 0 })
---
--- -- Place DP-2 to the right of DP-1, bottom borders aligned
---dp1:set_loc({ x = 0, y = 0 })
---dp2:set_loc({ x = 2560, y = 1440 - 1080 })
---@tparam table loc A table of the form `{ x: integer?, y: integer? }`
function output:set_loc(loc) end
---Set this output's location to the right of `op`.
---
--- top center bottom
--- ┌────────┬──────┐ ┌────────┐ ┌────────┐
--- │op │self │ │op ├──────┐ │op │
--- │ ├──────┘ │ │self │ │ ├──────┐
--- │ │ │ ├──────┘ │ │self │
--- └────────┘ └────────┘ └────────┴──────┘
---
---This will fail if `op` is an invalid output.
---@tparam Output op
---@tparam[opt="top"] string alignment One of `top`, `center`, or `bottom`. This is how you want to align the `self` output.
---@see Output.set_loc
function output:set_loc_right_of(op, alignment) end
---Set this output's location to the left of `op`.
---
--- top center bottom
--- ┌──────┬────────┐ ┌────────┐ ┌────────┐
--- │self │op │ ┌──────┤op │ │op │
--- └──────┤ │ │self │ │ ┌──────┤ │
--- │ │ └──────┤ │ │self │ │
--- └────────┘ └────────┘ └──────┴────────┘
---
---This will fail if `op` is an invalid output.
---@tparam Output op
---@tparam[opt="top"] string alignment One of `top`, `center`, or `bottom`. This is how you want to align the `self` output.
---@see Output.set_loc
function output:set_loc_left_of(op, alignment) end
---Set this output's location to the top of `op`.
---
--- left center right
--- ┌──────┐ ┌──────┐ ┌──────┐
--- │self │ │self │ │self │
--- ├──────┴─┐ ┌┴──────┴┐ ┌─┴──────┤
--- │op │ │op │ │op │
--- │ │ │ │ │ │
--- └────────┘ └────────┘ └────────┘
---
---This will fail if `op` is an invalid output.
---@tparam Output op
---@tparam[opt="left"] string alignment One of `left`, `center`, or `right`. This is how you want to align the `self` output.
---@see Output.set_loc
function output:set_loc_top_of(op, alignment) end
---Set this output's location to the bottom of `op`.
---
--- ┌────────┐ ┌────────┐ ┌────────┐
--- │op │ │op │ │op │
--- │ │ │ │ │ │
--- ├──────┬─┘ └┬──────┬┘ └─┬──────┤
--- │self │ │self │ │self │
--- └──────┘ └──────┘ └──────┘
--- left center right
---
---This will fail if `op` is an invalid output.
---@tparam Output op
---@tparam[opt="left"] string alignment One of `left`, `center`, or `right`. This is how you want to align the `self` output.
---@see Output.set_loc
function output:set_loc_bottom_of(op, alignment) end

35
api/lua/doc/pinnacle.lua
View file

@ -1,35 +0,0 @@
-- SPDX-License-Identifier: GPL-3.0-or-later
---The configuration entry point.
---@module PinnacleModule
local pinnacle = {
---Input and keybinds
---@tparam InputModule input
---@see InputModule
input = nil,
---Window management
---@tparam WindowModule window
---@see WindowModule
window = nil,
---Process management
---@tparam ProcessModule process
---@see ProcessModule
process = nil,
---Tag management
---@tparam TagModule tag
---@see TagModule
tag = nil,
---Output management
---@tparam OutputModule output
---@see OutputModule
output = nil,
}
---Quit Pinnacle.
function pinnacle.quit() end
---Configure Pinnacle.
---
---You should put mostly eveything into the config_func to avoid invalid state.
---@tparam function config_func A function that takes in the `Pinnacle` table.
function pinnacle.setup(config_func) end

29
api/lua/doc/process.lua
View file

@ -1,29 +0,0 @@
-- SPDX-License-Identifier: GPL-3.0-or-later
---This file houses LDoc documentation with dummy functions.---
---Process management
---@module ProcessModule
local process_module = {}
---Spawn a process with an optional callback for its stdout, stderr, and exit information.
---
---`callback` has the following parameters:<br>
--- - `stdout` - The process's stdout printed this line.<br>
--- - `stderr` - The process's stderr printed this line.<br>
--- - `exit_code` - The process exited with this code.<br>
--- - `exit_msg` - The process exited with this message.<br>
---@tparam string|string[] command The command as one whole string or a table of each of its arguments
---@tparam function callback A callback to do something whenever the process's stdout or stderr print a line, or when the process exits.
function process_module.spawn(command, callback) end
---Spawn a process only if it isn't already running, with an optional callback for its stdout, stderr, and exit information.
---
---`callback` has the following parameters:<br>
--- - `stdout` - The process's stdout printed this line.<br>
--- - `stderr` - The process's stderr printed this line.<br>
--- - `exit_code` - The process exited with this code.<br>
--- - `exit_msg` - The process exited with this message.<br>
---@tparam string|string[] command The command as one whole string or a table of each of its arguments
---@tparam function callback A callback to do something whenever the process's stdout or stderr print a line, or when the process exits.
function process_module.spawn_once(command, callback) end

154
api/lua/doc/tag.lua
View file

@ -1,154 +0,0 @@
-- SPDX-License-Identifier: GPL-3.0-or-later
---Tag management
---@module TagModule
local tag_module = {}
---Add tags to the specified output.
---
---@usage
---local op = output.get_by_name("DP-1")
---if op ~= nil then
--- tag.add(op, "1", "2", "3", "4", "5") -- Add tags with names 1-5
---end
--- -- You can also pass in a table.
---local tags = {"Terminal", "Browser", "Code", "Potato", "Email"}
---tag.add(op, tags) -- Add tags with those names
---@tparam Output output The output you want these tags to be added to.
---@tparam string ... The names of the new tags you want to add.
---@see Output.add_tags
function tag_module.add(output, ...) end
---Toggle a tag on the specified output. If `output` isn't specified, toggle it on the currently focused output instead.
---
---@usage
--- -- Assuming all tags are toggled off...
---local op = output.get_by_name("DP-1")
---tag.toggle("1", op)
---tag.toggle("2", op)
--- -- will cause windows on both tags 1 and 2 to be displayed at the same time.
---@tparam string name The name of the tag.
---@tparam ?Output output The output.
---@see Tag.toggle
function tag_module.toggle(name, output) end
---Switch to a tag on the specified output, deactivating any other active tags on it.
---If `output` is not specified, this uses the currently focused output instead.
---Alternatively, provide a tag object instead of a name and output.
---
---This is used to replicate what a traditional workspace is on some other Wayland compositors.
---
---@usage
--- -- Switches to and displays *only* windows on tag `3` on the focused output.
---tag.switch_to("3")
---@tparam string name The name of the tag.
---@tparam ?Output output The output.
---@see Tag.switch_to
function tag_module.switch_to(name, output) end
---Set a layout for the tag on the specified output. If no output is provided, set it for the tag on the currently focused one.
---Alternatively, provide a tag object instead of a name and output.
---
---@usage
--- -- Set tag `1` on `DP-1` to the `Dwindle` layout
--- tag.set_layout("1", "Dwindle", output.get_by_name("DP-1"))
---
--- -- Do the same as above. Note: if you have more than one tag named `1` then this picks the first one.
---local t = tag.get_by_name("1")[1]
---tag.set_layout(t, "Dwindle")
---@tparam string name The name of the tag.
---@tparam Layout layout The layout.
---@tparam ?Output output The output.
---@see Tag.set_layout
function tag_module.set_layout(name, layout, output) end
---Get all tags on the specified output.
---
---@usage
---local op = output.get_focused()
---if op ~= nil then
--- local tags = tag.get_on_output(op) -- All tags on the focused output
---end
---@tparam Output output
---@treturn Tag[]
---@see Output.tags
function tag_module.get_on_output(output) end
---Get all tags with this name across all outputs.
---
---@usage
--- -- Given one monitor with the tags "OBS", "OBS", "VSCode", and "Spotify"...
---local tags = tag.get_by_name("OBS")
--- -- ...will have 2 tags in `tags`, while...
---local no_tags = tag.get_by_name("Firefox")
--- -- ...will have `no_tags` be empty.
---@tparam string name The name of the tag(s) you want.
---@treturn Tag[]
function tag_module.get_by_name(name) end
---Get all tags across all outputs.
---
---@usage
--- -- With two monitors with the same tags: "1", "2", "3", "4", and "5"...
---local tags = tag.get_all()
--- -- ...`tags` should have 10 tags, with 5 pairs of those names across both outputs.
---@treturn Tag[]
function tag_module.get_all() end
---Get the specified tag's name.
---
---@usage
--- -- Assuming the tag `Terminal` exists...
---print(tag.name(tag.get_by_name("Terminal")[1]))
--- -- ...should print `Terminal`.
---@tparam Tag t
---@treturn string|nil
---@see Tag.name
function tag_module.name(t) end
---Get whether or not the specified tag is active.
---@tparam Tag t
---@treturn boolean|nil
---@see Tag.active
function tag_module.active(t) end
---Get the output the specified tag is on.
---@tparam Tag t
---@treturn Output|nil
---@see OutputModule.get_for_tag
---@see Tag.output
function tag_module.output(t) end
-----------------------------------------------------
---The tag object.
---@classmod Tag
local tag = {}
---Get this tag's active status.
---@treturn boolean|nil active `true` if the tag is active, `false` if not, and `nil` if the tag doesn't exist.
---@see TagModule.active
function tag:active() end
---Get this tag's name.
---@treturn string|nil name The name of this tag, or nil if it doesn't exist.
---@see TagModule.name
function tag:name() end
---Get this tag's output.
---@treturn Output|nil output The output this tag is on, or nil if the tag doesn't exist.
---@see TagModule.output
function tag:output() end
---Switch to this tag.
---@see TagModule.switch_to
function tag:switch_to() end
---Toggle this tag.
---@see TagModule.toggle
function tag:toggle() end
---Set this tag's layout.
---@tparam Layout layout
---@see TagModule.set_layout
function tag:set_layout(layout) end

315
api/lua/doc/window.lua
View file

@ -1,315 +0,0 @@
-- SPDX-License-Identifier: GPL-3.0-or-later
---Window management
---@module WindowModule
local window_module = {}
---Get all windows with the specified class (usually the name of the application).
---@tparam string class The class. For example, Alacritty's class is "Alacritty".
---@treturn Window[]
function window_module.get_by_class(class) end
---Get all windows with the specified title.
---@tparam string title The title.
---@treturn Window[]
function window_module.get_by_title(title) end
---Get the currently focused window.
---@treturn Window|nil
function window_module.get_focused() end
---Get all windows.
---@treturn Window[]
function window_module.get_all() end
---Toggle the tag with the given name and (optional) output for the specified window.
---You can also provide a tag object instead of a name and output.
---@tparam Window w
---@tparam string name
---@tparam ?Output output
---@see Window.toggle_tag
function window_module.toggle_tag(w, name, output) end
---Move the specified window to the tag with the given name and (optional) output.
---You can also provide a tag object instead of a name and output.
---@tparam Window w
---@tparam string name
---@tparam ?Output output
---@see Window.move_to_tag
function window_module.move_to_tag(w, name, output) end
---Set the specified window's size.
---
---@usage
---local win = window.get_focused()
---if win ~= nil then
--- window.set_size(win, { w = 500, h = 500 }) -- make the window square and 500 pixels wide/tall
--- window.set_size(win, { h = 300 }) -- keep the window's width but make it 300 pixels tall
--- window.set_size(win, {}) -- do absolutely nothing useful
---end
---@tparam Window win
---@tparam table size A table of the form { w: integer?, h: integer? }
---@see Window.set_size
function window_module.set_size(win, size) end
---Close the specified window.
---
---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.
---
---@usage
---local win = window.get_focused()
---if win ~= nil then
--- window.close(win) -- close the currently focused window
---end
---@tparam Window win
---@see Window.close
function window_module.close(win) end
---Get the specified window's size.
---
---@usage
--- -- With a 4K monitor, given a focused fullscreen window `win`...
---local size = window.size(win)
--- -- ...should have size equal to `{ w = 3840, h = 2160 }`.
---@tparam Window win
---@treturn table|nil size The size of the window in the form { w: integer, h: integer }, or nil if it doesn't exist.
---@see Window.size
function window_module.size(win) end
---Get the specified window's location in the global space.
---
---Think of your monitors as being laid out on a big sheet.
---The top left of the sheet if you trim it down is (0, 0).
---The location of this window is relative to that point.
---
---@usage
--- -- With two 1080p monitors side by side and set up as such,
--- -- if a window `win` is fullscreen on the right one...
---local loc = window.loc(win)
--- -- ...should have loc equal to `{ x = 1920, y = 0 }`.
---@tparam Window win
---@treturn table|nil loc The location of the window in the form { x: integer, y: integer }, or nil if it's not on-screen or alive.
---@see Window.loc
function window_module.loc(win) end
---Get the specified window's class. This is usually the name of the application.
---
---@usage
--- -- With Alacritty focused...
---local win = window.get_focused()
---if win ~= nil then
--- print(window.class(win))
---end
--- -- ...should print "Alacritty".
---@tparam Window win
---@treturn string|nil class This window's class, or nil if it doesn't exist.
---@see Window.class
function window_module.class(win) end
---Get the specified window's title.
---
---@usage
--- -- With Alacritty focused...
---local win = window.get_focused()
---if win ~= nil then
--- print(window.title(win))
---end
--- -- ...should print the directory Alacritty is in or what it's running (what's in its title bar).
---@tparam Window win
---@treturn string|nil title This window's title, or nil if it doesn't exist.
---@see Window.title
function window_module.title(win) end
---Toggle `win`'s floating status.
---
---When used on a floating window, this will change it to tiled, and vice versa.
---
---When used on a fullscreen or maximized window, this will still change its
---underlying floating/tiled status.
---@tparam Window win
function window_module.toggle_floating(win) end
---Toggle `win`'s fullscreen status.
---
---When used on a fullscreen window, this will change the window back to
---floating or tiled.
---
---When used on a non-fullscreen window, it becomes fullscreen.
---@tparam Window win
function window_module.toggle_fullscreen(win) end
---Toggle `win`'s maximized status.
---
---When used on a maximized window, this will change the window back to
---floating or tiled.
---
---When used on a non-maximized window, it becomes maximized.
---@tparam Window win
function window_module.toggle_maximized(win) end
---Get whether or not this window is focused.
---
---@usage
---local win = window.get_focused()
---if win ~= nil then
--- print(window.focused(win)) -- Should print `true`
---end
---@tparam Window win
---@treturn boolean|nil floating `true` if it's floating, `false` if it's tiled, or nil if it doesn't exist.
---@see Window.focused
function window_module.focused(win) end
---Get whether or not `win` is floating (true) or tiled (false).
---@treturn boolean|nil
function window_module.floating(win) end
---Get whether or not `win` is fullscreen.
---@treturn boolean|nil
function window_module.fullscreen(win) end
---Get whether or not `win` is maximized.
---@treturn boolean|nil
function window_module.maximized(win) end
--------------------------------------------------------
---The window object.
---@classmod Window
local window = {}
---Set this window's size.
---
---@usage
---window.get_focused():set_size({ w = 500, h = 500 }) -- make the window square and 500 pixels wide/tall
---window.get_focused():set_size({ h = 300 }) -- keep the window's width but make it 300 pixels tall
---window.get_focused():set_size({}) -- do absolutely nothing useful
---@tparam table size A table of the form { `w`: `integer?`, `h`: `integer?` }
---@see WindowModule.set_size
function window:set_size(size) end
---Move this window to a tag, removing all other ones.
---
---@usage
--- -- With the focused window on tags 1, 2, 3, and 4...
---window.get_focused():move_to_tag("5")
--- -- ...will make the window only appear on tag 5.
---@tparam string name
---@tparam ?Output output
---@see WindowModule.move_to_tag
function window:move_to_tag(name, output) end
---Toggle the specified tag for this window.
---
---Note: toggling off all tags currently makes a window not response to layouting.
---
---@usage
--- -- With the focused window only on tag 1...
---window.get_focused():toggle_tag("2")
--- -- ...will also make the window appear on tag 2.
---@tparam string name
---@tparam ?Output output
---@see WindowModule.toggle_tag
function window:toggle_tag(name, output) end
---Close this window.
---
---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.
---
---@usage
---window.get_focused():close() -- close the currently focused window
---@see WindowModule.close
function window:close() end
---Get this window's size.
---
---@usage
--- -- With a 4K monitor, given a focused fullscreen window...
---local size = window.get_focused():size()
--- -- ...should have size equal to `{ w = 3840, h = 2160 }`.
---@treturn table|nil size The size of the window in the form { `w`: `integer`, `h`: `integer` }, or nil if it doesn't exist.
---@see WindowModule.size
function window:size() end
---Get this window's location in the global space.
---
---Think of your monitors as being laid out on a big sheet.
---The top left of the sheet if you trim it down is (0, 0).
---The location of this window is relative to that point.
---
---@usage
--- -- With two 1080p monitors side by side and set up as such,
--- -- if a window is fullscreen on the right one...
---local loc = that_window:loc()
--- -- ...should have loc equal to `{ x = 1920, y = 0 }`.
---@treturn table|nil loc The location of the window in the form { `x`: `integer`, `y`: `integer` }, or nil if it's not on-screen or alive.
---@see WindowModule.loc
function window:loc() end
---Get this window's class. This is usually the name of the application.
---
---@usage
--- -- With Alacritty focused...
---print(window.get_focused():class())
--- -- ...should print "Alacritty".
---@treturn string|nil class This window's class, or nil if it doesn't exist.
---@see WindowModule.class
function window:class() end
---Get this window's title.
---
---@usage
--- -- With Alacritty focused...
---print(window.get_focused():title())
--- -- ...should print the directory Alacritty is in or what it's running (what's in its title bar).
---@treturn string|nil title This window's title, or nil if it doesn't exist.
---@see WindowModule.title
function window:title() end
---Toggle this window's floating status.
---
---When used on a floating window, this will change it to tiled, and vice versa.
---
---When used on a fullscreen or maximized window, this will still change its
---underlying floating/tiled status.
---@tparam Window win
function window:toggle_floating(win) end
---Toggle this window's fullscreen status.
---
---When used on a fullscreen window, this will change the window back to
---floating or tiled.
---
---When used on a non-fullscreen window, it becomes fullscreen.
---@tparam Window win
function window:toggle_fullscreen(win) end
---Toggle this window's maximized status.
---
---When used on a maximized window, this will change the window back to
---floating or tiled.
---
---When used on a non-maximized window, it becomes maximized.
---@tparam Window win
function window:toggle_maximized(win) end
---Get whether or not this window is focused.
---
---@usage
---print(window.get_focused():focused()) -- should print `true`.
---@treturn boolean|nil floating `true` if it's focused, `false` if it's tiled, or nil if it doesn't exist.
---@see WindowModule.focused
function window:focused() end
---Get whether or not this window is floating (true) or tiled (false).
---@treturn boolean|nil
function window:floating() end
---Get whether or not this window is fullscreen.
---@treturn boolean|nil
function window:fullscreen() end
---Get whether or not this window is maximized.
---@treturn boolean|nil
function window:maximized() end

2
api/lua/example_config.lua
View file

@ -90,7 +90,7 @@ require("pinnacle").setup(function(pinnacle)
op:add_tags("1", "2", "3", "4", "5")
-- Same as tag.add(op, "1", "2", "3", "4", "5")
tag.toggle("1", op)
tag.toggle({ "1", op })
end)
---@type Layout[]

0
api/lua/doc/ldoc.css → api/lua/ldoc.css
View file

106
api/lua/output.lua
View file

@ -1,12 +1,35 @@
-- SPDX-License-Identifier: GPL-3.0-or-later
---Output management.
---
---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.
---@class OutputModule
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 = {}
---@param params Output|string
---@return Output|nil
local function create_output_from_params(params)
if type(params) == "table" then
return params
end
return output_module.get_by_name(params --[[@as string]])
end
---Create a new output object from a name.
---The name is the unique identifier for each output.
---@param name string
@ -440,10 +463,16 @@ end
---------Fully-qualified functions
---Get the specified output's make.
---@param op Output
---@param op Output|string The name of the output or an output object.
---@return string|nil
---@see Output.make — The corresponding object method
function output_module.make(op)
local op = create_output_from_params(op)
if op == nil then
return nil
end
local response = Request({
GetOutputProps = {
output_name = op:name(),
@ -454,10 +483,16 @@ function output_module.make(op)
end
---Get the specified output's model.
---@param op Output
---@param op Output|string The name of the output or an output object.
---@return string|nil
---@see Output.model — The corresponding object method
function output_module.model(op)
local op = create_output_from_params(op)
if op == nil then
return nil
end
local response = Request({
GetOutputProps = {
output_name = op:name(),
@ -468,10 +503,16 @@ function output_module.model(op)
end
---Get the specified output's location in the global space, in pixels.
---@param op Output
---@param op Output|string The name of the output or an output object.
---@return { x: integer, y: integer }|nil
---@see Output.loc — The corresponding object method
function output_module.loc(op)
local op = create_output_from_params(op)
if op == nil then
return nil
end
local response = Request({
GetOutputProps = {
output_name = op:name(),
@ -486,10 +527,16 @@ function output_module.loc(op)
end
---Get the specified output's resolution in pixels.
---@param op Output
---@param op Output|string The name of the output or an output object.
---@return { w: integer, h: integer }|nil
---@see Output.res — The corresponding object method
function output_module.res(op)
local op = create_output_from_params(op)
if op == nil then
return nil
end
local response = Request({
GetOutputProps = {
output_name = op:name(),
@ -505,10 +552,16 @@ end
---Get the specified output's refresh rate in millihertz.
---For example, 60Hz will be returned as 60000.
---@param op Output
---@param op Output|string The name of the output or an output object.
---@return integer|nil
---@see Output.refresh_rate — The corresponding object method
function output_module.refresh_rate(op)
local op = create_output_from_params(op)
if op == nil then
return nil
end
local response = Request({
GetOutputProps = {
output_name = op:name(),
@ -519,10 +572,16 @@ function output_module.refresh_rate(op)
end
---Get the specified output's physical size in millimeters.
---@param op Output
---@param op Output|string The name of the output or an output object.
---@return { w: integer, h: integer }|nil
---@see Output.physical_size — The corresponding object method
function output_module.physical_size(op)
local op = create_output_from_params(op)
if op == nil then
return nil
end
local response = Request({
GetOutputProps = {
output_name = op:name(),
@ -537,10 +596,16 @@ function output_module.physical_size(op)
end
---Get whether or not the specified output is focused. This is currently defined as having the cursor on it.
---@param op Output
---@param op Output|string The name of the output or an output object.
---@return boolean|nil
---@see Output.focused — The corresponding object method
function output_module.focused(op)
local op = create_output_from_params(op)
if op == nil then
return nil
end
local response = Request({
GetOutputProps = {
output_name = op:name(),
@ -551,20 +616,33 @@ function output_module.focused(op)
end
---Get the specified output's tags.
---@param op Output
---@param op Output|string The name of the output or an output object.
---@return Tag[]
---@see TagModule.get_on_output — The called function
---@see Output.tags — The corresponding object method
function output_module.tags(op)
local op = create_output_from_params(op)
if op == nil then
return {}
end
return require("tag").get_on_output(op)
end
---Add tags to the specified output.
---@param op Output
---@param op Output|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.
---@overload fun(op: Output, tag_names: string[])
---@overload fun(op: Output|string, tag_names: string[])
---@see TagModule.add — The called function
---@see Output.add_tags — The corresponding object method
function output_module.add_tags(op, ...)
local op = create_output_from_params(op)
if op == nil then
return
end
require("tag").add(op, ...)
end
@ -588,9 +666,15 @@ end
---output.set_loc(dp1, { x = 0, y = 0 })
---output.set_loc(dp2, { x = 2560, y = 1440 - 1080 })
---```
---@param op Output
---@param op Output|string The name of the output or an output object.
---@param loc { x: integer?, y: integer? }
function output_module.set_loc(op, loc)
local op = create_output_from_params(op)
if op == nil then
return
end
SendMsg({
SetOutputLocation = {
output_name = op:name(),

11
api/lua/pinnacle.lua
View file

@ -5,6 +5,7 @@ local msgpack = require("msgpack")
local SOCKET_PATH = os.getenv("PINNACLE_SOCKET") or "/tmp/pinnacle_socket"
---@nodoc
---From https://gist.github.com/stuby/5445834#file-rprint-lua
---rPrint(struct, [limit], [indent]) Recursively print arbitrary data.
--- Set limit (default 100) to stanch infinite loops.
@ -71,10 +72,8 @@ local function read_exact(socket_fd, count)
return data
end
---@class Pinnacle
---The main Pinnacle table, where all of the config options come from.
---
---While you *can* import the fields directly, all config must be in the `setup` function, so you might as well just use the provided table. The ability to directly `require` fields may be dropped in the future.
---@class PinnacleModule
---The entry point to all configuration.
local pinnacle = {
---Key and mouse binds
input = require("input"),
@ -94,8 +93,8 @@ function pinnacle.quit()
end
---Configure Pinnacle. You should put mostly eveything into the config_func to avoid invalid state.
---The function takes one argument: the Pinnacle table, which is how you'll access all of the available config options.
---@param config_func fun(pinnacle: Pinnacle)
---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)
function pinnacle.setup(config_func)
---@type integer
local socket_fd = assert(

304
api/lua/tag.lua
View file

@ -1,5 +1,34 @@
-- SPDX-License-Identifier: GPL-3.0-or-later
---Tag management.
---
---This module provides utilities for creating and manipulating tags.
---
---A tag is a sort of marker for each of your windows. It allows you to present windows in ways that
---traditional workspaces cannot.
---
---More specifically:
--- - A window can have multiple tags.
--- - This means that you can have one window show up across multiple "workspaces" if you come
--- something like i3.
--- - An output can display multiple tags at once.
--- - This allows you to toggle a tag and have windows on both tags display at once.
--- 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.
---
---Many of the functions in this module take Tag|TagTable|TagTableNamed|string.
---This is a convenience so you don't have to get a tag object every time you want to do
---something with tags.
---
---Instead, you can pass in either:
--- - A string of the tag's name (ex. "1")
--- - 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") })
--- - 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" })
--- - This is simply for those who want more clarity in their config.
---
---If you need to get tags beyond the first with the same name, use a `get` function and find what you need.
---@class TagModule
local tag_module = {}
@ -12,10 +41,103 @@ 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.
---| "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 { [1]: string, [2]: (string|Output)? }
---@alias TagTableNamed { name: string, output: (string|Output)? }
---A tag object.
---
---This can be retrieved through the various `get` functions in the `TagModule`.
---@classmod
---@class Tag
---@field private _id integer The internal id of this tag.
local tag = {}
---@nodoc
---***You probably don't need to use this function.***
---
---Create a tag from `Tag|TagTable|TagTableNamed|string`.
---@param tb Tag|TagTable|TagTableNamed|string
---@return Tag|nil
function tag_module.create_tag_from_params(tb)
-- If creating from a tag object, just return the obj
if tb.id then
return tb --[[@as Tag]]
end
-- string passed in
if type(tb) == "string" then
local op = require("output").get_focused()
if op == nil then
return nil
end
local tags = tag_module.get_by_name(tb)
for _, t in pairs(tags) do
if t:output() and t:output():name() == op:name() then
return t
end
end
return nil
end
-- TagTable was passed in
local tag_name = tb[1]
if type(tag_name) == "string" then
local op = tb[2]
if op == nil then
local o = require("output").get_focused()
if o == nil then
return nil
end
op = o
elseif type(op) == "string" then
local o = require("output").get_by_name(op)
if o == nil then
return nil
end
op = o
end
local tags = tag_module.get_by_name(tag_name)
for _, t in pairs(tags) do
if t:output() and t:output():name() == op:name() then
return t
end
end
return nil
end
-- TagTableNamed was passed in
local tb = tb --[[@as TagTableNamed]]
local tag_name = tb.name
local op = tb.output
if op == nil then
local o = require("output").get_focused()
if o == nil then
return nil
end
op = o
elseif type(op) == "string" then
local o = require("output").get_by_name(op)
if o == nil then
return nil
end
op = o
end
local tags = tag_module.get_by_name(tag_name)
for _, t in pairs(tags) do
if t:output() and t:output():name() == op:name() then
return t
end
end
return nil
end
---Create a tag from an id.
---The id is the unique identifier for each tag.
---@param id TagId
@ -122,142 +244,142 @@ function tag_module.add(output, ...)
end
end
---Toggle a tag on the specified output. If `output` isn't specified, toggle it on the currently focused output instead.
---Toggle a tag on the specified output. If the output isn't specified, toggle it on the currently focused output instead.
---
---### Example
---
---```lua
----- Assuming all tags are toggled off...
---local op = output.get_by_name("DP-1")
---tag.toggle("1", op)
---tag.toggle("2", op)
----- will cause windows on both tags 1 and 2 to be displayed at the same time.
---
---tag.toggle("1") -- Toggle tag 1 on the focused output
---tag.toggle({ "1" }) -- Same as above
---
---tag.toggle({ "1", "DP-1" }) -- Toggle tag 1 on DP-1
---tag.toggle({ "1", op }) -- Same as above
---
----- Verbose versions of the two above
---tag.toggle({ name = "1", output = "DP-1" })
---tag.toggle({ name = "1", output = op })
---
----- Using a tag object
---local t = tag.get_by_name("1")[1] -- `t` is the first tag with the name "1"
---tag.toggle(t)
---```
---@param name string The name of the tag.
---@param output Output? The output.
---@overload fun(t: Tag)
---@param t Tag|TagTable|TagTableNamed|string
---@see Tag.toggle — The corresponding object method
function tag_module.toggle(name, output)
if type(name) == "table" then
function tag_module.toggle(t)
local t = tag_module.create_tag_from_params(t)
if t then
SendMsg({
ToggleTag = {
tag_id = name--[[@as Tag]]:id(),
tag_id = t:id(),
},
})
return
end
local output = output or require("output").get_focused()
if output == nil then
return
end
print("before tag_global.get_by_name")
local tags = tag_module.get_by_name(name)
print("after tag_global.get_by_name")
for _, t in pairs(tags) do
if t:output() and t:output():name() == output:name() then
SendMsg({
ToggleTag = {
tag_id = t:id(),
},
})
return
end
end
end
---Switch to a tag on the specified output, deactivating any other active tags on it.
---If `output` is not specified, this uses the currently focused output instead.
---Alternatively, provide a tag object instead of a name and output.
---If the output is not specified, this uses the currently focused output instead.
---
---This is used to replicate what a traditional workspace is on some other Wayland compositors.
---
---### Examples
---```lua
----- Switches to and displays *only* windows on tag `3` on the focused output.
---tag.switch_to("3")
---local op = output.get_by_name("DP-1")
---
---tag.switch_to("1") -- Switch to tag 1 on the focused output
---tag.switch_to({ "1" }) -- Same as above
---
---tag.switch_to({ "1", "DP-1" }) -- Switch to tag 1 on DP-1
---tag.switch_to({ "1", op }) -- Same as above
---
----- Verbose versions of the two above
---tag.switch_to({ name = "1", output = "DP-1" })
---tag.switch_to({ name = "1", output = op })
---
----- Using a tag object
---local t = tag.get_by_name("1")[1] -- `t` is the first tag with the name "1"
---tag.switch_to(t)
---```
---@param name string The name of the tag.
---@param output Output? The output.
---@overload fun(t: Tag)
---@param t Tag|TagTable|TagTableNamed|string
---@see Tag.switch_to — The corresponding object method
function tag_module.switch_to(name, output)
if type(name) == "table" then
function tag_module.switch_to(t)
local t = tag_module.create_tag_from_params(t)
if t then
SendMsg({
SwitchToTag = {
tag_id = name--[[@as Tag]]:id(),
tag_id = t:id(),
},
})
return
end
local output = output or require("output").get_focused()
if output == nil then
return
end
local tags = tag_module.get_by_name(name)
for _, t in pairs(tags) do
if t:output() and t:output():name() == output:name() then
SendMsg({
SwitchToTag = {
tag_id = t:id(),
},
})
return
end
end
end
---Set a layout for the tag on the specified output. If no output is provided, set it for the tag on the currently focused one.
---Alternatively, provide a tag object instead of a name and output.
---
---### Examples
---```lua
----- Set tag `1` on `DP-1` to the `Dwindle` layout
---tag.set_layout("1", "Dwindle", output.get_by_name("DP-1"))
---local op = output.get_by_name("DP-1")
---
----- Do the same as above. Note: if you have more than one tag named `1` then this picks the first one.
---local t = tag.get_by_name("1")[1]
---tag.set_layout("1", "Dwindle") -- Set tag 1 on the focused output to "Dwindle"
---tag.set_layout({ "1" }, "Dwindle") -- Same as above
---
---tag.set_layout({ "1", "DP-1" }, "Dwindle") -- Set tag 1 on DP-1 to "Dwindle"
---tag.set_layout({ "1", op }, "Dwindle") -- Same as above
---
----- Verbose versions of the two above
---tag.set_layout({ name = "1", output = "DP-1" }, "Dwindle")
---tag.set_layout({ name = "1", output = op }, "Dwindle")
---
----- Using a tag object
---local t = tag.get_by_name("1")[1] -- `t` is the first tag with the name "1"
---tag.set_layout(t, "Dwindle")
---```
---@param name string The name of the tag.
---
---@param t Tag|TagTable|TagTableNamed|string
---@param layout Layout The layout.
---@param output Output? The output.
---@overload fun(t: Tag, layout: Layout)
---@see Tag.set_layout — The corresponding object method
function tag_module.set_layout(name, layout, output)
if type(name) == "table" then
function tag_module.set_layout(t, layout)
local t = tag_module.create_tag_from_params(t)
if t then
SendMsg({
SetLayout = {
tag_id = name--[[@as Tag]]:id(),
tag_id = t:id(),
layout = layout,
},
})
return
end
end
local output = output or require("output").get_focused()
if output == nil then
return
end
local tags = tag_module.get_by_name(name)
for _, t in pairs(tags) do
if t:output() and t:output():name() == output:name() then
SendMsg({
SetLayout = {
tag_id = t:id(),
layout = layout,
},
})
return
end
end
---Get a tag with the specified name and optional output.
---
---If the output isn't specified, the focused one is used.
---
---If you have duplicate tags on an output, this returns the first one.
---If you need access to all duplicates, use `tag.get_on_output`, `tag.get_by_name`, or `tag.get_all`
---and filter for what you need.
---
---### Examples
---```lua
---local t = tag.get("1")
---local t = tag.get({ "1", "HDMI-A-0" })
---local t = tag.get({ name = "3" })
---
---local op = output.get_by_name("DP-2")
---if op ~= nil then
--- local t = tag.get({ name = "Code", output = op })
---end
---```
---@param params TagTable|TagTableNamed|string
---@return Tag|nil
---
---@see TagModule.get_on_output
---@see TagModule.get_by_name
---@see TagModule.get_all
function tag_module.get(params)
return tag_module.create_tag_from_params(params)
end
---Get all tags on the specified output.

173
api/lua/window.lua
View file

@ -1,8 +1,18 @@
-- SPDX-License-Identifier: GPL-3.0-or-later
---Window management.
---
---This module helps you deal with setting windows to fullscreen and maximized, setting their size,
---moving them between tags, and various other actions.
---@class WindowModule
local window_module = {}
---A window object.
---
---This is a representation of an application window to the config process.
---
---You can retrieve windows through the various `get` function in the `WindowModule`.
---@classmod
---@class Window
---@field private _id integer The internal id of this window
local window = {}
@ -30,12 +40,8 @@ end
---Set this window's size.
---
---### Examples
---```lua
---window.get_focused():set_size({ w = 500, h = 500 }) -- make the window square and 500 pixels wide/tall
---window.get_focused():set_size({ h = 300 }) -- keep the window's width but make it 300 pixels tall
---window.get_focused():set_size({}) -- do absolutely nothing useful
---```
---See `WindowModule.set_size` for examples.
---
---@param size { w: integer?, h: integer? }
---@see WindowModule.set_size — The corresponding module function
function window:set_size(size)
@ -44,36 +50,23 @@ end
---Move this window to a tag, removing all other ones.
---
---### Example
---```lua
----- With the focused window on tags 1, 2, 3, and 4...
---window.get_focused():move_to_tag("5")
----- ...will make the window only appear on tag 5.
---```
---@param name string
---@param output Output?
---@overload fun(self: self, t: Tag)
---See `WindowModule.move_to_tag` for examples.
---
---@param t Tag|TagTable|TagTableNamed|string
---@see WindowModule.move_to_tag — The corresponding module function
function window:move_to_tag(name, output)
window_module.move_to_tag(self, name, output)
function window:move_to_tag(t)
window_module.move_to_tag(self, t)
end
---Toggle the specified tag for this window.
---
---Note: toggling off all tags currently makes a window not response to layouting.
---Note: toggling off all tags currently makes a window not respond to layouting.
---
---### Example
---```lua
----- With the focused window only on tag 1...
---window.get_focused():toggle_tag("2")
----- ...will also make the window appear on tag 2.
---```
---@param name string
---@param output Output?
---@overload fun(self: self, t: Tag)
---See `WindowModule.toggle_tag` for examples.
---@param t Tag|TagTable|TagTableNamed|string
---@see WindowModule.toggle_tag — The corresponding module function
function window:toggle_tag(name, output)
window_module.toggle_tag(self, name, output)
function window:toggle_tag(t)
window_module.toggle_tag(self, t)
end
---Close this window.
@ -81,10 +74,7 @@ end
---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.
---
---### Example
---```lua
---window.get_focused():close() -- close the currently focused window
---```
---See `WindowModule.close` for examples.
---@see WindowModule.close — The corresponding module function
function window:close()
window_module.close(self)
@ -92,12 +82,7 @@ end
---Get this window's size.
---
---### Example
---```lua
----- With a 4K monitor, given a focused fullscreen window...
---local size = window.get_focused():size()
----- ...should have size equal to `{ w = 3840, h = 2160 }`.
---```
---See `WindowModule.size` for examples.
---@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
function window:size()
@ -107,16 +92,12 @@ end
---Get this window's location in the global space.
---
---Think of your monitors as being laid out on a big sheet.
---The top left of the sheet if you trim it down is (0, 0).
---The location of this window is relative to that point.
---The location of this window is relative inside the sheet.
---
---### Example
---```lua
----- With two 1080p monitors side by side and set up as such,
----- if a window is fullscreen on the right one...
---local loc = that_window:loc()
----- ...should have loc equal to `{ x = 1920, y = 0 }`.
---```
---If you don't set the location of your monitors, they will start at (0, 0)
---and extend rightward with their tops aligned.
---
---See `WindowModule.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.
---@see WindowModule.loc — The corresponding module function
function window:loc()
@ -125,12 +106,7 @@ end
---Get this window's class. This is usually the name of the application.
---
---### Example
---```lua
----- With Alacritty focused...
---print(window.get_focused():class())
----- ...should print "Alacritty".
---```
---See `WindowModule.class` for examples.
---@return string|nil class This window's class, or nil if it doesn't exist.
---@see WindowModule.class — The corresponding module function
function window:class()
@ -139,12 +115,7 @@ end
---Get this window's title.
---
---### Example
---```lua
----- With Alacritty focused...
---print(window.get_focused():title())
----- ...should print the directory Alacritty is in or what it's running (what's in its title bar).
---```
---See `WindowModule.title` for examples.
---@return string|nil title This window's title, or nil if it doesn't exist.
---@see WindowModule.title — The corresponding module function
function window:title()
@ -204,10 +175,7 @@ end
---Get whether or not this window is focused.
---
---### Example
---```lua
---print(window.get_focused():focused()) -- should print `true`.
---```
---See `WindowModule.focused` for examples.
---@return boolean|nil
---@see WindowModule.focused — The corresponding module function
function window:focused()
@ -269,87 +237,50 @@ end
function window_module.get_all()
local window_ids =
Request("GetWindows").RequestResponse.response.Windows.window_ids
---@type Window[]
local windows = {}
for _, window_id in pairs(window_ids) do
table.insert(windows, create_window(window_id))
end
return windows
end
---Toggle the tag with the given name and (optional) output for the specified window.
---You can also provide a tag object instead of a name and output.
---
---@param w Window
---@param name string
---@param output Output?
---@overload fun(w: Window, t: Tag)
---@param t Tag|TagTable|TagTableNamed|string
---@see Window.toggle_tag — The corresponding object method
function window_module.toggle_tag(w, name, output)
if type(name) == "table" then
function window_module.toggle_tag(w, t)
local t = require("tag").create_tag_from_params(t)
if t then
SendMsg({
ToggleTagOnWindow = {
window_id = w:id(),
tag_id = name--[[@as Tag]]:id(),
tag_id = t:id(),
},
})
return
end
local output = output or require("output").get_focused()
if output == nil then
return
end
local tags = require("tag").get_by_name(name)
for _, t in pairs(tags) do
if t:output() and t:output():name() == output:name() then
SendMsg({
ToggleTagOnWindow = {
window_id = w:id(),
tag_id = t:id(),
},
})
return
end
end
end
---Move the specified window to the tag with the given name and (optional) output.
---You can also provide a tag object instead of a name and output.
---
---@param w Window
---@param name string
---@param output Output?
---@overload fun(w: Window, t: Tag)
---@param t Tag|TagTable|TagTableNamed|string
---@see Window.move_to_tag — The corresponding object method
function window_module.move_to_tag(w, name, output)
if type(name) == "table" then
function window_module.move_to_tag(w, t)
local t = require("tag").create_tag_from_params(t)
if t then
SendMsg({
MoveWindowToTag = {
window_id = w:id(),
tag_id = name--[[@as Tag]]:id(),
tag_id = t:id(),
},
})
return
end
local output = output or require("output").get_focused()
if output == nil then
return
end
local tags = require("tag").get_by_name(name)
for _, t in pairs(tags) do
if t:output() and t:output():name() == output:name() then
SendMsg({
MoveWindowToTag = {
window_id = w:id(),
tag_id = t:id(),
},
})
return
end
end
end
@ -475,8 +406,10 @@ end
---Get the specified window's location in the global space.
---
---Think of your monitors as being laid out on a big sheet.
---The top left of the sheet if you trim it down is (0, 0).
---The location of this window is relative to that point.
---The location of this window is relative inside the sheet.
---
---If you don't set the location of your monitors, they will start at (0, 0)
---and extend rightward with their tops aligned.
---
---### Example
---```lua