Skip to content
Open
22 changes: 22 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -230,6 +230,28 @@ Bookmarks are exported as workspaces over `ext-workspace-v1` — bars that suppo
it can list them and click to jump. It's an export for tooling, not real
workspaces; driftwm is still one canvas.

### Scratchpad

`toggle-scratchpad <app_id> <command>` is a one-key dropdown: it spawns the app
if it isn't running, instantly stows its window when showing, and brings it
back at the exact place and size you left it. Paired with a `pinned_to_screen`
window rule, it makes a Yakuake-style dropdown terminal (or a mail client, a
music player) with no animation and no external script. The app keeps running
while stowed.

```toml
[keybindings]
"mod+w" = "toggle-scratchpad dropdown-term kitty --class dropdown-term"

[[window_rules]]
app_id = "dropdown-term"
pinned_to_screen = true
position = [0, 185]
size = [1200, 450]
```

See [docs/scratchpad.md](docs/scratchpad.md).

### Window suspend & session restore

https://github.com/user-attachments/assets/a91d92bd-55af-4646-8be8-81f35f8f38ca
Expand Down
4 changes: 4 additions & 0 deletions config.reference.toml
Original file line number Diff line number Diff line change
Expand Up @@ -357,6 +357,8 @@
# # fit-window-snapped — fit-window, moving its snap cluster along
# # fill-window — grow the focused window into the free space around it; again to restore
# # toggle-pin-to-screen — pin the focused window to the screen, ignoring pan and zoom
# # toggle-scratchpad <app_id> <cmd> — hide or show the window with that app_id, spawning <cmd> if none exists;
# # such apps are not session-restored (a `restore_windows = true` rule overrides)
# # reload-config — hot-reload the config file
# # toggle-cursor-pan — toggle bare-cursor edge-pan (see [navigation.edge_pan])
# # set-trackpad on|off|toggle — turn every trackpad on or off for this session
Expand Down Expand Up @@ -434,6 +436,8 @@
# # Example: set-trackpad (unbound by default)
# # "mod+f10" = "set-trackpad toggle" # flip the trackpad between on and off
# # "mod+shift+f10" = "set-trackpad off" # turn it off whatever the current state
# # Example: dropdown terminal; pair with a pinned_to_screen window rule for its place
# # "mod+grave" = "toggle-scratchpad dropdown kitty --class dropdown"
# # Example: grow and shrink the right edge by resize_step screen px (unbound by default)
# # "mod+ctrl+alt+right" = "grow-window right"
# # "mod+ctrl+alt+left" = "shrink-window right"
Expand Down
1 change: 1 addition & 0 deletions dev/site/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
- [Home](index.md)
- [Configuration](config.md)
- [Window rules](window-rules.md)
- [Scratchpad](scratchpad.md)
- [Window suspend & session restore](session.md)
- [IPC](ipc.md)
- [CLI](cli.md)
Expand Down
7 changes: 7 additions & 0 deletions docs/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -779,6 +779,7 @@ Actions:
- `fit-window-snapped` — fit-window, moving its snap cluster along
- `fill-window` — grow the focused window into the free space around it; again to restore
- `toggle-pin-to-screen` — pin the focused window to the screen, ignoring pan and zoom
- `toggle-scratchpad <app_id> <cmd>` — hide or show the window with that app_id, spawning <cmd> if none exists; such apps are not session-restored (a `restore_windows = true` rule overrides)
- `reload-config` — hot-reload the config file
- `toggle-cursor-pan` — toggle bare-cursor edge-pan (see [navigation.edge_pan])
- `set-trackpad on|off|toggle` — turn every trackpad on or off for this session
Expand Down Expand Up @@ -880,6 +881,12 @@ Directions: up, down, left, right, up-left, up-right, down-left, down-right
"mod+shift+f10" = "set-trackpad off" # turn it off whatever the current state
```

**Example: dropdown terminal; pair with a pinned_to_screen window rule for its place**

```toml
"mod+grave" = "toggle-scratchpad dropdown kitty --class dropdown"
```

**Example: grow and shrink the right edge by resize_step screen px (unbound by default)**

```toml
Expand Down
102 changes: 102 additions & 0 deletions docs/scratchpad.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
# Scratchpad

A scratchpad is a window you summon and dismiss with one key: a dropdown
terminal, a mail client, a music player. Pressing the key **spawns** the app if
it isn't running, **stows** its window when it is showing, and **shows** it
again when it is stowed. Stowing is instant and animation-free, the window
stays mapped and its app keeps running (a terminal keeps its shell and
scrollback), and showing it puts it back exactly where, and at the size, you
left it.

driftwm has no minimize, so this is the way to get a Quake/Yakuake-style
dropdown without an external script.

## Set one up

Three steps: bind a key, give the window a place, reload.

**1. Find the app's `app_id`.** Start the app and run `driftwm msg state`; each
window is listed with its `app_id`. The binding matches it **exactly**
(`kitty` and `Kitty` are different). Many terminals let you choose it, which
keeps a dropdown terminal apart from your ordinary ones:

| Terminal | Flag |
| --------- | ------------------------ |
| kitty | `--class dropdown-term` |
| foot | `--app-id dropdown-term` |
| alacritty | `--class dropdown-term` |

**2. Bind a key.** `toggle-scratchpad <app_id> <command...>` takes the
`app_id` to look for and the command that spawns it when no such window exists:

```toml
[keybindings]
"mod+w" = "toggle-scratchpad dropdown-term kitty --class dropdown-term"
```

Any binding type works: a key, a tap-modifier chord, a mouse button or a
gesture.

**3. Give it a place.** Where the window appears is decided by an ordinary
[window rule](window-rules.md). Pin it to the screen so it floats above
everything and always comes back on screen, wherever the canvas is panned:

```toml
[[window_rules]]
app_id = "dropdown-term"
pinned_to_screen = true
position = [0, 185] # output-relative, Y-up from the output centre
size = [1200, 450]
```

See [screen-pinned windows](window-rules.md#screen-pinned-windows) for how
`position` works. To find the numbers, run the app, pin it with
`toggle-pin-to-screen` (`Mod+T`), drag and resize it into place, and copy
`position`/`size` from the `pinned` section of `driftwm msg state`.

Reload with `driftwm msg action reload-config` (rules apply to windows opened
afterwards, so close any copy that is already running), then press the key.

## How it behaves

- **It remembers.** The rule only sets the *first* placement. If you move or
resize the window while it is up, the next show restores that geometry.
- **It follows the display.** With several monitors, showing a pinned
scratchpad puts it on the monitor the pointer is on, not the one it was
stowed from. It keeps its position relative to the monitor (centred stays
centred and flush stays flush, whatever the sizes; the share of free space
around the window is kept, so it never ends up off a smaller monitor), and that becomes its position for the next
show.
- **Focus.** Showing raises and focuses the window. Stowing the focused window
hands focus to the most recently used other window.
- **Hidden means gone.** A stowed window is not drawn, takes no clicks, and is
left out of Alt-Tab, the overview and focus-nearest. It still gets frame
callbacks at a throttled rate, so a terminal keeps processing output.
- **Everything of the app toggles together.** All windows with that `app_id`
(a mail client's compose windows, say) and their dialogs are stowed and shown
as one.
- **Fullscreen.** Stowing a fullscreen window leaves fullscreen so you see the
desktop, and showing it puts it back into fullscreen. A fullscreen or maximize
the app asks for while stowed is applied when it is shown.
- **Slow starters.** A repeat press within 3 seconds of a spawn does not launch
the app twice, and a window is never stowed before its first placement, so
its rules still apply.
- **No placeholders.** A scratchpad app is not [session-restored](session.md):
no stand-in comes back after a restart, since the key respawns the app. A
`restore_windows = true` rule for the app overrides this.
- **Reload.** If a reload leaves a stowed window with no binding that can reach
it, it is shown again instead of being stranded.

You can drive one without a binding too:
`driftwm msg action toggle-scratchpad dropdown-term kitty --class dropdown-term`.

## Limitations

- **Pin it.** Scratchpads are meant for `pinned_to_screen` windows. An unpinned
one works, but showing it does not pan the camera to it, so it may be off
screen.
- **Monitor changes.** Unplugging the monitor a pinned window lives on moves it
to a remaining monitor, clamped to fit, and plugging the monitor back in does
not restore the original spot. This is how pinned windows behave in general.
- **IPC wording.** `msg focus`, `move`, `pin` and `suspend` refuse a stowed
window, with a "mid-relaunch" error that does not describe the situation.
5 changes: 5 additions & 0 deletions docs/session.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,11 @@ app_id = "footclient"
restore_windows = false
```

A window that a `toggle-scratchpad` binding (key, tap, mouse or gesture) manages
defaults to `false` here, since its binding respawns it on demand and a restored
stand-in would only sit next to the fresh window. A `restore_windows = true` rule
for that app overrides this.

Two things to keep in mind:

- The flag is **independent of `suspend_on_close`**: that one governs closes,
Expand Down
6 changes: 5 additions & 1 deletion docs/window-rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,9 @@ decoration = "none"
- **Dragging it across monitors** reassigns it to that output. Combine with
`widget = true` to make it immovable.

A pinned window also makes a [scratchpad](scratchpad.md): a key that stows and
shows it without animation.

To find the numbers for a rule, pin the window live with `toggle-pin-to-screen`
(`Mod+T`), drag and resize it into place, then copy `position`/`size` from its
entry in the per-output `pinned` section of `driftwm msg state` — those are
Expand Down Expand Up @@ -481,7 +484,8 @@ evaluated per frame (likewise),
the session is saved or loaded. On load, `restore_windows` is matched against a
saved record, which carries an `app_id` but no title, so only the `app_id`
criterion is consulted there (see
[session restore](session.md#restore_windows)).
[session restore](session.md#restore_windows)). With no rule, an app managed by a
`toggle-scratchpad` binding resolves to `false`.

## Debugging

Expand Down
23 changes: 23 additions & 0 deletions src/config/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -321,6 +321,29 @@ impl Config {
self.bindings.get(&combo)
}

/// Whether any binding (key, tap, mouse, gesture or touch) toggles `app_id`
/// as a scratchpad. A scratchpad is respawned by its own binding, so a
/// restored stand-in for it is only in the way.
pub fn is_scratchpad_app(&self, app_id: &str) -> bool {
let is = |action: &Action| matches!(action, Action::ToggleScratchpad { app_id: a, .. } if a == app_id);
let gesture = |entry: &GestureConfigEntry| {
matches!(
entry,
GestureConfigEntry::Threshold(ThresholdAction::Fixed(a)) if is(a)
)
};
self.bindings
.values()
.chain(self.tap_bindings.values())
.any(is)
|| self
.mouse
.values()
.any(|m| matches!(m, MouseAction::Action(a) if is(a)))
|| self.gestures.values().any(gesture)
|| self.touch_gestures.values().any(gesture)
}

/// Look up a tap-modifier binding by the completed chord's modifier set.
pub fn tap_lookup(&self, mods: &Modifiers) -> Option<&Action> {
self.tap_bindings.get(mods)
Expand Down
12 changes: 12 additions & 0 deletions src/config/parse.rs
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,16 @@ pub fn parse_action(s: &str) -> Result<Action, String> {
let cmd = arg.ok_or("spawn requires a command argument")?;
Ok(Action::Spawn(cmd.to_string()))
}
"toggle-scratchpad" => {
let arg = arg.ok_or("toggle-scratchpad requires an app_id and a command")?;
let (app_id, command) = arg
.split_once(char::is_whitespace)
.ok_or("toggle-scratchpad requires a command after the app_id")?;
Ok(Action::ToggleScratchpad {
app_id: app_id.to_string(),
command: command.trim().to_string(),
})
}
"exec-terminal" => Ok(Action::ExecTerminal),
"exec-launcher" => Ok(Action::ExecLauncher),
"close-window" => Ok(Action::CloseWindow),
Expand Down Expand Up @@ -273,6 +283,7 @@ pub const ACTION_NAMES: &[(&str, &str)] = &[
("toggle-cursor-pan", "toggle-cursor-pan"),
("toggle-fullscreen", "toggle-fullscreen"),
("toggle-pin-to-screen", "toggle-pin-to-screen"),
("toggle-scratchpad", "toggle-scratchpad foo foo"),
("zoom-in", "zoom-in"),
("zoom-out", "zoom-out"),
("zoom-reset", "zoom-reset"),
Expand Down Expand Up @@ -632,6 +643,7 @@ mod tests {
Action::ExecTerminal => "exec-terminal",
Action::ExecLauncher => "exec-launcher",
Action::Spawn(_) => "spawn",
Action::ToggleScratchpad { .. } => "toggle-scratchpad",
Action::CloseWindow => "close-window",
Action::SuspendWindow => "suspend-window",
Action::NudgeWindow(_) => "nudge-window",
Expand Down
17 changes: 16 additions & 1 deletion src/config/types.rs
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,11 @@ pub enum Action {
ExecTerminal,
ExecLauncher,
Spawn(String),
/// Show or hide the window with this `app_id`, spawning `command` when none exists.
ToggleScratchpad {
app_id: String,
command: String,
},
CloseWindow,
SuspendWindow,
NudgeWindow(Direction),
Expand All @@ -63,7 +68,9 @@ pub enum Action {
CenterWindow,
CenterNearest(Direction),
FocusNearest(Direction),
CycleWindows { backward: bool },
CycleWindows {
backward: bool,
},
HomeToggle,
GoToBookmark(String),
SetBookmark(String),
Expand Down Expand Up @@ -418,6 +425,14 @@ impl<K: Eq + Hash, V> ContextBindings<K, V> {
}
}

/// Every bound value across all three contexts.
pub fn values(&self) -> impl Iterator<Item = &V> {
self.on_window
.values()
.chain(self.on_canvas.values())
.chain(self.anywhere.values())
}

pub fn lookup(&self, key: &K, context: BindingContext) -> Option<&V> {
let specific = match context {
BindingContext::OnWindow => &self.on_window,
Expand Down
3 changes: 3 additions & 0 deletions src/input/actions.rs
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,9 @@ impl DriftWm {
tracing::info!("Spawning (no cursor): {cmd}");
crate::state::spawn_command(cmd, &self.config.child_env);
}
Action::ToggleScratchpad { app_id, command } => {
self.toggle_scratchpad_from(app_id, command, was_fullscreen.as_ref());
}
Action::CloseWindow => match self.focused_element() {
// A focused stand-in has no client to close — the close binding
// dismisses it instead.
Expand Down
12 changes: 11 additions & 1 deletion src/input/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1910,6 +1910,9 @@ impl DriftWm {
let Some(p) = self.stage.pin_of(window) else {
continue;
};
if self.hidden_by_deferred_adopt(window) {
continue;
}
if p.output != output_name {
continue;
}
Expand Down Expand Up @@ -2066,6 +2069,9 @@ impl DriftWm {
let Some(p) = self.stage.pin_of(window) else {
continue;
};
if self.hidden_by_deferred_adopt(window) {
continue;
}
if p.output != output_name {
continue;
}
Expand Down Expand Up @@ -2153,6 +2159,9 @@ impl DriftWm {
let Some(p) = self.stage.pin_of(window) else {
continue;
};
if self.hidden_by_deferred_adopt(window) {
continue;
}
if p.output != output_name {
continue;
}
Expand Down Expand Up @@ -2575,7 +2584,8 @@ impl DriftWm {
.filter_map(|w| w.client())
.find(|&window| {
self.stage.pin_of(window).is_some_and(|p| {
p.output == output_name
!self.hidden_by_deferred_adopt(window)
&& p.output == output_name
&& self
.resize_margin_hit_for(window, p.screen_pos, screen_pos)
.is_some()
Expand Down
4 changes: 3 additions & 1 deletion src/render/lifecycle.rs
Original file line number Diff line number Diff line change
Expand Up @@ -265,7 +265,9 @@ pub fn post_render(state: &mut crate::state::DriftWm, output: &Output) {
let geom_loc = window.geometry().loc;
let mut bbox = window.bbox_with_popups();
bbox.loc += loc - geom_loc;
let on_screen = visible_rect.overlaps(bbox);
// A stowed scratchpad window is not drawn but keeps its client alive, so
// it gets the off-screen heartbeat and a terminal can keep rendering.
let on_screen = visible_rect.overlaps(bbox) && !state.hidden_by_deferred_adopt(window);

window.send_frame(
output,
Expand Down
2 changes: 2 additions & 0 deletions src/state/init.rs
Original file line number Diff line number Diff line change
Expand Up @@ -371,6 +371,8 @@ impl DriftWm {
pending_relaunches: BTreeMap::new(),
pending_adoptions: HashMap::new(),
deferred_adoptions: Vec::new(),
scratchpad_hidden: Vec::new(),
scratchpad_spawns: HashMap::new(),
session_store: super::SessionStore::default(),
bookmarks,
window_focus: None,
Expand Down
Loading