diff --git a/.github/workflows/ldoc.yml b/.github/workflows/ldoc.yml new file mode 100644 index 0000000..05808f7 --- /dev/null +++ b/.github/workflows/ldoc.yml @@ -0,0 +1,34 @@ +# From https://github.com/lunarmodules/ldoc/blob/master/.github/workflows/doc.yml + +# Based on https://gist.github.com/domenic/ec8b0fc8ab45f39403dd +name: Build Docs +on: + pull_request: + branches: + - main + push: + branches: + - main +jobs: + build: + name: Build docs + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + - name: Setup Lua + uses: leafo/gh-actions-lua@v8 + with: + luaVersion: 5.4 + - name: Setup Lua Rocks + uses: leafo/gh-actions-luarocks@v4 + - name: Setup dependencies + run: luarocks install ldoc + - name: Build docs + run: cd ./api/lua/doc && 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 diff --git a/.gitignore b/.gitignore index 6985cf1..08b32d6 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,5 @@ Cargo.lock # MSVC Windows builds of rustc generate these, which store debugging information *.pdb + +api/lua/doc/doc diff --git a/api/lua/doc.md b/api/lua/doc.md deleted file mode 100644 index 085babd..0000000 --- a/api/lua/doc.md +++ /dev/null @@ -1,1395 +0,0 @@ -This is absolutely not automatible and I think I'll need to use LDoc, which means I now have the privilege of duplicating documentation. Yay! - -# InputModule - -## keybind - - -```lua -function InputModule.keybind(modifiers: ("Alt"|"Ctrl"|"Shift"|"Super")[], key: Keys, action: fun()) -``` - -Set a keybind. If called with an already existing keybind, it gets replaced. - -### Example - -```lua --- Set `Super + Return` to open Alacritty -input.keybind({ "Super" }, input.keys.Return, function() - process.spawn("Alacritty") -end) -``` - -@*param* `key` — The key for the keybind. - -@*param* `modifiers` — Which modifiers need to be pressed for the keybind to trigger. - -@*param* `action` — What to do. - - - ---- - -# Layout - -```lua -Layout: - | "MasterStack" -- One master window on the left with all other windows stacked to the right. - | "Dwindle" -- Windows split in half towards the bottom right corner. - | "Spiral" -- Windows split in half in a spiral. - | "CornerTopLeft" -- One main corner window in the top left with a column of windows on the right and a row on the bottom. - | "CornerTopRight" -- One main corner window in the top right with a column of windows on the left and a row on the bottom. - | "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. -``` - - -```lua -"CornerBottomLeft"|"CornerBottomRight"|"CornerTopLeft"|"CornerTopRight"|"Dwindle"...(+2) -``` - - ---- - -# Modifier - -```lua -Modifier: - | "Alt" -- The "Alt" key - | "Ctrl" -- The "Control" key - | "Shift" -- The "Shift" key - | "Super" -- The "Super" key, aka "Meta", "Mod4" in X11, the Windows key, etc. -``` - - -```lua -"Alt"|"Ctrl"|"Shift"|"Super" -``` - - ---- - -# Output - -## _name - - -```lua -string -``` - -The name of this output (or rather, of its connector). - -## add_tags - - -```lua -(method) Output:add_tags(...string) -``` - -Add tags to this output. - -@*param* `...` — The names of the tags you want to add. You can also pass in a table. - -See: OutputModule.add_tags — The corresponding module function - -## focused - - -```lua -(method) Output:focused() - -> boolean|nil -``` - -Get whether or not this output is focused. This is currently defined as having the cursor on it. - -See: OutputModule.focused — The corresponding module function - -## loc - - -```lua -(method) Output:loc() - -> { x: integer, y: integer }|nil -``` - -Get this output's location in the global space, in pixels. - -See: OutputModule.loc — The corresponding module function - -## make - - -```lua -(method) Output:make() - -> string|nil -``` - -Get this output's make. - -See: OutputModule.make — The corresponding module function - -## model - - -```lua -(method) Output:model() - -> string|nil -``` - -Get this output's model. - -See: OutputModule.model — The corresponding module function - -## name - - -```lua -(method) Output:name() - -> string -``` - -Get this output's name. This is something like "eDP-1" or "HDMI-A-0". - -## physical_size - - -```lua -(method) Output:physical_size() - -> { w: integer, h: integer }|nil -``` - -Get this output's physical size in millimeters. - -See: OutputModule.physical_size — The corresponding module function - -## refresh_rate - - -```lua -(method) Output:refresh_rate() - -> integer|nil -``` - -Get this output's refresh rate in millihertz. -For example, 60Hz will be returned as 60000. - -See: OutputModule.refresh_rate — The corresponding module function - -## res - - -```lua -(method) Output:res() - -> { w: integer, h: integer }|nil -``` - -Get this output's resolution in pixels. - -See: OutputModule.res — The corresponding module function - -## tags - - -```lua -(method) Output:tags() - -> Tag[] -``` - -Get all tags on this output. - -See: OutputModule.tags — The corresponding module function - - ---- - -# OutputModule - -## add_tags - - -```lua -function OutputModule.add_tags(op: Output, ...string) -``` - -Add tags to the specified output. - -@*param* `...` — The names of the tags you want to add. You can also pass in a table. - -See: - * [TagModule.add](file:///home/jason/projects/pinnacle/api/lua/tag.lua#105#9) — The called function - * [Output.add_tags](file:///home/jason/projects/pinnacle/api/lua/output.lua#46#9) — The corresponding object method - -## connect_for_all - - -```lua -function OutputModule.connect_for_all(func: fun(output: Output)) -``` - -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. - -@*param* `func` — The function that will be run. - -## focused - - -```lua -function OutputModule.focused(op: Output) - -> boolean|nil -``` - -Get whether or not the specified output is focused. This is currently defined as having the cursor on it. - -See: Output.focused — The corresponding object method - -## get_by_model - - -```lua -function OutputModule.get_by_model(model: string) - -> outputs: Output[] -``` - -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. - -@*param* `model` — The model of the output(s). - -@*return* `outputs` — All outputs with this model. - -## get_by_name - - -```lua -function OutputModule.get_by_name(name: string) - -> output: Output|nil -``` - -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. - -### Example -```lua -local monitor = output.get_by_name("DP-1") -print(monitor.name) -- should print `DP-1` -``` - -@*param* `name` — The name of the output. - -@*return* `output` — The output, or nil if none have the provided name. - -## get_by_res - - -```lua -function OutputModule.get_by_res(width: integer, height: integer) - -> outputs: Output[] -``` - -Get outputs by their resolution. - -@*param* `width` — The width of the outputs, in pixels. - -@*param* `height` — The height of the outputs, in pixels. - -@*return* `outputs` — All outputs with this resolution. - -## get_focused - - -```lua -function OutputModule.get_focused() - -> output: Output|nil -``` - -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: -```lua -local op = output.get_focused() --[[@as Output]] -``` -or by disabling nil check warnings for the line: -```lua -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. -```lua -local tags = output.get_focused():tags() -- will NOT warn for nil -``` - -@*return* `output` — The output, or nil if none are focused. - -## get_for_tag - - -```lua -function OutputModule.get_for_tag(tag: Tag) - -> Output|nil -``` - -Get the output the specified tag is on. - -See: - * [TagModule.output](file:///home/jason/projects/pinnacle/api/lua/tag.lua#396#9) — A global method for fully qualified syntax (for you Rustaceans out there) - * [Tag.output](file:///home/jason/projects/pinnacle/api/lua/tag.lua#62#9) — The corresponding object method - -## loc - - -```lua -function OutputModule.loc(op: Output) - -> { x: integer, y: integer }|nil -``` - -Get the specified output's location in the global space, in pixels. - -See: Output.loc — The corresponding object method - -## make - - -```lua -function OutputModule.make(op: Output) - -> string|nil -``` - -Get the specified output's make. - -See: Output.make — The corresponding object method - -## model - - -```lua -function OutputModule.model(op: Output) - -> string|nil -``` - -Get the specified output's model. - -See: Output.model — The corresponding object method - -## physical_size - - -```lua -function OutputModule.physical_size(op: Output) - -> { w: integer, h: integer }|nil -``` - -Get the specified output's physical size in millimeters. - -See: Output.physical_size — The corresponding object method - -## refresh_rate - - -```lua -function OutputModule.refresh_rate(op: Output) - -> integer|nil -``` - -Get the specified output's refresh rate in millihertz. -For example, 60Hz will be returned as 60000. - -See: Output.refresh_rate — The corresponding object method - -## res - - -```lua -function OutputModule.res(op: Output) - -> { w: integer, h: integer }|nil -``` - -Get the specified output's resolution in pixels. - -See: Output.res — The corresponding object method - -## tags - - -```lua -function OutputModule.tags(op: Output) - -> Tag[] -``` - -Get the specified output's tags. - -See: - * [TagModule.get_on_output](file:///home/jason/projects/pinnacle/api/lua/tag.lua#282#9) — The called function - * [Output.tags](file:///home/jason/projects/pinnacle/api/lua/output.lua#38#9) — The corresponding object method - - ---- - -# OutputName - - -```lua -string -``` - - ---- - -# Pinnacle - -## quit - - -```lua -function Pinnacle.quit() -``` - -Quit Pinnacle. - -## setup - - -```lua -function Pinnacle.setup(config_func: fun(pinnacle: Pinnacle)) -``` - -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. - - ---- - -# ProcessModule - -## spawn - - -```lua -function ProcessModule.spawn(command: string|string[], callback?: fun(stdout: string|nil, stderr: string|nil, exit_code: integer|nil, exit_msg: string|nil)) -``` - -Spawn a process with an optional callback for its stdout, stderr, and exit information. - -`callback` has the following parameters: - - `stdout`: The process's stdout printed this line. - - `stderr`: The process's stderr printed this line. - - `exit_code`: The process exited with this code. - - `exit_msg`: The process exited with this message. - -@*param* `command` — The command as one whole string or a table of each of its arguments - -@*param* `callback` — A callback to do something whenever the process's stdout or stderr print a line, or when the process exits. - -## spawn_once - - -```lua -function ProcessModule.spawn_once(command: string|string[], callback?: fun(stdout: string|nil, stderr: string|nil, exit_code: integer|nil, exit_msg: string|nil)) -``` - -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: - - `stdout`: The process's stdout printed this line. - - `stderr`: The process's stderr printed this line. - - `exit_code`: The process exited with this code. - - `exit_msg`: The process exited with this message. - -`spawn_once` checks for the process using `pgrep`. If your system doesn't have `pgrep`, this won't work properly. - -@*param* `command` — The command as one whole string or a table of each of its arguments - -@*param* `callback` — A callback to do something whenever the process's stdout or stderr print a line, or when the process exits. - - ---- - -# Tag - -## _id - - -```lua -integer -``` - -The internal id of this tag. - -## active - - -```lua -(method) Tag:active() - -> active: boolean|nil -``` - -Get this tag's active status. - -@*return* `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 - -## id - - -```lua -(method) Tag:id() - -> integer -``` - -Get this tag's internal id. -***You probably won't need to use this.*** - -## name - - -```lua -(method) Tag:name() - -> name: string|nil -``` - -Get this tag's name. - -@*return* `name` — The name of this tag, or nil if it doesn't exist. - -See: TagModule.name — The corresponding module function - -## output - - -```lua -(method) Tag:output() - -> output: Output|nil -``` - -Get this tag's output. - -@*return* `output` — The output this tag is on, or nil if the tag doesn't exist. - -See: TagModule.output — The corresponding module function - -## set_layout - - -```lua -(method) Tag:set_layout(layout: "CornerBottomLeft"|"CornerBottomRight"|"CornerTopLeft"|"CornerTopRight"|"Dwindle"...(+2)) -``` - -Set this tag's layout. - -```lua -layout: - | "MasterStack" -- One master window on the left with all other windows stacked to the right. - | "Dwindle" -- Windows split in half towards the bottom right corner. - | "Spiral" -- Windows split in half in a spiral. - | "CornerTopLeft" -- One main corner window in the top left with a column of windows on the right and a row on the bottom. - | "CornerTopRight" -- One main corner window in the top right with a column of windows on the left and a row on the bottom. - | "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. -``` - -See: TagModule.set_layout — The corresponding module function - -## switch_to - - -```lua -(method) Tag:switch_to() -``` - -Switch to this tag. - -See: TagModule.switch_to — The corresponding module function - -## toggle - - -```lua -(method) Tag:toggle() -``` - -Toggle this tag. - -See: TagModule.toggle — The corresponding module function - - ---- - -# TagId - - -```lua -integer -``` - - ---- - -# TagModule - -## active - - -```lua -function TagModule.active(t: Tag) - -> boolean|nil -``` - -Get whether or not the specified tag is active. - -See: Tag.active — The corresponding object method - -## add - - -```lua -function TagModule.add(output: Output, ...string) -``` - -Add tags to the specified output. - -### Examples -```lua -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. -```lua -local tags = {"Terminal", "Browser", "Code", "Potato", "Email"} -tag.add(op, tags) -- Add tags with those names -``` - -@*param* `output` — The output you want these tags to be added to. - -@*param* `...` — The names of the new tags you want to add. - -See: Output.add_tags — The corresponding object method - -## get_all - - -```lua -function TagModule.get_all() - -> Tag[] -``` - -Get all tags across all outputs. - -### Example -```lua --- 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. -``` - -## get_by_name - - -```lua -function TagModule.get_by_name(name: string) - -> Tag[] -``` - -Get all tags with this name across all outputs. - -### Example -```lua --- 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. -``` - -@*param* `name` — The name of the tag(s) you want. - -## get_on_output - - -```lua -function TagModule.get_on_output(output: Output) - -> Tag[] -``` - -Get all tags on the specified output. - -### Example -```lua -local op = output.get_focused() -if op ~= nil then - local tags = tag.get_on_output(op) -- All tags on the focused output -end -``` - -See: Output.tags — The corresponding object method - -## name - - -```lua -function TagModule.name(t: Tag) - -> string|nil -``` - -Get the specified tag's name. - -### Example -```lua --- Assuming the tag `Terminal` exists... -print(tag.name(tag.get_by_name("Terminal")[1])) --- ...should print `Terminal`. -``` - -See: Tag.name — The corresponding object method - -## output - - -```lua -function TagModule.output(t: Tag) - -> Output|nil -``` - -Get the output the specified tag is on. - -See: - * [OutputModule.get_for_tag](file:///home/jason/projects/pinnacle/api/lua/output.lua#232#9) — The called function - * [Tag.output](file:///home/jason/projects/pinnacle/api/lua/tag.lua#62#9) — The corresponding object method - -## set_layout - - -```lua -function TagModule.set_layout(name: string, layout: "CornerBottomLeft"|"CornerBottomRight"|"CornerTopLeft"|"CornerTopRight"|"Dwindle"...(+2), output?: Output) -``` - -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")) - --- 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") -``` - -@*param* `name` — The name of the tag. - -@*param* `layout` — The layout. - -@*param* `output` — The output. - ---- - -```lua -layout: - | "MasterStack" -- One master window on the left with all other windows stacked to the right. - | "Dwindle" -- Windows split in half towards the bottom right corner. - | "Spiral" -- Windows split in half in a spiral. - | "CornerTopLeft" -- One main corner window in the top left with a column of windows on the right and a row on the bottom. - | "CornerTopRight" -- One main corner window in the top right with a column of windows on the left and a row on the bottom. - | "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. -``` - -See: Tag.set_layout — The corresponding object method - -## switch_to - - -```lua -function TagModule.switch_to(name: string, output?: Output) -``` - -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. - -### Examples -```lua --- Switches to and displays *only* windows on tag `3` on the focused output. -tag.switch_to("3") - -local -``` - -@*param* `name` — The name of the tag. - -@*param* `output` — The output. - -See: Tag.switch_to — The corresponding object method - -## toggle - - -```lua -function TagModule.toggle(name: string, output?: Output) -``` - -Toggle a tag on the specified output. If `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. -``` - -@*param* `name` — The name of the tag. - -@*param* `output` — The output. - -See: Tag.toggle — The corresponding object method - - ---- - -# Window - -## _id - - -```lua -integer -``` - -The internal id of this window - -## class - - -```lua -(method) Window:class() - -> class: string|nil -``` - -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". -``` - -@*return* `class` — This window's class, or nil if it doesn't exist. - -See: WindowModule.class — The corresponding module function - -## close - - -```lua -(method) Window:close() -``` - -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. - -### Example -```lua -window.get_focused():close() -- close the currently focused window -``` - -See: WindowModule.close — The corresponding module function - -## floating - - -```lua -(method) Window:floating() - -> floating: boolean|nil -``` - -Get this window's floating status. - -### Example -```lua --- With the focused window floating... -print(window.get_focused():floating()) --- ...should print `true`. -``` - -@*return* `floating` — `true` if it's floating, `false` if it's tiled, or nil if it doesn't exist. - -See: WindowModule.floating — The corresponding module function - -## focused - - -```lua -(method) Window:focused() - -> floating: boolean|nil -``` - -Get whether or not this window is focused. - -### Example -```lua -print(window.get_focused():focused()) -- should print `true`. -``` - -@*return* `floating` — `true` if it's floating, `false` if it's tiled, or nil if it doesn't exist. - -See: WindowModule.focused — The corresponding module function - -## id - - -```lua -(method) Window:id() - -> integer -``` - -Get this window's unique id. - -***You will probably not need to use this.*** - -## loc - - -```lua -(method) Window:loc() - -> loc: { x: integer, y: integer }|nil -``` - -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. - -### 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 }`. -``` - -@*return* `loc` — The location of the window, or nil if it's not on-screen or alive. - -See: WindowModule.loc — The corresponding module function - -## move_to_tag - - -```lua -(method) Window:move_to_tag(name: string, output?: Output) -``` - -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. -``` - -See: WindowModule.move_to_tag — The corresponding module function - -## set_size - - -```lua -(method) Window:set_size(size: { w: integer?, h: integer? }) -``` - -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 — The corresponding module function - -## size - - -```lua -(method) Window:size() - -> size: { w: integer, h: integer }|nil -``` - -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 }`. -``` - -@*return* `size` — The size of the window, or nil if it doesn't exist. - -See: WindowModule.size — The corresponding module function - -## title - - -```lua -(method) Window:title() - -> title: string|nil -``` - -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). -``` - -@*return* `title` — This window's title, or nil if it doesn't exist. - -See: WindowModule.title — The corresponding module function - -## toggle_floating - - -```lua -(method) Window:toggle_floating() -``` - -Toggle this window's floating status. - -### Example -```lua -window.get_focused():toggle_floating() -- toggles the focused window between tiled and floating -``` - -See: WindowModule.toggle_floating — The corresponding module function - -## toggle_tag - - -```lua -(method) Window:toggle_tag(name: string, output?: Output) -``` - -Toggle the specified tag for this window. - -Note: toggling off all tags currently makes a window not response 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. -``` - -See: WindowModule.toggle_tag — The corresponding module function - - ---- - -# WindowId - - -```lua -integer -``` - - ---- - -# WindowModule - -## class - - -```lua -function WindowModule.class(win: Window) - -> class: string|nil -``` - -Get the specified window's class. This is usually the name of the application. - -### Example -```lua --- With Alacritty focused... -local win = window.get_focused() -if win ~= nil then - print(window.class(win)) -end --- ...should print "Alacritty". -``` - -@*return* `class` — This window's class, or nil if it doesn't exist. - -See: Window.class — The corresponding object method - -## close - - -```lua -function WindowModule.close(win: Window) -``` - -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. - -### Example -```lua -local win = window.get_focused() -if win ~= nil then - window.close(win) -- close the currently focused window -end -``` - -See: Window.close — The corresponding object method - -## floating - - -```lua -function WindowModule.floating(win: Window) - -> floating: boolean|nil -``` - -Get this window's floating status. - -### Example -```lua --- With the focused window floating... -local win = window.get_focused() -if win ~= nil then - print(window.floating(win)) -end --- ...should print `true`. -``` - -@*return* `floating` — `true` if it's floating, `false` if it's tiled, or nil if it doesn't exist. - -See: Window.floating — The corresponding object method - -## focused - - -```lua -function WindowModule.focused(win: Window) - -> floating: boolean|nil -``` - -Get whether or not this window is focused. - -### Example -```lua -local win = window.get_focused() -if win ~= nil then - print(window.focused(win)) -- Should print `true` -end -``` - -@*return* `floating` — `true` if it's floating, `false` if it's tiled, or nil if it doesn't exist. - -See: Window.focused — The corresponding object method - -## get_all - - -```lua -function WindowModule.get_all() - -> Window[] -``` - -Get all windows. - -## get_by_class - - -```lua -function WindowModule.get_by_class(class: string) - -> Window[] -``` - -Get all windows with the specified class (usually the name of the application). - -@*param* `class` — The class. For example, Alacritty's class is "Alacritty". - -## get_by_title - - -```lua -function WindowModule.get_by_title(title: string) - -> Window[] -``` - -Get all windows with the specified title. - -@*param* `title` — The title. - -## get_focused - - -```lua -function WindowModule.get_focused() - -> Window|nil -``` - -Get the currently focused window. - -## loc - - -```lua -function WindowModule.loc(win: Window) - -> loc: { x: integer, y: integer }|nil -``` - -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. - -### Example -```lua --- 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 }`. -``` - -@*return* `loc` — The location of the window, or nil if it's not on-screen or alive. - -See: Window.loc — The corresponding object method - -## move_to_tag - - -```lua -function WindowModule.move_to_tag(w: Window, name: string, output?: Output) -``` - -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. - -See: Window.move_to_tag — The corresponding object method - -## set_size - - -```lua -function WindowModule.set_size(win: Window, size: { w: integer?, h: integer? }) -``` - -Set the specified window's size. - -### Examples -```lua -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 -``` - -See: Window.set_size — The corresponding object method - -## size - - -```lua -function WindowModule.size(win: Window) - -> size: { w: integer, h: integer }|nil -``` - -Get the specified window's size. - -### Example -```lua --- With a 4K monitor, given a focused fullscreen window `win`... -local size = window.size(win) --- ...should have size equal to `{ w = 3840, h = 2160 }`. -``` - -@*return* `size` — The size of the window, or nil if it doesn't exist. - -See: Window.size — The corresponding object method - -## title - - -```lua -function WindowModule.title(win: Window) - -> title: string|nil -``` - -Get the specified window's title. - -### Example -```lua --- 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). -``` - -@*return* `title` — This window's title, or nil if it doesn't exist. - -See: Window.title — The corresponding object method - -## toggle_floating - - -```lua -function WindowModule.toggle_floating(win: Window) -``` - -Toggle the specified window between tiled and floating. - -See: Window.toggle_floating — The corresponding object method - -## toggle_tag - - -```lua -function WindowModule.toggle_tag(w: Window, name: string, output?: Output) -``` - -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. - -See: Window.toggle_tag — The corresponding object method - - ---- - diff --git a/api/lua/doc/config.ld b/api/lua/doc/config.ld new file mode 100644 index 0000000..cb91c46 --- /dev/null +++ b/api/lua/doc/config.ld @@ -0,0 +1,7 @@ +project = "Pinnacle" +format = "markdown" +description = "A very, VERY WIP Smithay-based Wayland compositor" +boilerplate = true +multimodule = true +no_space_before_args = true +style = true diff --git a/api/lua/doc/index.html b/api/lua/doc/index.html new file mode 100644 index 0000000..cc7e8e0 --- /dev/null +++ b/api/lua/doc/index.html @@ -0,0 +1,180 @@ + + + + + Reference + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module ProcessModule

+

+ +

+

+ +

+ + +

Functions

+ + + + + + + + + +
process_module.spawn (command, callback)Spawn a process with an optional callback for its stdout, stderr, and exit information.
process_module.spawn_once (command, callback)Spawn a process only if it isn't already running, with an optional callback for its stdout, stderr, and exit information.
+

Fields

+ + + + + +
args + +
+ +
+
+ + +

Functions

+ +
+
+ + process_module.spawn (command, callback) +
+
+ Spawn a process with an optional callback for its stdout, stderr, and exit information.

+ +

callback has the following parameters: + - stdout - The process's stdout printed this line. + - stderr - The process's stderr printed this line. + - exit_code - The process exited with this code. + - exit_msg - The process exited with this message. + + +

Parameters:

+
    +
  • command + string|string[] The command as one whole string or a table of each of its arguments +
    • +
  • callback + fun(stdout: string|nil, stderr: string|nil, exitcode: integer|nil, exitmsg: string|nil)? A callback to do something whenever the process's stdout or stderr print a line, or when the process exits. +
    • +
+ + + + + +
+
+ + process_module.spawn_once (command, callback) +
+
+ 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: + - stdout: The process's stdout printed this line. + - stderr: The process's stderr printed this line. + - exit_code: The process exited with this code. + - exit_msg: The process exited with this message.

+ +

spawn_once checks for the process using pgrep. If your system doesn't have pgrep, this won't work properly. + + +

Parameters:

+
    +
  • command + string|string[] The command as one whole string or a table of each of its arguments +
    • +
  • callback + fun(stdout: string|nil, stderr: string|nil, exitcode: integer|nil, exitmsg: string|nil)? A callback to do something whenever the process's stdout or stderr print a line, or when the process exits. +
    • +
+ + + + + +
+
+

Fields

+ +
+
+ + args +
+
+ + + + + +
    +
  • args + Args +
    • +
+ + + + + +
+
+ + +
+
+
+generated by LDoc 1.5.0 +Last updated 2023-07-22 11:35:14 +
+
+ + diff --git a/api/lua/doc/input.lua b/api/lua/doc/input.lua new file mode 100644 index 0000000..1e61304 --- /dev/null +++ b/api/lua/doc/input.lua @@ -0,0 +1,21 @@ +-- This Source Code Form is subject to the terms of the Mozilla Public +-- License, v. 2.0. If a copy of the MPL was not distributed with this +-- file, You can obtain one at https://mozilla.org/MPL/2.0/. +-- +-- SPDX-License-Identifier: MPL-2.0 + +---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 diff --git a/api/lua/doc/ldoc.css b/api/lua/doc/ldoc.css new file mode 100644 index 0000000..3088cbb --- /dev/null +++ b/api/lua/doc/ldoc.css @@ -0,0 +1,320 @@ +/* BEGIN RESET + +Copyright (c) 2010, Yahoo! Inc. All rights reserved. +Code licensed under the BSD License: +http://developer.yahoo.com/yui/license.html +version: 2.8.2r1 +*/ +html { + color: #e4e4e5; + background: #202020; /* Background of page if it doesn't fill the screen */ +} +body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td { + margin: 0; + padding: 0; +} +table { + border-collapse: collapse; + border-spacing: 0; +} +fieldset,img { + border: 0; +} +address,caption,cite,code,dfn,em,strong,th,var,optgroup { + font-style: inherit; + font-weight: inherit; +} +del,ins { + text-decoration: none; +} +li { + margin-left: 20px; +} +caption,th { + text-align: left; +} +h1,h2,h3,h4,h5,h6 { + font-size: 100%; + font-weight: bold; +} +q:before,q:after { + content: ''; +} +abbr,acronym { + border: 0; + font-variant: normal; +} +sup { + vertical-align: baseline; +} +sub { + vertical-align: baseline; +} +legend { + color: #000; +} +input,button,textarea,select,optgroup,option { + font-family: inherit; + font-size: inherit; + font-style: inherit; + font-weight: inherit; +} +input,button,textarea,select {*font-size:100%; +} +/* END RESET */ + +body { /* Body of window (makes it look like sidebars) */ + margin-left: 1em; + margin-right: 1em; + font-family: arial, helvetica, geneva, sans-serif; + background-color: #202020; margin: 0px; +} + +code, tt { font-family: "JetBrains Mono", monospace; font-size: 1em; } +span.parameter { font-family: "JetBrains Mono", monospace; } +span.parameter:after { content:":"; } +span.types:before { content:"("; } +span.types:after { content:")"; } +.type { font-weight: bold; font-style:italic } + +body, p, td, th { font-size: 1em; line-height: 1.2em;} + +p, ul { margin: 10px 0 0 0px;} + +strong { font-weight: bold;} + +em { font-style: italic;} + +h1 { + font-size: 1.5em; + margin: 20px 0 20px 0; +} +h2, h3, h4 { margin: 15px 0 10px 0; } +h2 { font-size: 1.25em; } +h3 { font-size: 1.15em; } +h4 { font-size: 1.06em; } + +a:link { font-weight: bold; color: #33b1ff; text-decoration: none; } +a:visited { font-weight: bold; color: #33b1ff; text-decoration: none; } +a:link:hover { text-decoration: underline; } + +hr { + color:#cccccc; + background: #00007f; + height: 1px; +} + +blockquote { margin-left: 3em; } + +ul { list-style-type: disc; } + +p.name { + font-family: "JetBrains Mono", "Andale Mono", monospace; + padding-top: 1em; +} + +pre { + background-color: #2a2a2a; + border: 1px solid #505050; + padding: 10px; + margin: 10px 0 10px 0; + overflow: auto; + font-family: "JetBrains Mono", "Andale Mono", monospace; +} + +pre.example { + font-size: .85em; +} + +table.index { border: 1px #00007f; } +table.index td { text-align: left; vertical-align: top; } + +#container { + /* margin-left: 1em; */ + /* margin-right: 1em; */ + background-color: #f0f0f0; +} + +#product { + text-align: center; + border-bottom: 0px solid #cccccc; + background-color: #ffffff; +} + +#product big { + font-size: 2em; +} + +#main { + background-color: #101010; + border-left: 0px solid #cccccc; +} + +#navigation { /* Sidebar */ + float: left; + width: 20%; + vertical-align: top; + background-color: #101010; + overflow: visible; +} + +#navigation h1 { + padding: 0.2em; + font-size: 2em; +} + +#navigation h2 { /* Sidebar subheaders */ + background-color:#2a2a2a; + font-size:1.1em; + color:#e4e4e5; + text-align: left; + padding:0.2em; + margin: 0px; + border-top:0px solid #dddddd; + border-bottom:0px solid #dddddd; +} + +#navigation ul +{ + font-size:1em; + list-style-type: none; + margin: 1px 1px 10px 1px; +} + +#navigation li { + text-indent: -1em; + display: block; + margin: 3px 0px 0px 22px; +} + +#navigation li li a { + margin: 0px 3px 0px -1em; +} + +#content { /* Content background (the stuff with the actual docs) */ + margin-left: 20%; + width: 80% - 32px; + border-left: 0px solid #cccccc; + border-right: 0px solid #cccccc; + background-color: #202020; + padding: 16px; +} + +#content h1 { + /* margin: 0%; */ +} + +#about { /* The about footer */ + clear: both; + /* margin: 5px; */ + border-top: 2px solid #505050; + background-color: #202020; + width: 100%; +} + +#about i { /* The two text thingys in the footer */ + padding-left: 1em; + padding-right: 1em; +} + +@media print { + body { + font: 12pt "Times New Roman", "TimeNR", Times, serif; + } + a { font-weight: bold; color: #004080; text-decoration: underline; } + + #main { + background-color: #ffffff; + border-left: 0px; + } + + #container { + margin-left: 2%; + margin-right: 2%; + background-color: #ffffff; + } + + #content { + padding: 1em; + background-color: #ffffff; + } + + #navigation { + display: none; + } + pre.example { + font-family: "JetBrains Mono", "Andale Mono", monospace; + font-size: 10pt; + page-break-inside: avoid; + } +} + +table.module_list { + border-width: 0px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.module_list td { + border-width: 2px; + padding: 3px; + border-style: solid; + border-color: #505050; +} +table.module_list td.name { background-color: #2a2a2a; min-width: 200px; vertical-align: top; } /* Modules/Classes Name section */ +table.module_list td.summary { background-color: #161616; width: 80%; vertical-align: top; } /* Summary section */ + +/* Same stuff but for function tables */ +table.function_list { + border-width: 0px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.function_list td { + border-width: 2px; + padding: 3px; + border-style: solid; + border-color: #505050; +} +table.function_list td.name { background-color: #2a2a2a; min-width: 200px; vertical-align: top; } +table.function_list td.summary { width: 100%; vertical-align: top; } + +ul.nowrap { + overflow:auto; + white-space:nowrap; +} + +dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;} +dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;} +dl.table h3, dl.function h3 {font-size: .95em;} + +/* stop sublists from having initial vertical space */ +ul ul { margin-top: 0px; } +ol ul { margin-top: 0px; } +ol ol { margin-top: 0px; } +ul ol { margin-top: 0px; } + +/* make the target distinct; helps when we're navigating to a function */ +a:target + * { + background-color: #FF9; +} + + +/* styles for prettification of source */ +pre .comment { color: #558817; } +pre .constant { color: #a8660d; } +pre .escape { color: #844631; } +pre .keyword { color: #aa5050; font-weight: bold; } +pre .library { color: #0e7c6b; } +pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; } +pre .string { color: #8080ff; } +pre .number { color: #f8660d; } +pre .function-name { color: #60447f; } +pre .operator { color: #2239a8; font-weight: bold; } +pre .preprocessor, pre .prepro { color: #a33243; } +pre .global { color: #800080; } +pre .user-keyword { color: #800080; } +pre .prompt { color: #558817; } +pre .url { color: #272fc2; text-decoration: underline; } + diff --git a/api/lua/doc/output.lua b/api/lua/doc/output.lua new file mode 100644 index 0000000..44afe99 --- /dev/null +++ b/api/lua/doc/output.lua @@ -0,0 +1,182 @@ +-- This Source Code Form is subject to the terms of the Mozilla Public +-- License, v. 2.0. If a copy of the MPL was not distributed with this +-- file, You can obtain one at https://mozilla.org/MPL/2.0/. +-- +-- SPDX-License-Identifier: MPL-2.0 + +---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. +--- +---### Example +--- 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 + +---------------------------------------------------------- + +---Output objects +---@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 diff --git a/api/lua/doc/pinnacle.lua b/api/lua/doc/pinnacle.lua new file mode 100644 index 0000000..2883bb2 --- /dev/null +++ b/api/lua/doc/pinnacle.lua @@ -0,0 +1,30 @@ +-- This Source Code Form is subject to the terms of the Mozilla Public +-- License, v. 2.0. If a copy of the MPL was not distributed with this +-- file, You can obtain one at https://mozilla.org/MPL/2.0/. +-- +-- SPDX-License-Identifier: MPL-2.0 + +---The configuration entry point. +---@module Pinnacle +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, +} diff --git a/api/lua/doc/process.lua b/api/lua/doc/process.lua new file mode 100644 index 0000000..fb3e2c5 --- /dev/null +++ b/api/lua/doc/process.lua @@ -0,0 +1,33 @@ +-- This Source Code Form is subject to the terms of the Mozilla Public +-- License, v. 2.0. If a copy of the MPL was not distributed with this +-- file, You can obtain one at https://mozilla.org/MPL/2.0/. +-- +-- SPDX-License-Identifier: MPL-2.0 + +---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:
+--- - `stdout` - The process's stdout printed this line.
+--- - `stderr` - The process's stderr printed this line.
+--- - `exit_code` - The process exited with this code.
+--- - `exit_msg` - The process exited with this message.
+---@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:
+--- - `stdout` - The process's stdout printed this line.
+--- - `stderr` - The process's stderr printed this line.
+--- - `exit_code` - The process exited with this code.
+--- - `exit_msg` - The process exited with this message.
+---@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 diff --git a/api/lua/doc/tag.lua b/api/lua/doc/tag.lua new file mode 100644 index 0000000..0bd1239 --- /dev/null +++ b/api/lua/doc/tag.lua @@ -0,0 +1,167 @@ +-- This Source Code Form is subject to the terms of the Mozilla Public +-- License, v. 2.0. If a copy of the MPL was not distributed with this +-- file, You can obtain one at https://mozilla.org/MPL/2.0/. +-- +-- SPDX-License-Identifier: MPL-2.0 + +---Tag management +---@module TagModule +local tag_module = {} + +---@alias Layout +---| "MasterStack" # One master window on the left with all other windows stacked to the right. +---| "Dwindle" # Windows split in half towards the bottom right corner. +---| "Spiral" # Windows split in half in a spiral. +---| "CornerTopLeft" # One main corner window in the top left with a column of windows on the right and a row on the bottom. +---| "CornerTopRight" # One main corner window in the top right with a column of windows on the left and a row on the bottom. +---| "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. + +---Add tags to the specified output. +--- +---### Examples +--- 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. +--- +---### Example +--- -- 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. +--- +---### Examples +--- -- 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. +--- +---### Examples +--- -- 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. +--- +---### Example +--- 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. +--- +---### Example +--- -- 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. +--- +---### Example +--- -- 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. +--- +---### Example +--- -- 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 + +----------------------------------------------------- + +---Tag objects +---@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 diff --git a/api/lua/doc/window.lua b/api/lua/doc/window.lua new file mode 100644 index 0000000..9f43427 --- /dev/null +++ b/api/lua/doc/window.lua @@ -0,0 +1,277 @@ +-- This Source Code Form is subject to the terms of the Mozilla Public +-- License, v. 2.0. If a copy of the MPL was not distributed with this +-- file, You can obtain one at https://mozilla.org/MPL/2.0/. +-- +-- SPDX-License-Identifier: MPL-2.0 + +---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. +--- +---### Examples +---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. +--- +---### Example +--- 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 + +---Toggle the specified window between tiled and floating. +---@tparam Window win +---@see Window.toggle_floating +function window_module.toggle_floating(win) end + +---Get the specified window's size. +--- +---### Example +--- -- 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. +--- +---### Example +--- -- 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. +--- +---### Example +--- -- 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. +--- +---### Example +--- -- 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 + +---Get this window's floating status. +--- +---### Example +--- -- With the focused window floating... +--- local win = window.get_focused() +--- if win ~= nil then +--- print(window.floating(win)) +--- end +--- -- ...should print `true`. +---@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.floating +function window_module.floating(win) end + +---Get whether or not this window is focused. +--- +---### Example +--- 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 + +-------------------------------------------------------- + +---Window objects +---@classmod Window +local window = {} + +---Set this window's size. +--- +---### Examples +--- 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. +--- +---### Example +--- -- 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. +--- +---### Example +--- -- 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. +--- +---### Example +--- window.get_focused():close() -- close the currently focused window +---@see WindowModule.close +function window:close() end + +---Toggle this window's floating status. +--- +---### Example +--- window.get_focused():toggle_floating() -- toggles the focused window between tiled and floating +---@see WindowModule.toggle_floating +function window:toggle_floating() end + +---Get this window's size. +--- +---### Example +--- -- 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. +--- +---### Example +--- -- 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. +--- +---### Example +--- -- 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. +--- +---### Example +--- -- 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 + +---Get this window's floating status. +--- +---### Example +--- -- With the focused window floating... +--- print(window.get_focused():floating()) +--- -- ...should print `true`. +---@treturn boolean|nil floating `true` if it's floating, `false` if it's tiled, or nil if it doesn't exist. +---@see WindowModule.floating +function window:floating() end + +---Get whether or not this window is focused. +--- +---### Example +--- print(window.get_focused():focused()) -- should print `true`. +---@treturn boolean|nil floating `true` if it's floating, `false` if it's tiled, or nil if it doesn't exist. +---@see WindowModule.focused +function window:focused() end diff --git a/api/lua/msg.lua b/api/lua/msg.lua index 17b2b11..2f135a9 100644 --- a/api/lua/msg.lua +++ b/api/lua/msg.lua @@ -7,25 +7,24 @@ ---@meta _ ---@class _Msg ----@field SetKeybind { key: Keys, modifiers: Modifier[], callback_id: integer } ----@field SetMousebind { button: integer } +---@field SetKeybind { key: Keys, modifiers: Modifier[], callback_id: integer }? +---@field SetMousebind { button: integer }? --Windows ----@field CloseWindow { window_id: WindowId } ----@field ToggleFloating { window_id: WindowId } ----@field SetWindowSize { window_id: WindowId, width: integer?, height: integer? } ----@field MoveWindowToTag { window_id: WindowId, tag_id: TagId } ----@field ToggleTagOnWindow { window_id: WindowId, tag_id: TagId } --- ----@field Spawn { command: string[], callback_id: integer? } ----@field Request Request +---@field CloseWindow { window_id: WindowId }? +---@field ToggleFloating { window_id: WindowId }? +---@field SetWindowSize { window_id: WindowId, width: integer?, height: integer? }? +---@field MoveWindowToTag { window_id: WindowId, tag_id: TagId }? +---@field ToggleTagOnWindow { window_id: WindowId, tag_id: TagId }? +---@field Spawn { command: string[], callback_id: integer? }? +---@field Request Request? --Tags ----@field ToggleTag { tag_id: TagId } ----@field SwitchToTag { tag_id: TagId } ----@field AddTags { output_name: string, tag_names: string[] } ----@field RemoveTags { tag_ids: TagId[] } ----@field SetLayout { tag_id: TagId, layout: Layout } +---@field ToggleTag { tag_id: TagId }? +---@field SwitchToTag { tag_id: TagId }? +---@field AddTags { output_name: string, tag_names: string[] }? +---@field RemoveTags { tag_ids: TagId[] }? +---@field SetLayout { tag_id: TagId, layout: Layout }? --Outputs ----@field ConnectForAllOutputs { callback_id: integer } +---@field ConnectForAllOutputs { callback_id: integer }? ---@alias Msg _Msg | "Quit" @@ -33,22 +32,22 @@ ---@class __Request --Windows ----@field GetWindowProps { window_id: WindowId } +---@field GetWindowProps { window_id: WindowId }? --Outputs ----@field GetOutputProps { output_name: string } +---@field GetOutputProps { output_name: string }? --Tags ----@field GetTagProps { tag_id: TagId } +---@field GetTagProps { tag_id: TagId }? ---@alias _Request __Request | "GetWindows" | "GetOutputs" | "GetTags" ---@alias Request { request_id: integer, request: _Request } ---@class IncomingMsg ----@field CallCallback { callback_id: integer, args: Args? } ----@field RequestResponse { request_id: integer, response: RequestResponse } +---@field CallCallback { callback_id: integer, args: Args? }? +---@field RequestResponse { request_id: integer, response: RequestResponse }? ---@class Args ----@field Spawn { stdout: string?, stderr: string?, exit_code: integer?, exit_msg: string? } ----@field ConnectForAllOutputs { output_name: string } +---@field Spawn { stdout: string?, stderr: string?, exit_code: integer?, exit_msg: string? }? +---@field ConnectForAllOutputs { output_name: string }? ---@alias WindowId integer ---@alias TagId integer @@ -57,13 +56,13 @@ ---@class RequestResponse --Windows ----@field Window { window_id: WindowId|nil } ----@field Windows { window_ids: WindowId[] } ----@field WindowProps { size: integer[]?, loc: integer[]?, class: string?, title: string?, floating: boolean?, focused: boolean? } +---@field Window { window_id: WindowId|nil }? +---@field Windows { window_ids: WindowId[] }? +---@field WindowProps { size: integer[]?, loc: integer[]?, class: string?, title: string?, floating: boolean?, focused: boolean? }? --Outputs ----@field Output { output_name: OutputName? } ----@field Outputs { output_names: OutputName[] } ----@field OutputProps { make: string?, model: string?, loc: integer[]?, res: integer[]?, refresh_rate: integer?, physical_size: integer[]?, focused: boolean?, tag_ids: integer[]? } +---@field Output { output_name: OutputName? }? +---@field Outputs { output_names: OutputName[] }? +---@field OutputProps { make: string?, model: string?, loc: integer[]?, res: integer[]?, refresh_rate: integer?, physical_size: integer[]?, focused: boolean?, tag_ids: integer[]? }? --Tags ----@field Tags { tag_ids: TagId[] } ----@field TagProps { active: boolean?, name: string?, output_name: string? } +---@field Tags { tag_ids: TagId[] }? +---@field TagProps { active: boolean?, name: string?, output_name: string? }? diff --git a/api/lua/output.lua b/api/lua/output.lua index 9de2da2..7e6db78 100644 --- a/api/lua/output.lua +++ b/api/lua/output.lua @@ -157,7 +157,7 @@ function output_module.get_by_res(width, height) local output_names = response.RequestResponse.response.Outputs.output_names - ---@type Output + ---@type Output[] local outputs = {} for _, output_name in pairs(output_names) do local o = create_output(output_name) diff --git a/api/lua/process.lua b/api/lua/process.lua index 001eb77..83062ed 100644 --- a/api/lua/process.lua +++ b/api/lua/process.lua @@ -12,10 +12,10 @@ local process_module = {} ---Spawn a process with an optional callback for its stdout, stderr, and exit information. --- ---`callback` has the following parameters: ---- - `stdout`: The process's stdout printed this line. ---- - `stderr`: The process's stderr printed this line. ---- - `exit_code`: The process exited with this code. ---- - `exit_msg`: The process exited with this message. +--- - `stdout` - The process's stdout printed this line. +--- - `stderr` - The process's stderr printed this line. +--- - `exit_code` - The process exited with this code. +--- - `exit_msg` - The process exited with this message. ---@param command string|string[] The command as one whole string or a table of each of its arguments ---@param callback fun(stdout: string|nil, stderr: string|nil, exit_code: integer|nil, exit_msg: string|nil)? 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) diff --git a/api/lua/tag.lua b/api/lua/tag.lua index d167a92..87a3493 100644 --- a/api/lua/tag.lua +++ b/api/lua/tag.lua @@ -182,8 +182,6 @@ end ---```lua ----- Switches to and displays *only* windows on tag `3` on the focused output. ---tag.switch_to("3") ---- ----local ---``` ---@param name string The name of the tag. ---@param output Output? The output.