aria
993bc0f88f
- Add optional modifier-only Super binding whose tap is cancelled by other input, focus changes, grabs, locks, and session teardown. - Ship the native ferese-rime user service, Rime defaults, installer inventory, package dependencies, session environment, and docs. - Vendor Smithay 8a27023 with the SHM texture-cache format fix and add GPU regressions for format changes and resize snapshots. - Release reused CRTC owners before staging output modes, then restore changed outputs before former owners when a transaction fails. - Wait for resize-capture GPU completion, expand filtered surface damage, and preserve IME popup origin under fractional scaling. - Mark weekends like holidays in both calendar layouts.
178 lines
9.2 KiB
Markdown
178 lines
9.2 KiB
Markdown
# Commands and bindings
|
||
|
||
See [Shortcuts and gestures](../shortcuts.md) for the full default keymap and mouse actions.
|
||
|
||
`commands` maps arbitrary names to nonempty argument arrays. The built-in
|
||
`terminal "foot"` can be overridden. Commands run directly, without a shell.
|
||
|
||
| `binding` key | Type / values | Default |
|
||
| --- | --- | --- |
|
||
| `keys` | chord or gesture, e.g. `"Super+Enter"`, `"Swipe3Up"` | required |
|
||
| `match` | `"keysym"`, `"physical"` | `"keysym"` |
|
||
| `action` | action name below | required unless disabled |
|
||
| `argument` | string | required only for actions listed below |
|
||
| `disabled` | boolean | `false` |
|
||
|
||
Modifiers: `Super`/`Logo`/`Mod4`, `Ctrl`/`Control`, `Alt`, `Shift`.
|
||
Keys use XKB keysyms (`Enter`, letters, `[`/`]`) or physical XKB names (`AD06`).
|
||
A binding replaces the same normalized chord/match mode. Duplicate bindings are
|
||
invalid. A disabled binding must omit `action` and `argument`.
|
||
|
||
A modifier-only `Super` binding is optional:
|
||
|
||
```kdl
|
||
binding "Super" action="toggle-launcher"
|
||
```
|
||
|
||
Either Super key triggers this action when released after an isolated press.
|
||
The original press and release still reach the focused application. Other keys,
|
||
both Super keys together, pointer movement, clicks, scrolling, gestures and touch
|
||
cancel the tap; a mouse button already held also prevents it. Existing Super
|
||
chords, including Super+Space, keep their actions. Key repeat does not retrigger
|
||
the tap. Locking, shortcut inhibition, client keyboard grabs, focus changes and
|
||
device/session teardown cancel pending taps. Native input-method grabs remain
|
||
compatible. `Logo` and `Mod4` name the same tap, so they cannot be configured as
|
||
separate bindings. Physical matching is not supported for this trigger.
|
||
|
||
Use `binding "Super" disabled=#true` to remove a configured tap. Without a tap
|
||
binding, Super keeps its existing modifier behavior.
|
||
|
||
| Actions | Argument |
|
||
| --- | --- |
|
||
| `spawn` | Name in `commands` |
|
||
| `binding-mode` | Named mode, or `"default"` to leave it |
|
||
| `focus`, `move`, `resize`, `join-tab` | `"left"`, `"right"`, `"up"`, `"down"` |
|
||
| `workspace`, `move-to-workspace` | Workspace number string, 1–255 |
|
||
| `workspace-next`, `workspace-previous` | None; next/previous workspace on this monitor |
|
||
| `workspace-back-and-forth` | None; return to the previous workspace on this monitor |
|
||
| `focus-last-window` | None; return to the last focused window |
|
||
| `focus-floating` | None; focus the last focused window in the opposite tiled/floating layer on this workspace |
|
||
| `focus-mru-next`, `focus-mru-previous` | None; cycle windows in focus order |
|
||
| `none` | None; ignore this trigger |
|
||
| `close`, `exit`, `toggle-maximized`, `toggle-fullscreen`, `toggle-layout`, `cycle-column-width`, `center-column`, `consume`, `expel`, `toggle-column-tabbed`, `leave-tab`, `next-tab`, `previous-tab`, `toggle-floating`, `toggle-overview`, `toggle-launcher` | None |
|
||
|
||
```kdl
|
||
commands {
|
||
terminal "foot"
|
||
}
|
||
binding keys="Super+Enter" action="spawn" argument="terminal"
|
||
binding keys="Super+V" action="focus-floating"
|
||
```
|
||
|
||
See [Tabbed windows](../tabbed-windows.md) for grouping actions and
|
||
[Layout configuration](layout.md#tabbed-columns) for scrolling tab settings.
|
||
|
||
`focus-floating` switches focus between tiled and floating windows without
|
||
changing placement. It stays on the active workspace and does nothing when the
|
||
opposite layer has no candidate. `toggle-floating` changes window placement.
|
||
|
||
## Binding modes
|
||
|
||
Named modes provide a separate keyboard map for resizing, launching, or other
|
||
sets of actions. No modes are enabled by default. For example:
|
||
|
||
```kdl
|
||
binding "Super+Shift+r" "binding-mode" "resize"
|
||
binding "Super+Shift+Return" "binding-mode" "launch"
|
||
binding-mode "resize" {
|
||
binding "h" "resize" "left"
|
||
binding "j" "resize" "down"
|
||
binding "k" "resize" "up"
|
||
binding "l" "resize" "right"
|
||
binding "Return" "binding-mode" "default"
|
||
}
|
||
binding-mode "launch" {
|
||
binding "t" "spawn" "terminal"
|
||
binding "r" "binding-mode" "resize"
|
||
binding "Return" "binding-mode" "default"
|
||
}
|
||
```
|
||
|
||
Release the entry chord's modifiers before using an unmodified mode binding.
|
||
Modifiers keep their usual exact matching semantics; entering a mode never
|
||
changes the application's modifier state. Escape exits with any modifiers held
|
||
and cannot be overridden inside a mode. The bar shows the active name and Escape
|
||
hint, including over fullscreen windows, and restores its ordinary contents on
|
||
exit. Long names truncate to keep the exit hint visible. Mode changes reach the
|
||
shell through its existing snapshot protocol.
|
||
|
||
Entering a mode closes panel popovers and workspace tooltips. An expanded Morph
|
||
panel collapses and releases keyboard focus. Hover, activity updates, and queued
|
||
menu requests cannot reopen it while the mode indicator is displayed.
|
||
Live Activities continue updating their data, but leave the hidden Morph panel's
|
||
geometry unchanged until the mode exits.
|
||
|
||
Mode bindings replace the default keyboard map while active. Unmatched keys
|
||
reach the focused application; default compositor bindings and portal shortcuts
|
||
do not run as fallbacks. Gestures keep the default configuration. Normal shortcut
|
||
inhibition still applies, with Escape available to leave the mode. A mode remains
|
||
active across actions and focus/workspace changes until explicitly changed or
|
||
exited; launching an application does not implicitly leave it.
|
||
|
||
Each mode must have a unique name of 1–48 ASCII letters, digits, underscores, or
|
||
hyphens. `default` is reserved. Mode bindings accept the same actions and physical
|
||
key matching as ordinary bindings; swipes, disabled records, duplicate chords,
|
||
and Escape bindings are rejected, including physical keys remapped to Escape.
|
||
References to undefined modes reject the configuration before it is applied.
|
||
|
||
An accepted change to bindings, modes, commands, or input settings returns to
|
||
default and closes any focus preview. Unrelated reloads preserve the mode;
|
||
rejected reloads keep the previous configuration and mode. Locking, input capture,
|
||
and session suspension also exit.
|
||
The first press owns its matching release across these transitions. Held keys
|
||
are never reinterpreted by a new mode; consumed releases stay consumed. Repeated
|
||
presses retain their original action and repeat only while its chord still
|
||
matches. A mode/configuration transition stops that action's repeats.
|
||
`feresectl keybindings` lists the active keyboard map.
|
||
|
||
Defaults: Super+Enter terminal; Super+Q close; Super+H/J/K/L focus;
|
||
Super+Shift+H/J/K/L move; Super+Ctrl+H/J/K/L resize; Super+1–9 workspace;
|
||
Super+Shift+1–9 move to workspace; Super+R width cycle; Super+C center;
|
||
Super+[/] consume/expel; Super+Shift+T stacked/tabbed column; Super+Ctrl+[/] previous/next tab;
|
||
Super+F maximize; Super+Shift+F fullscreen;
|
||
Super+M layout; Super+Shift+Space floating; Super+V focus tiled/floating; Super+Tab overview;
|
||
Super+Escape previous visited workspace;
|
||
Super+BackSpace last focused window; Alt+Tab/Alt+Shift+Tab MRU switching;
|
||
Super+Shift+S area screenshot; Print Screen whole-screen screenshot;
|
||
Super+Shift+E logout confirmation.
|
||
|
||
Hold Super and drag a floating or tiled window with the left mouse button to move it.
|
||
Hold Super and drag with the right mouse button to resize. The starting position
|
||
selects an edge or corner using a 3×3 grid; the center selects the nearest corner.
|
||
The selected edges stay fixed for the whole drag. These work even when an app has
|
||
no title bar or resize border.
|
||
|
||
Tiled drops can reorder windows, join tab groups or move between monitors.
|
||
Mouse buttons and wheel directions can also use the regular binding actions;
|
||
see [mouse bindings](input.md#mouse-bindings) for configuration and drag controls.
|
||
|
||
For a floating window, Super+Shift+H/J/K/L moves left/down/up/right by 32 logical
|
||
pixels. Super+Ctrl+H/L shrinks/grows its width; Super+Ctrl+K/J shrinks/grows its
|
||
height by the same step. Keyboard adjustments respect client size limits and
|
||
keep the window reachable in its output's work area. Fullscreen and maximized
|
||
floating windows ignore these actions.
|
||
|
||
Floating moves and resizes snap to work-area edges and nearby visible window edges at
|
||
10 logical pixels, then resist movement until 20 pixels from the attached edge.
|
||
Window edges are eligible only when the windows overlap along the other axis,
|
||
with a 10-pixel allowance. Hold Shift during a drag to bypass snapping.
|
||
|
||
The screenshot shortcut runs `ferese-screenshot`: drag to select an area, or
|
||
press Escape to cancel. Captures open in Satty for annotation. Press Enter to
|
||
save the edited PNG under your Pictures directory in `Screenshots` and copy it
|
||
to the clipboard; Escape discards the capture. It requires `slurp`, `satty`, and
|
||
`wl-copy` (from `wl-clipboard`); the capture itself is done by the compositor
|
||
through `feresectl screenshot`. Override the `screenshot` command to use another
|
||
screenshot tool.
|
||
Print Screen runs `ferese-screenshot --full` and captures the active monitor
|
||
without a selector, falling back to the sole enabled output when focus is
|
||
unavailable. It never silently captures every output. Fn+PrtSc works when the
|
||
keyboard emits the Print Screen key; Fn is handled by the keyboard firmware.
|
||
Override `screenshot-full` to customize this command. Both modes open Satty with
|
||
the same save and copy workflow.
|
||
|
||
`ferese-screenshot --all` captures every enabled output as one image.
|
||
|
||
Satty opens as a floating window sized for the captured image and constrained
|
||
to the workspace.
|