mapping capslock to escape when tapped and control otherwise

[ad-chaos]

Mapping capslock to escape when tapped and control otherwise is very easy todo on linux, on macos however the process todo that is much more intrusive, requiring external software like karabiner elements.

Given that my usecase for this is mostly in vim, zsh and other terminal programs, I wondered if there was some way to add this in kitty. I've written a patch as a PoC

diff --git a/kitty/keys.c b/kitty/keys.c
index 2307657c1..ecbc89d76 100644
--- a/kitty/keys.c
+++ b/kitty/keys.c
@@ -307,6 +307,26 @@ on_key_input(const GLFWkeyevent *ev) {
         k[w->buffered_keys.count++] = *ev;
         debug("buffering key until child is ready\n");
     } else send_key_to_child(w->id, screen, ev);
+
+    static bool ctrl_was_pressed_alone = false;
+    const bool is_ctrl = (key == GLFW_FKEY_LEFT_CONTROL || key == GLFW_FKEY_RIGHT_CONTROL);
+    const bool press_ctrl = is_ctrl && (action == GLFW_PRESS);
+    const bool release_ctrl = is_ctrl && (action == GLFW_RELEASE);
+
+    if(press_ctrl) {
+        ctrl_was_pressed_alone = true;
+    } else if (ctrl_was_pressed_alone && release_ctrl) {
+#define ESCAPE(ac)                                                             \
+    send_key_to_child(                                                         \
+        w->id, screen,                                                         \
+        &(GLFWkeyevent){.key = GLFW_FKEY_ESCAPE, .action = GLFW_##ac})
+      ESCAPE(PRESS);
+      ESCAPE(RELEASE);
+    } else if (action == GLFW_PRESS) {
+      ctrl_was_pressed_alone = false;
+    }
+
+#undef ESCAPE
 #undef dispatch_key_event
 }

But this is probably horrible.

I don't know of any other keys that would benefit from this tapped and pressed along with something else distinction
What do you think?

[kovidgoyal]

Not a fan of this. To make this generally useful you need some kind of configuration language for this, which becomes a lot of complexity, for a very niche use case. Also, to do this robustly you would need to map the keys at the input layer (in glfw) long before they reach kitty code. Which means doing it separately for each OS. On macOS for instance, because of the way shortcuts are handled in the global menubar, the mapping would need to be done before the keys are even passed into cocoa. Similarly on Linux you would need to do it before the keys are fed into the IME, which means before they reach kitty code.

[ad-chaos]

Makes sense, what do you think about supporting a mapping like:
map ctrl esc
This would have the same effect without having to introduce a complex configuration language or patching kitty's source

[ad-chaos]

The reason I bring that up is because macos provides a way to change caps lock to ctrl natively

[kovidgoyal]

On Mon, Aug 18, 2025 at 06:49:45AM -0700, ad-chaos wrote: Makes sense, what do you think about supporting a mapping like: `map ctrl esc`

It would need to be a different keyword like modmap, map cant be overloaded for this. And it still needs code for each platform separately. If you mean you want pressing capslock to generate an escape key press you can more or less do that already with something like map capslock send_key esc

[ad-chaos]

The problem with that is it will only work when going from capslock on to capslock off, when doing caps off -> caps on esc will not be sent.
But that's not a problem, I can do a system wide change for capslock to be ctrl in macos settings

so capslock+<key> will work as expected, as it sends ctrl+<key> to kitty, what I am looking for in addition to this is when I tap on the capslock, which due to the setting above will send a ctrl key event to kitty, to raise an ESCAPE key event.

In the patch above I did that, in the on_key function in keys.c, I look if GLFW_FKEY_LEFT_CONTROL or GLFW_FKEY_LEFT_CONTROL were pressed (the capslock was pressed which is mapped to control) and in the interim if no other keys were pressed (which means capslock was tapped on) then when capslock is released I send a GLFW_FKEY_ESCAPE .

The patch is horrible, what I'm asking is if it would be possible to support mappings like

map ctrl esc
map ctrl+a ctrl+a
map ctrl+* ctrl+*

so ctrl alone is actually escape but ctrl+* is ctrl+*

[kovidgoyal]

you should be able to do that by mapping the left and right control keys using their native codes, see https://sw.kovidgoyal.net/kitty/mapping/#syntax-for-specifying-keys though you might need to patch things a bit to get this working with modifier keys, should be s relatively simply path though.

[kovidgoyal]

And just for testing, on Linux I managed it with this:
kitty -o 'map ctrl+Control_L send_key esc' showkey -a

macOS should be something similar except you will need to use the actual hex code for the key

[ad-chaos]

I got it to work using

map ctrl+left_control send_key esc
map ctrl+right_control send_key esc

That's incredible!

But looks like if I do ctrl+l it sends esc and also sends ctrl+l

[kovidgoyal]

On Mon, Aug 18, 2025 at 09:19:57AM -0700, ad-chaos wrote: I got it to work using ``` map ctrl+left_control send_key esc map ctrl+right_control send_key esc ``` That's incredible! But looks like if I do `ctrl+l` it sends `esc` and also sends `ctrl+l`

haha well yes, I didnt think of that. when you press the control key it has no way to know you mean to use it as a modifier or as a key. I dont really see a good fix for that.

[ad-chaos]

Oh well :(
So close yet so far

[kovidgoyal]

You should probably just map caps lock to esc and leave it at that. trying to get it to work both as esc and ctrl is a bridge to far. Although personally I prefer to use jj as esc in vim and vim likes.

[ad-chaos]

Fair enough, I've been using karabiner ever since I started using vim and old habits die hard 😅
But its probably time to use a saner mapping

[ad-chaos]

I think map ctrl+right_control>right_control send_key esc might just solve my problem
When right_control is pressed followed by a right_control release then send an escape, otherwise ignore the mapping, however there seems to be now way to say right_control release to map

[kovidgoyal]

On Tue, Aug 19, 2025 at 01:58:13AM -0700, ad-chaos wrote: I think `map ctrl+right_control>right_control send_key esc` might just solve my problem When `right_control` is pressed followed by a `right_control` release then send an escape, otherwise ignore the mapping, however there seems to be now way to say `right_control release` to `map`

map only works on press events since it's meant for shortcuts not arbitrary key mapping.

[ad-chaos]

but a key like right_control can only be sent as a release

ctrl+RIGHT_CONTROL PRESS 
CSI 57448 ; 5 u

RIGHT_CONTROL RELEASE 
CSI 57448 ; 1 : 3 u

so perhaps there's an exception to be made for modifier keys :)

[kovidgoyal]

Not sure what you mean? IIRC when you map to send_key it will consume the release event as well, but map itself triggers on the press/repeat event and has no effect on release events.

…

On Tue, Aug 19, 2025 at 02:10:32AM -0700, ad-chaos wrote: but a key like `right_control` can only be sent as a release ``` ctrl+RIGHT_CONTROL PRESS CSI 57448 ; 5 u RIGHT_CONTROL RELEASE CSI 57448 ; 1 : 3 u ``` so perhaps modifier keys there's an exception to be made :) -- Reply to this email directly or view it on GitHub: #8912 (reply in thread) You are receiving this because you commented. Message ID: ***@***.***>

--

_____________________________________ Dr. Kovid Goyal https://www.kovidgoyal.net https://calibre-ebook.com

_____________________________________

[ad-chaos]

When kitty calls dispatch_possible_special_key here

kitty/kitty/keys.c

Lines 281 to 283 in 8451ad4

	if (action == GLFW_PRESS || action == GLFW_REPEAT) {
	w->last_special_key_pressed = 0;
	dispatch_key_event(dispatch_possible_special_key);

currently its only called on GLFW_PRESS and GLFW_REPEAT however, when in a mapping like:
map ctrl+right_control>right_control send_key esc

Pressing the right control key sends a ctrl+right_control and only on a release is a right_control (no modifiers just the key itself) is sent, thus currently the above mapping is never triggered and leaves kitty in a weird state.

What I'm saying is that maybe for modifier keys (like ctrl, alt, etc) we should also send release events as well to dispatch_possible_special_key

[kovidgoyal]

On Tue, Aug 19, 2025 at 02:38:19AM -0700, ad-chaos wrote: When kitty calls `dispatch_possible_special_key` here https://github.com/kovidgoyal/kitty/blob/8451ad44b595581f90f12129cf5dd3909c10b2fb/kitty/keys.c#L281-L283 currently its only called on `GLFW_PRESS` and `GLFW_REPEAT` however, when in a mapping like: `map ctrl+right_control>right_control send_key esc` Pressing the right control key sends a `ctrl+right_control` and only on a release is a `right_control` (no modifiers just the key itself) is sent, thus currently the above mapping is never triggered and leaves kitty in a weird state.

That's because that mapping is mapped to a *press* of ctrl+right_control followed by a *press* of just right_control. Like I said map only works on press events.

What I'm saying is that maybe for modifier keys (like ctrl, alt, etc) we should also send release events as well to `dispatch_possible_special_key`

That would be pointless without adding infrastructure to map release events as well, which is waaay too much work.

[ad-chaos]

But there is no way to press a right_control without it also having the ctrl modifier bit set!
Wouldn't it be fair to say that when a user says they want to map on a right_control it means whenever kitty gets a right_control which is only when the right_control is released?

It's just

diff --git a/kitty/keys.c b/kitty/keys.c
index 2307657c1..b04558a62 100644
--- a/kitty/keys.c
+++ b/kitty/keys.c
@@ -278,7 +278,7 @@ on_key_input(const GLFWkeyevent *ev) {
     else { consumed = ret == Py_True; Py_CLEAR(ret); } \
     w = window_for_window_id(active_window_id); \
 }
-    if (action == GLFW_PRESS || action == GLFW_REPEAT) {
+    if (is_modifier_key(key) || action == GLFW_PRESS || action == GLFW_REPEAT) {
         w->last_special_key_pressed = 0;
         dispatch_key_event(dispatch_possible_special_key);
         if (dispatch_ok) {

[kovidgoyal]

On Tue, Aug 19, 2025 at 02:51:46AM -0700, ad-chaos wrote: But there is no way to press a `right_control` without it also having the ctrl modifier bit set! Wouldn't it be fair to say that when a user says they want to map on a `right_control` it means whenever kitty gets a `right_control` which is only when the `right_control` is released?

It's equally fair to say that kitty doesn't support mapping of modifier keys alone as shortcuts. You are essentially using a hack to try to get your ctrl modifier to work both as a modifier and a shortcut. While I admire the chutzpah, I am not willing to complicate things to support that.

It's just

Sure, to enable your use case, but that *might* break other things and does break the simple mental model of map being something that maps press events and not release events.

…

--

_____________________________________ Dr. Kovid Goyal https://www.kovidgoyal.net https://calibre-ebook.com

_____________________________________

[ad-chaos]

Fair enough, before I give up, are you open to patches that add support for mapping release key events :)

[kovidgoyal]

In principle, maybe. Depends on how complex they turn out to be. The keyboard handling code is extremely gnarly already.

[ad-chaos]

In anycase, thank you for your work on kitty! Its an incredible terminal with awesome innovations and I have enjoyed using all its features! 😄

[kovidgoyal]

You are welcome!