| 1 |
# Special Workspaces (Scratchpads) |
| 2 |
|
| 3 |
Special workspaces are named overlay workspaces that can be toggled on and off over the current workspace. They're useful for quick-access tools like terminals, music players, or chat apps. |
| 4 |
|
| 5 |
## Defining a special workspace |
| 6 |
|
| 7 |
In your config: |
| 8 |
|
| 9 |
```lua |
| 10 |
gar.special_workspace("term", { |
| 11 |
position = "center", |
| 12 |
width = 0.8, |
| 13 |
height = 0.8, |
| 14 |
}) |
| 15 |
``` |
| 16 |
|
| 17 |
This creates a special workspace named `"term"` that appears as a centered overlay covering 80% of the screen in both dimensions. |
| 18 |
|
| 19 |
## Options |
| 20 |
|
| 21 |
| Key | Type | Default | Description | |
| 22 |
|-----|------|---------|-------------| |
| 23 |
| `position` | string | `"center"` | Overlay placement: `"center"`, `"top"`, `"bottom"` | |
| 24 |
| `width` | number | `0.7` | Width as fraction of screen (0.0 – 1.0) | |
| 25 |
| `height` | number | `0.7` | Height as fraction of screen (0.0 – 1.0) | |
| 26 |
|
| 27 |
### Position behavior |
| 28 |
|
| 29 |
- **`"center"`** — the overlay is centered both horizontally and vertically |
| 30 |
- **`"top"`** — the overlay is anchored to the top of the screen, centered horizontally |
| 31 |
- **`"bottom"`** — the overlay is anchored to the bottom, centered horizontally |
| 32 |
|
| 33 |
## Toggling a special workspace |
| 34 |
|
| 35 |
Bind a key to toggle visibility: |
| 36 |
|
| 37 |
```lua |
| 38 |
gar.bind("mod+grave", "toggle-special term") |
| 39 |
``` |
| 40 |
|
| 41 |
When toggled on, all windows in the special workspace are shown as an overlay on the current monitor. When toggled off, they're hidden. |
| 42 |
|
| 43 |
Via IPC: |
| 44 |
|
| 45 |
```bash |
| 46 |
tarmacctl toggle-special term |
| 47 |
``` |
| 48 |
|
| 49 |
## Moving windows to a special workspace |
| 50 |
|
| 51 |
```lua |
| 52 |
gar.bind("mod+shift+grave", "move-to-special term") |
| 53 |
``` |
| 54 |
|
| 55 |
```bash |
| 56 |
tarmacctl move-to-special term |
| 57 |
``` |
| 58 |
|
| 59 |
This removes the focused window from its current workspace and places it in the named special workspace. The window will be visible next time the special workspace is toggled on. |
| 60 |
|
| 61 |
## Multiple scratchpads |
| 62 |
|
| 63 |
You can define as many special workspaces as you want: |
| 64 |
|
| 65 |
```lua |
| 66 |
gar.special_workspace("term", { |
| 67 |
position = "center", |
| 68 |
width = 0.8, |
| 69 |
height = 0.8, |
| 70 |
}) |
| 71 |
|
| 72 |
gar.special_workspace("music", { |
| 73 |
position = "bottom", |
| 74 |
width = 1.0, |
| 75 |
height = 0.4, |
| 76 |
}) |
| 77 |
|
| 78 |
gar.special_workspace("chat", { |
| 79 |
position = "top", |
| 80 |
width = 0.6, |
| 81 |
height = 0.5, |
| 82 |
}) |
| 83 |
|
| 84 |
gar.bind("mod+grave", "toggle-special term") |
| 85 |
gar.bind("mod+m", "toggle-special music") |
| 86 |
gar.bind("mod+c", "toggle-special chat") |
| 87 |
``` |
| 88 |
|
| 89 |
## Assigning windows via rules |
| 90 |
|
| 91 |
Force a window into a special workspace on creation: |
| 92 |
|
| 93 |
```lua |
| 94 |
gar.rule({ app_name = "Spotify" }, { workspace = "special:music" }) |
| 95 |
``` |
| 96 |
|
| 97 |
The `workspace` value must be `"special:NAME"` where NAME matches the special workspace name. |
| 98 |
|
| 99 |
<img |
| 100 |
src="/scratchpad.png" |
| 101 |
alt="tarmac scratchpad — a centered terminal overlay on top of the tiled layout" |
| 102 |
className="rounded-lg border border-surface-200 dark:border-surface-700 my-6 w-full" |
| 103 |
loading="lazy" |
| 104 |
/> |