Scratchpads
Named floating tools you can summon and hide with one key
A scratchpad is a floating tool you summon over your desktop. The first press starts it, later presses reuse the same window.
-- Foot terminal
sweets.scratchpad("terminal", {
command = { "foot", "--app-id", "sweets-scratch-terminal" },
match = { app_id = "sweets-scratch-terminal" },
size = { 0.8, 0.5 },
position = "center",
})
sweets.bind("MOD+Alt+F12", "scratchpad_toggle", "terminal")
sweets.bind("MOD+Alt+Shift+F12", "scratchpad_release", "terminal")-- Nautilus
sweets.scratchpad("nautilus", {
command = { "nautilus", "--new-window" },
match = { app_id = "org.gnome.Nautilus" },
size = { 1920, 1080 },
position = "center",
hide_on_focus_loss = true,
})
sweets.bind("MOD+N", "scratchpad_toggle", "nautilus")
sweets.bind("MOD+Shift+N", "scratchpad_release", "nautilus")| Field | Default | Effect |
|---|---|---|
command | required | Command and arguments used to start the tool |
match | required | Identify its window with the window matcher |
size | { 0.8, 0.5 } | Initial width and height; fractions use the available monitor area |
position | "center" | Initial floating position, using the window-rule positions |
hide_on_focus_loss | false | Hide when keyboard focus moves to another desktop window |
Give the tool a dedicated app ID so match can't grab another window.
Actions
Each action takes the scratchpad's name.
| Action | Result |
|---|---|
scratchpad_toggle | Show a hidden tool, focus an unfocused one, or hide the focused tool |
scratchpad_show | Show and focus the tool, starting it if necessary |
scratchpad_hide | Hide without closing or starting it |
scratchpad_release | Keep the window as an ordinary floating window |
Hiding restores the previous focus. Several tools can be visible at once, and their dialogs and menus follow them.
Behavior
- Move and resize tools freely. Placement is remembered per monitor until Sweets exits.
- Moving a tool to a numbered workspace releases it. Release it before tiling, grouping or pinning it.
- Minimizing hides the whole tool. Fullscreen and maximize work normally.
- Leaving the host workspace, showing a special workspace, opening Overview, locking, or losing the monitor hides visible tools.
- Config changes apply to the next window, except
hide_on_focus_loss, which applies on reload. Removing a definition hides its tool. Keep a show or release binding so you can get it back.
IPC
sweets msg scratchpads
sweets msg scratchpad terminal
sweets msg scratchpad-show terminal
sweets msg scratchpad-hide terminal
sweets msg scratchpad-toggle terminal
sweets msg scratchpad-release terminal
sweets msg subscribe scratchpadCommands follow the same rules as bindings and take no launch arguments.
Show and hide report changed=false when nothing changes. Names are 1–32 ASCII
letters, digits, _ or -, and case-sensitive. Up to 16 can exist at once.
Inspection returns name, active, startup, root, family, host and
desired_visible:
active = falseis a removed definition whose tool is still alive.startupisidle,launchingorwaiting_for_map.hostisnullwhile hidden, otherwise{ workspace, output }.
Inspection works while locked; actions return locked. Other errors are
invalid_request for a bad name, not_found for an unknown one, and
unavailable for refusals.
The scratchpad event means "query again". Use the usual
subscribe and reconnect flow.