Sweets

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")
FieldDefaultEffect
commandrequiredCommand and arguments used to start the tool
matchrequiredIdentify 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_lossfalseHide 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.

ActionResult
scratchpad_toggleShow a hidden tool, focus an unfocused one, or hide the focused tool
scratchpad_showShow and focus the tool, starting it if necessary
scratchpad_hideHide without closing or starting it
scratchpad_releaseKeep 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 scratchpad

Commands 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 = false is a removed definition whose tool is still alive.
  • startup is idle, launching or waiting_for_map.
  • host is null while 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.

On this page