# Hyprland Desktop Environment

The Hyprland setup is the primary desktop environment — a Wayland compositor with a full ecosystem of bars, launchers, notification daemons, and theming tools.

---

## Overview

| Component | Role |
|-----------|------|
| **Hyprland** | Wayland tiling compositor (dwindle layout) |
| **Kitty** | Primary terminal emulator |
| **EWW** | Status bar (three device variants) |
| **Waybar** | Alternative status bar |
| **Wofi** | App launcher (keyboard-driven) |
| **Walker** | Fast CLI launcher |
| **uLauncher** | GUI app launcher |
| **Dunst** | Notification daemon |
| **Hyprlock** | Screen locker |
| **Hyprpaper** | Wallpaper daemon |
| **Hypridle** | Idle management (sleep, lock) |
| **nwg-dock** | Application dock |
| **nwg-drawer** | Application drawer |
| **nwg-panel** | Desktop menu |
| **Vicinae** | Gesture-triggered context launcher |
| **ly** | TUI login manager |

---

## Config File Map

```
desktopenvs/hyprland/
├── hypr/
│   ├── hyprland.conf          # Root config — imports all below
│   ├── hyprtoolkit.conf       # Toolkit utilities
│   ├── hyprlock.conf          # Lock screen
│   ├── hypridle.conf          # Idle timeouts
│   └── hyprpaper.conf         # Wallpaper
├── hypr-usr/                  # Per-user override layer
│   ├── binds.conf             # All keybindings
│   ├── input.conf             # Keyboard/mouse settings
│   ├── monitors.conf          # Display layout
│   ├── windowrules.conf       # Per-app behaviour rules
│   └── autostart.conf         # Startup programs
├── kitty/
│   ├── kitty.conf             # Terminal config
│   ├── current-theme.conf     # Active palette (CyberQueer)
│   └── themes/cyberqueer.conf # Theme definition
├── waybar/
│   ├── config                 # Module layout and data sources
│   └── style.css              # CyberQueer styling
├── wofi/style.css             # Launcher styling
├── walker/themes/             # Walker theme (cyberqueer.css)
├── dunst/                     # Notification styling
├── eww/                       # EWW bar (PC — no battery)
├── eww-nobattery/             # EWW bar alias
├── eww-touch/                 # EWW bar (tablet / touchscreen)
├── spicetify/                 # Spotify CyberQueer themes
├── Vencord/                   # Discord CyberQueer themes
├── btop/                      # System monitor + cyberqueer.theme
├── scripts/                   # 20+ utility scripts
└── config-updater/            # Config synchronisation tool
```

---

## Keybindings

All bindings live in `hypr-usr/binds.conf`.

### Applications

| Binding | Action |
|---------|--------|
| `Super + T` | Kitty terminal |
| `Super + Shift + T` | Cool Retro Term (CRT profile) |
| `Super + M` | Micro editor |
| `Super + E` | Thunar file manager |
| `Super + X` | Wofi app launcher |
| `Super + F` | File search (wofi) |
| `Super + Shift + F` | Folder search (wofi) |

### Window Management

| Binding | Action |
|---------|--------|
| `Super + Q` | Close focused window |
| `Super + V` | Toggle floating |
| `Super + Shift + V` | Centre floating window |
| `Super + P` | Toggle pseudo-tiling |
| `Super + J` | Toggle split direction |
| `Super + Arrow / hjkl` | Focus window by direction |
| `Super + Shift + Arrow / hjkl` | Move window by direction |
| `Super + [0-9]` | Switch workspace |
| `Super + Shift + [0-9]` | Move window to workspace |
| `Super + mouse drag` | Move/resize floating window |

### System

| Binding | Action |
|---------|--------|
| `Super + O` | Lock screen (hyprlock) |
| `Super + Alt + O` | Power menu |
| `Super + Ctrl + O` | Shutdown immediately |
| `Super + Z` | Toggle EWW bar |
| `Super + Ctrl + P` | Start screen recording |

### Touchpad Gestures

| Gesture | Action |
|---------|--------|
| 3-finger swipe left/right | Switch workspace |
| 3-finger swipe up/down | Move window to workspace |
| 3-finger pinch | Toggle overview |
| 4-finger tap | Open launcher |

---

## Status Bar (EWW)

EWW (Elkowar's Wayland Window Manager) is compiled from source during Hyprland install and comes in three variants:

| Variant | Device | Battery Widget |
|---------|--------|---------------|
| `eww/` | Desktop PC | No |
| `eww-nobattery/` | Desktop PC | No |
| `eww-touch/` | Laptop / tablet | Yes |

During install the EWW installer asks which variant to use.

### Waybar

An alternative to EWW — always installed. The bar layout:

- **Left**: clock, disk usage, RAM, CPU, temperature
- **Centre**: workspace switcher, active window title
- **Right**: network speed, IP address, system tray, audio volume, battery (if present)

---

## Launchers

### Wofi

Keyboard-driven app/file launcher. Activated with `Super + X`.  
Config: `wofi/style.css` — themed with CyberQueer colours.

### Walker

Fast CLI launcher (`walker`). Pre-configured with `walker/config.toml` and the `cyberqueer.css` / `cyberqueer.toml` theme files.

### uLauncher

GUI launcher with plugin support. Theme: `ulauncher/user-themes/cyberqueer/`.  
Colours in the theme are colour-substitution targets (updated by `apply-theme.sh`).

---

## Notification Daemon (Dunst)

Lightweight notification daemon. Config in `dunst/dunstrc`.  
Notifications appear top-right with CyberQueer styling.

---

## Lock Screen (Hyprlock)

`hyprlock` is the Wayland screen locker. Config at `hypr/hyprlock.conf`.  
Activated by `Super + O` or automatically via `hypridle` after idle timeout.

---

## Scripts Reference

All scripts live in `desktopenvs/hyprland/scripts/` and are deployed to `~/.config/scripts/`.

| Script | Purpose |
|--------|---------|
| `caffeine.sh` | Toggle hypridle (prevent sleep) |
| `ewwstart.sh` | Launch EWW bar on startup |
| `ewwstart-niri.sh` | EWW for niri compositor variant |
| `togglebar.sh` | Show/hide EWW bar (monitor-aware) |
| `helpmenu.sh` | Display keybindings from binds.conf |
| `screenshot.sh` | Region/full screenshot via grim + slurp |
| `screenrec.sh` | Screen recording |
| `screenrotationacw.sh` | Rotate screen anti-clockwise (tablet) |
| `screenrotationwcw.sh` | Rotate screen clockwise (tablet) |
| `unified-rotate.sh` | Unified rotation handler |
| `hyprland-toggle-touchpad.sh` | Enable/disable touchpad |
| `wofi-file-search.sh` | File search via wofi |
| `foldersearch.sh` | Folder search via wofi |
| `pwr-dmenu.sh` | Power menu (shutdown/reboot/suspend) |
| `caffeine.sh` | Toggle idle inhibitor |
| `getispeed.sh` | Internet speed test display |
| `journal.sh` | Quick journal entry |
| `date.sh` / `time.sh` | Date/time waybar helpers |
| `uptime.sh` | Uptime display |
| `dysk-phydisks.sh` | Physical disk info (dysk) |
| `drawer.sh` | Open nwg-drawer |
| `menu.sh` | Application menu |
| `onscreenkb.sh` | On-screen keyboard (wvkbd) |
| `bluetooth-applet.sh` | Bluetooth UI wrapper |
| `togglewinbars.sh` | Toggle window title bars |
| `toggle-layout.sh` | Switch tiling layout |
| `playpause.sh` | Media play/pause |
| `calender-fix.sh` | Calendar waybar widget fix |

---

## Application Theming

### Spotify (Spicetify)

Two CyberQueer Spicetify themes are available:

| Theme | Style |
|-------|-------|
| `cli-cyberqueer` | CLI-inspired, minimal |
| `matte-cyberqueer` | Matte finish variant |

Applied automatically when the `spotify` module is installed.

### Discord (Vencord)

Two Discord themes:

| Theme | Location |
|-------|----------|
| `cyberqueer.theme.css` | Standalone CyberQueer theme |
| `system24/…/cyberqueer.theme.css` | system24 framework with CyberQueer colours |

### Terminal (Kitty)

The `kitty/themes/cyberqueer.conf` file defines the full 16-colour palette mapped to CyberQueer values. It is sourced by `current-theme.conf` which is imported in `kitty.conf`.

---

## Login Manager (ly)

`ly` is a TUI display manager configured via `etc-ly-config.ini` (deployed to `/etc/ly/config.ini`). Its colours are tracked by `apply-theme.sh` (system file, applied via `sudo`).

---

## Installing Hyprland

```bash
# Via the TUI installer
bash ~/Dotfiles/setup/tui-install.sh
# → Select "shell" and "Hyprland" in the dialogs

# On an existing system
bash ~/Dotfiles/setup/install-modules.sh
# → Not available; Hyprland is a base DE, use the full installer

# Direct script
bash ~/Dotfiles/setup/modules/Desktop-Environments/hyprland.sh
```

The install script compiles EWW from source (requires Rust), copies all configs, installs the GTK and cursor themes, enables `ly@tty1`, and configures `greetd`.