234 lines
7.1 KiB
Markdown
234 lines
7.1 KiB
Markdown
# 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%" })
|
|
```
|