Aqueous layout.toml Reference

# =============================================================================
# Aqueous layout configuration reference
# =============================================================================
#
# This optional sidecar keeps layout selection and geometry separate from
# wm.toml. Aqueous uses a small TOML-compatible parser: unknown sections, keys,
# and malformed values are ignored while recognized valid values are applied.
#
# Actual discovery order (first usable path wins):
#   1. ~/.config/aqueous/layout.toml, when $HOME is set and the file exists
#   2. $AQUEOUS_LAYOUT (~ is expanded)
#   3. [layout].path from wm.toml (relative to wm.toml)
#   4. $XDG_CONFIG_HOME/aqueous/layout.toml
#   5. /etc/xdg/aqueous/layout.toml
#
# The sidecar is applied after wm.toml. Recognized scalar and per-layout fields
# are merged one key at a time, so omitted values retain their wm.toml/default
# value. [[output]] and [[workspace]] layout mappings are also accepted here,
# but matching mappings already loaded from wm.toml are resolved first. Define
# each mapping in only one file to avoid ambiguous duplicates.
#
# Configuration is polled and hot-reloaded on the Wayland event loop. Super+R
# requests the same reload immediately.

# -----------------------------------------------------------------------------
# Global layout defaults
# -----------------------------------------------------------------------------
[layout]
# Layout used when there is no runtime, output, or workspace override.
# Accepted: tile | monocle | grid | rows | dwindle | reverse-dwindle |
#           reverse_dwindle | scrolling | float | floating | stack | stacking | game-mode |
#           game_mode | composable
default = "tile"
# Default named snap layout for stacking workspaces.
snap_layout = "work"

# Common geometry applied to every layout. Layout-specific sections below can
# override any common field for one engine.
gaps_outer  = 8       # pixels around the usable output rectangle; >= 0
gaps_inner  = 4       # pixels between placements; >= 0
master_ratio = 0.55   # master share used by tile/dwindle/reverse-dwindle; strictly 0 < value < 1
master_count = 1      # number of windows in tile's master area; >= 1

# Center a lone tiled window in tile, grid, rows, dwindle and reverse-dwindle.
# Keep the available height and cap width at height * aspect ratio. Narrower
# outputs keep their available width. Floating/dialog/minimized/fullscreen and
# maximized windows do not count. Each composable child counts independently.
# Opening a second tile restores normal tiling; returning to one centers again.
center_single_window = false
single_window_aspect_ratio = 1.7777777777777777 # approximately 16:9; finite and > 0

# Border colors use 0xAARRGGBB.
border_width   = 2
border_focused = 0xFF88C0D0
border_normal  = 0xFF3B4252
border_urgent  = 0xFFBF616A

# Force server-side mode for native clients. Aqueous enforces the mode for
# clients that create an xdg-decoration object and publishes the matching
# display-wide legacy server-decoration preference used by GTK 3 and GTK 4.
# Reloading this setting updates both protocols; GTK applies the new preference
# to newly created windows but does not rebuild existing window chrome.
# This cannot remove a title bar drawn into the application's own content.
# Diagnose a remaining title bar with:
#   aqueousctl windows --json | jq '.[] | {app_id, title, decoration}'
# `capability: "unavailable"` means there is no per-window xdg-decoration
# object. A normal GTK window may still follow the legacy display preference;
# a custom GtkHeaderBar/AdwHeaderBar remains application content.
force_ssd = false

# Optional when these settings live in wm.toml instead of this sidecar:
# path = "~/.config/aqueous/layout.toml"

# -----------------------------------------------------------------------------
# Runtime layout slots
# -----------------------------------------------------------------------------
# The set_layout_primary/secondary/tertiary/quaternary actions resolve through
# these four slots. Every slot accepts any layout ID listed above.
[layout.slots]
primary    = "tile"
secondary  = "scrolling"
tertiary   = "monocle"
quaternary = "grid"

# -----------------------------------------------------------------------------
# Composable regions
# -----------------------------------------------------------------------------
# Optional. Select `composable` as the default, a slot, or a workspace/output
# layout to divide that workspace into as many as four independent layouts.
# Region names are fixed: a, b, c, and d. Unconfigured regions are disabled.
#
# Points are normalized [x, y] coordinates in the strut-adjusted usable output:
# p1 = top-left, p2 = top-right, p3 = bottom-right, p4 = bottom-left. The four
# points must describe a non-zero, axis-aligned rectangle in clockwise order.
# Regions may touch and may leave unused space, but must not overlap. Invalid or
# incomplete region configuration makes `composable` fall back to full-area
# `tile` placement.
#
# Child layouts may be tile, monocle, grid, rows, dwindle, reverse-dwindle, scrolling, or float.
# game-mode and composable cannot be nested. Each child retains independent
# ordering, scrolling, and floating state. A region is active whenever one of
# its windows has focus, and newly managed windows join that active region.

[layout.composable.a]
layout = "tile"
p1 = [0.0, 0.0]
p2 = [0.5, 0.0]
p3 = [0.5, 1.0]
p4 = [0.0, 1.0]

[layout.composable.b]
layout = "scrolling"
p1 = [0.5, 0.0]
p2 = [1.0, 0.0]
p3 = [1.0, 1.0]
p4 = [0.5, 1.0]

# Optional custom actions in wm.toml can target a region directly:
# [keybinds.custom]
# "Super+Alt+1"       = "builtin:focus_composable:a"
# "Super+Alt+Shift+1" = "builtin:move_to_composable:a"
# Region arguments also accept b/c/d or their numeric aliases 1/2/3/4.

# -----------------------------------------------------------------------------
# Per-layout options
# -----------------------------------------------------------------------------
# Every [layout.options.<leaf-id>] section accepts the common
# geometry/border keys from [layout]: gaps_outer, gaps_inner, master_ratio,
# master_count,
# border_width, border_focused, border_normal, and border_urgent.
# Unknown options are ignored; there is no generic Extra option map.
# tile, grid, rows, dwindle and reverse-dwindle also honor center_single_window
# and single_window_aspect_ratio. Omit either key to inherit its global value.

[layout.options.tile]
# Master/stack layout: the first master_count windows occupy master_ratio of
# the width; remaining windows form the stack.
master_ratio = 0.55
master_count = 1

[layout.options.monocle]
# Show only the focused/current window when true. false leaves every monocle
# participant visible in its full-output stack.
hide_others = true
# Draw the configured border around the visible window.
show_borders = false

[layout.options.grid]
# Grid has no engine-only keys; common gaps and borders control it.
gaps_inner = 4

[layout.options.rows]
# Rows has no engine-only keys; common gaps and borders control it.
gaps_inner = 4

[layout.options.dwindle]
# Dwindle moves overflow to the next workspace with room on the same output.
# Minimum content size uses the usable logical output area (after scaling and
# panel reservations): max(client minimum, 320, ceil(width / 5)) horizontally,
# and max(client minimum, 200, ceil(height / 4)) vertically, plus borders/gaps.
# If all nine workspaces are full, workspace 9 switches to scrolling and takes
# the overflow. It stays scrolling until you select another layout there.
# Reverse dwindle and focused splitting use the same capacity policy.
# Enable for dwindle only, overriding the global setting:
# center_single_window = true
# single_window_aspect_ratio = 1.7777777777777777
# Fraction assigned to each recursive split, strictly between 0 and 1.
split_ratio = 0.5
# First split: vertical = left/right; horizontal = top/bottom.
start_axis = "vertical" # vertical | horizontal
# Split the focused window when a new one opens, along its longer side, instead
# of always splitting the last window. Closing a window gives its space to the
# other side of its split. start_axis then only breaks ties for square areas.
split_focused = false

[layout.options.reverse-dwindle]
# Horizontal mirror of dwindle: vertical splits start on the right while
# horizontal splits still start at the top.
split_ratio = 0.5
start_axis = "vertical" # vertical | horizontal
split_focused = false

[layout.options.scrolling]
# Width of each scrolling column as a fraction of the usable output.
column_fraction = 0.5
# Automatically pan to keep the focused column centered.
# When false, pan only enough to keep it visible, preserving other columns that
# fit beside it in the viewport.
center_focused = true
# Pan to a newly managed window when it extends the column order.
follow_new_windows = true
# Insert immediately after the focused column instead of at the far right.
# When enabled, this takes precedence over portrait stacking.
open_new_windows_to_right = false
# Add new windows to a vertical stack when this scrolling instance's local
# usable rectangle is taller than it is wide. false keeps horizontal placement.
# Vertically arranged instances also swap the wheel navigation chords.
prefer_vertical_on_portrait = false
# Quantize manual viewport movement to whole column steps.
snap_to_columns = false
# Permit the first/last column to move beyond the centered viewport bound.
allow_overscroll = true
# Milliseconds of real pointer dwell before focus follows a scrolling member.
# Keyboard navigation and pointer clicks remain immediate. Zero disables delay.
focus_follows_mouse_delay_ms = 0

[layout.options.float]
# `stack` and `stacking` are aliases for this layout.
# New-window policy: cascade | center | under-pointer | minimal-overlap.
placement = "cascade"
cascade_step = 32
# Opt-in keyboard actions use these pixel increments.
move_step = 10
move_step_coarse = 50
resize_step = 10
# Pointer snapping uses half/quarter regions. Reaching the top edge maximizes
# to the usable area by default; false selects the top half instead.
# Snaps inherit gaps_outer/gaps_inner by default. An explicit snap_gap
# selects the legacy output inset (no inner gap), including explicit zero.
# snap_gap = 0
snap_threshold = 24
resistance = 12
top_edge_maximize = true
border_width = 2

# Named zone sets are available only while the workspace uses stacking. The
# active set is tracked per output; padding is applied after resolving each
# normalized region against that output's usable area.
[layout.snap-layout.work]
name = "Work"
# Omit padding to inherit gaps_outer/gaps_inner. Explicit padding overrides
# both with a per-zone inset; adjacent zones then have twice this spacing.
# padding = 8

[layout.snap-layout.work.zone.editor]
name = "Editor"
x = 0.0
y = 0.0
width = 0.6666667
height = 1.0

[layout.snap-layout.work.zone.terminal]
name = "Terminal"
x = 0.6666667
y = 0.0
width = 0.3333333
height = 1.0

# Legacy normalized regions remain supported for existing a-d bindings when
# no named snap layout is configured.
[layout.snap-zone.a]
x = 0.0
y = 0.0
width = 0.6666667
height = 1.0

[layout.snap-zone.b]
x = 0.6666667
y = 0.0
width = 0.3333333
height = 1.0

[layout.options.game-mode]
# Only common geometry/border keys are accepted here. Game Mode's
# remainder_layout, fallback_layout, and gaps_inner policy lives in the
# [game_mode] section of rules.toml.
gaps_inner = 4

# -----------------------------------------------------------------------------
# Output layout selection
# -----------------------------------------------------------------------------
# Optional. These blocks select a default layout for matching outputs; display
# mode/scale/position fields belong in wm.toml. Matching priority is connector
# name, then EDID, then make/model/serial metadata.
#
# [[output]]
# name   = "DP-1"
# layout = "scrolling"
#
# [[output]]
# edid   = "edid-identifier"
# make   = "Example Vendor"
# model  = "Example Display"
# serial = "1234"
# layout = "grid"

# -----------------------------------------------------------------------------
# Workspace layout selection
# -----------------------------------------------------------------------------
# workspace is 1-based. Omit output for a global workspace override, or set an
# output connector name for a more specific output/workspace mapping.
# Resolution order is runtime selection, output+workspace, workspace-only,
# output default, then [layout].default.

[[workspace]]
workspace = 1
layout = "tile"

[[workspace]]
workspace = 2
layout = "monocle"

[[workspace]]
workspace = 3
layout = "scrolling"

[[workspace]]
workspace = 4
layout = "float"

# [[workspace]]
# output = "DP-1"
# workspace = 5
# layout = "grid"