Keyboard protocol: Remove CSI R from the allowed encodings of the F3 key as it conflicts with the *Cursor Position Report* escape code

docs/changelog.rst

@@ -47,6 +47,8 @@ Detailed list of changes
 - Speed up the ``kitty @`` executable by ~10x reducing the time for typical
   remote control commands from ~50ms to ~5ms
 
+- Keyboard protocol: Remove ``CSI R`` from the allowed encodings of the :kbd:`F3` key as it conflicts with the *Cursor Position Report* escape code (:disc:`5813`)
+
 - Allow using the cwd of the original process for :option:`launch --cwd` (:iss:`5672`)
 
 - Implement :ref:`edit-in-kitty <edit_file>` using the new ``kitty-tool`` static executable (:iss:`5546`, :iss:`5630`)

docs/keyboard-protocol.rst

@@ -68,7 +68,7 @@ text, or using the following escape codes, for those keys that do not produce
 text (``CSI`` is the bytes ``0x1b 0x5b``)::
 
     CSI number ; modifiers [u~]
-    CSI 1; modifiers [ABCDEFHPQRS]
+    CSI 1; modifiers [ABCDEFHPQS]
     0x0d - for the Enter key
     0x7f or 0x08 - for Backspace
     0x09 - for Tab
@@ -83,7 +83,7 @@ The second form is used for a few functional keys, such as the :kbd:`Home`,
 :kbd:`End`, :kbd:`Arrow` keys and :kbd:`F1` ... :kbd:`F4`, they are enumerated in
 the :ref:`functional` table below.  Note that if no modifiers are present the
 parameters are omitted entirely giving an escape code of the form ``CSI
-[ABCDEFHPQRS]``.
+[ABCDEFHPQS]``.
 
 If you want support for more advanced features such as repeat and release
 events, alternate keys for shortcut matching et cetera, these can be turned on
@@ -314,7 +314,7 @@ With this flag turned on, all key events that do not generate text are
 represented in one of the following two forms::
 
     CSI number; modifier u
-    CSI 1; modifier [~ABCDEFHPQRS]
+    CSI 1; modifier [~ABCDEFHPQS]
 
 This makes it very easy to parse key events in an application. In particular,
 :kbd:`ctrl+c` will no longer generate the ``SIGINT`` signal, but instead be
@@ -405,7 +405,7 @@ Legacy functional keys
 These keys are encoded using three schemes::
 
     CSI number ; modifier ~
-    CSI 1 ; modifier {ABCDEFHPQRS}
+    CSI 1 ; modifier {ABCDEFHPQS}
     SS3 {ABCDEFHPQRS}
 
 In the above, if there are no modifiers, the modifier parameter is omitted.
@@ -533,7 +533,7 @@ compatibility reasons.
    "NUM_LOCK", "``57360 u``", "PRINT_SCREEN", "``57361 u``"
    "PAUSE", "``57362 u``", "MENU", "``57363 u``"
    "F1", "``1 P or 11 ~``", "F2", "``1 Q or 12 ~``"
-   "F3", "``1 R or 13 ~``", "F4", "``1 S or 14 ~``"
+   "F3", "``13 ~``", "F4", "``1 S or 14 ~``"
    "F5", "``15 ~``", "F6", "``17 ~``"
    "F7", "``18 ~``", "F8", "``19 ~``"
    "F9", "``20 ~``", "F10", "``21 ~``"
@@ -582,8 +582,14 @@ compatibility reasons.
 .. end functional key table
 .. }}}
 
-Note that the escape codes above of the form ``CSI 1 letter`` will omit the
-``1`` if there are no modifiers, since ``1`` is the default value.
+.. note::
+    The escape codes above of the form ``CSI 1 letter`` will omit the
+    ``1`` if there are no modifiers, since ``1`` is the default value.
+
+.. note::
+   The original version of this specification allowed F3 to be encoded as both
+   CSI R and CSI ~. However, CSI R conflicts with the Cursor Position Report,
+   so it was removed.
 
 .. _ctrl_mapping:
 

gen-key-constants.py

@@ -130,7 +130,7 @@
 }
 different_trailer_functionals = {
     'up': 'A', 'down': 'B', 'right': 'C', 'left': 'D', 'kp_begin': 'E', 'end': 'F', 'home': 'H',
-    'f1': 'P', 'f2': 'Q', 'f3': 'R', 'f4': 'S', 'enter': 'u', 'tab': 'u',
+    'f1': 'P', 'f2': 'Q', 'f3': '~', 'f4': 'S', 'enter': 'u', 'tab': 'u',
     'backspace': 'u', 'escape': 'u'
 }
 

kitty/key_encoding.c

@@ -222,7 +222,7 @@ encode_function_key(const KeyEvent *ev, char *output) {
         case GLFW_FKEY_END: S(1, 'F');
         case GLFW_FKEY_F1: S(1, 'P');
         case GLFW_FKEY_F2: S(1, 'Q');
-        case GLFW_FKEY_F3: S(1, 'R');
+        case GLFW_FKEY_F3: S(13, '~');
         case GLFW_FKEY_F4: S(1, 'S');
         case GLFW_FKEY_F5: S(15, '~');
         case GLFW_FKEY_F6: S(17, '~');

kitty/key_encoding.py

@@ -146,8 +146,8 @@
     24: 57375,
     27: 57344,
     127: 57347}
-letter_trailer_to_csi_number_map = {'A': 57352, 'B': 57353, 'C': 57351, 'D': 57350, 'E': 57427, 'F': 8, 'H': 7, 'P': 11, 'Q': 12, 'R': 13, 'S': 14}
-tilde_trailers = {57348, 57349, 57354, 57355, 57368, 57369, 57370, 57371, 57372, 57373, 57374, 57375}
+letter_trailer_to_csi_number_map = {'A': 57352, 'B': 57353, 'C': 57351, 'D': 57350, 'E': 57427, 'F': 8, 'H': 7, 'P': 11, 'Q': 12, 'S': 14}
+tilde_trailers = {57348, 57349, 57354, 57355, 57366, 57368, 57369, 57370, 57371, 57372, 57373, 57374, 57375}
 # end csi mapping
 # }}}
 

kitty_tests/keys.py

@@ -92,7 +92,7 @@ def mkp(name, *a, **kw):
         mkp('END', csi_num=1, trailer='F')
         mods_test(defines.GLFW_FKEY_F1, '\x1bOP', csi_num=1, trailer='P')
         mods_test(defines.GLFW_FKEY_F2, '\x1bOQ', csi_num=1, trailer='Q')
-        mods_test(defines.GLFW_FKEY_F3, '\x1bOR', csi_num=1, trailer='R')
+        mods_test(defines.GLFW_FKEY_F3, '\x1bOR', csi_num=13, trailer='~')
         mods_test(defines.GLFW_FKEY_F4, '\x1bOS', csi_num=1, trailer='S')
         mods_test(defines.GLFW_FKEY_F5, csi_num=15, trailer='~')
         mods_test(defines.GLFW_FKEY_F6, csi_num=17, trailer='~')

tools/tui/loop/key-encoding.go

@@ -16,10 +16,9 @@ var functional_key_number_to_name_map = map[int]string{57344: "ESCAPE", 57345: "
 
 var csi_number_to_functional_number_map = map[int]int{2: 57348, 3: 57349, 5: 57354, 6: 57355, 7: 57356, 8: 57357, 9: 57346, 11: 57364, 12: 57365, 13: 57345, 14: 57367, 15: 57368, 17: 57369, 18: 57370, 19: 57371, 20: 57372, 21: 57373, 23: 57374, 24: 57375, 27: 57344, 127: 57347}
 
-var letter_trailer_to_csi_number_map = map[string]int{"A": 57352, "B": 57353, "C": 57351, "D": 57350, "E": 57427, "F": 8, "H": 7, "P": 11, "Q": 12, "R": 13, "S": 14}
-
-var tilde_trailers = map[int]bool{57348: true, 57349: true, 57354: true, 57355: true, 57368: true, 57369: true, 57370: true, 57371: true, 57372: true, 57373: true, 57374: true, 57375: true}
+var letter_trailer_to_csi_number_map = map[string]int{"A": 57352, "B": 57353, "C": 57351, "D": 57350, "E": 57427, "F": 8, "H": 7, "P": 11, "Q": 12, "S": 14}
 
+var tilde_trailers = map[int]bool{ 57348:true, 57349:true, 57354:true, 57355:true, 57366:true, 57368:true, 57369:true, 57370:true, 57371:true, 57372:true, 57373:true, 57374:true, 57375:true }
 // end csi mapping
 // }}}