2019-11-19 08:21:06 +03:00
# swappy
2019-12-15 21:59:06 +03:00
2021-02-18 07:58:30 +03:00
A Wayland native snapshot and editor tool, inspired by [Snappy] on macOS. Works great with [grim], [slurp] and [sway]. But can easily work with other screen copy tools that can output a final image to `stdout` . See [below ](#example-usage ).
2019-12-29 03:50:47 +03:00
2019-12-30 08:44:42 +03:00
## Screenshot
2019-12-15 21:59:06 +03:00
2020-06-21 05:35:14 +03:00
![Swappy Screenshot ](docs/images/screenshot-1.0.0.png )
2019-12-15 21:59:06 +03:00
2019-12-28 03:56:05 +03:00
## Example usage
2019-12-15 21:59:06 +03:00
2021-02-18 07:58:30 +03:00
Output of `grim` (or any tool outputing an image file):
2019-12-30 08:44:42 +03:00
```sh
grim -g "$(slurp)" - | swappy -f -
```
2020-06-17 06:02:58 +03:00
Swappshot a PNG file:
2019-12-30 08:44:42 +03:00
```sh
swappy -f "~/Desktop/my-gnome-saved-file.png"
```
2020-01-20 02:09:15 +03:00
Print final surface to stdout (useful to pipe with other tools):
```sh
grim -g "$(slurp)" - | swappy -f - -o - | pngquant -
```
2019-12-28 03:56:05 +03:00
Grab a swappshot from a specific window under Sway, using `swaymsg` and `jq` :
```sh
2019-12-30 08:44:42 +03:00
grim -g "$(swaymsg -t get_tree | jq -r '.. | select(.pid? and .visible?) | .rect | "\(.x),\(.y) \(.width)x\(.height)"' | slurp)" - | swappy -f -
2019-12-15 21:59:06 +03:00
```
2019-12-28 03:56:05 +03:00
2020-01-12 23:32:38 +03:00
## Config
The config file is located at `$XDG_CONFIG_HOME/swappy/config` or at `$HOME/.config/swappy/config` .
The file follows the GLib `conf` format. See the `man` page for details. There is example config file [here ](example/config ).
The following lines can be used as swappy's default:
```
2020-06-21 23:47:06 +03:00
[Default]
save_dir=$HOME/Desktop
2020-11-10 01:04:03 +03:00
save_filename_format=swappy-%Y%m%d-%H%M%S.png
2020-06-21 23:47:06 +03:00
show_panel=false
line_size=5
text_size=20
text_font=sans-serif
2021-12-25 20:26:11 +03:00
paint_mode=brush
2022-07-31 13:04:54 +03:00
early_exit=false
2022-11-19 00:05:37 +03:00
fill_shape=false
2020-01-12 23:32:38 +03:00
```
2021-12-25 20:26:11 +03:00
- `save_dir` is where swappshots will be saved, can contain env variables, when it does not exist, swappy attempts to create it first, but does not abort if directory creation fails
2021-08-30 09:57:51 +03:00
- `save_filename_format` : is the filename template, if it contains a date format, this will be parsed into a timestamp. Format is detailed in [strftime(3) ](https://man.archlinux.org/man/strftime.3 ). If this date format is missing, filename will have no timestamp
2021-02-21 02:35:10 +03:00
- `show_panel` is used to toggle the paint panel on or off upon startup
- `line_size` is the default line size (must be between 1 and 50)
- `text_size` is the default text size (must be between 10 and 50)
- `text_font` is the font used to render text, its format is pango friendly
2021-12-25 20:26:11 +03:00
- `paint_mode` is the mode activated at application start (must be one of: brush|text|rectangle|ellipse|arrow|blur, matching is case-insensitive)
2022-07-31 13:04:54 +03:00
- `early_exit` is used to make the application exit after saving the picture or copying it to the clipboard
2022-11-19 00:05:37 +03:00
- `fill_shape` is used to toggle shape filling (for the rectangle and ellipsis tools) on or off upon startup
2020-01-12 23:32:38 +03:00
2019-12-29 03:50:47 +03:00
## Keyboard Shortcuts
2021-02-21 02:35:10 +03:00
- `Ctrl+b` : Toggle Paint Panel
2019-12-29 03:50:47 +03:00
2019-12-29 04:20:50 +03:00
< hr >
2019-12-29 03:50:47 +03:00
2021-02-21 02:35:10 +03:00
- `b` : Switch to Brush
- `t` : Switch to Text
- `r` : Switch to Rectangle
- `o` : Switch to Ellipse
- `a` : Switch to Arrow
- `d` : Switch to Blur (`d` stands for droplet)
2019-12-29 03:50:47 +03:00
2019-12-29 04:20:50 +03:00
< hr >
2019-12-29 03:50:47 +03:00
2021-02-21 02:35:10 +03:00
- `R` : Use Red Color
- `G` : Use Green Color
- `B` : Use Blue Color
- `C` : Use Custom Color
- `Minus` : Reduce Stroke Size
- `Plus` : Increase Stroke Size
- `Equal` : Reset Stroke Size
2022-11-19 00:05:37 +03:00
- `f` : Toggle Shape Filling
2021-02-21 02:35:10 +03:00
- `k` : Clear Paints (cannot be undone)
2019-12-29 03:50:47 +03:00
2019-12-29 04:20:50 +03:00
< hr >
2019-12-29 03:50:47 +03:00
2021-02-21 04:53:24 +03:00
- `Ctrl` : Center Shape (Rectangle & Ellipse) based on draw start
< hr >
2021-02-21 02:35:10 +03:00
- `Ctrl+z` : Undo
- `Ctrl+Shift+z` or `Ctrl+y` : Redo
- `Ctrl+s` : Save to file (see man page)
- `Ctrl+c` : Copy to clipboard
- `Escape` or `q` or `Ctrl+w` : Quit swappy
2019-12-29 03:50:47 +03:00
## Limitations
2021-02-21 02:35:10 +03:00
- **Copy**: If you don't have [wl-clipboard] installed, copy to clipboard won't work if you close swappy (the content of the clipboard is lost). This because GTK 3.24 [has not implemented persistent storage on wayland backend yet ](https://gitlab.gnome.org/GNOME/gtk/blob/3.24.13/gdk/wayland/gdkdisplay-wayland.c#L857 ). We need to do it on the [Wayland level ](https://github.com/swaywm/wlr-protocols/blob/master/unstable/wlr-data-control-unstable-v1.xml ), or wait for GTK 4. For now, we use `wl-copy` if installed and revert to `gtk` clipboard if not found.
- **Fonts**: Swappy relies on Font Awesome 5 being present to properly render the icons. On Arch you can simply install those with: `sudo pacman -S otf-font-awesome`
2019-12-29 03:50:47 +03:00
2019-12-29 01:46:35 +03:00
## Installation
2019-12-28 03:56:05 +03:00
2021-02-21 08:30:06 +03:00
- [Arch Linux ](https://archlinux.org/packages/community/x86_64/swappy/ )
2021-02-21 02:35:10 +03:00
- [Arch Linux (git) ](https://aur.archlinux.org/packages/swappy-git )
2021-08-30 09:57:51 +03:00
- [Fedora ](https://src.fedoraproject.org/rpms/swappy )
2021-02-21 02:35:10 +03:00
- [openSUSE ](https://build.opensuse.org/package/show/X11:Wayland/swappy )
- [Void Linux ](https://github.com/void-linux/void-packages/tree/master/srcpkgs/swappy )
2019-12-28 03:56:05 +03:00
## Building from source
2020-05-17 19:52:01 +03:00
Install dependencies (on Arch, name can vary for other distros):
2019-12-28 03:56:05 +03:00
2021-02-21 02:35:10 +03:00
- meson
- ninja
- cairo
- pango
- gtk
- glib2
- scdoc
2019-12-28 03:56:05 +03:00
Optional dependencies:
2021-02-21 02:35:10 +03:00
- `wl-clipboard` (to make sure the copy is saved if you close swappy)
- `otf-font-awesome` (to draw the paint icons properly)
2019-12-28 03:56:05 +03:00
Then run:
```sh
meson build
ninja -C build
2019-12-15 21:59:06 +03:00
```
2019-12-28 03:56:05 +03:00
2021-02-19 06:39:16 +03:00
### i18n
2021-02-21 03:05:14 +03:00
This section is for developers, maintainers and translators.
To add support to a new locale or when translations are updated:
1. Update `src/po/LINGUAS` (when new locales are added)
2. Generate a new `po` file (ignore and do not commit potential noise in other files):
```sh
ninja -C build swappy-update-po
```
To rebuild the base template (should happen less often):
2021-02-19 06:39:16 +03:00
```sh
ninja -C build swappy-pot
```
2021-02-21 03:05:14 +03:00
See the [meson documentation ](https://mesonbuild.com/Localisation.html ) for details.
2019-12-28 03:56:05 +03:00
## Contributing
2020-06-23 06:03:37 +03:00
Pull requests are welcome. This project uses [conventional commits ](https://www.conventionalcommits.org/en/v1.0.0/ ) to automate changelog generation.
2021-02-21 02:31:57 +03:00
## Release
2020-06-23 06:03:37 +03:00
2021-02-21 02:31:57 +03:00
We rely on [standard-version ](https://github.com/conventional-changelog/standard-version ) which is part of the JavaScript ecosystem but works well with any project.
2020-06-23 06:03:37 +03:00
2022-11-21 00:35:52 +03:00
```sh
./script/github-release
2020-06-23 06:03:37 +03:00
```
2022-11-21 00:35:52 +03:00
Make sure everything is valid in the Draft release, then publish the draft.
2019-12-28 03:56:05 +03:00
2021-02-21 02:31:57 +03:00
Release tarballs are signed with this PGP key: `F44D05A50F6C9EB5C81BCF966A6B35DBE9442683`
2019-12-28 03:56:05 +03:00
## License
MIT
2019-12-30 08:44:42 +03:00
[snappy]: http://snappy-app.com/
2019-12-28 03:56:05 +03:00
[slurp]: https://github.com/emersion/slurp
[grim]: https://github.com/emersion/grim
[sway]: https://github.com/swaywm/sway
2020-01-06 06:34:16 +03:00
[wl-clipboard]: https://github.com/bugaevc/wl-clipboard