From 8a6cb3b37f109755c93a12c8d3c60f0d48af25d5 Mon Sep 17 00:00:00 2001 From: "s0wlz (Matthias Puchstein)" Date: Tue, 12 May 2026 04:36:13 +0200 Subject: [PATCH] let gemini write an api overview of hyprland_lua --- dot_config/hypr/hyprland_lua_api.md | 233 ++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 dot_config/hypr/hyprland_lua_api.md diff --git a/dot_config/hypr/hyprland_lua_api.md b/dot_config/hypr/hyprland_lua_api.md new file mode 100644 index 0000000..46d9631 --- /dev/null +++ b/dot_config/hypr/hyprland_lua_api.md @@ -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%" }) +```