kossLAN/wry
1
0
Fork 0
forked from wry/wry
Code Pull requests Activity
wry/toml-spec/spec/spec.yaml
Julian Orth a1df575262 config: allow spawning clients with tags
2026-02-27 22:19:47 +01:00

4428 lines
122 KiB
YAML
Raw Blame History

Keymap:
description: |
A keymap.
kind: variable
variants:
- kind: string
description: |
Defines a keymap by its XKB representation.
- Example:
```toml
keymap = """
xkb_keymap {
xkb_keycodes { include "evdev+aliases(qwerty)" };
xkb_types { include "complete" };
xkb_compat { include "complete" };
xkb_symbols { include "pc+us+inet(evdev)" };
};
"""
```
- kind: table
description: |
Defines or references a keymap.
- Example:
```toml
keymap.name = "my-keymap"
[[keymaps]]
name = "my-keymap"
path = "./my-keymap.xkb"
```
fields:
name:
kind: string
required: false
description: |
Defines a keymap name or references a defined keymap.
If the value is set in the top-level `keymaps` array, it defines a named
keymap.
Otherwise it references a named keymap that should have been defined in the
`keymaps` array.
map:
kind: string
required: false
description: |
Defines a keymap by its XKB representation.
For each keymap defined in the top-level `keymaps` array, exactly one of `map`
and `path` has to be defined.
path:
kind: string
required: false
description: |
Loads a keymap's XKB representation from a file.
If the path is relative, it will be interpreted relative to the Jay config
directory.
For each keymap defined in the top-level `keymaps` array, exactly one of `map`
and `path` has to be defined.
Action:
description: |
An `Action` is an action performed by the compositor.
- Example:
```toml
[shortcuts]
alt-q = "quit"
```
kind: variable
variants:
- kind: string
ref: SimpleActionName
description: |
The value should be the name of a `simple` action. See the description of that
variant for more details.
- Example:
```toml
[shortcuts]
alt-q = "quit"
```
- kind: string
pattern: "^\\$.*$"
description: |
The value should be the name of a `named` action, prefixed with the `$` character.
This is the same as using the `named` action with the `$` removed.
- Example:
```toml
[actions]
q = "quit"
[shortcuts]
alt-q = "$q"
```
- kind: array
items:
ref: Action
description: |
A list of actions to execute in sequence.
- Example:
```toml
[shortcuts]
alt-q = [
{ type = "exec", exec = ["notify-send", "exiting"] },
"quit",
]
```
- kind: table
description: ''
types:
simple:
description: |
A simple action that takes no arguments. These are usually written as plain
strings instead.
- Example 1:
```toml
[shortcuts]
alt-q = { type = "simple", cmd = "quit" }
```
- Example 2:
```toml
[shortcuts]
alt-q = "quit"
```
fields:
cmd:
description: The simple action to execute.
required: true
ref: SimpleActionName
named:
description: |
A named action that was defined via the top-level `actions` table or a
`define-action` action. These are usually written as plain strings with a `$`
prefix.
- Example 1:
```toml
[actions]
my-action = "quit"
[shortcuts]
alt-q = { type = "named", name = "my-action" }
```
- Example 2:
```toml
[shortcuts]
alt-q = [
{ type = "define-action", name = "my-action", action = "quit" },
{ type = "named", name = "my-action" },
]
```
fields:
name:
kind: string
description: The named action to execute.
required: true
multi:
description: |
A list of actions to execute in sequence. These are usually written as plain
arrays instead.
- Example 1:
```toml
[shortcuts]
alt-q = { type = "multi", actions = ["quit", "quit"] }
```
- Example 2:
```toml
[shortcuts]
alt-q = ["quit", "quit"]
```
fields:
actions:
description: The actions to execute.
required: true
kind: array
items:
ref: Action
exec:
description: |
Executes a program.
- Example:
```toml
[shortcuts]
ctrl-a = { type = "exec", exec = "alacritty" }
ctrl-b = { type = "exec", exec = ["notify-send", "hello world"] }
```
fields:
exec:
description: The command to execute.
required: true
ref: Exec
switch-to-vt:
description: |
Switches to a virtual terminal.
- Example:
```toml
[shortcuts]
ctrl-alt-F1 = { type = "switch-to-vt", num = 1 }
```
fields:
num:
description: |
The VT number to switch to.
required: true
kind: number
integer_only: true
minimum: 1
show-workspace:
description: |
Switches to a workspace.
- Example 1:
```toml
[shortcuts]
alt-F1 = { type = "show-workspace", name = "1" }
```
- Example 2:
```toml
[shortcuts]
alt-F1 = { type = "show-workspace", name = "1", output.name = "left" }
```
fields:
name:
description: The name of the workspace.
required: true
kind: string
output:
description: |
The output to show a newly created workspace on. This has no effect on
workspaces that already exist.
If this is not set, then a new workspace is shown on the output that
contains the cursor.
If multiple outputs match, the workspace is shown on the first matching
output.
required: false
ref: OutputMatch
move-to-workspace:
description: |
Moves the currently focused window to a workspace.
- Example:
```toml
[shortcuts]
alt-F1 = { type = "move-to-workspace", name = "1" }
```
fields:
name:
description: The name of the workspace.
required: true
kind: string
move-to-output:
description: |
Moves a workspace to a different output.
- Example 1: Move a specific workspace to a named output
```toml
[shortcuts]
alt-F1 = { type = "move-to-output", workspace = "1", output.name = "right" }
```
- Example 2: Move the current workspace to a named output
```toml
[shortcuts]
alt-F1 = { type = "move-to-output", output.name = "right" }
```
- Example 3: Move the current workspace to the output on the right (directional)
```toml
[shortcuts]
"logo+ctrl+shift+Right" = { type = "move-to-output", direction = "right" }
"logo+ctrl+shift+Left" = { type = "move-to-output", direction = "left" }
"logo+ctrl+shift+Up" = { type = "move-to-output", direction = "up" }
"logo+ctrl+shift+Down" = { type = "move-to-output", direction = "down" }
```
fields:
workspace:
description: |
The name of the workspace.
If this is omitted, the currently active workspace is moved.
required: false
kind: string
output:
description: |
The output to move to.
If multiple outputs match, the workspace is moved to the first matching
output.
Either `output` or `direction` must be specified, but not both.
required: false
ref: OutputMatch
direction:
description: |
The direction to search for the next output.
Finds the closest output in the specified direction based on
center-to-center distance, with preference for outputs better aligned
with the movement axis.
Either `output` or `direction` must be specified, but not both.
required: false
ref: Direction
configure-connector:
description: |
Applies a configuration to connectors.
- Example:
```toml
[shortcuts]
alt-j = { type = "configure-connector", connector = { match.name = "eDP-1", enabled = false } }
alt-k = { type = "configure-connector", connector = { match.name = "eDP-1", enabled = true } }
```
fields:
connector:
description: The connector configuration.
required: true
ref: Connector
configure-input:
description: |
Applies a configuration to input devices.
- Example:
```toml
[shortcuts]
alt-l = { type = "configure-input", input = { match.tag = "mouse", left-handed = true } }
alt-r = { type = "configure-input", input = { match.tag = "mouse", left-handed = false } }
[[inputs]]
tag = "mouse"
match.is-pointer = true
```
fields:
input:
description: The input configuration.
required: true
ref: Input
configure-idle:
description: |
Configures the idle timeout.
- Example:
```toml
[shortcuts]
alt-l = { type = "configure-idle", idle.minutes = 0 }
alt-r = { type = "configure-idle", idle.minutes = 10 }
```
fields:
idle:
description: The idle timeout.
required: true
ref: Idle
configure-output:
description: |
Applies a configuration to input devices.
- Example:
```toml
[shortcuts]
alt-l = { type = "configure-output", output = { match.name = "right", transform = "none" } }
alt-r = { type = "configure-output", output = { match.name = "right", transform = "rotate-90" } }
[[outputs]]
name = "right"
match.serial-number = "33K03894SL0"
```
fields:
output:
description: The output configuration.
required: true
ref: Output
set-env:
description: |
Sets environment variables for all programs started afterwards.
- Example:
```toml
[shortcuts]
alt-l = { type = "set-env", env.GTK_THEME = "Adwaita:dark" }
```
fields:
env:
description: The environment variables.
required: true
kind: map
values:
kind: string
unset-env:
description: |
Unsets environment variables for all programs started afterwards.
- Example:
```toml
[shortcuts]
alt-l = { type = "unset-env", env = ["Adwaita:dark"] }
```
fields:
env:
description: The environment variables.
required: true
kind: array
items:
kind: string
set-keymap:
description: |
Sets the keymap.
- Example:
```toml
[shortcuts]
alt-j = { type = "set-keymap", keymap.name = "laptop" }
alt-k = { type = "set-keymap", keymap.name = "external" }
[[keymaps]]
name = "laptop"
path = "./laptop-keymap.xkb"
[[keymaps]]
name = "external"
path = "./external-keymap.xkb"
```
fields:
keymap:
description: The keymap.
required: true
ref: Keymap
set-repeat-rate:
description: |
Sets the keyboard repeat rate.
- Example:
```toml
[shortcuts]
alt-x = { type = "set-repeat-rate", rate = { rate = 25, delay = 250 } }
```
fields:
rate:
description: The rate.
required: true
ref: RepeatRate
set-status:
description: |
Sets the status command.
- Example:
```toml
[shortcuts]
alt-j = { type = "set-status", status = { exec = "i3status" } }
```
fields:
status:
description: |
The status setting.
Omitting this causes the status to be reset to empty.
required: false
ref: Status
set-theme:
description: |
Sets the theme.
- Example:
```toml
[shortcuts]
alt-j = { type = "set-theme", theme.bg-color = "#ff0000" }
```
fields:
theme:
description: The theme.
required: true
ref: Theme
set-log-level:
description: |
Sets the log level of the compositor.
- Example:
```toml
[shortcuts]
alt-j = { type = "set-log-level", level = "debug" }
```
fields:
theme:
description: The log level.
required: true
ref: LogLevel
set-gfx-api:
description: |
Sets the graphics API used by new DRM devices.
Setting this after the compositor has started usually has no effect.
- Example:
```toml
[shortcuts]
alt-j = { type = "set-gfx-api", api = "Vulan" }
```
fields:
api:
description: The API.
required: true
ref: GfxApi
configure-direct-scanout:
description: |
Configure whether the compositor attempts direct scanout of client surfaces.
- Example:
```toml
[shortcuts]
alt-j = { type = "configure-direct-scanout", enabled = false }
```
fields:
enabled:
description: Whether direct scanout is enabled.
required: true
kind: boolean
configure-drm-device:
description: |
Applies a configuration to DRM devices.
- Example:
```toml
[shortcuts]
alt-j = { type = "configure-drm-device", dev = { match.name = "integrated", gfx-api = "Vulkan" } }
[[drm-devices]]
name = "integrated"
match.syspath = "/sys/devices/pci0000:00/0000:00:08.1/0000:14:00.0"
```
fields:
dev:
description: The DRM device configuration.
required: true
ref: DrmDevice
set-render-device:
description: |
Sets the render device used for compositing.
Changing this after the compositor has started might cause client windows to
become invisible until they are resized.
- Example:
```toml
[shortcuts]
alt-j = { type = "set-render-device", dev.name = "integrated" }
[[drm-devices]]
name = "integrated"
match.syspath = "/sys/devices/pci0000:00/0000:00:08.1/0000:14:00.0"
```
fields:
dev:
description: |
The rule to find the device.
The first matching device is used.
required: true
ref: DrmDeviceMatch
define-action:
description: |
Defines a name for an action. Usually you would define these by using the
top-level `actions` table. This action can be used to re-define actions.
- Example:
```toml
[actions]
a1 = "quit"
a2 = "$a1"
[shortcuts]
alt-q = [
{ type = "define-action", name = "a2", action = [] },
"$2", # does nothing
]
```
fields:
name:
kind: string
description: The name of the action.
required: true
action:
description: The action to execute.
required: true
ref: Action
undefine-action:
description: |
Removes a named action.
fields:
name:
kind: string
description: The name of the action.
required: true
create-mark:
description: |
Creates a mark for the currently focused window.
- Example 1:
This example interactively selects a key that identifies the mark.
```toml
[shortcuts]
alt-x = { type = "create-mark" }
```
- Example 2:
This example hard-codes a key.
```toml
[shortcuts]
alt-x = { type = "create-mark", id.key = "a" }
```
fields:
id:
description: |
The identifier of the mark.
If this field is omitted, the next pressed key identifies the mark.
required: false
ref: MarkId
jump-to-mark:
description: |
Moves the keyboard focus to a window identified by a mark.
- Example 1:
This example interactively selects a key that identifies the mark.
```toml
[shortcuts]
alt-x = { type = "jump-to-mark" }
```
- Example 2:
This example hard-codes a key.
```toml
[shortcuts]
alt-x = { type = "jump-to-mark", id.key = "a" }
```
fields:
id:
description: |
The identifier of the mark.
If this field is omitted, the next pressed key identifies the mark.
required: false
ref: MarkId
copy-mark:
description: |
Copies a mark.
If the `src` id identifies a mark before this function is called, the `dst`
id will identify the same mark afterwards.
fields:
src:
description: The source id to copy from.
required: true
ref: MarkId
dst:
description: The destination id to copy to.
required: true
ref: MarkId
push-mode:
description: |
Pushes an input mode on top of the input-mode stack. The mode can be popped
with the `pop-mode` action.
- Example:
```toml
[shortcuts]
alt-x = { type = "push-mode", name = "navigation" }
```
fields:
name:
description: The name of the mode.
required: true
kind: string
latch-mode:
description: |
Temporarily pushes an input mode on top of the input-mode stack. The new mode
will automatically be popped when the next shortcut is invoked.
- Example:
```toml
[shortcuts]
alt-x = { type = "latch-mode", name = "navigation" }
```
fields:
name:
description: The name of the mode.
required: true
kind: string
Exec:
description: |
Describes how to execute a program.
- Example 1:
```toml
[shortcuts]
ctrl-a = { type = "exec", exec = "alacritty" }
```
- Example 2:
```toml
[shortcuts]
ctrl-a = { type = "exec", exec = ["notify-send", "hello world"] }
```
- Example 3:
```toml
[shortcuts]
ctrl-a = { type = "exec", exec = { prog = "notify-send", args = ["hello world"], env.WAYLAND_DISPLAY = "2" } }
```
- Example 4:
```toml
[shortcuts]
ctrl-a = { type = "exec", exec = { shell = "grim - | wl-copy", privileged = true } }
```
kind: variable
variants:
- kind: string
description: |
The name of the executable to execute.
- Example:
```toml
[shortcuts]
ctrl-a = { type = "exec", exec = "alacritty" }
```
- kind: array
items:
kind: string
description: |
The name and arguments of the executable to execute.
- Example:
```toml
[shortcuts]
ctrl-a = { type = "exec", exec = ["notify-send", "hello world"] }
```
- kind: table
description: |
The name, arguments, and environment variables of the executable to execute.
Exactly one of the `prog` or `shell` fields must be specified.
- Example 1:
```toml
[shortcuts]
ctrl-a = { type = "exec", exec = { prog = "notify-send", args = ["hello world"], env.WAYLAND_DISPLAY = "2" } }
```
- Example 2:
```toml
[shortcuts]
ctrl-a = { type = "exec", exec = { shell = "grim - | wl-copy", privileged = true } }
```
fields:
prog:
kind: string
required: false
description: The name of the executable.
shell:
kind: string
required: false
description: |
The name of a shell command to execute. The command will be executed as
`$SHELL -c "command"`.
args:
kind: array
required: false
items:
kind: string
description: |
The arguments to pass to the executable.
This field must not be specified if a shell command is used.
env:
kind: map
required: false
values:
kind: string
description: The environment variables to pass to the executable.
privileged:
kind: boolean
required: false
description: |
If `true`, the executable gets access to privileged wayland protocols.
The default is `false`.
tag:
kind: string
required: false
description: |
Specifies a tag to apply to all spawned wayland connections.
SimpleActionName:
description: |
The name of a `simple` Action.
When used inside a window rule, the following actions apply to the matched window
instead fo the focused window:
- `move-left`
- `move-down`
- `move-up`
- `move-right`
- `split-horizontal`
- `split-vertical`
- `toggle-split`
- `tile-horizontal`
- `tile-vertical`
- `toggle-split`
- `show-single`
- `show-all`
- `toggle-fullscreen`
- `enter-fullscreen`
- `exit-fullscreen`
- `close`
- `toggle-floating`
- `float`
- `tile`
- `toggle-float-pinned`
- `pin-float`
- `unpin-float`
- Example:
```toml
[shortcuts]
alt-q = "quit"
```
kind: string
values:
- value: focus-left
description: Move the keyboard focus to the left of the currently focused window.
- value: focus-down
description: Move the keyboard focus down from the currently focused window.
- value: focus-up
description: Move the keyboard focus up from the currently focused window.
- value: focus-right
description: Move the keyboard focus to the right of the currently focused window.
- value: move-left
description: Move the currently focused window one to the left.
- value: move-down
description: Move the currently focused window one down.
- value: move-up
description: Move the currently focused window one up.
- value: move-right
description: Move the currently focused window one to the right.
- value: move-right
description: Move the currently focused window one to the right.
- value: split-horizontal
description: Split the currently focused window horizontally.
- value: split-vertical
description: Split the currently focused window vertically.
- value: toggle-split
description: |
Toggle the split of the currently focused container between vertical and
horizontal.
- value: tile-horizontal
description: Sets the split of the currently focused container to horizontal.
- value: tile-vertical
description: Sets the split of the currently focused container to vertical.
- value: toggle-mono
description: |
Toggle the currently focused container between showing a single and all children.
- value: show-single
description: Makes the currently focused container show a single child.
- value: show-all
description: Makes the currently focused container show all children.
- value: toggle-fullscreen
description: Toggle the currently focused window between fullscreen and windowed.
- value: enter-fullscreen
description: Makes the currently focused window fullscreen.
- value: exit-fullscreen
description: Makes the currently focused window windowed.
- value: focus-parent
description: Focus the parent of the currently focused window.
- value: close
description: Close the currently focused window.
- value: disable-pointer-constraint
description: |
Disable the currently active pointer constraint, allowing you to move the pointer
outside the window.
The constraint will be re-enabled when the pointer re-enters the window.
- value: toggle-floating
description: Toggle the currently focused window between floating and tiled.
- value: float
description: Makes the currently focused window floating.
- value: tile
description: Makes the currently focused window tiled.
- value: quit
description: Terminate the compositor.
- value: reload-config-toml
description: Reload the `config.toml`.
- value: reload-config-so
description: Reload the `config.so`.
- value: consume
description: |
Consume the current key event. Don't forward it to the focused application.
This action only has an effect in shortcuts.
Key-press events events that trigger shortcuts are consumed by default.
Key-release events events that trigger shortcuts are forwarded by default.
Note that consuming key-release events can cause keys to get stuck in the focused
application.
See the `forward` action to achieve the opposite effect.
- value: forward
description: |
Forward the current key event to the focused application.
See the `consume` action for more details.
- value: none
description: |
Perform no action.
As a special case, if this is the action of a shortcut, the shortcut will be
unbound. This can be used in modes to unbind a key.
- value: enable-window-management
description: |
Enables window management mode.
In window management mode, floating windows can be moved by pressing the left
mouse button and all windows can be resize by pressing the right mouse button.
- value: disable-window-management
description: |
Disables window management mode.
- value: enable-float-above-fullscreen
description: |
Enables floating windows showing above fullscreen windows.
By default, floating windows are hidden below fullscreen windows.
- value: disable-float-above-fullscreen
description: |
Disables floating windows showing above fullscreen windows.
- value: toggle-float-above-fullscreen
description: |
Toggles floating windows showing above fullscreen windows.
- value: pin-float
description: |
Pins the currently focused floating window.
If a floating window is pinned, it will stay visible even when switching to a
different workspace.
- value: unpin-float
description: |
Unpins the currently focused floating window.
- value: toggle-float-pinned
description: |
Toggles whether the currently focused floating window is pinned.
- value: kill-client
description: |
Kills a client.
Within a window rule, it applies to the client of the window. Within a client rule
it applies to the matched client. Has no effect otherwise.
- value: show-bar
description: Shows the built-in bar.
- value: hide-bar
description: Hides the built-in bar.
- value: toggle-bar
description: Toggles the built-in bar.
- value: show-titles
description: Shows window titles.
- value: hide-titles
description: Hides window titles.
- value: toggle-titles
description: Toggles window titles.
- value: focus-prev
description: Focuses the previous window in the focus history.
- value: focus-next
description: Focuses the next window in the focus history.
- value: focus-below
description: Focuses the layer below the currently focused layer.
- value: focus-above
description: Focuses the layer above the currently focused layer.
- value: focus-tiles
description: Focuses the tile layer.
- value: create-mark
description: |
Interactively creates a mark.
The next pressed key becomes the identifier for the mark.
- value: jump-to-mark
description: |
Interactively jumps to a mark.
The next pressed key identifies the mark to jump to.
- value: clear-modes
description: Disables all previously set input modes, clearing the input-mode stack.
- value: pop-mode
description: Pops the topmost mode from the input-mode stack.
- value: enable-simple-im
description: |
Enables the simple, XCompose based input method.
Even if the input method is enabled, it will only be used if there is no
running external IM.
- value: disable-simple-im
description: |
Disables the simple, XCompose based input method.
- value: toggle-simple-im-enabled
description: |
Toggles whether the simple, XCompose based input method is enabled.
- value: reload-simple-im
description: |
Reloads the simple, XCompose based input method.
This is useful if you change the XCompose files after starting the compositor.
- value: enable-unicode-input
description: |
Enables Unicode input in the simple, XCompose based input method.
This has no effect if the simple IM is not currently active.
Color:
kind: string
description: |
A color.
The format should be one of the following:
- `#rgb`
- `#rrggbb`
- `#rgba`
- `#rrggbba`
ConnectorMatch:
kind: variable
description: |
Rules to match one of the connectors used by the compositor.
variants:
- kind: array
items:
ref: ConnectorMatch
description: |
This rule matches if any of the rules in the array match.
- kind: table
description: |
Describes a rule that matches a subset of connectors.
This rule matches if all of the specified fields match.
- Example:
```toml
[[connectors]]
match.name = "DP-1"
```
fields:
name:
kind: string
required: false
description: |
The name of the connector.
These values are not necessarily stable. You can find out the value by running
`jay randr`.
Connector:
kind: table
description: |
Describes configuration to apply to a connector.
- Example: To disable the built-in display of a laptop:
```toml
[[connectors]]
match.name = "eDP-1"
enabled = false
```
fields:
match:
ref: ConnectorMatch
required: true
description: |
The rule by which the connectors to modify are selected.
enabled:
kind: boolean
required: false
description: |
If specified, enables or disables the connector.
DrmDeviceMatch:
kind: variable
description: |
Rules to match one of the DRM devices (graphics cards) used by the compositor.
variants:
- kind: array
items:
ref: DrmDeviceMatch
description: |
This rule matches if any of the rules in the array match.
- kind: table
description: |
Describes a rule that matches a subset of DRM devices.
This rule matches if all of the specified fields match.
- Example:
```toml
[[drm-devices]]
name = "dedicated"
match = { pci-vendor = 0x1002, pci-model = 0x73ff }
```
fields:
name:
kind: string
required: false
description: |
The name of another DrmDeviceMatch rule.
For this rule to match, the referenced rule must match. The name of the rule
should have been defined in the top-level `drm-devices` array.
This can be used to easily refer to DRM devices.
- Example:
```toml
[shortcuts]
alt-v = { type = "configure-drm-device", dev = { match.name = "dedicated", gfx-api = "Vulkan" } }
alt-o = { type = "configure-drm-device", dev = { match.name = "dedicated", gfx-api = "OpenGl" } }
[[drm-devices]]
name = "dedicated"
match = { pci-vendor = 0x1002, pci-model = 0x73ff }
```
syspath:
kind: string
required: false
description: |
The syspath of the device.
This is useful if you have multiple copies of the same device installed so that
the PCI numbers are not unique.
The values are usually stable unless you re-configure your hardware.
- Example:
```toml
[[drm-devices]]
name = "integrated"
match.syspath = "/sys/devices/pci0000:00/0000:00:08.1/0000:14:00.0"
```
devnode:
kind: string
required: false
description: |
The devnode of the device.
The values are usually not-stable across PC restarts.
- Example:
```toml
[[drm-devices]]
name = "integrated"
match.devnode = "/dev/dri/card0"
```
vendor:
kind: string
required: false
description: |
The name of the vendor.
- Example:
```toml
[[drm-devices]]
name = "integrated"
match.vendor = "Advanced Micro Devices, Inc. [AMD/ATI]"
```
model:
kind: string
required: false
description: |
The name of the model.
- Example:
```toml
[[drm-devices]]
name = "integrated"
match.vendor = "Raphael"
```
pci-vendor:
kind: number
integer_only: true
required: false
description: |
The PCI number of the vendor.
- Example:
```toml
[[drm-devices]]
name = "integrated"
match.pci-vendor = 0x1002
```
pci-model:
kind: number
integer_only: true
required: false
description: |
The PCI number of the model.
- Example:
```toml
[[drm-devices]]
name = "integrated"
match.pci-model = 0x164e
```
DrmDevice:
kind: table
description: |
Describes configuration to apply to a DRM device (graphics card).
- Example: To disable direct scanout on a device:
```toml
[[drm-devices]]
match = { pci-vendor = 0x1002, pci-model = 0x73ff }
direct-scanout = false
```
fields:
name:
kind: string
required: false
description: |
Assigns a name to the rule in the `match` field.
This only has an effect when used in the top-level `drm-devices` array.
match:
ref: DrmDeviceMatch
required: true
description: |
The rule by which the DRM devices to modify are selected.
direct-scanout:
kind: boolean
required: false
description: |
If specified, enables or disables direct scanout on this device.
gfx-api:
ref: GfxApi
required: false
description: |
If specified, sets the graphics API to use for this device.
flip-margin-ms:
kind: number
required: false
description: |
If specified, sets the flip margin of this device.
This is duration between the compositor initiating a page flip and the output's
vblank event. This determines the minimum input latency. The default is 1.5 ms.
Note that if the margin is too small, the compositor will dynamically increase it.
GfxApi:
kind: string
description: A graphics API used for rendering.
values:
- value: OpenGl
description: The OpenGL API.
- value: Vulkan
description: |
The Vulkan API.
Note that this API has the following restriction: If any of the DRM devices in
the system use Vulkan, then all devices must support DRM format modifiers. This
is usually the case but not for AMD devices older than RX 5xxx.
InputMatch:
kind: variable
description: |
Rules to match one of the input devices used by the compositor.
variants:
- kind: array
items:
ref: InputMatch
description: |
This rule matches if any of the rules in the array match.
- kind: table
description: |
Describes a rule that matches a subset of input devices.
This rule matches if all of the specified fields match.
- Example:
```toml
[[inputs]]
match.is-pointer = true
left-handed = true
```
fields:
tag:
kind: string
required: false
description: |
The tag of another InputMatch rule.
For this rule to match, the referenced rule must match. The name of the rule
should have been defined in the top-level `inputs` array.
This can be used to easily refer to input devices.
- Example:
```toml
[shortcuts]
alt-l = { type = "configure-input", input = { match.tag = "mouse", left-handed = true } }
alt-r = { type = "configure-input", input = { match.tag = "mouse", left-handed = false } }
[[inputs]]
tag = "mouse"
match.is-pointer = true
```
name:
kind: string
required: false
description: |
The libinput name of the device.
You can find out the name of the devices by running `jay input`.
- Example:
```toml
[[inputs]]
match.name = "Logitech G300s Optical Gaming Mouse"
left-handed = true
```
syspath:
kind: string
required: false
description: |
The syspath of the device.
This is useful if you have multiple copies of the same device installed so that
the name is not unique.
The values are usually stable unless you re-configure your hardware.
- Example:
```toml
[[inputs]]
match.syspath = "/sys/devices/pci0000:00/0000:00:08.1/0000:14:00.4/usb5/5-1/5-1.1/5-1.1.2/5-1.1.2:1.0"
left-handed = true
```
devnode:
kind: string
required: false
description: |
The devnode of the device.
The values are usually not-stable across PC restarts.
- Example:
```toml
[[inputs]]
match.devnode = "/dev/input/event4"
left-handed = true
```
is-keyboard:
kind: boolean
required: false
description: |
Whether the devices has been identified as a keyboard.
- Example:
```toml
[[inputs]]
match.is-keyboard = false
left-handed = true
```
is-pointer:
kind: boolean
required: false
description: |
Whether the devices has been identified as a pointer.
- Example:
```toml
[[inputs]]
match.is-pointer = false
left-handed = true
```
is-touch:
kind: boolean
required: false
description: |
Whether the devices has been identified as a touch device.
- Example:
```toml
[[inputs]]
match.is-touch = true
tap-enabled = true
```
is-tablet-tool:
kind: boolean
required: false
description: |
Whether the devices has been identified as a tablet tool.
- Example:
```toml
[[inputs]]
match.is-tablet-tool = true
tap-enabled = true
```
is-tablet-pad:
kind: boolean
required: false
description: |
Whether the devices has been identified as a tablet pad.
- Example:
```toml
[[inputs]]
match.is-tablet-tool = true
tap-enabled = true
```
is-gesture:
kind: boolean
required: false
description: |
Whether the devices has been identified as a switch.
- Example:
```toml
[[inputs]]
match.is-switch = true
```
Input:
kind: table
description: |
Describes configuration to apply to an input device.
- Example: To make mice left handed:
```toml
[[inputs]]
match.is-pointer = true
left-handed = true
```
fields:
tag:
kind: string
required: false
description: |
Assigns a name to the rule in the `match` field.
This only has an effect when used in the top-level `inputs` array.
match:
ref: InputMatch
required: true
description: |
The rule by which the input devices to modify are selected.
accel-profile:
ref: AccelProfile
required: false
description: |
The acceleration profile to use.
See the libinput documentation for more details.
accel-speed:
kind: number
required: false
description: |
The acceleration speed to use.
Values should be in the range -1 to 1.
See the libinput documentation for more details.
tap-enabled:
kind: boolean
required: false
description: |
Whether tap is enabled for this device.
See the libinput documentation for more details.
tap-drag-enabled:
kind: boolean
required: false
description: |
Whether tap drag is enabled for this device.
See the libinput documentation for more details.
tap-drag-lock-enabled:
kind: boolean
required: false
description: |
Whether tap drag lock is enabled for this device.
See the libinput documentation for more details.
left-handed:
kind: boolean
required: false
description: |
Whether the device is left handed.
See the libinput documentation for more details.
natural-scrolling:
kind: boolean
required: false
description: |
Whether the device uses natural scrolling.
See the libinput documentation for more details.
middle-button-emulation:
kind: boolean
required: false
description: |
Converts a simultaneous left and right button click into a middle button click.
See the libinput documentation for more details.
click-method:
ref: ClickMethod
required: false
description: |
Defines how button events are triggered on a clickable touchpad.
See the libinput documentation for more details.
px-per-wheel-scroll:
kind: boolean
required: false
description: |
The number of pixels to scroll for each scroll wheel dedent.
transform-matrix:
kind: array
items:
kind: array
items:
kind: number
required: false
description: |
A transformation matrix to apply to each motion event of this device.
The matrix should be 2x2.
- Example: To slow down the mouse to 35% of normal speed:
```toml
[[inputs]]
match.is-pointer = true
transform-matrix = [[0.35, 0], [0, 0.35]]
```
keymap:
ref: Keymap
required: false
description: |
The keymap to use for this device.
This overrides the global keymap. The keymap becomes active when a key is pressed.
- Example:
```toml
[[inputs]]
match.name = "ZSA Technology Labs Inc ErgoDox EZ"
keymap.name = "external"
```
on-lid-closed:
ref: Action
required: false
description: |
An action to execute when the laptop lid is closed.
This should only be used in the top-level inputs array.
- Example:
```toml
[[inputs]]
match.name = "<switch name>"
on-lid-closed = { type = "configure-connector", connector = { match.name = "eDP-1", enabled = false } }
on-lid-opened = { type = "configure-connector", connector = { match.name = "eDP-1", enabled = true } }
```
on-lid-opened:
ref: Action
required: false
description: |
An action to execute when the laptop lid is opened.
This should only be used in the top-level inputs array.
- Example:
```toml
[[inputs]]
match.name = "<switch name>"
on-lid-closed = { type = "configure-connector", connector = { match.name = "eDP-1", enabled = false } }
on-lid-opened = { type = "configure-connector", connector = { match.name = "eDP-1", enabled = true } }
```
on-converted-to-laptop:
ref: Action
required: false
description: |
An action to execute when the convertible device is converted to a laptop.
This should only be used in the top-level inputs array.
on-converted-to-tablet:
ref: Action
required: false
description: |
An action to execute when the convertible device is converted to a tablet.
This should only be used in the top-level inputs array.
output:
ref: OutputMatch
required: false
description: |
Maps this input device to an output.
This is used to map touch screen and graphics tablets to outputs.
- Example:
```toml
[[inputs]]
match.name = "Wacom Bamboo Comic 2FG Pen"
output.connector = "DP-1"
```
remove-mapping:
kind: boolean
required: false
description: |
Removes the mapping of from this device to an output.
This should only be used within `configure-input` actions.
- Example:
```toml
[shortcuts]
alt-x = { type = "configure-input", input = { match.tag = "wacom", remove-mapping = true } }
[[inputs]]
tag = "wacom"
match.name = "Wacom Bamboo Comic 2FG Pen"
output.connector = "DP-1"
```
calibration-matrix:
kind: array
items:
kind: array
items:
kind: number
required: false
description: |
The calibration matrix of the device. This matrix should be 2x3.
See the libinput documentation for more details.
- Example: To flip the device 90 degrees:
```toml
[[inputs]]
calibration-matrix = [[0, 1, 0], [-1, 0, 1]]
```
AccelProfile:
kind: string
values:
- value: Flat
description: The flat profile.
- value: Adaptive
description: The adaptive profile.
description: |
The acceleration profile to apply to an input device.
See the libinput documentation for more details.
ClickMethod:
kind: string
values:
- value: none
description: No click method handling.
- value: button-areas
description: Bottom area of the touchpad is divided into a left, middle and right button area.
- value: clickfinger
description: |
Number of fingers on the touchpad decide the button type.
Clicking with 1, 2, 3 fingers triggers a left, right, or middle click, respectively.
description: |
The click method to apply to an input device.
See the libinput documentation for more details.
LogLevel:
kind: string
description: A log level.
values:
- value: trace
description: Trace log level.
- value: debug
description: Debug log level.
- value: info
description: Info log level.
- value: warn
description: Warn log level.
- value: error
description: Error log level.
Mode:
kind: table
description: |
The mode of a display.
- Example:
```toml
[[outputs]]
match.serial-number = "33K03894SL0"
mode = { width = 1920, height = 1080, refresh-rate = 59.94 }
```
fields:
width:
kind: number
integer_only: true
required: true
description: The width of the mode.
height:
kind: number
integer_only: true
required: true
description: The height of the mode.
refresh-rate:
kind: number
required: false
description: The refresh rate of the mode in HZ.
OutputMatch:
kind: variable
description: |
Rules to match one of the outputs used by the compositor.
variants:
- kind: array
items:
ref: OutputMatch
description: |
This rule matches if any of the rules in the array match.
- kind: table
description: |
Describes a rule that matches a subset of outputs.
This rule matches if all of the specified fields match.
- Example:
```toml
[[outputs]]
name = "right"
match.serial-number = "33K03894SL0"
x = 1920
y = 0
```
fields:
name:
kind: string
required: false
description: |
The name of another OutputMatch rule.
For this rule to match, the referenced rule must match. The name of the rule
should have been defined in the top-level `outputs` array.
This can be used to easily refer to outputs.
- Example:
```toml
[shortcuts]
alt-l = { type = "configure-output", output = { match.name = "right", transform = "none" } }
alt-r = { type = "configure-output", output = { match.name = "right", transform = "rotate-90" } }
[[outputs]]
name = "right"
match.serial-number = "33K03894SL0"
```
connector:
kind: string
required: false
description: |
The name of the connector the output is connected to.
You can find out the name of the connector by running `jay randr`.
- Example:
```toml
[[outputs]]
match.connector = "DP-1"
scale = 1.25
```
serial-number:
kind: string
required: false
description: |
The serial number of the output.
You can find out the serial number by running `jay randr`.
- Example:
```toml
[[outputs]]
match.serial-number = "33K03894SL0"
scale = 1.25
```
manufacturer:
kind: string
required: false
description: |
The manufacturer of the output.
You can find out the manufacturer by running `jay randr`.
- Example:
```toml
[[outputs]]
match.manufacturer = "BNQ"
scale = 1.25
```
model:
kind: string
required: false
description: |
The model of the output.
You can find out the model by running `jay randr`.
- Example:
```toml
[[outputs]]
match.model = "BenQ GW2480"
scale = 1.25
```
Output:
kind: table
description: |
Describes configuration to apply to an output.
- Example: To set the scale of an output.
```toml
[[outputs]]
match.serial-number = "33K03894SL0"
scale = 1.25
```
fields:
name:
kind: string
required: false
description: |
Assigns a name to the rule in the `match` field.
This only has an effect when used in the top-level `outputs` array.
match:
ref: OutputMatch
required: true
description: |
The rule by which the outputs to modify are selected.
x:
kind: number
integer_only: true
minimum: 0
required: false
description: |
The x coordinate of the output in compositor space.
y:
kind: number
integer_only: true
minimum: 0
required: false
description: |
The y coordinate of the output in compositor space.
scale:
kind: number
minimum: 0
exclusive_minimum: true
required: false
description: |
The scale of the output.
transform:
ref: Transform
required: false
description: |
The transform of the output.
mode:
ref: Mode
required: false
description: |
The mode of the output.
If the refresh rate is not specified, the first mode with the specified width and
height is used.
vrr:
ref: Vrr
required: false
description: |
Configures the VRR settings of this output.
By default, the VRR mode is `never` and the cursor refresh rate is unbounded.
- Example:
```toml
[[outputs]]
match.serial-number = "33K03894SL0"
vrr = { mode = "always", cursor-hz = 90 }
```
tearing:
ref: Tearing
required: false
description: |
Configures the tearing settings of this output.
By default, the tearing mode is `variant3`.
- Example:
```toml
[[outputs]]
match.serial-number = "33K03894SL0"
tearing.mode = "never"
```
format:
ref: Format
required: false
description: |
Configures the framebuffer format of this output.
By default, the format is `xrgb8888`.
- Example:
```toml
[[outputs]]
match.serial-number = "33K03894SL0"
format = "rgb565"
```
color-space:
ref: ColorSpace
required: false
description: |
The color space of the output.
transfer-function:
ref: Eotf
required: false
description: |
The EOTF of the output.
brightness:
ref: Brightness
required: false
description: |
The brightness of the output.
This setting has no effect unless the vulkan renderer is used.
blend-space:
ref: BlendSpace
required: false
description: |
The blend space of the output.
The default is `srgb`.
use-native-gamut:
kind: boolean
required: false
description: |
Configures whether the display primaries are used.
By default, Jay pretends that the display uses sRGB primaries. This is also how
most other systems behave. In reality, most displays use a much larger gamut. For
example, they advertise that they support 95% of the DCI-P3 gamut. If the display
is interpreting colors in their native gamut, then colors will appear more
saturated than their specification.
If this is set to `true`, Jay assumes that the display uses the primaries
advertised in its EDID. This might produce more accurate colors while also
allowing color-managed applications to use the full gamut of the display.
This setting has no effect when the display is explicitly operating in a wide
color space.
The default is `false`.
Transform:
kind: string
description: An output transformation.
values:
- value: none
description: No transformation.
- value: rotate-90
description: The content of the output is rotated 90 degrees counter clockwise.
- value: rotate-180
description: The content of the output is rotated 180 degrees counter clockwise.
- value: rotate-270
description: The content of the output is rotated 270 degrees counter clockwise.
- value: flip
description: The content of the output is flipped around the vertical axis.
- value: flip-rotate-90
description: |
The content of the output is flipped around the vertical axis and then rotated
90 degrees counter clockwise.
- value: flip-rotate-180
description: |
The content of the output is flipped around the vertical axis and then rotated
180 degrees counter clockwise.
- value: flip-rotate-270
description: |
The content of the output is flipped around the vertical axis and then rotated
270 degrees counter clockwise.
MessageFormat:
kind: string
description: A message format used by status programs.
values:
- value: plain
description: The messages are in plain text.
- value: pango
description: The messages contain pango markup.
- value: i3bar
description: The messages are in i3bar format.
Status:
kind: table
description: |
The configuration of a status program whose output will be shown in the bar.
- Example:
```toml
[status]
format = "i3bar"
exec = "i3status"
```
fields:
format:
ref: MessageFormat
required: false
description: The format used by the program.
exec:
ref: Exec
required: true
description: The program that will emit the status messages.
i3bar-separator:
kind: string
required: false
description: |
The separator to be used between i3bar components.
The default is ` | `.
Theme:
kind: table
description: |
The theme of the compositor.
fields:
attention-requested-bg-color:
ref: Color
required: false
description: The background color of title that have requested attention.
bg-color:
ref: Color
required: false
description: The background color of the desktop.
bar-bg-color:
ref: Color
required: false
description: The background color of the bar.
bar-status-text-color:
ref: Color
required: false
description: The color of the status text in the bar.
border-color:
ref: Color
required: false
description: The color of the borders between windows.
captured-focused-title-bg-color:
ref: Color
required: false
description: The background color of focused titles that are being recorded.
captured-unfocused-title-bg-color:
ref: Color
required: false
description: The background color of unfocused titles that are being recorded.
focused-inactive-title-bg-color:
ref: Color
required: false
description: The background color of focused titles that are inactive.
focused-inactive-title-text-color:
ref: Color
required: false
description: The text color of focused titles that are inactive.
focused-title-bg-color:
ref: Color
required: false
description: The background color of focused titles.
focused-title-text-color:
ref: Color
required: false
description: The text color of focused titles.
separator-color:
ref: Color
required: false
description: The color of the separator between titles and window content.
unfocused-title-bg-color:
ref: Color
required: false
description: The background color of unfocused titles.
unfocused-title-text-color:
ref: Color
required: false
description: The text color of unfocused titles.
highlight-color:
ref: Color
required: false
description: Color used to highlight parts of the UI.
border-width:
kind: number
integer_only: true
minimum: 0
required: false
description: The width of borders between windows.
title-height:
kind: number
integer_only: true
minimum: 0
required: false
description: The height of tabs.
bar-height:
kind: number
integer_only: true
minimum: 0
required: false
description: The height of the bar. Defaults to the title-height if not set.
bar-position:
ref: BarPosition
required: false
description: The position of the bar. Defaults to `top` if not set.
bar-separator-width:
kind: number
integer_only: true
minimum: 0
required: false
description: The width of the bar's separator. Defaults to 1.
font:
kind: string
required: false
description: The name of the font to use.
title-font:
kind: string
required: false
description: The name of the font to use in window titles. Defaults to `font` if not set.
bar-font:
kind: string
required: false
description: The name of the font to use in the bar. Defaults to `font` if not set.
Config:
kind: table
description: |
This is the top-level table.
- Example:
```toml
keymap = """
xkb_keymap {
xkb_keycodes { include "evdev+aliases(qwerty)" };
xkb_types { include "complete" };
xkb_compat { include "complete" };
xkb_symbols { include "pc+us+inet(evdev)" };
};
"""
on-graphics-initialized = { type = "exec", exec = "mako" }
[shortcuts]
alt-h = "focus-left"
alt-j = "focus-down"
alt-k = "focus-up"
alt-l = "focus-right"
alt-shift-h = "move-left"
alt-shift-j = "move-down"
alt-shift-k = "move-up"
alt-shift-l = "move-right"
alt-d = "split-horizontal"
alt-v = "split-vertical"
alt-t = "toggle-split"
alt-m = "toggle-mono"
alt-u = "toggle-fullscreen"
alt-f = "focus-parent"
alt-shift-c = "close"
alt-shift-f = "toggle-floating"
Super_L = { type = "exec", exec = "alacritty" }
alt-p = { type = "exec", exec = "bemenu-run" }
alt-q = "quit"
alt-shift-r = "reload-config-toml"
ctrl-alt-F1 = { type = "switch-to-vt", num = 1 }
ctrl-alt-F2 = { type = "switch-to-vt", num = 2 }
# ...
alt-F1 = { type = "show-workspace", name = "1" }
alt-F2 = { type = "show-workspace", name = "2" }
# ...
alt-shift-F1 = { type = "move-to-workspace", name = "1" }
alt-shift-F2 = { type = "move-to-workspace", name = "2" }
# ...
```
fields:
keymap:
ref: Keymap
required: false
description: |
The keymap to use.
- Example:
```toml
keymap = """
xkb_keymap {
xkb_keycodes { include "evdev+aliases(qwerty)" };
xkb_types { include "complete" };
xkb_compat { include "complete" };
xkb_symbols { include "pc+us+inet(evdev)" };
};
"""
```
repeat-rate:
ref: RepeatRate
required: false
description: |
The keyboard repeat rate.
- Example:
```toml
repeat-rate = { rate = 25, delay = 250 }
```
shortcuts:
kind: map
values:
ref: Action
required: false
description: |
The compositor shortcuts.
The keys should be in the following format:
```
(MOD-)*KEYSYM
```
`MOD` should be one of `shift`, `lock`, `ctrl`, `mod1`, `mod2`, `mod3`, `mod4`,
`mod5`, `caps`, `alt`, `num`, `logo`, or `release`.
Using the `release` modifier causes the shortcut to trigger when the key is
released.
`KEYSYM` should be the name of a keysym. The authorative location for these names
is [1] with the `XKB_KEY_` prefix removed.
The keysym should be the unmodified keysym. E.g. `shift-q` not `shift-Q`.
[1]: https://github.com/xkbcommon/libxkbcommon/blob/master/include/xkbcommon/xkbcommon-keysyms.h
- Example:
```toml
[shortcuts]
alt-q = "quit"
```
complex-shortcuts:
kind: map
values:
ref: ComplexShortcut
required: false
description: |
Complex compositor shortcuts.
The keys should have the same format as in the `shortcuts` table.
- Example:
```toml
[complex-shortcuts.XF86AudioRaiseVolume]
mod-mask = "alt"
action = { type = "exec", exec = ["pactl", "set-sink-volume", "0", "+10%"] }
```
on-graphics-initialized:
ref: Action
required: false
description: |
An action to execute when the graphics have been initialized for the first time.
This is a good place to start graphical applications.
- Example:
```toml
on-graphics-initialized = { type = "exec", exec = "mako" }
```
status:
ref: Status
required: false
description: |
The status program that will be used for the status text.
- Example:
```toml
[status]
format = "i3bar"
exec = "i3status"
```
outputs:
kind: array
items:
ref: Output
required: false
description: |
An array of output configurations.
This can be used to configure outputs and create named outputs that can be
referred to in actions.
The configurations defined here will only be applied the first time matching
outputs are connected to the compositor after the compositor has started.
If you want change the configuration afterwards, use `jay randr` or a
`configure-output` action.
- Example:
```toml
[[outputs]]
name = "left"
match.serial-number = "33K03894SL0"
x = 0
y = 0
[[outputs]]
name = "right"
match.serial-number = "ETW1M02062SL0"
x = 1920
y = 0
```
connectors:
kind: array
items:
ref: Connector
required: false
description: |
An array of connector configurations.
This can be used to configure connectors.
The configurations defined here will only be applied when the connector is first
discovered by the compositor. This usually never happens after the compositor has
started unless you attach an external graphics card.
- Example:
```toml
[[connectors]]
name = "eDP-1"
enabled = false
```
workspace-capture:
kind: boolean
required: false
description: |
Configures whether newly created workspaces can be captured.
The default is `true`.
env:
kind: map
values:
kind: string
required: false
description: |
Defines environment variables that will be set for all applications.
- Example:
```toml
[env]
GTK_THEME = "Adwaita:dark"
```
on-startup:
ref: Action
required: false
description: |
An action to execute as early as possible when the compositor starts.
At this point, graphics have not yet been initialized. You should not use this
to start graphical applications. See `on-graphics-initialized`.
This setting has no effect during configuration reloads.
keymaps:
kind: array
items:
ref: Keymap
required: false
description: |
Defines named keymaps.
These keymaps can be used to easily switch between keymaps for different
keyboards.
- Example:
```toml
keymap.name = "laptop"
[shortcuts]
alt-j = { type = "set-keymap", keymap.name = "laptop" }
alt-k = { type = "set-keymap", keymap.name = "external" }
[[keymaps]]
name = "laptop"
path = "./laptop-keymap.xkb"
[[keymaps]]
name = "external"
path = "./external-keymap.xkb"
```
log-level:
ref: LogLevel
required: false
description: |
Sets the log level of the compositor.
This setting cannot be changed by re-loading the configuration. Use
`jay set-log-level` instead.
- Example:
```toml
log-level = "debug"
```
theme:
ref: Theme
required: false
description: |
Sets the theme of the compositor.
gfx-api:
ref: GfxApi
required: false
description: |
Sets the graphics API used for newly discovered DRM devices.
Changing this setting after the compositor has started usually has no effect
unless you attach an external graphics card. Use `jay randr` to change the API
used by individual devices at runtime.
- Example:
```toml
gfx-api = "Vulkan"
```
drm-devices:
kind: array
items:
ref: DrmDevice
required: false
description: |
Names and configures DRM devices.
These settings are only applied to devices discovered after the configuration
has been loaded. Therefore changing these settings usually has no effect at
runtime unless you attach an external graphics card. You can use `jay randr` or
a `configure-drm-device` Action to change these settings at runtime.
- Example:
```toml
render-device.name = "dedicated"
[[drm-devices]]
name = "dedicated"
match = { pci-vendor = 0x1002, pci-model = 0x73ff }
[[drm-devices]]
name = "integrated"
match = { pci-vendor = 0x1002, pci-model = 0x164e }
gfx-api = "OpenGl"
```
direct-scanout:
kind: boolean
required: false
description: |
Configured whether the compositor attempts direct scanout.
explicit-sync:
kind: boolean
required: false
description: |
Configures whether the compositor supports explicit sync.
This cannot be changed after the compositor has started.
The default is `true`.
render-device:
ref: DrmDeviceMatch
required: false
description: |
Selects the device to use for rendering in a system with multiple GPUs.
The first device that matches will be used.
- Example:
```toml
render-device.name = "dedicated"
[[drm-devices]]
name = "dedicated"
match = { pci-vendor = 0x1002, pci-model = 0x73ff }
```
inputs:
kind: array
items:
ref: Input
required: false
description: |
Names and configures input devices.
These settings are only applied to devices connected after the configuration
has been loaded. You can apply setting without re-connecting the device by using
`jay input` or a `configure-input` Action.
- Example:
```toml
render-device.name = "dedicated"
[[inputs]]
match.is-pointer = true
left-handed = true
transform-matrix = [[0.35, 0], [0, 0.35]]
tap-enabled = true
```
on-idle:
ref: Action
required: false
description: |
An action to execute when the compositor becomes idle.
- Example:
```toml
on-idle = { type = "exec", exec = "lock" }
```
idle:
ref: Idle
required: false
description: |
The configuration of the idle timeout.
Changing thise field after compositor startup has no effect. Use `jay idle`
or a `configure-idle` action to change the idle timeout at runtime.
- Example:
```toml
idle.minutes = 10
```
focus-follows-mouse:
kind: boolean
required: false
description: |
Configures whether moving the mouse over a window automatically moves the keyboard
focus to that window.
The default is `true`.
window-management-key:
kind: string
required: false
description: |
Configures a key that will enable window management mode while pressed.
In window management mode, floating windows can be moved by pressing the left
mouse button and all windows can be resize by pressing the right mouse button.
- Example:
```toml
window-management-key = "Alt_L"
```
vrr:
ref: Vrr
required: false
description: |
Configures the default VRR settings.
This can be overwritten for individual outputs.
By default, the VRR mode is `never` and the cursor refresh rate is unbounded.
- Example:
```toml
vrr = { mode = "always", cursor-hz = 90 }
```
tearing:
ref: Tearing
required: false
description: |
Configures the default tearing settings.
This can be overwritten for individual outputs.
By default, the tearing mode is `variant3`.
- Example:
```toml
tearing.mode = "never"
```
libei:
ref: Libei
required: false
description: |
Configures the libei settings.
- Example:
```toml
libei.enable-socket = true
```
ui-drag:
ref: UiDrag
required: false
description: |
Configures the ui-drag settings.
- Example:
```toml
ui-drag = { enabled = false, threshold = 20 }
```
xwayland:
ref: Xwayland
required: false
description: |
Configures the Xwayland settings.
- Example:
```toml
xwayland = { scaling-mode = "downscaled" }
```
color-management:
ref: ColorManagement
required: false
description: |
Configures the color-management settings.
- Example:
```toml
[color-management]
enabled = true
```
float:
ref: Float
required: false
description: |
Configures the settings of floating windows.
- Example:
```toml
[float]
show-pin-icon = true
```
actions:
kind: map
values:
ref: Action
required: false
description: |
Named actions.
Named actions can be used everywhere an action can be used. This can be used to
avoid repeating the same action multiple times.
- Example:
```toml
actions.switch-to-1 = [
{ type = "show-workspace", name = "1" },
{ type = "define-action", name = "switch-to-next", action = "$switch-to-2" },
]
actions.switch-to-2 = [
{ type = "show-workspace", name = "2" },
{ type = "define-action", name = "switch-to-next", action = "$switch-to-3" },
]
actions.switch-to-3 = [
{ type = "show-workspace", name = "3" },
{ type = "define-action", name = "switch-to-next", action = "$switch-to-1" },
]
actions.switch-to-next = "$switch-to-1"
[shortcuts]
alt-x = "$switch-to-next"
```
max-action-depth:
kind: number
integer_only: true
minimum: 0
required: false
description: |
The maximum call depth of named actions. This setting prevents infinite recursion
when using named actions. Setting this value to 0 or less disables named actions
completely. The default is `16`.
clients:
kind: array
items:
ref: ClientRule
required: false
description: |
An array of client rules.
These rules can be used to give names to clients and to manipulate them.
- Example:
```toml
[[clients]]
name = "spotify"
match.sandbox-app-id = "com.spotify.Client"
```
windows:
kind: array
items:
ref: WindowRule
required: false
description: |
An array of window rules.
These rules can be used to give names to windows and to manipulate them.
- Example:
```toml
[[windows]]
name = "spotify"
match.title-regex = "Spotify"
action = { type = "move-to-workspace", name = "music" }
```
pointer-revert-key:
kind: string
required: false
description: |
Sets the keysym that can be used to revert the pointer to the default state.
Pressing this key cancels any grabs, drags, selections, etc.
The default is `Escape`. Setting this to `NoSymbol` effectively disables
this functionality.
The value of the string should be the name of a keysym. The authoritative location
for these names is [1] with the `XKB_KEY_` prefix removed.
[1]: https://github.com/xkbcommon/libxkbcommon/blob/master/include/xkbcommon/xkbcommon-keysyms.h
- Example:
```toml
pointer-revert-key = "NoSymbol"
```
use-hardware-cursor:
kind: boolean
required: false
description: |
Configures whether the default seat uses hardware cursors.
The default is `true`.
show-bar:
kind: boolean
required: false
description: |
Configures whether the built-in bar is shown.
The default is `true`.
show-titles:
kind: boolean
required: false
description: |
Configures whether title bars on windows are shown.
The default is `true`.
focus-history:
ref: FocusHistory
required: false
description: |
Configures the focus-history settings.
- Example:
```toml
[focus-history]
only-visible: true
same-workspace: true
```
middle-click-paste:
kind: boolean
required: false
description: |
Configures whether middle-click pasting is enabled.
Changing this has no effect on running applications.
The default is `true`.
modes:
kind: map
values:
ref: InputMode
required: false
description: |
Configures the input modes.
Modes can be used to define shortcuts that are only active when the mode is
active.
- Example
```toml
[modes."navigation".shortcuts]
w = "focus-up"
a = "focus-left"
s = "focus-down"
d = "focus-right"
r = "focus-above"
f = "focus-below"
q = "focus-prev"
e = "focus-next"
```
Modes can be activated with the `push-mode` and `latch-mode` actions.
workspace-display-order:
ref: WorkspaceDisplayOrder
required: false
description: |
Configures the order of workspaces displayed.
The default is `manual`.
- Example:
```toml
workspace-display-order = "sorted"
```
simple-im:
ref: SimpleIm
required: false
description: |
Configures the simple, XCompose based input method.
By default, the input method is enabled.
Even if the input method is enabled, it will only be used if there is no
running external IM.
- Example:
```toml
[simple-im]
enabled = false
```
fallback-output-mode:
ref: FallbackOutputMode
required: false
description: |
Sets the fallback output mode.
The default is `cursor`.
- Example:
```toml
fallback-output-mode = "focus"
```
Idle:
kind: table
description: |
The definition of an idle timeout.
Omitted values are set to 0. If any value is explicitly set and all values are 0, the
idle timeout is disabled.
- Example:
```toml
idle.minutes = 10
```
fields:
minutes:
description: The number of minutes before going idle.
kind: number
integer_only: true
minimum: 0
required: false
seconds:
description: The number of seconds before going idle.
kind: number
integer_only: true
minimum: 0
required: false
grace-period:
description: |
The grace period after the timeout expires.
During the grace period, the screen goes black but the outputs are not yet
disabled and the `on-idle` action does not yet run. This is a visual indicator
that the system will soon get idle.
The default is 5 seconds.
ref: GracePeriod
required: false
GracePeriod:
kind: table
description: |
The definition of a grace period.
Omitted values are set to 0. If all values are 0, the grace period is disabled.
- Example:
```toml
idle.grace-period.seconds = 3
```
fields:
minutes:
description: The number of minutes the grace period lasts.
kind: number
integer_only: true
minimum: 0
required: false
seconds:
description: The number of seconds the grace period lasts.
kind: number
integer_only: true
minimum: 0
required: false
RepeatRate:
kind: table
description: |
Describes a keyboard repeat rate.
- Example:
```toml
repeat-rate = { rate = 25, delay = 250 }
```
fields:
rate:
kind: number
integer_only: true
required: true
description: The number of times to repeat per second.
delay:
kind: number
integer_only: true
required: true
description: |
The number of milliseconds after a key is pressed before repeating begins.
ComplexShortcut:
kind: table
description: |
Describes a complex shortcut.
- Example:
```toml
[complex-shortcuts.XF86AudioRaiseVolume]
mod-mask = "alt"
action = { type = "exec", exec = ["pactl", "set-sink-volume", "0", "+10%"] }
```
fields:
mod-mask:
kind: string
required: false
description: |
The mod mask to apply to this shortcut.
Should be a string containing modifiers concatenated by `-`. See the description
of `Config.shortcuts` for more details.
If this field is omitted, all modifiers are included in the mask.
- Example:
To raise the volume whenever the XF86AudioRaiseVolume key is pressed regardless
of any modifiers except `alt`:
```toml
[complex-shortcuts.XF86AudioRaiseVolume]
mod-mask = "alt"
action = { type = "exec", exec = ["pactl", "set-sink-volume", "0", "+10%"] }
```
Set `mod-mask = ""` to ignore all modifiers.
action:
ref: Action
required: false
description: |
The action to execute.
Omitting this is the same as setting it to `"none"`.
latch:
ref: Action
required: false
description: |
An action to execute when the key is released.
This registers an action to be executed when the key triggering the shortcut is
released. The active modifiers are ignored for this purpose.
- Example:
To mute audio while the key is pressed:
```toml
[complex-shortcuts.alt-x]
action = { type = "exec", exec = ["pactl", "set-sink-mute", "0", "1"] }
latch = { type = "exec", exec = ["pactl", "set-sink-mute", "0", "0"] }
```
Audio will be un-muted once `x` key is released, regardless of any other keys
that are pressed at the time.
Vrr:
kind: table
description: |
Describes VRR settings.
- Example:
```toml
vrr = { mode = "always", cursor-hz = 90 }
```
fields:
mode:
ref: VrrMode
required: false
description: The VRR mode.
cursor-hz:
ref: VrrHz
required: false
description: |
The VRR cursor refresh rate.
Limits the rate at which cursor movement forces a screen update
when VRR is active.
VrrMode:
description: |
The VRR mode of an output.
- Example:
```toml
vrr = { mode = "always", cursor-hz = 90 }
```
kind: string
values:
- value: never
description: VRR is never enabled.
- value: always
description: VRR is always enabled.
- value: variant1
description: VRR is enabled when one or more applications are displayed fullscreen.
- value: variant2
description: VRR is enabled when a single application is displayed fullscreen.
- value: variant3
description: |
VRR is enabled when a single application is displayed fullscreen and
describes its content type as video or game through the
wp_content_type_v1 protocol.
VrrHz:
description: |
A VRR cursor refresh rate limit.
- Example 1:
```toml
vrr = { cursor-hz = 90 }
```
- Example 2:
```toml
vrr = { cursor-hz = "none" }
```
kind: variable
variants:
- kind: string
description: |
The string `none` can be used to disable the limit.
This means the cursor refresh rate is unbounded, meaning every mouse
movement will update the screen.
If the mouse reporting interval (polling rate) is >= screen refresh
rate, this results in the screen spiking to maximum refresh rate on
mouse movement.
- kind: number
description: |
The cursor refresh rate limit in Hz.
This means the cursor is updated whenever the rest of the screen is
updated but no later than `1 / cursor-hz` after the last screen update.
If the application's content refresh rate is higher than `cursor-hz`,
the cursor will update with the content.
Setting `cursor-hz = 1` would force it to always match content refresh
rate.
However, if content refresh rate regularly drops low, cursor movement
will feel choppy. Consider setting `cursor-hz` to a reasonable minimum
value to keep cursor movement smooth.
Tearing:
kind: table
description: |
Describes tearing settings.
- Example:
```toml
tearing.mode = "never"
```
fields:
mode:
ref: TearingMode
required: false
description: The tearing mode.
TearingMode:
description: |
The tearing mode of an output.
- Example:
```toml
tearing.mode = "never"
```
kind: string
values:
- value: never
description: Tearing is never enabled.
- value: always
description: Tearing is always enabled.
- value: variant1
description: Tearing is enabled when one or more applications are displayed fullscreen.
- value: variant2
description: Tearing is enabled when a single application is displayed fullscreen.
- value: variant3
description: |
Tearing is enabled when a single application is displayed and the application has
requested tearing.
Libei:
kind: table
description: |
Describes libei settings.
- Example:
```toml
libei.enable-socket = "true"
```
fields:
enable-socket:
kind: boolean
required: false
description: |
Enables or disables the unauthenticated libei socket.
Even if the socket is disabled, application can still request access via the portal.
The default is `false`.
Format:
description: |
A graphics format.
These formats are documented in https://github.com/torvalds/linux/blob/master/include/uapi/drm/drm_fourcc.h
- Example:
```toml
[[outputs]]
match.serial-number = "33K03894SL0"
format = "rgb565"
```
kind: string
values:
- value: argb8888
description: ""
- value: xrgb8888
description: ""
- value: abgr8888
description: ""
- value: xbgr8888
description: ""
- value: r8
description: ""
- value: gr88
description: ""
- value: rgb888
description: ""
- value: bgr888
description: ""
- value: rgba4444
description: ""
- value: rgbx4444
description: ""
- value: bgra4444
description: ""
- value: bgrx4444
description: ""
- value: rgb565
description: ""
- value: bgr565
description: ""
- value: rgba5551
description: ""
- value: rgbx5551
description: ""
- value: bgra5551
description: ""
- value: bgrx5551
description: ""
- value: argb1555
description: ""
- value: xrgb1555
description: ""
- value: argb2101010
description: ""
- value: xrgb2101010
description: ""
- value: abgr2101010
description: ""
- value: xbgr2101010
description: ""
- value: abgr16161616
description: ""
- value: xbgr16161616
description: ""
- value: abgr16161616f
description: ""
- value: xbgr16161616f
description: ""
UiDrag:
kind: table
description: |
Describes ui-drag settings.
- Example:
```toml
ui-drag = { enabled = false, threshold = 20 }
```
fields:
enabled:
kind: boolean
required: false
description: |
Enables or disables dragging of tiles and workspaces.
The default is `true`.
threshold:
kind: number
integer_only: true
required: false
description: |
Sets the distance at which ui dragging starts.
The default is `10`.
Xwayland:
kind: table
description: |
Describes Xwayland settings.
- Example:
```toml
xwayland = { scaling-mode = "downscaled" }
```
fields:
enabled:
kind: boolean
required: false
description: |
Enables or disables XWayland.
The default is `true`.
scaling-mode:
ref: XScalingMode
required: false
description: The scaling mode of X windows.
XScalingMode:
description: |
The scaling mode of X windows.
- Example:
```toml
xwayland = { scaling-mode = "downscaled" }
```
kind: string
values:
- value: default
description: |
The default mode.
Currently this means that windows are rendered at the lowest scale and then upscaled
if necessary.
- value: downscaled
description: |
Windows are rendered at the highest integer scale and then downscaled.
This has significant performance implications unless the window is running on the
output with the highest scale and that scale is an integer scale.
For example, on a 3840x2160 output with a 1.5 scale, a fullscreen window will be
rendered at 3840x2160 * 2 / 1.5 = 5120x2880 pixels and then downscaled to
3840x2160. This overhead gets worse the lower the scale of the output is.
Additionally, this mode requires the X window to scale its contents itself. In the
example above, you might achieve this by setting the environment variable
`GDK_SCALE=2`.
ColorManagement:
kind: table
description: |
Describes color-management settings.
- Example:
```toml
[color-management]
enabled = true
```
fields:
enabled:
description: |
Whether the color management protocol is enabled.
This has no effect on running applications.
The default is `false`.
kind: boolean
required: false
ColorSpace:
description: |
The color space of an output.
kind: string
values:
- value: default
description: The default color space (usually sRGB).
- value: bt2020
description: The BT.2020 color space.
Eotf:
description: |
The EOTF of an output.
kind: string
values:
- value: default
description: The default EOTF (usually gamma22).
- value: pq
description: The PQ EOTF.
Brightness:
kind: variable
description: |
The brightness setting of an output.
variants:
- kind: string
description: |
The default brightness setting.
values:
- value: default
description: |
The default brightness setting.
The behavior depends on the EOTF:
- `default`: The maximum brightness of the output.
- `PQ`: 203 cd/m^2
When used with the default transfer function, the default brightness is anchored
at 80 cd/m^2. That is, setting this to 40 cd/m^2 makes everything appear half as
bright as normal and creates 50% HDR headroom.
- kind: number
description: |
The brightness in cd/m^2.
Float:
kind: table
description: |
Describes settings of floating windows.
- Example:
```toml
[float]
show-pin-icon = true
```
fields:
show-pin-icon:
description: |
Sets whether floating windows always show a pin icon.
The default is `false`.
kind: boolean
required: false
ClientRule:
kind: table
description: |
A client rule.
fields:
name:
kind: string
required: false
description: |
The name of this rule.
This name can be referenced in other rules.
- Example
```toml
[[clients]]
name = "spotify"
match.sandbox-app-id = "com.spotify.Client"
[[clients]]
match.name = "spotify"
action = "kill-client"
```
match:
ref: ClientMatch
required: false
description: The criteria that select the client that this rule applies to.
action:
ref: Action
required: false
description: An action to execute when a client matches the criteria.
latch:
ref: Action
required: false
description: An action to execute when a client no longer matches the criteria.
capabilities:
ref: ClientCapabilities
required: false
description: |
Sets the capabilities granted to clients matching this matcher.
If multiple matchers match a client, the capabilities are added.
If no matcher matches a client, it is granted the default capabilities depending
on whether it's sandboxed or not. If it is not sandboxed, it is granted the
capabilities `layer-shell` and `drm-lease`. Otherwise it is granted the
capability `drm-lease`.
Regardless of any capabilities set through this function, the capabilities of the
client can never exceed its bounding capabilities.
sandbox-bounding-capabilities:
ref: ClientCapabilities
required: false
description: |
Sets the upper capability bounds for clients in sandboxes created by this client.
If multiple matchers match a client, the capabilities are added.
If no matcher matches a client, the bounding capabilities for sandboxes depend on
whether the client is itself sandboxed. If it is sandboxed, the bounding
capabilities are the effective capabilities of the client. Otherwise the bounding
capabilities are all capabilities.
Regardless of any capabilities set through this function, the capabilities set
through this function can never exceed the client's bounding capabilities.
ClientMatch:
kind: table
description: |
Criteria for matching clients.
If no fields are set, all clients are matched. If multiple fields are set, all fields
must match the client.
fields:
name:
kind: string
required: false
description: |
Matches if the client rule with this name matches.
- Example:
```toml
[[clients]]
name = "spotify"
match.sandbox-app-id = "com.spotify.Client"
# Matches the same clients as the previous rule.
[[clients]]
match.name = "spotify"
```
not:
ref: ClientMatch
required: false
description: |
Matches if the contained criteria don't match.
- Example:
```toml
[[clients]]
name = "not-spotify"
match.not.sandbox-app-id = "com.spotify.Client"
```
all:
kind: array
items:
ref: ClientMatch
required: false
description: |
Matches if all of the contained criteria match.
- Example:
```toml
[[clients]]
match.all = [
{ sandbox-app-id = "com.spotify.Client" },
{ sandbox-engine = "org.flatpak" },
]
```
any:
kind: array
items:
ref: ClientMatch
required: false
description: |
Matches if any of the contained criteria match.
- Example:
```toml
[[clients]]
match.any = [
{ sandbox-app-id = "com.spotify.Client" },
{ sandbox-app-id = "com.valvesoftware.Steam" },
]
```
exactly:
ref: ClientMatchExactly
required: false
description: |
Matches if a specific number of contained criteria match.
- Example:
```toml
# Matches any client that is either steam or sandboxed by flatpak but not both.
[[clients]]
match.exactly.num = 1
match.exactly.list = [
{ sandbox-engine = "org.flatpak" },
{ sandbox-app-id = "com.valvesoftware.Steam" },
]
```
sandboxed:
kind: boolean
required: false
description: |
Matches if the client is/isn't sandboxed.
- Example:
```toml
[[clients]]
match.sandboxed = true
```
sandbox-engine:
kind: string
required: false
description: |
Matches the engine name of the client's sandbox verbatim.
- Example:
```toml
[[clients]]
match.sandbox-engine = "org.flatpak"
```
sandbox-engine-regex:
kind: string
required: false
description: |
Matches the engine name of the client's sandbox with a regular expression.
- Example:
```toml
[[clients]]
match.sandbox-engine = "flatpak"
```
sandbox-app-id:
kind: string
required: false
description: |
Matches the app id of the client's sandbox verbatim.
- Example:
```toml
[[clients]]
match.sandbox-app-id = "com.spotify.Client"
```
sandbox-app-id-regex:
kind: string
required: false
description: |
Matches the app id of the client's sandbox with a regular expression.
- Example:
```toml
[[clients]]
match.sandbox-app-id-regex = "(?i)spotify"
```
sandbox-instance-id:
kind: string
required: false
description: |
Matches the instance id of the client's sandbox verbatim.
sandbox-instance-id-regex:
kind: string
required: false
description: |
Matches the instance id of the client's sandbox with a regular expression.
uid:
kind: number
integer_only: true
required: false
description: Matches the user ID of the client.
pid:
kind: number
integer_only: true
required: false
description: Matches the process ID of the client.
is-xwayland:
kind: boolean
required: false
description: Matches if the client is/isn't Xwayland.
comm:
kind: string
required: false
description: Matches the `/proc/pid/comm` of the client verbatim.
comm-regex:
kind: string
required: false
description: Matches the `/proc/pid/comm` of the client with a regular expression.
exe:
kind: string
required: false
description: Matches the `/proc/pid/exe` of the client verbatim.
exe-regex:
kind: string
required: false
description: Matches the `/proc/pid/exe` of the client with a regular expression.
tag:
kind: string
required: false
description: Matches the tag of the client verbatim.
tag-regex:
kind: string
required: false
description: Matches the tag of the client with a regular expression.
ClientMatchExactly:
kind: table
description: |
Criterion for matching a specific number of client criteria.
fields:
num:
kind: number
required: true
description: The number of criteria that must match.
list:
kind: array
items:
ref: ClientMatch
required: true
description: The list of criteria.
WindowRule:
kind: table
description: |
A window rule.
fields:
name:
kind: string
required: false
description: |
The name of this rule.
This name can be referenced in other rules.
- Example
```toml
[[windows]]
name = "spotify"
match.title-regex = "Spotify"
[[windows]]
match.name = "spotify"
action = "enter-fullscreen"
```
match:
ref: WindowMatch
required: false
description: The criteria that select the window that this rule applies to.
action:
ref: Action
required: false
description: An action to execute when a window matches the criteria.
latch:
ref: Action
required: false
description: An action to execute when a window no longer matches the criteria.
auto-focus:
kind: boolean
required: false
description: |
Whether newly mapped windows that match this rule get the keyboard focus.
If a window matches any rule for which this is false, the window will not be
automatically focused.
initial-tile-state:
ref: TileState
required: false
description: Specifies if the window is initially mapped tiled or floating.
WindowMatch:
kind: table
description: |
Criteria for matching windows.
If no fields are set, all windows are matched. If multiple fields are set, all fields
must match the window.
fields:
name:
kind: string
required: false
description: |
Matches if the window rule with this name matches.
- Example:
```toml
[[windows]]
name = "spotify"
match.title-regex = "Spotify"
# Matches the same windows as the previous rule.
[[windows]]
match.name = "spotify"
```
not:
ref: WindowMatch
required: false
description: |
Matches if the contained criteria don't match.
- Example:
```toml
[[windows]]
name = "not-spotify"
match.not.title-regex = "Spotify"
```
all:
kind: array
items:
ref: WindowMatch
required: false
description: |
Matches if all of the contained criteria match.
- Example:
```toml
[[windows]]
match.all = [
{ title-regex = "Spotify" },
{ title-regex = "Premium" },
]
```
any:
kind: array
items:
ref: WindowMatch
required: false
description: |
Matches if any of the contained criteria match.
- Example:
```toml
[[windows]]
match.any = [
{ title-regex = "Spotify" },
{ title-regex = "Alacritty" },
]
```
exactly:
ref: WindowMatchExactly
required: false
description: |
Matches if a specific number of contained criteria match.
- Example:
```toml
# Matches any window that is either Alacritty or on workspace 3 but not both.
[[windows]]
match.exactly.num = 1
match.exactly.list = [
{ workspace = "3" },
{ title-regex = "Alacritty" },
]
```
types:
ref: WindowTypeMask
required: false
description: Matches windows whose type is contained in the mask.
client:
ref: ClientMatch
required: false
description: Matches if the window's client matches the client criterion.
title:
kind: string
required: false
description: Matches the title of the window verbatim.
title-regex:
kind: string
required: false
description: Matches the title of the window with a regular expression.
app-id:
kind: string
required: false
description: Matches the app-id of the window verbatim.
app-id-regex:
kind: string
required: false
description: Matches the app-id of the window with a regular expression.
floating:
kind: boolean
required: false
description: Matches if the window is/isn't floating.
visible:
kind: boolean
required: false
description: Matches if the window is/isn't visible.
urgent:
kind: boolean
required: false
description: Matches if the window has/hasn't the urgency flag set.
focused:
kind: boolean
required: false
description: Matches if the window has/hasn't the keyboard focus.
fullscreen:
kind: boolean
required: false
description: Matches if the window is/isn't fullscreen.
just-mapped:
kind: boolean
required: false
description: |
Matches if the window has/hasn't just been mapped.
This is true for one iteration of the compositor's main loop immediately after the
window has been mapped.
tag:
kind: string
required: false
description: Matches the toplevel-tag of the window verbatim.
tag-regex:
kind: string
required: false
description: Matches the toplevel-tag of the window with a regular expression.
x-class:
kind: string
required: false
description: Matches the X class of the window verbatim.
x-class-regex:
kind: string
required: false
description: Matches the X class of the window with a regular expression.
x-instance:
kind: string
required: false
description: Matches the X instance of the window verbatim.
x-instance-regex:
kind: string
required: false
description: Matches the X instance of the window with a regular expression.
x-role:
kind: string
required: false
description: Matches the X role of the window verbatim.
x-role-regex:
kind: string
required: false
description: Matches the X role of the window with a regular expression.
workspace:
kind: string
required: false
description: Matches the workspace of the window verbatim.
workspace-regex:
kind: string
required: false
description: Matches the workspace of the window with a regular expression.
content-types:
ref: ContentTypeMask
required: false
description: Matches windows whose content type is contained in the mask.
WindowMatchExactly:
kind: table
description: |
Criterion for matching a specific number of window criteria.
fields:
num:
kind: number
required: true
description: The number of criteria that must match.
list:
kind: array
items:
ref: WindowMatch
required: true
description: The list of criteria.
WindowTypeMask:
description: |
A mask of window types.
kind: variable
variants:
- kind: string
description: A named mask.
values:
- value: none
description: The empty mask.
- value: any
description: The mask containing every possible type.
- value: container
description: The mask matching a container.
- value: xdg-toplevel
description: The mask matching an XDG toplevel.
- value: x-window
description: The mask matching an X window.
- value: client-window
description: The mask matching any type of client window.
- kind: array
description: An array of masks that are OR'd.
items:
ref: WindowTypeMask
TileState:
description: Whether a window is tiled or floating.
kind: string
values:
- value: tiled
description: The window is tiled.
- value: floating
description: The window is floating.
ContentTypeMask:
description: |
A mask of content types.
kind: variable
variants:
- kind: string
description: A named mask.
values:
- value: none
description: The mask matching windows without a content type.
- value: any
description: The mask containing every possible type except `none`.
- value: photo
description: The mask matching photo content.
- value: video
description: The mask matching video content.
- value: game
description: The mask matching game content.
- kind: array
description: An array of masks that are OR'd.
items:
ref: ContentTypeMask
FocusHistory:
kind: table
description: |
Describes settings of the focus history.
- Example:
```toml
[focus-history]
only-visible: true
same-workspace: true
```
fields:
only-visible:
description: |
Sets whether the focus history only moves to windows that are already visible.
If this is false, then the window will be made visible before focusing it.
The default is `false`.
kind: boolean
required: false
same-workspace:
description: |
Sets whether the focus history only moves to windows on the same workspace.
The default is `false`.
kind: boolean
required: false
MarkId:
kind: table
description: |
Identifies a mark.
Exactly one of the fields must be set.
- Example:
```toml
[shortcuts]
alt-x = { type = "create-mark", id.key = "a" }
```
fields:
key:
description: |
Identifies a mark by a key press.
The names of the keys can be found in [1] with the `KEY_` prefix removed. The key
names must be written all lowercase.
[1]: https://github.com/torvalds/linux/blob/master/include/uapi/linux/input-event-codes.h
kind: string
required: false
name:
description: |
Identifies a mark with an arbitrary string.
kind: string
required: false
InputMode:
kind: table
description: |
Defines an input mode.
Modes can be used to define shortcuts that are only active when the mode is active.
- Example
```toml
[modes."navigation".shortcuts]
w = "focus-up"
a = "focus-left"
s = "focus-down"
d = "focus-right"
r = "focus-above"
f = "focus-below"
q = "focus-prev"
e = "focus-next"
```
fields:
parent:
kind: string
required: false
description: |
The parent of this input mode.
This mode inherits all shortcuts from this parent. If this field is not set, then
it inherits the shortcuts from the top-level shortcuts.
Note that you can disable a shortcut by explicitly assigning it the action `none`.
shortcuts:
kind: map
values:
ref: Action
required: false
description: |
The shortcuts of this mode.
See the same field in the top-level `Config` object for a description.
complex-shortcuts:
kind: map
values:
ref: ComplexShortcut
required: false
description: |
The complex shortcuts of this mode.
See the same field in the top-level `Config` object for a description.
WorkspaceDisplayOrder:
kind: string
description: |
The order of workspaces displayed.
values:
- value: manual
description: Workspaces are not sorted and can be manually dragged.
- value: sorted
description: Workspaces are sorted alphabetically and cannot be manually dragged.
BlendSpace:
kind: string
description: |
A color blend space.
values:
- value: srgb
description: The sRGB blend space. This is the classic desktop blend space.
- value: linear
description: Linear color space. This is the physically correct blend space.
Direction:
kind: string
description: |
A directional value used for output selection.
values:
- value: left
description: The left direction.
- value: right
description: The right direction.
- value: up
description: The up direction.
- value: down
description: The down direction.
ClientCapabilities:
description: |
A mask of client capabilities.
kind: variable
variants:
- kind: string
description: A named mask.
values:
- value: none
description: No capabilities.
- value: all
description: The mask containing all capabilities.
- value: data-control
description: |
Grants access to the `ext_data_control_manager_v1` and
`zwlr_data_control_manager_v1` globals.
- value: virtual-keyboard
description: |
Grants access to the `zwp_virtual_keyboard_manager_v1` global.
- value: foreign-toplevel-list
description: |
Grants access to the `ext_foreign_toplevel_list_v1` global.
- value: idle-notifier
description: |
Grants access to the `ext_idle_notifier_v1` global.
- value: session-lock
description: |
Grants access to the `ext_session_lock_manager_v1` global.
- value: layer-shell
description: |
Grants access to the `zwlr_layer_shell_v1` global.
- value: screencopy
description: |
Grants access to the `ext_image_copy_capture_manager_v1` and
`zwlr_screencopy_manager_v1` globals.
- value: seat-manager
description: |
Grants access to the `ext_transient_seat_manager_v1` global.
- value: drm-lease
description: |
Grants access to the `wp_drm_lease_device_v1` global.
- value: input-method
description: |
Grants access to the `zwp_input_method_manager_v2` global.
- value: workspace-manager
description: |
Grants access to the `ext_workspace_manager_v1` global.
- value: foreign-toplevel-manager
description: |
Grants access to the `zwlr_foreign_toplevel_manager_v1` global.
- value: head-manager
description: |
Grants access to the `jay_head_manager_v1` and `zwlr_output_manager_v1`
globals.
- value: gamma-control-manager
description: |
Grants access to the `zwlr_gamma_control_manager_v1` global.
- kind: array
description: An array of masks that are OR'd.
items:
ref: ClientCapabilities
SimpleIm:
kind: table
description: |
Describes the settings of the simple, XCompose based input method.
- Example:
```toml
[simple-im]
enabled = false
```
fields:
enabled:
kind: boolean
required: false
description: |
Whether the input method is enabled.
Even if the input method is enabled, it will only be used if there is no
running external IM.
BarPosition:
kind: string
description: The position of the bar.
values:
- value: top
description: The bar is at the top of the output.
- value: bottom
description: The bar is at the bottom of the output.
FallbackOutputMode:
kind: string
description: |
Defines which output is used when no particular output is specified.
This configures where to place a newly opened window or workspace, what window to focus when a
window is closed, which workspace is moved with move-to-output, and similar actions.
values:
- value: cursor
description: Use the output the cursor is on.
- value: focus
description: Use the output the focus is on (highlighted window).
View git blame Copy permalink