Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Workspaces and monitors

Workspaces

Ten fixed workspaces by default, defined by workspace blocks in the config. They always exist; nothing spawns or destroys them. Each holds an ordered list of windows, its own layout algorithm, and its own layout parameters (master ratio, master count, stack columns, flip, gaps).

A window belongs to exactly one workspace. There is no multi-membership and no tagging.

Workspaces have no monitor affinity. Any workspace can appear on any monitor.

Monitors

Each connected monitor shows exactly one workspace, and no two monitors show the same one. Bringing a workspace to a monitor (Mod+1 through Mod+0) does one of two things:

  • if the workspace is on another monitor, the two monitors swap workspaces;
  • if the workspace is unattached, it replaces the one on this monitor, which becomes unattached.

An unattached workspace keeps its windows and layout state. Nothing is lost; it is simply not on screen.

Monitors are identified by EDID (manufacturer, model, serial) for persistent configuration, falling back to the connector name.

Hotplug

When a monitor connects, it gets the workspace last shown on it, or the lowest-numbered unattached workspace. When a monitor disconnects, its workspace becomes unattached with everything preserved, and can be brought to any remaining monitor.

Focus

Focus follows keyboard commands, not the pointer. Clicking a window focuses it; moving the pointer over it does not. focus-follows-mouse in the input block turns pointer focus on.

Mod+N moves focus to the next monitor; Mod+Shift+N moves the focused window there.

Where new windows open

On the active workspace of the active monitor, unless a window rule says otherwise (open-on-workspace). Dialogs float and open on their parent’s monitor. Fixed-size windows float.

Sending windows

  • Mod+Shift+<n>: send the focused window to workspace n and stay.
  • Mod+Ctrl+<n>: send it and follow.
  • Mod+Shift+Left/Right: send it to the previous or next workspace.

Labels and icons

A workspace can carry a display label and an SVG icon for bars:

workspace "1" {
    label "Trading"
    icon "icons/heroicons/o-chart-bar.svg"
}

Relative icon paths resolve under $XDG_DATA_HOME/atrium/ then /usr/share/atrium/, where the compositor installs 325 Heroicons. Both fields are exposed over IPC and rendered by atrium-shell.