Files
nixos-setup/configs/fwbook/hypr/ABOUTME.md
T
ari 3c86efa4ff clean up & hyprland experiments
- Cleaned up docs
- removed hyprglass
- added various ways to do scroll view
2026-08-28 12:58:27 -04:00

6.2 KiB

configs/fwbook/hypr/

Host-specific Hyprland configuration for fwbook. Symlinked to ~/.config/hypr by the skyg.nixos.desktop.tiler.hyprland module, which defaults its configName to the machine hostName (configs/${hostName}/hypr).

Why it lives here (and not configs/hypr)

The Hyprland module links configs/<configName>/hypr -> ~/.config/hypr, with configName defaulting to the hostName. Keeping the config under configs/fwbook/ lets each host own its own Hyprland tweaks (monitors, etc.) without stepping on other machines. The old shared configs/hypr/ (waybar + hyprpanel) was removed when this replaced it.

Config format: Lua

Written in Lua (hyprland.lua), not hyprlang. Hyprland 0.55+ deprecated hyprlang in favor of Lua, and reads ~/.config/hypr/hyprland.lua. Files are split under conf/ and pulled in with require().

The folder is named conf, not hyprland.d, because Hyprland's require() treats . as a path separator — require("hyprland.d/env") would resolve to hyprland/d/env.

Design

  • Layout: Hyprland's native scrolling layout (0.54+), no plugins required. This mirrors niri's scrollable-tiling model. See conf/general.lua.
  • Shell: noctalia (noctalia-shell), autostarted in conf/autostart.lua via hl.on("hyprland.start", ...). Launched with setpriv --ambient-caps -all to drop capabilities inherited from the compositor; without it, D-Bus calls inside quickshell-based apps fail silently (hyprwm/Hyprland#14844). There is intentionally no waybar/hyprpanel.
  • Keybinds: conf/keybindings.lua mirrors configs/niri/shared/binds.kdl and configs/niri/dms/binds.kdl as closely as Hyprland allows.
  • Overview: Pure-Lua workspace overview (conf/overview.lua), no plugin. It enumerates workspaces via hl.get_workspaces() and presents them in a wofi --dmenu picker, dispatching the chosen workspace with hyprctl dispatch workspace. Hyprland's Lua API has no "render a workspace to a texture" primitive, so this is a switcher-style overview (id, name, window count, active/empty/urgent flags) rather than live scaled thumbnails. Bound to Mod+Tab (niri parity) and Mod+G.
  • Overview (plugin, WIP): ScrollOverview (conf/scrolloverview.lua), a niri-like overview plugin (github.com/yayuuu/hyprland-scroll-overview), is the live-thumbnail alternative. Currently disabled (commented out in hyprland.lua) while it's being debugged; would load via hl.plugin.load from the SCROLLOVERVIEW_SO session variable set in modules/nixos/desktop/tiler/hyprland.nix.

Files

hypr/
├── hyprland.lua                 # entry point; require()s conf/*.lua in order
├── screen-record.sh             # wf-recorder toggle (bound to Mod+R)
├── xdph.conf                    # xdph screencopy workaround (force_shm); hyprlang, read by xdph itself
├── stylua.toml                  # stylua formatter settings for the Lua files
├── .luarc.json                  # lua-language-server config (uses types/ as library)
├── dms/                         # DMS-auto-generated Hyprland overrides (colors/layout/windowrules);
│                                # not loaded by default — require() them from hyprland.lua to enable
├── types/
│   └── hl.lua                   # EmmyLua type stubs for the `hl` global (editor-only, never executed)
└── conf/
    ├── env.lua                  # cursor size + Wayland/Qt/Electron env hints (hl.env)
    ├── general.lua              # scrolling layout, gaps/border/rounding (hl.config)
    ├── animations.lua           # workspaces slide = "slidevert" (niri-like); only the `workspaces`
    │                            # leaf overridden — other styles: slide, fade, slidefade, slidefadevert
    ├── monitors.lua             # hl.monitor per display (from configs/niri/.../outputs.kdl)
    ├── inputs.lua               # touchpad tap + natural scroll, kb us, hl.gesture
    ├── window-rules.lua         # hl.window_rule floats for small dialogs/utilities
    ├── keybindings.lua          # niri + noctalia binds, scrolling dispatchers (hl.bind/hl.dsp)
    ├── autostart.lua            # noctalia, hypridle via setpriv (hl.on hyprland.start; drops compositor caps)
    ├── overview.lua             # pure-Lua workspace switcher overview (wofi picker, Mod+Tab/Mod+G)
    └── scrolloverview.lua       # ScrollOverview plugin (niri-like, live thumbnails) — WIP/disabled;
                                 # loads via $SCROLLOVERVIEW_SO, require() commented out in hyprland.lua

Bindings without a clean 1:1 niri mapping

  • Mod+Shift+H (show-hotkey-overlay) — no native Hyprland equivalent; left commented.
  • Mod+Escape (toggle-keyboard-shortcuts-inhibit) — no native equivalent; omitted.
  • Mod+W (toggle-column-tabbed-display) — mapped to hl.dsp.group.toggle() as the nearest analog.
  • Mod+Tab (toggle-overview) — pure-Lua overview (conf/overview.lua); previously the ScrollOverview plugin, and cyclenext before that existed.

Touchpad gestures (niri parity)

niri's 3-finger swipes are mirrored in conf/inputs.lua:

  • Horizontal → scroll_move (scroll through columns along the tape)
  • Vertical → workspace (switch workspaces up/down)
  • Mod + swipe (any direction) → move the whole workspace to the monitor in that direction (movecurrentworkspacetomonitor), mirroring niri's Mod+TouchpadScroll* binds. This replaced the old Mod + mouse wheel approach.

The gesture action is scroll_move (underscore), not scrollmove. The mods = "SUPER" mask is what lets the Mod + swipe variants coexist with the plain swipes. Both require a Hyprland new enough to expose configurable Lua gestures (0.55+). The older scrollmove name and the scrollmove action do not exist — they error with "unknown action".

Behavior deltas from the old hyprlang config

  • Ctrl+Alt+Delete runs uwsm stop (not the exit dispatcher). The Hyprland wiki warns UWSM users that exit breaks the ordered shutdown sequence.
  • Mod+Shift+-/= (window height) uses a fixed pixel delta instead of a percent, since the Lua window.resize dispatcher takes pixels, not %.