Josh Piasecki
057c3c1206
I love keybindings. I spend way to much time thinking about them. I also REALLY like working in Zed. so far, however, I have found the key context system in Zed to be less flexible than in VSCode. the HUGE context that is available in VSCode helps you create keybindings for very specific targeted scenarios. the tree like structure of the Zed key context means you loose some information as focus moves throughout the application. For example, it is not currently possible to create a keybinding in the editor that will only work when one of the Docks is open, or if a specific dock is open. this would be useful in implementing solutions to ideas like #24222 we already have an action for moving focus to the dock, and we have an action for opening/closing the dock, but to my knowledge (very limited lol) we cannot determine if that dock *is open* unless we are focused on it. I think it is possible to create a more flexible key binding system by adding more context information to the higher up context ancestors. while: ``` Workspace right_dock=GitPanel Dock GitPanel Editor ``` may seem redundant, it actually communicates fundamentally different information than: ``` Workspace right_dock=GitPanel Pane Editor ``` the first says "the GitPanel is in the right hand dock AND IT IS FOCUSED", while the second means "Focus is on the Editor, and the GitPanel just happens to be open in the right hand dock" This change adds a new set of identifiers to the `Workspace` key_context that will indicate which docks are open and what is the specific panel that is currently visible in that dock. examples: - `left_dock=ProjectPanel` - `bottom_dock=TerminalPanel` - `right_dock=GitPanel` in my testing the following types of keybindings seem to be supported with this change: ```jsonc // match for any value of the identifier "context": "Workspace && bottom_dock" "context": "Workspace && !bottom_dock" // match only a specific value to an identifier "context": "Workspace && bottom_dock=TerminalPanel" // match only in a child context if the ancestor workspace has the correct identifier "context": "Workspace && !bottom_dock=DebugPanel > Editor" ``` some screen shots of the context matching in different circumstances: <img width="2032" height="1167" alt="Screenshot 2025-10-16 at 23 20 34" src="https://github.com/user-attachments/assets/116d0575-a1ae-4577-95b9-8415cda57e52" /> <img width="2032" height="1167" alt="Screenshot 2025-10-16 at 23 20 57" src="https://github.com/user-attachments/assets/000fdbb6-80bd-46e9-b668-f4b54ab708d2" /> <img width="2032" height="1167" alt="Screenshot 2025-10-16 at 23 21 37" src="https://github.com/user-attachments/assets/7b1c82da-b82f-4e14-a97c-3cd0e71bbca0" /> <img width="2032" height="1167" alt="Screenshot 2025-10-16 at 23 21 52" src="https://github.com/user-attachments/assets/1fd4b65a-09f7-47a9-a9b7-fdce4252aec3" /> <img width="2032" height="1167" alt="Screenshot 2025-10-16 at 23 22 38" src="https://github.com/user-attachments/assets/f4c2ac5c-e6f9-4e0e-b683-522b237e3328" /> the persistent_name values for `ProjectPanel` and `OutlinePanel` needed to be updated to not have a space in them in order to pass the `Identifier` check. all the other Panels already had names that did not include spaces, so it just makes these conform with the other ones. I think this is a great place to start with adding more context identifiers and i think this type of additional information will make it possible to create really dynamic keybindings! Release Notes: - Workspace key context now includes the state of the 3 docks
Design notes:
This crate is split into two conceptual halves:
- The terminal.rs file and the src/mappings/ folder, these contain the code for interacting with Alacritty and maintaining the pty event loop. Some behavior in this file is constrained by terminal protocols and standards. The Zed init function is also placed here.
- Everything else. These other files integrate the
Terminalstruct created in terminal.rs into the rest of GPUI. The main entry point for GPUI is the terminal_view.rs file and the modal.rs file.
ttys are created externally, and so can fail in unexpected ways. However, GPUI currently does not have an API for models than can fail to instantiate. TerminalBuilder solves this by using Rust's type system to split tty instantiation into a 2 step process: first attempt to create the file handles with TerminalBuilder::new(), check the result, then call TerminalBuilder::subscribe(cx) from within a model context.
The TerminalView struct abstracts over failed and successful terminals, passing focus through to the associated view and allowing clients to build a terminal without worrying about errors.
#Input
There are currently many distinct paths for getting keystrokes to the terminal:
-
Terminal specific characters and bindings. Things like ctrl-a mapping to ASCII control character 1, ANSI escape codes associated with the function keys, etc. These are caught with a raw key-down handler in the element and are processed immediately. This is done with the
try_keystroke()method on Terminal -
GPU Action handlers. GPUI clobbers a few vital keys by adding bindings to them in the global context. These keys are synthesized and then dispatched through the same
try_keystroke()API as the above mappings -
IME text. When the special character mappings fail, we pass the keystroke back to GPUI to hand it to the IME system. This comes back to us in the
View::replace_text_in_range()method, and we then send that to the terminal directly, bypassingtry_keystroke(). -
Pasted text has a separate pathway.
Generally, there's a distinction between 'keystrokes that need to be mapped' and 'strings which need to be written'. I've attempted to unify these under the '.try_keystroke()' API and the .input() API (which try_keystroke uses) so we have consistent input handling across the terminal