From 1814510b5cb61dfcde7348a097a13a1013eb896f Mon Sep 17 00:00:00 2001 From: xtheeq Date: Wed, 13 May 2026 20:01:35 +0530 Subject: [PATCH] docs: add screenshot example binds and workflow --- docs/meta.json | 2 + docs/screenshot.md | 213 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 215 insertions(+) create mode 100644 docs/screenshot.md diff --git a/docs/meta.json b/docs/meta.json index 8c10c621..89c34444 100644 --- a/docs/meta.json +++ b/docs/meta.json @@ -10,6 +10,8 @@ "visuals", "window-management", "bindings", + "---Examples---", + "screenshot", "---Reference---", "nix-options", "ipc", diff --git a/docs/screenshot.md b/docs/screenshot.md new file mode 100644 index 00000000..f07cdf0c --- /dev/null +++ b/docs/screenshot.md @@ -0,0 +1,213 @@ +--- + +title: Screenshots +description: Example screenshot keybindings and capture workflows for mangowm. + +--- + +mangowm does not include a built-in screenshot tool. This keeps the compositor lean. +Instead, compose your own workflow from small Wayland utilities and bind them to keys; + +| Tool | Purpose | +| :--- | :--- | +| [`grim`](https://github.com/emersion/grim) | Capture the screen or a region to a file | +| [`slurp`](https://github.com/emersion/slurp) | Interactively select a region for `grim` | +| [`wl-copy`](https://github.com/bugaevc/wl-clipboard) | Copy screenshots directly to the clipboard | +| [`satty`](https://github.com/gabm/Satty) | Annotate screenshots before saving | +| [`wayfreeze`](https://github.com/nicbk/wayfreeze) | Freeze the screen before capture | + +Install the required with your package manager or from source. + +`grim` writes to the file path you give it, but **will not create missing directories**. Create one first: + +```bash +mkdir -p ~/Pictures/Screenshots +``` + +Any directory works. `~/Pictures/Screenshots/` is just a convention. + +## Quick Binds + +Short, single-step commands can be placed directly in `config.conf` with `spawn_shell`. +No script file needed. + +### Fullscreen + +Captures the entire display. + +```ini +bind=NONE,Print,spawn_shell,grim $HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png +``` + +### Region + +Select an area with `slurp` before capturing. + +```ini +bind=SHIFT,Print,spawn_shell,g=$(slurp -d) && [ -n "$g" ] && grim -g "$g" $HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png +``` + +### Pointer + +Captures the full screen including the cursor. + +```ini +bind=ALT,Print,spawn_shell,grim -c $HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png +``` + +### Clipboard + +Captures to a temporary file and copies the image to the clipboard; no file is saved. + +```ini +bind=CTRL,Print,spawn_shell,f=$(mktemp -t screenshot-XXXXXX.png) && grim "$f" && wl-copy < "$f" && rm -f "$f" +``` + +### Annotate + +Captures and opens `satty` for drawing before saving. + +```ini +bind=SUPER,Print,spawn_shell,f=$HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png && grim "$f" && satty --filename "$f" --output-filename "$f" --actions-on-enter save-to-file --early-exit +``` + +## Script Binds + +When a command involves multi-step logic, geometry parsing, FIFOs, or screen freezing, +move it into a script and invoke it with `spawn` instead of `spawn_shell`. + +Create the scripts directory first: + +```bash +mkdir -p ~/.config/mango/scripts/screenshot +``` + +### Window + +Uses `mmsg` (ships with mango) to capture the focused window. + +`~/.config/mango/scripts/screenshot/window.sh`: + +```bash +#!/usr/bin/env bash +geometry=$(mmsg -x | awk '/x / {x=$3} /y / {y=$3} /width / {w=$3} /height / {h=$3} END {print x","y" "w"x"h}') +[ -z "$geometry" ] && exit 1 +grim -g "$geometry" "$HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png" +``` + +```ini +bind=CTRL+SHIFT,Print,spawn,$HOME/.config/mango/scripts/screenshot/window.sh +``` + +### Freeze + +Freezes the screen with `wayfreeze` before capturing. + +`~/.config/mango/scripts/screenshot/freeze.sh`: + +```bash +#!/usr/bin/env bash +pipe=$(mktemp -u).fifo +mkfifo "$pipe" +wayfreeze --after-freeze-timeout 100 --after-freeze-cmd "echo > $pipe" & +wayfreeze_pid=$! +read -r < "$pipe" +grim "$HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png" +kill "$wayfreeze_pid" 2>/dev/null +rm -f "$pipe" +``` + +```ini +bind=CTRL+SUPER,Print,spawn,$HOME/.config/mango/scripts/screenshot/freeze.sh +``` + +### Freeze + Region + +Freeze, then select a region with `slurp`. Cleans up on cancel. + +`~/.config/mango/scripts/screenshot/freeze-region.sh`: + +```bash +#!/usr/bin/env bash +pipe=$(mktemp -u).fifo +mkfifo "$pipe" +wayfreeze --after-freeze-timeout 100 --after-freeze-cmd "echo > $pipe" & +wayfreeze_pid=$! +read -r < "$pipe" +geometry=$(slurp -d) +if [[ -z "$geometry" ]]; then + kill "$wayfreeze_pid" 2>/dev/null + rm -f "$pipe" + exit 1 +fi +grim -g "$geometry" "$HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png" +kill "$wayfreeze_pid" 2>/dev/null +rm -f "$pipe" +``` + +```ini +bind=SHIFT+SUPER,Print,spawn,$HOME/.config/mango/scripts/screenshot/freeze-region.sh +``` + +Make all three scripts executable: + +```bash +chmod +x ~/.config/mango/scripts/screenshot/*.sh +``` + +## All-in-One Script + +Prefer fewer files? A single script with subcommands covers every mode above. +Place it in the same directory and use it in place of the individual scripts. + +`~/.config/mango/scripts/screenshot/screenshot.sh`: + +```bash +#!/usr/bin/env bash +set -euo pipefail +mkdir -p "$HOME/Pictures/Screenshots" +filepath="$HOME/Pictures/Screenshots/$(date +%Y%m%d%H%M%S).png" + +case "${1:-fullscreen}" in + region) + g=$(slurp -d); [ -z "$g" ] && exit 1 + grim -g "$g" "$filepath" ;; + window) + g=$(mmsg -x | awk '/x / {x=$3} /y / {y=$3} /width / {w=$3} /height / {h=$3} END {print x","y" "w"x"h}') + [ -z "$g" ] && exit 1 + grim -g "$g" "$filepath" ;; + freeze) + p=$(mktemp -u).fifo; mkfifo "$p" + wayfreeze --after-freeze-timeout 100 --after-freeze-cmd "echo > $p" & wp=$! + read -r < "$p"; grim "$filepath" + kill "$wp" 2>/dev/null; rm -f "$p" ;; + freeze-region) + p=$(mktemp -u).fifo; mkfifo "$p" + wayfreeze --after-freeze-timeout 100 --after-freeze-cmd "echo > $p" & wp=$! + read -r < "$p"; g=$(slurp -d) + if [ -z "$g" ]; then kill "$wp" 2>/dev/null; rm -f "$p"; exit 1; fi + grim -g "$g" "$filepath" + kill "$wp" 2>/dev/null; rm -f "$p" ;; + annotate) + grim "$filepath"; satty --filename "$filepath" --output-filename "$filepath" --actions-on-enter save-to-file --early-exit ;; + *) grim "$filepath" ;; +esac +``` + +Make the script executable: + + +```bash +chmod +x ~/.config/mango/scripts/screenshot/screenshot.sh +``` + +Then add the binds to `config.conf`: + +```ini +bind=NONE,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh fullscreen +bind=SHIFT,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh region +bind=CTRL+SHIFT,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh window +bind=CTRL+SUPER,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh freeze +bind=SHIFT+SUPER,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh freeze-region +bind=SUPER,Print,spawn,$HOME/.config/mango/scripts/screenshot/screenshot.sh annotate +```