aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorDaniel Eklöf <daniel@ekloef.se>2025-01-27 11:31:50 +0000
committerDaniel Eklöf <daniel@ekloef.se>2025-01-27 11:31:50 +0000
commit1c7c9f6c16a55c47ea8f2740cd9d7619c4e0f9a8 (patch)
treeb25d4d48700c81b606494c733f148814ad0df148 /doc
parentkey-bindings: try all bindings in translated mode before matching untranslated, and then finally raw (diff)
doc: foot.ini: describe key binding match logic
Diffstat (limited to 'doc')
-rw-r--r--doc/foot.ini.5.scd33
1 files changed, 31 insertions, 2 deletions
diff --git a/doc/foot.ini.5.scd b/doc/foot.ini.5.scd
index 733168bf..35f78674 100644
--- a/doc/foot.ini.5.scd
+++ b/doc/foot.ini.5.scd
@@ -1096,7 +1096,36 @@ Note that *Alt* is usually called *Mod1*.
*xkbcli interactive-wayland* can be useful for finding keysym names.
-A key combination can only be mapped to *one* action. Lets say you
+When matching key presses to key bindings, foot uses a couple of
+different approaches.
+
+As an example, let's say you press ctrl+shift+c (assume plain us ASCII
+layout). XKB will tell foot *Control+C* was pressed. Note the lack of
+the shift modifier, and the upper case 'C'. Internally, this is called
+the "translated" form, and is what foot tries to match first.
+
+If no "translated" key bindings can be found, foot proceeds to
+checking the "untranslated" variant. Using the same example as above,
+this will match *Control+Shift+c* (shift modifier present, lower case
+'c').
+
+This means you can use either form in your foot configuration, and
+that *Control+C* (and similar) has higher priority than
+*Control+Shift+c*. Also note that while foot normally detects when the
+same combination is assigned to multiple actions, it will not detect
+*Control+C* vs. *Control+Shift+c* collisions. Call it a known bug...
+
+Finally, foot tries to match the raw key code. Here, the primary
+layout is queried for all key codes that generate a particular XKB
+symbol, and the pressed key's code is matched against this. For
+example, if you use the layouts *"us,de(neo)"*, the 'r' key generates
+the symbol 'c' in the neo layout. I.e. to get a 'c', you press
+'r'. The match logic described above will only match 'c' key bindings
+(e.g. *Control+Shift+c*). The raw mode however, will match 'r' key
+bindings (e.g. *Control+Shift+r*). This is useful for non-latin
+layouts, where you would otherwise have to customize all key bindings.
+
+A key combination can only be mapped to *one* action. Let's say you
want to bind *Control+Shift+R* to *fullscreen*. Since this is the
default shortcut for *search-start*, you first need to unmap the
default binding. This can be done by setting _action=none_;
@@ -1453,7 +1482,7 @@ events never generate a *COUNT* larger than 1. That is,
Foot also recognizes tiltable wheels; to map these, use
*BTN_WHEEL_LEFT* and *BTN_WHEEL_RIGHT*.
-A modifier+button combination can only be mapped to *one* action. Lets
+A modifier+button combination can only be mapped to *one* action. Let's
say you want to bind *BTN\_MIDDLE* to *fullscreen*. Since
*BTN\_MIDDLE* is the default binding for *primary-paste*, you first
need to unmap the default binding. This can be done by setting