1mod binding;
2mod context;
3
4pub use binding::*;
5pub use context::*;
6
7use crate::{Action, KeybindingKeystroke, Keystroke, is_no_action};
8use collections::HashMap;
9use smallvec::SmallVec;
10use std::any::TypeId;
11
12/// An opaque identifier of which version of the keymap is currently active.
13/// The keymap's version is changed whenever bindings are added or removed.
14#[derive(Copy, Clone, Eq, PartialEq, Default)]
15pub struct KeymapVersion(usize);
16
17/// A collection of key bindings for the user's application.
18#[derive(Default)]
19pub struct Keymap {
20 bindings: Vec<KeyBinding>,
21 binding_indices_by_action_id: HashMap<TypeId, SmallVec<[usize; 3]>>,
22 no_action_binding_indices: Vec<usize>,
23 version: KeymapVersion,
24}
25
26/// Index of a binding within a keymap.
27#[derive(Copy, Clone, Debug, Eq, PartialEq)]
28pub struct BindingIndex(usize);
29
30impl Keymap {
31 /// Create a new keymap with the given bindings.
32 pub fn new(bindings: Vec<KeyBinding>) -> Self {
33 let mut this = Self::default();
34 this.add_bindings(bindings);
35 this
36 }
37
38 /// Get the current version of the keymap.
39 pub fn version(&self) -> KeymapVersion {
40 self.version
41 }
42
43 /// Add more bindings to the keymap.
44 pub fn add_bindings<T: IntoIterator<Item = KeyBinding>>(&mut self, bindings: T) {
45 for binding in bindings {
46 let action_id = binding.action().as_any().type_id();
47 if is_no_action(&*binding.action) {
48 self.no_action_binding_indices.push(self.bindings.len());
49 } else {
50 self.binding_indices_by_action_id
51 .entry(action_id)
52 .or_default()
53 .push(self.bindings.len());
54 }
55 self.bindings.push(binding);
56 }
57
58 self.version.0 += 1;
59 }
60
61 /// Reset this keymap to its initial state.
62 pub fn clear(&mut self) {
63 self.bindings.clear();
64 self.binding_indices_by_action_id.clear();
65 self.no_action_binding_indices.clear();
66 self.version.0 += 1;
67 }
68
69 /// Iterate over all bindings, in the order they were added.
70 pub fn bindings(&self) -> impl DoubleEndedIterator<Item = &KeyBinding> + ExactSizeIterator {
71 self.bindings.iter()
72 }
73
74 /// Iterate over all bindings for the given action, in the order they were added. For display,
75 /// the last binding should take precedence.
76 pub fn bindings_for_action<'a>(
77 &'a self,
78 action: &'a dyn Action,
79 ) -> impl 'a + DoubleEndedIterator<Item = &'a KeyBinding> {
80 self.bindings_for_action_with_indices(action)
81 .map(|(_, binding)| binding)
82 }
83
84 /// Like `bindings_for_action_with_indices`, but also returns the binding indices.
85 pub fn bindings_for_action_with_indices<'a>(
86 &'a self,
87 action: &'a dyn Action,
88 ) -> impl 'a + DoubleEndedIterator<Item = (BindingIndex, &'a KeyBinding)> {
89 let action_id = action.type_id();
90 let binding_indices = self
91 .binding_indices_by_action_id
92 .get(&action_id)
93 .map_or(&[] as _, SmallVec::as_slice)
94 .iter();
95
96 binding_indices.filter_map(|ix| {
97 let binding = &self.bindings[*ix];
98 if !binding.action().partial_eq(action) {
99 return None;
100 }
101
102 for null_ix in &self.no_action_binding_indices {
103 if null_ix > ix {
104 let null_binding = &self.bindings[*null_ix];
105 if null_binding.keystrokes == binding.keystrokes {
106 let null_binding_matches =
107 match (&null_binding.context_predicate, &binding.context_predicate) {
108 (None, _) => true,
109 (Some(_), None) => false,
110 (Some(null_predicate), Some(predicate)) => {
111 null_predicate.is_superset(predicate)
112 }
113 };
114 if null_binding_matches {
115 return None;
116 }
117 }
118 }
119 }
120
121 Some((BindingIndex(*ix), binding))
122 })
123 }
124
125 /// Returns all bindings that might match the input without checking context. The bindings
126 /// returned in precedence order (reverse of the order they were added to the keymap).
127 pub fn all_bindings_for_input(&self, input: &[Keystroke]) -> Vec<KeyBinding> {
128 self.bindings()
129 .rev()
130 .filter_map(|binding| {
131 binding.match_keystrokes(input).filter(|pending| !pending)?;
132 Some(binding.clone())
133 })
134 .collect()
135 }
136
137 /// Returns a list of bindings that match the given input, and a boolean indicating whether or
138 /// not more bindings might match if the input was longer. Bindings are returned in precedence
139 /// order (higher precedence first, reverse of the order they were added to the keymap).
140 ///
141 /// Precedence is defined by the depth in the tree (matches on the Editor take precedence over
142 /// matches on the Pane, then the Workspace, etc.). Bindings with no context are treated as the
143 /// same as the deepest context.
144 ///
145 /// In the case of multiple bindings at the same depth, the ones added to the keymap later take
146 /// precedence. User bindings are added after built-in bindings so that they take precedence.
147 ///
148 /// If a user has disabled a binding with `"x": null` it will not be returned. Disabled bindings
149 /// are evaluated with the same precedence rules so you can disable a rule in a given context
150 /// only.
151 pub fn bindings_for_input(
152 &self,
153 input: &[Keystroke],
154 context_stack: &[KeyContext],
155 ) -> (SmallVec<[KeyBinding; 1]>, bool) {
156 let (bindings, pending) = self.bindings_for_input_with_indices(input, context_stack);
157 let bindings = bindings
158 .into_iter()
159 .map(|(_, binding)| binding)
160 .collect::<SmallVec<[KeyBinding; 1]>>();
161 (bindings, pending)
162 }
163
164 /// Like `bindings_for_input`, but also returns the binding indices.
165 pub fn bindings_for_input_with_indices(
166 &self,
167 input: &[Keystroke],
168 context_stack: &[KeyContext],
169 ) -> (SmallVec<[(BindingIndex, KeyBinding); 1]>, bool) {
170 let possibilities = self
171 .bindings()
172 .enumerate()
173 .rev()
174 .filter_map(|(ix, binding)| {
175 binding
176 .match_keystrokes(input)
177 .map(|pending| (BindingIndex(ix), binding, pending))
178 });
179
180 self.bindings_for_keystrokes_with_indices_inner(possibilities, context_stack)
181 }
182
183 /// TODO:
184 pub fn bindings_for_keybinding_keystroke_with_indices(
185 &self,
186 input: &[KeybindingKeystroke],
187 context_stack: &[KeyContext],
188 ) -> (SmallVec<[(BindingIndex, KeyBinding); 1]>, bool) {
189 let possibilities = self
190 .bindings()
191 .enumerate()
192 .rev()
193 .filter_map(|(ix, binding)| {
194 binding
195 .match_keybinding_keystrokes(input)
196 .map(|pending| (BindingIndex(ix), binding, pending))
197 });
198
199 self.bindings_for_keystrokes_with_indices_inner(possibilities, context_stack)
200 }
201
202 fn bindings_for_keystrokes_with_indices_inner<'a>(
203 &'a self,
204 possibilities: impl Iterator<Item = (BindingIndex, &'a KeyBinding, bool)>,
205 context_stack: &[KeyContext],
206 ) -> (SmallVec<[(BindingIndex, KeyBinding); 1]>, bool) {
207 let mut bindings: SmallVec<[(BindingIndex, KeyBinding, usize); 1]> = SmallVec::new();
208
209 // (pending, is_no_action, depth, keystrokes)
210 let mut pending_info_opt: Option<(bool, bool, usize, &[KeybindingKeystroke])> = None;
211
212 'outer: for (binding_index, binding, pending) in possibilities {
213 for depth in (0..=context_stack.len()).rev() {
214 if self.binding_enabled(binding, &context_stack[0..depth]) {
215 let is_no_action = is_no_action(&*binding.action);
216 // We only want to consider a binding pending if it has an action
217 // This, however, means that if we have both a NoAction binding and a binding
218 // with an action at the same depth, we should still set is_pending to true.
219 if let Some(pending_info) = pending_info_opt.as_mut() {
220 let (
221 already_pending,
222 pending_is_no_action,
223 pending_depth,
224 pending_keystrokes,
225 ) = *pending_info;
226
227 // We only want to change the pending status if it's not already pending AND if
228 // the existing pending status was set by a NoAction binding. This avoids a NoAction
229 // binding erroneously setting the pending status to true when a binding with an action
230 // already set it to false
231 //
232 // We also want to change the pending status if the keystrokes don't match,
233 // meaning it's different keystrokes than the NoAction that set pending to false
234 if pending
235 && !already_pending
236 && pending_is_no_action
237 && (pending_depth == depth
238 || pending_keystrokes != binding.keystrokes())
239 {
240 pending_info.0 = !is_no_action;
241 }
242 } else {
243 pending_info_opt = Some((
244 pending && !is_no_action,
245 is_no_action,
246 depth,
247 binding.keystrokes(),
248 ));
249 }
250
251 if !pending {
252 bindings.push((binding_index, binding.clone(), depth));
253 continue 'outer;
254 }
255 }
256 }
257 }
258 // sort by descending depth
259 bindings.sort_by(|a, b| a.2.cmp(&b.2).reverse());
260 let bindings = bindings
261 .into_iter()
262 .map_while(|(binding_index, binding, _)| {
263 if is_no_action(&*binding.action) {
264 None
265 } else {
266 Some((binding_index, binding))
267 }
268 })
269 .collect();
270
271 (bindings, pending_info_opt.unwrap_or_default().0)
272 }
273
274 /// Check if the given binding is enabled, given a certain key context.
275 fn binding_enabled(&self, binding: &KeyBinding, context: &[KeyContext]) -> bool {
276 // If binding has a context predicate, it must match the current context,
277 if let Some(predicate) = &binding.context_predicate {
278 if !predicate.eval(context) {
279 return false;
280 }
281 }
282
283 true
284 }
285}
286
287#[cfg(test)]
288mod tests {
289 use super::*;
290 use crate as gpui;
291 use gpui::NoAction;
292
293 actions!(
294 test_only,
295 [ActionAlpha, ActionBeta, ActionGamma, ActionDelta,]
296 );
297
298 #[test]
299 fn test_keymap() {
300 let bindings = [
301 KeyBinding::new("ctrl-a", ActionAlpha {}, None),
302 KeyBinding::new("ctrl-a", ActionBeta {}, Some("pane")),
303 KeyBinding::new("ctrl-a", ActionGamma {}, Some("editor && mode==full")),
304 ];
305
306 let mut keymap = Keymap::default();
307 keymap.add_bindings(bindings.clone());
308
309 // global bindings are enabled in all contexts
310 assert!(keymap.binding_enabled(&bindings[0], &[]));
311 assert!(keymap.binding_enabled(&bindings[0], &[KeyContext::parse("terminal").unwrap()]));
312
313 // contextual bindings are enabled in contexts that match their predicate
314 assert!(!keymap.binding_enabled(&bindings[1], &[KeyContext::parse("barf x=y").unwrap()]));
315 assert!(keymap.binding_enabled(&bindings[1], &[KeyContext::parse("pane x=y").unwrap()]));
316
317 assert!(!keymap.binding_enabled(&bindings[2], &[KeyContext::parse("editor").unwrap()]));
318 assert!(keymap.binding_enabled(
319 &bindings[2],
320 &[KeyContext::parse("editor mode=full").unwrap()]
321 ));
322 }
323
324 #[test]
325 fn test_keymap_disabled() {
326 let bindings = [
327 KeyBinding::new("ctrl-a", ActionAlpha {}, Some("editor")),
328 KeyBinding::new("ctrl-b", ActionAlpha {}, Some("editor")),
329 KeyBinding::new("ctrl-a", NoAction {}, Some("editor && mode==full")),
330 KeyBinding::new("ctrl-b", NoAction {}, None),
331 ];
332
333 let mut keymap = Keymap::default();
334 keymap.add_bindings(bindings.clone());
335
336 // binding is only enabled in a specific context
337 assert!(
338 keymap
339 .bindings_for_input(
340 &[Keystroke::parse("ctrl-a").unwrap()],
341 &[KeyContext::parse("barf").unwrap()],
342 )
343 .0
344 .is_empty()
345 );
346 assert!(
347 !keymap
348 .bindings_for_input(
349 &[Keystroke::parse("ctrl-a").unwrap()],
350 &[KeyContext::parse("editor").unwrap()],
351 )
352 .0
353 .is_empty()
354 );
355
356 // binding is disabled in a more specific context
357 assert!(
358 keymap
359 .bindings_for_input(
360 &[Keystroke::parse("ctrl-a").unwrap()],
361 &[KeyContext::parse("editor mode=full").unwrap()],
362 )
363 .0
364 .is_empty()
365 );
366
367 // binding is globally disabled
368 assert!(
369 keymap
370 .bindings_for_input(
371 &[Keystroke::parse("ctrl-b").unwrap()],
372 &[KeyContext::parse("barf").unwrap()],
373 )
374 .0
375 .is_empty()
376 );
377 }
378
379 #[test]
380 /// Tests for https://github.com/zed-industries/zed/issues/30259
381 fn test_multiple_keystroke_binding_disabled() {
382 let bindings = [
383 KeyBinding::new("space w w", ActionAlpha {}, Some("workspace")),
384 KeyBinding::new("space w w", NoAction {}, Some("editor")),
385 ];
386
387 let mut keymap = Keymap::default();
388 keymap.add_bindings(bindings.clone());
389
390 let space = || Keystroke::parse("space").unwrap();
391 let w = || Keystroke::parse("w").unwrap();
392
393 let space_w = [space(), w()];
394 let space_w_w = [space(), w(), w()];
395
396 let workspace_context = || [KeyContext::parse("workspace").unwrap()];
397
398 let editor_workspace_context = || {
399 [
400 KeyContext::parse("workspace").unwrap(),
401 KeyContext::parse("editor").unwrap(),
402 ]
403 };
404
405 // Ensure `space` results in pending input on the workspace, but not editor
406 let space_workspace = keymap.bindings_for_input(&[space()], &workspace_context());
407 assert!(space_workspace.0.is_empty());
408 assert_eq!(space_workspace.1, true);
409
410 let space_editor = keymap.bindings_for_input(&[space()], &editor_workspace_context());
411 assert!(space_editor.0.is_empty());
412 assert_eq!(space_editor.1, false);
413
414 // Ensure `space w` results in pending input on the workspace, but not editor
415 let space_w_workspace = keymap.bindings_for_input(&space_w, &workspace_context());
416 assert!(space_w_workspace.0.is_empty());
417 assert_eq!(space_w_workspace.1, true);
418
419 let space_w_editor = keymap.bindings_for_input(&space_w, &editor_workspace_context());
420 assert!(space_w_editor.0.is_empty());
421 assert_eq!(space_w_editor.1, false);
422
423 // Ensure `space w w` results in the binding in the workspace, but not in the editor
424 let space_w_w_workspace = keymap.bindings_for_input(&space_w_w, &workspace_context());
425 assert!(!space_w_w_workspace.0.is_empty());
426 assert_eq!(space_w_w_workspace.1, false);
427
428 let space_w_w_editor = keymap.bindings_for_input(&space_w_w, &editor_workspace_context());
429 assert!(space_w_w_editor.0.is_empty());
430 assert_eq!(space_w_w_editor.1, false);
431
432 // Now test what happens if we have another binding defined AFTER the NoAction
433 // that should result in pending
434 let bindings = [
435 KeyBinding::new("space w w", ActionAlpha {}, Some("workspace")),
436 KeyBinding::new("space w w", NoAction {}, Some("editor")),
437 KeyBinding::new("space w x", ActionAlpha {}, Some("editor")),
438 ];
439 let mut keymap = Keymap::default();
440 keymap.add_bindings(bindings.clone());
441
442 let space_editor = keymap.bindings_for_input(&[space()], &editor_workspace_context());
443 assert!(space_editor.0.is_empty());
444 assert_eq!(space_editor.1, true);
445
446 // Now test what happens if we have another binding defined BEFORE the NoAction
447 // that should result in pending
448 let bindings = [
449 KeyBinding::new("space w w", ActionAlpha {}, Some("workspace")),
450 KeyBinding::new("space w x", ActionAlpha {}, Some("editor")),
451 KeyBinding::new("space w w", NoAction {}, Some("editor")),
452 ];
453 let mut keymap = Keymap::default();
454 keymap.add_bindings(bindings.clone());
455
456 let space_editor = keymap.bindings_for_input(&[space()], &editor_workspace_context());
457 assert!(space_editor.0.is_empty());
458 assert_eq!(space_editor.1, true);
459
460 // Now test what happens if we have another binding defined at a higher context
461 // that should result in pending
462 let bindings = [
463 KeyBinding::new("space w w", ActionAlpha {}, Some("workspace")),
464 KeyBinding::new("space w x", ActionAlpha {}, Some("workspace")),
465 KeyBinding::new("space w w", NoAction {}, Some("editor")),
466 ];
467 let mut keymap = Keymap::default();
468 keymap.add_bindings(bindings.clone());
469
470 let space_editor = keymap.bindings_for_input(&[space()], &editor_workspace_context());
471 assert!(space_editor.0.is_empty());
472 assert_eq!(space_editor.1, true);
473 }
474
475 #[test]
476 fn test_bindings_for_action() {
477 let bindings = [
478 KeyBinding::new("ctrl-a", ActionAlpha {}, Some("pane")),
479 KeyBinding::new("ctrl-b", ActionBeta {}, Some("editor && mode == full")),
480 KeyBinding::new("ctrl-c", ActionGamma {}, Some("workspace")),
481 KeyBinding::new("ctrl-a", NoAction {}, Some("pane && active")),
482 KeyBinding::new("ctrl-b", NoAction {}, Some("editor")),
483 ];
484
485 let mut keymap = Keymap::default();
486 keymap.add_bindings(bindings.clone());
487
488 assert_bindings(&keymap, &ActionAlpha {}, &["ctrl-a"]);
489 assert_bindings(&keymap, &ActionBeta {}, &[]);
490 assert_bindings(&keymap, &ActionGamma {}, &["ctrl-c"]);
491
492 #[track_caller]
493 fn assert_bindings(keymap: &Keymap, action: &dyn Action, expected: &[&str]) {
494 let actual = keymap
495 .bindings_for_action(action)
496 .map(|binding| binding.keystrokes[0].unparse())
497 .collect::<Vec<_>>();
498 assert_eq!(actual, expected, "{:?}", action);
499 }
500 }
501}