kossLAN/wry
1
0
Fork 0
forked from wry/wry
Code Pull requests Activity
wry/toml-spec/spec/spec.yaml
Julian Orth dcf57db3df config: add visibility window criteria
2025-05-07 22:41:43 +02:00

3536 lines
94 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:
```toml
[shortcuts]
alt-F1 = { type = "show-workspace", name = "1" }
```
fields:
name:
description: The name of the workspace.
required: true
kind: string
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:
```toml
[shortcuts]
alt-F1 = { type = "move-to-output", workspace = "1", output.name = "right" }
```
- Example 2:
```toml
[shortcuts]
alt-F1 = { type = "move-to-output", output.name = "right" }
```
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.
required: true
ref: OutputMatch
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
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" } }
```
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.
- Example:
```toml
[shortcuts]
ctrl-a = { type = "exec", exec = { prog = "notify-send", args = ["hello world"], env.WAYLAND_DISPLAY = "2" } }
```
fields:
prog:
kind: string
required: true
description: The name of the executable.
args:
kind: array
required: false
items:
kind: string
description: The arguments to pass to the executable.
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`.
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-to
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.
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.
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.
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: TransferFunction
required: false
description: |
The transfer function 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.
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.
font:
kind: string
required: false
description: The name of the font to use.
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" }
```
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 cursors are updated on screen when VRR is active.
VrrMode:
description: |
The VRR mode of an output.
- Example:
```toml
vrr = { mode = "always", cursor-hz = 90 }
```
kind: string
values:
- value: always
description: VRR is never enabled.
- value: never
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 game or video is displayed fullscreen.
VrrHz:
description: |
A VRR refresh rate limiter.
- 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 limiter.
- kind: number
description: The refresh rate in HZ.
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: always
description: Tearing is never enabled.
- value: never
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:
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.
TransferFunction:
description: |
The transfer function of an output.
kind: string
values:
- value: default
description: The default transfer function (usually sRGB).
- value: pq
description: The PQ transfer function.
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 transfer function:
- `default`: The maximum brightness of the output.
- `PQ`: 203 cd/m^2
- 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.
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.
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.
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.
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
View git blame Copy permalink