Covers the empty default, a single remap, that both directions of a swap are
recorded, that the last declaration for a source wins wherever it appears,
multi-modifier destinations, and that every rejection is reported rather than
silently ignored: wrong arity, unknown or non-remappable modifier names, a
source naming more than one modifier, and a no-op mapping.
Whether the permutation is applied simultaneously rather than sequentially is
a property of the C code and is not observable from the parsed dict, which is
identical either way; the comment says so rather than implying more coverage
than exists.
remap_modifier <from> <to>
Repeatable and off by default. The declarations compose as a single
simultaneous permutation applied once per event, so
remap_modifier ctrl super
remap_modifier super ctrl
exchanges the two rather than collapsing to the identity. Only shift, alt,
ctrl, super, hyper and meta may be named; anything else is rejected with an
error. The last declaration for a given source wins.
The remap is applied to the modifier mask BEFORE the platform produces the
keysym and text - in glfw_xkb_update_modifiers() before xkb_state_update_mask()
on Linux, and in remap_cocoa_flags() before UCKeyTranslate() and
interpretKeyEvents: on macOS. Applying it to the finished event instead
desynchronises the modifiers from the text for any modifier that participates
in text production: shift on Linux, and Option on macOS, which produces text
natively unless macos_option_as_alt is set.
Because the GLFW modifiers are themselves derived from that state, this is
application wide: kitty's own shortcuts, kitty_mod and the bytes sent to the
child all see the remapped modifier, and every mapping in kitty.conf is written
in terms of the modifier a key becomes. X11 pointer events do not go through
xkb, so translateState() - which only ever sees button and DND events - gets
the same treatment; Wayland pointer events already carry xkb-derived modifiers.
A modifier key's own event has its identity remapped too, so a program using
the full keyboard protocol does not see ctrl reported together with LEFT_HYPER.
The press/release state fixup on Linux is given the remapped modifier rather
than the physical one, so press and release agree.
--debug-input reports each remapped event.
Notes: on Wayland kitty only detects hyper and meta when
KITTY_WAYLAND_DETECT_MODIFIERS is set, so remapping to or from them has nothing
to act on there. On macOS hyper and meta have no Cocoa modifier flag, so a
remap onto them is left unapplied rather than silently dropping the modifier,
and interpretKeyEvents: is only approximately corrected because the event's
characters strings were computed by the OS from the physical flags; the
UCKeyTranslate() path, normally the one taken, is exact.
Generated option files and the glfw wrapper come from their generators.
save_as_session recorded only the state of the tab's active layout, so the state
of any layout the tab had been toggled away from was lost. Toggling a splits tab
to the stack layout and saving discarded the splits tree entirely, because Stack
has no layout_state() of its own, and switching back to splits after restoring
rebuilt the tree from scratch along the default axis.
The session file also carried no last_used_layout, so _last_used_layout was None
after a restore and toggle_layout <current layout> silently did nothing, since it
delegates to last_used_layout() which returns early when unset. The key that
produced the stack layout no longer undid it.
Tab now keeps the layouts it has used, by name, and writes their state plus
last_used_layout into the existing set_layout_state JSON rather than adding new
session commands. Older versions of kitty ignore unknown keys in that dict but
abort on unknown commands, so nesting keeps session files readable by them.
Restoring the state of a layout that is not being made current must not reorder
the window list, since only the current layout determines window order, hence
apply_to_window_list. Splits.set_layout_state also has to accept state for a
layout whose tree is still empty, which is the case for a layout that has not
laid out any windows yet.
Fixes#10320
