diff --git a/docs/architecture.md b/docs/architecture.md index 3f372d0..fd2491d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -98,7 +98,7 @@ Desktop widgets render GTK widgets directly on the wallpaper background. - **Built-in widgets** (`src/window/desktop/*.py`): Date, weather, calendar, CPU/RAM info. Each module registers itself at import time. - **User widgets** (`config/desktop/*.py`): Drop-in `.py` files that call `DesktopWidgetRegistry.register()`. Loaded dynamically at startup and watched for live reload. - **Position Manager** (`src/window/desktop/main.py`): Reads widget positions from `config/desktop.toml` (per-monitor, fractional coords). Merges with defaults from registry. Drag/drop saves overrides. -- **Desktop Window** (`src/window/desktop/main.py`): `DesktopWidgetWindow` uses a `Gtk.Fixed` container to position widgets at fractional screen coordinates. Handles edit mode (drag and drop), fade animations, and file monitoring. +- **Desktop Window** (`src/window/desktop/main.py`): `DesktopWidgetWindow` uses a `Gtk.Fixed` container to position widgets at fractional screen coordinates. Handles edit mode (drag and drop), fade animations, and file monitoring. Uses a **partial input region** (via `cairo.Region`) so only widget areas receive pointer input — empty desktop space passes through to windows below, preventing interference with Hyprland keybinds like `Super+Q`. ### Lifecycle diff --git a/docs/desktop_widgets.md b/docs/desktop_widgets.md index 0c8c6d1..5d62879 100644 --- a/docs/desktop_widgets.md +++ b/docs/desktop_widgets.md @@ -188,6 +188,17 @@ class LiveClockWidget(Box): DesktopWidgetRegistry.register("live_clock", LiveClockWidget, (174, 174), (0.5, 0.0)) ``` +## Input Regions & Keybind Compatibility + +The desktop widget window uses a **partial input region** — only the rectangular areas occupied by widgets receive pointer and keyboard input. Empty desktop space passes through to windows below. + +This means: +- Hyprland keybinds (e.g., `Super+Q` minimize) work normally even with widgets visible +- Right-clicking on widget areas opens the edit context menu; right-clicking on empty desktop passes through +- Drag and drop works within widget areas + +No configuration needed — this is automatic. If widgets ever interfere with keybinds, check that the widget's `size` in `register()` matches its actual rendered size. + ## Troubleshooting ### Widget not appearing? diff --git a/docs/faqs_tips.md b/docs/faqs_tips.md index a6dce97..7181632 100644 --- a/docs/faqs_tips.md +++ b/docs/faqs_tips.md @@ -68,6 +68,15 @@ The cleanup runs within 2 seconds via file monitor + poll fallback. If it persis - If you delete `desktop.toml`, positions revert to defaults from `register()` calls - Ensure `config/desktop.toml` is writable +### 11. Desktop widget interfering with window keybinds (e.g., Super+Q)? + +The desktop window is a full-screen layer shell surface, which can intercept pointer events and make Hyprland treat it as the focused window. Modus handles this by using a **partial input region** — only widget areas receive input; empty desktop space passes through. + +If keybinds still don't work: +- Check the widget's `size` in `register()` matches its actual rendered size +- Ensure no widget is expanding beyond its expected bounds (e.g., `h_expand=True` without fixed width) +- Restart Modus: `uv run start` + --- ## Pro Tips