0
# Keybindings
1

2
Theia's keybinding system provides comprehensive key combination handling with context awareness, command integration, and platform-specific key mapping for accessible applications.
3

4
## Capabilities
5

6
### Keybinding Definition
7

8
Define key combinations that trigger commands.
9

10
```typescript { .api }
11
/**
12
 * Keybinding definition
13
 */
14
interface Keybinding {
15
    /** Key combination string (e.g., 'ctrl+s', 'cmd+shift+p') */
16
    keybinding: string;
17
    
18
    /** Command to execute */
19
    command: string;
20
    
21
    /** Optional context expression */
22
    context?: string;
23
    
24
    /** Optional arguments to pass to command */
25
    args?: any[];
26
    
27
    /** When clause for conditional activation */
28
    when?: string;
29
}
30
```
31

32
### Keybinding Registry
33

34
Central registry for managing keybindings and key event handling.
35

36
```typescript { .api }
37
/**
38
 * Registry for keybindings
39
 */
40
interface KeybindingRegistry {
41
    /**
42
     * Register a keybinding
43
     * @param binding - Keybinding definition
44
     * @returns Disposable to unregister
45
     */
46
    registerKeybinding(binding: Keybinding): Disposable;
47
    
48
    /**
49
     * Get keybindings for command
50
     * @param commandId - Command identifier
51
     * @returns Array of keybindings
52
     */
53
    getKeybindingsForCommand(commandId: string): Keybinding[];
54
    
55
    /**
56
     * Get all keybindings
57
     * @returns Array of all registered keybindings
58
     */
59
    getKeybindings(): Keybinding[];
60
    
61
    /**
62
     * Handle key event
63
     * @param event - Keyboard event
64
     * @returns True if event was handled
65
     */
66
    run(event: KeyboardEvent): boolean;
67
}
68

69
/**
70
 * Service token for KeybindingRegistry  
71
 */
72
const KeybindingRegistry: symbol;
73
```
74

75
**Usage Example:**
76

77
```typescript
78
import { inject, injectable } from "@theia/core";
79
import { KeybindingRegistry, Keybinding } from "@theia/core/lib/browser";
80

81
@injectable()
82
export class MyKeybindingContribution {
83
    constructor(
84
        @inject(KeybindingRegistry) 
85
        private readonly keybindings: KeybindingRegistry
86
    ) {}
87
    
88
    registerKeybindings(): void {
89
        // Simple keybinding
90
        this.keybindings.registerKeybinding({
91
            keybinding: 'ctrl+alt+t',
92
            command: 'my-extension.toggle-feature'
93
        });
94
        
95
        // Context-aware keybinding
96
        this.keybindings.registerKeybinding({
97
            keybinding: 'f2',
98
            command: 'my-extension.rename',
99
            when: 'editorFocus && !readonly'
100
        });
101
        
102
        // Keybinding with arguments
103
        this.keybindings.registerKeybinding({
104
            keybinding: 'ctrl+1',
105
            command: 'workbench.action.openEditorAtIndex',
106
            args: [0]
107
        });
108
    }
109
}
110
```
111

112
### Keybinding Contribution
113

114
Extension point for contributing keybindings.
115

116
```typescript { .api }
117
/**
118
 * Contribution interface for keybindings
119
 */
120
interface KeybindingContribution {
121
    /**
122
     * Register keybindings
123
     * @param keybindings - Keybinding registry
124
     */
125
    registerKeybindings(keybindings: KeybindingRegistry): void;
126
}
127

128
/**
129
 * Service token for KeybindingContribution
130
 */
131
const KeybindingContribution: symbol;
132
```
133

134
### Key Sequences
135

136
Advanced key sequence and chord support.
137

138
```typescript { .api }
139
/**
140
 * Key sequence for multi-key combinations
141
 */
142
interface KeySequence {
143
    /** Array of key combinations */
144
    sequence: string[];
145
    
146
    /** Command to execute */
147
    command: string;
148
    
149
    /** Optional context */
150
    context?: string;
151
}
152

153
/**
154
 * Chord keybinding (multi-step key sequence)
155
 */
156
interface ChordKeybinding extends Keybinding {
157
    /** First key combination */
158
    firstPart: string;
159
    
160
    /** Second key combination */
161
    chordPart: string;
162
}
163
```
164

165
## Types
166

167
```typescript { .api }
168
type KeyCode = string;
169
type KeyModifier = 'ctrl' | 'cmd' | 'alt' | 'shift' | 'meta';
170

171
interface KeybindingContext {
172
    [key: string]: any;
173
}
174
```