Skip to content

docs: per-compositor Quick Preview keybind recipes #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
green2grey merged 1 commit into from
Jul 6, 2026
Merged

docs: per-compositor Quick Preview keybind recipes #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions templates/keybind-examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,56 @@ If your file manager supports desktop actions, the provided `quickview.desktop`
Compositors can bind keys to commands, but they generally do *not* know which file is selected inside your file manager.
This approach works best if you have a helper that can query the selected file (desktop-specific).

The recipes below sidestep that limitation with the most common use case:
previewing the **newest screenshot**. Adjust the glob to your screenshot
directory.

QuickView is single-instance: pressing the bind while a preview is already
open **closes it** (toggle), so one bind is enough for both open and dismiss.

> Rule-matching cheat sheet: **layer rules** match the layer-surface
> namespace `quickview` (the normal path on wlroots compositors), while
> **window rules** match the app ID `io.github.Green2Grey2.QuickView` — those
> only apply on the fallback path when gtk4-layer-shell is unavailable.
> They are different matchers; a window rule will not catch the layer surface.

#### niri

```kdl
binds {
Mod+Shift+Space {
spawn "sh" "-c" "quickview --quick-preview \"$(ls -t ~/Pictures/Screenshots/* | head -n1)\"";
}
}
```

Optional cosmetics for the overlay (matches the layer-surface namespace):

```kdl
layer-rule {
match namespace="quickview"
// e.g. shadow { on; }
}
```

#### Hyprland

```conf
bind = SUPER SHIFT, SPACE, exec, quickview --quick-preview "$(ls -t ~/Pictures/Screenshots/* | head -n1)"

# Optional cosmetics (layer surface, normal path):
layerrule = blur, quickview

# Fallback path only (no layer shell): keep the borderless window floating.
windowrulev2 = float, class:^(io\.github\.Green2Grey2\.QuickView)$
Comment on lines +66 to +69

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 6, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Update the Hyprland rule examples to current syntax

For current Hyprland users on Arch, these rule examples use the old rule grammar: the Hyprland 0.54 Window Rules docs show layer rules as layerrule = blur on, match:namespace waybar and window matches as match:class, while this snippet uses layerrule = blur, quickview and windowrulev2 ... class:. Users copying the recipe on Hyprland 0.53/0.54+ will get config errors or rules that do not apply, so the example should either use the new match:namespace / match:class form or be explicitly labeled for old Hyprland versions.

Useful? React with 👍 / 👎.

```

#### Sway

```conf
bindsym $mod+Shift+space exec quickview --quick-preview "$(ls -t ~/Pictures/Screenshots/* | head -n1)"

# Fallback path only (no layer shell): keep the borderless window floating.
for_window [app_id="io.github.Green2Grey2.QuickView"] floating enable
```

Loading