let gemini write an api overview of hyprland_lua
This commit is contained in:
@@ -0,0 +1,233 @@
|
||||
# Hyprland Lua API Documentation
|
||||
|
||||
## 1. Introduction
|
||||
Since Hyprland v0.55, the traditional `hyprlang` syntax has been deprecated in favor of a powerful **Lua configuration system**. The configuration file is located at `~/.config/hypr/hyprland.lua`. This system allows for dynamic scripting, logic-based configurations, and better integration with external tools through Lua's standard libraries and Hyprland's internal API (`hl`).
|
||||
|
||||
## 2. Global Configuration (`hl.config`)
|
||||
The `hl.config` function is used to set global variables. It accepts a table where keys correspond to configuration sections.
|
||||
|
||||
```lua
|
||||
hl.config({
|
||||
general = {
|
||||
border_size = 2,
|
||||
gaps_in = 5,
|
||||
gaps_out = 20,
|
||||
layout = "dwindle",
|
||||
["col.active_border"] = "rgba(33ccffee) rgba(00ff99ee) 45deg",
|
||||
["col.inactive_border"] = "rgba(595959aa)"
|
||||
},
|
||||
decoration = {
|
||||
rounding = 10,
|
||||
blur = {
|
||||
enabled = true,
|
||||
size = 3,
|
||||
passes = 1
|
||||
},
|
||||
shadow = {
|
||||
enabled = true,
|
||||
range = 4,
|
||||
render_power = 3,
|
||||
color = "rgba(1a1a1aee)"
|
||||
}
|
||||
},
|
||||
input = {
|
||||
kb_layout = "us",
|
||||
follow_mouse = 1,
|
||||
touchpad = {
|
||||
natural_scroll = false
|
||||
}
|
||||
},
|
||||
gestures = {
|
||||
workspace_swipe = true
|
||||
},
|
||||
misc = {
|
||||
force_default_wallpaper = 0,
|
||||
disable_hyprland_logo = true
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Main Categories
|
||||
* **General**: `border_size`, `gaps_in`, `gaps_out`, `layout`, `col.active_border`, `col.inactive_border`, `allow_tearing`, `no_focus_fallback`.
|
||||
* **Decoration**: `rounding`, `rounding_power`, `active_opacity`, `inactive_opacity`, `blur` (subcategory), `shadow` (subcategory), `glow` (subcategory).
|
||||
* **Animations**: `enabled`, `workspace_wraparound`.
|
||||
* **Input**: `kb_layout`, `kb_model`, `sensitivity`, `repeat_rate`, `follow_mouse`, `touchpad` (subcategory), `tablet` (subcategory).
|
||||
* **Gestures**: `workspace_swipe_distance`, `workspace_swipe_touch`, `workspace_swipe_create_new`.
|
||||
* **Group**: `auto_group`, `insert_after_current`, `col.border_active`, `groupbar` (subcategory).
|
||||
* **Misc**: `disable_hyprland_logo`, `vrr`, `animate_manual_resizes`, `enable_swallow`, `focus_on_activate`.
|
||||
* **Binds**: `pass_mouse_when_bound`, `scroll_event_delay`, `workspace_back_and_forth`.
|
||||
* **XWayland**: `enabled`, `use_nearest_neighbor`, `force_zero_scaling`.
|
||||
* **Render**: `direct_scanout`, `ctm_animation`, `cm_enabled`.
|
||||
* **Cursor**: `no_hardware_cursors`, `zoom_factor`, `inactive_timeout`, `hide_on_key_press`.
|
||||
* **Ecosystem**: `no_update_news`, `no_donation_nag`, `enforce_permissions`.
|
||||
|
||||
## 3. Monitors (`hl.monitor`)
|
||||
Monitors are configured using the `hl.monitor` function.
|
||||
|
||||
**Syntax:**
|
||||
```lua
|
||||
hl.monitor({
|
||||
output = "DP-1", -- Name or "desc:..."
|
||||
mode = "1920x1080@144", -- Resolution@Hz or "preferred", "highres", "highrr"
|
||||
position = "0x0", -- Layout position or "auto"
|
||||
scale = 1, -- Scale factor or "auto"
|
||||
transform = 0, -- Rotation (0-7)
|
||||
disabled = false, -- Whether to disable the output
|
||||
mirror = "DP-2", -- Mirror another output
|
||||
bitdepth = 10, -- 8 or 10
|
||||
vrr = 1 -- VRR mode
|
||||
})
|
||||
```
|
||||
|
||||
## 4. Window Rules (`hl.window_rule`)
|
||||
Window rules allow targeting windows by properties to apply static or dynamic effects.
|
||||
|
||||
**Syntax:**
|
||||
```lua
|
||||
hl.window_rule({
|
||||
name = "my-rule", -- Optional for handle management
|
||||
match = {
|
||||
class = "kitty",
|
||||
title = ".*term.*",
|
||||
floating = true
|
||||
},
|
||||
opacity = "0.8",
|
||||
rounding = 10
|
||||
})
|
||||
```
|
||||
|
||||
### Props (Match fields)
|
||||
`class`, `title`, `initial_class`, `initial_title`, `tag`, `xwayland`, `floating`, `fullscreen`, `focus`, `group`, `modal`, `workspace`.
|
||||
|
||||
### Effects
|
||||
* **Static**: `float`, `tile`, `fullscreen`, `move`, `size`, `center`, `pseudo`, `workspace`, `monitor`, `pin`.
|
||||
* **Dynamic**: `opacity`, `border_color`, `rounding`, `animation`, `no_blur`, `idle_inhibit`, `dim_around`, `no_anim`, `stay_focused`.
|
||||
|
||||
## 5. Layer Rules (`hl.layer_rule`)
|
||||
Layer rules target Wayland layers like waybar, rofi, and wallpapers.
|
||||
|
||||
```lua
|
||||
hl.layer_rule({
|
||||
match = { namespace = "waybar" },
|
||||
blur = true,
|
||||
ignore_alpha = 0.5
|
||||
})
|
||||
```
|
||||
|
||||
## 6. Workspace Rules (`hl.workspace_rule`)
|
||||
Workspace rules define behavior for specific workspaces.
|
||||
|
||||
```lua
|
||||
hl.workspace_rule({
|
||||
workspace = "3",
|
||||
monitor = "DP-1",
|
||||
default = true,
|
||||
persistent = true,
|
||||
gaps_in = 0,
|
||||
gaps_out = 0,
|
||||
no_border = true
|
||||
})
|
||||
```
|
||||
|
||||
## 7. Keybinds (`hl.bind`, `hl.unbind`, `hl.define_submap`)
|
||||
Keybinds are created using `hl.bind`.
|
||||
|
||||
**Syntax:**
|
||||
```lua
|
||||
hl.bind(keys, dispatcher, flags)
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```lua
|
||||
-- Simple command
|
||||
hl.bind("SUPER + Q", hl.dsp.exec_cmd("kitty"))
|
||||
|
||||
-- Lua function with logic
|
||||
hl.bind("SUPER + T", function()
|
||||
local win = hl.get_active_window()
|
||||
if win then print(win.title) end
|
||||
end)
|
||||
|
||||
-- Flags
|
||||
hl.bind("SUPER + L", hl.dsp.exec_cmd("swaylock"), { locked = true })
|
||||
```
|
||||
|
||||
### Submaps
|
||||
```lua
|
||||
hl.define_submap("resize", function()
|
||||
hl.bind("right", hl.dsp.window.resize({ x = 10, y = 0, relative = true }), { repeating = true })
|
||||
hl.bind("escape", hl.dsp.submap("reset"))
|
||||
end)
|
||||
hl.bind("ALT + R", hl.dsp.submap("resize"))
|
||||
```
|
||||
|
||||
## 8. Dispatchers (`hl.dsp.*`)
|
||||
Dispatchers perform compositor actions.
|
||||
|
||||
| Category | Dispatchers |
|
||||
|---|---|
|
||||
| **General** | `exec_cmd(cmd, rules?)`, `focus({ direction/window/monitor/workspace })`, `exit()`, `dpms({ action })`, `global(string)` |
|
||||
| **Window** | `close()`, `kill()`, `float({ action })`, `fullscreen({ mode, action })`, `move({ direction/workspace/monitor/coords })`, `resize({ x, y, relative })`, `pin()`, `tag({ tag })` |
|
||||
| **Workspace** | `rename({ workspace, name })`, `move({ monitor })`, `toggle_special(name)` |
|
||||
| **Group** | `toggle()`, `next()`, `prev()`, `active(index)`, `lock({ action })` |
|
||||
|
||||
## 9. Events (`hl.on`)
|
||||
Define callbacks for compositor events.
|
||||
|
||||
```lua
|
||||
hl.on("window.open", function(window)
|
||||
print("New window opened: " .. window.class)
|
||||
end)
|
||||
```
|
||||
**Events**: `hyprland.start`, `window.active`, `workspace.active`, `monitor.added`, `config.reloaded`.
|
||||
|
||||
## 10. Timers (`hl.timer`)
|
||||
Timers for delayed or repeating actions.
|
||||
|
||||
```lua
|
||||
local myTimer = hl.timer(function()
|
||||
hl.notification.create({ text = "Timer fired!" })
|
||||
end, { timeout = 1000, type = "oneshot" })
|
||||
```
|
||||
|
||||
## 11. Convenience Functions
|
||||
* `hl.get_active_window()`
|
||||
* `hl.get_active_workspace()`
|
||||
* `hl.get_monitors()`
|
||||
* `hl.get_config(key)`
|
||||
* `hl.get_cursor_pos()`
|
||||
|
||||
## 12. Environment Variables (`hl.env`)
|
||||
Set environment variables.
|
||||
|
||||
```lua
|
||||
hl.env("QT_QPA_PLATFORM", "wayland;xcb")
|
||||
hl.env("XCURSOR_SIZE", "24")
|
||||
```
|
||||
|
||||
## 13. Custom Layouts (`hl.layout.register`)
|
||||
Register custom Lua-based layouts.
|
||||
|
||||
## 14. Permissions (`hl.permission`)
|
||||
Control sensitive application access.
|
||||
|
||||
```lua
|
||||
hl.permission({ binary = "/usr/bin/grim", type = "screencopy", mode = "allow" })
|
||||
```
|
||||
|
||||
## 15. Plugins
|
||||
Configure and interact with plugins.
|
||||
|
||||
```lua
|
||||
if hl.plugin.csgo_vulkan_fix ~= nil then
|
||||
hl.config({ plugin = { csgo_vulkan_fix = { fix_mouse = false } } })
|
||||
end
|
||||
```
|
||||
|
||||
## 16. Animations & Curves (`hl.animation`, `hl.curve`)
|
||||
Define easing curves and apply them to the animation tree.
|
||||
|
||||
```lua
|
||||
hl.curve("myBezier", { type = "bezier", points = { {0.1, 1}, {1, 0.1} } })
|
||||
hl.animation({ leaf = "windows", enabled = true, speed = 8, curve = "myBezier", style = "popin 80%" })
|
||||
```
|
||||
Reference in New Issue
Block a user