| Flutter macOS Embedder |

FlutterEmbedderKeyResponder.mm
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4
5 #import <objc/message.h>
6 #include <memory>
7
8 #import "FlutterEmbedderKeyResponder.h"
9 #import "KeyCodeMap_Internal.h"
10 #import "flutter/shell/platform/darwin/common/framework/Headers/FlutterCodecs.h"
11 #import "flutter/shell/platform/darwin/macos/framework/Source/FlutterViewController_Internal.h"
12 #import "flutter/shell/platform/embedder/embedder.h"
13
14 namespace {
15
16 /**
17 * Isolate the least significant 1-bit.
18 *
19 * For example,
20 *
21 * * lowestSetBit(0x1010) returns 0x10.
22 * * lowestSetBit(0) returns 0.
23 */
24 static NSUInteger lowestSetBit(NSUInteger bitmask) {
25 // This utilizes property of two's complement (negation), which propagates a
26 // carry bit from LSB to the lowest set bit.
27 return bitmask & -bitmask;
28 }
29
30 /**
31 * Whether a string represents a control character.
32 */
33 static bool IsControlCharacter(uint64_t character) {
34 return (character <= 0x1f && character >= 0x00) || (character >= 0x7f && character <= 0x9f);
35 }
36
37 /**
38 * Whether a string represents an unprintable key.
39 */
40 static bool IsUnprintableKey(uint64_t character) {
41 return character >= 0xF700 && character <= 0xF8FF;
42 }
43
44 /**
45 * Returns a key code composed with a base key and a plane.
46 *
47 * Examples of unprintable keys are "NSUpArrowFunctionKey = 0xF700" or
48 * "NSHomeFunctionKey = 0xF729".
49 *
50 * See
51 * https://developer.apple.com/documentation/appkit/1535851-function-key_unicodes?language=objc
52 * for more information.
53 */
54 static uint64_t KeyOfPlane(uint64_t baseKey, uint64_t plane) {
55 return plane | (baseKey & flutter::kValueMask);
56 }
57
58 /**
59 * Returns the physical key for a key code.
60 */
61 static uint64_t GetPhysicalKeyForKeyCode(unsigned short keyCode) {
62 NSNumber* physicalKey = [flutter::keyCodeToPhysicalKey objectForKey:@(keyCode)];
63 if (physicalKey == nil) {
64 return KeyOfPlane(keyCode, flutter::kMacosPlane);
65 }
66 return physicalKey.unsignedLongLongValue;
67 }
68
69 /**
70 * Returns the logical key for a modifier physical key.
71 */
72 static uint64_t GetLogicalKeyForModifier(unsigned short keyCode, uint64_t hidCode) {
73 NSNumber* fromKeyCode = [flutter::keyCodeToLogicalKey objectForKey:@(keyCode)];
74 if (fromKeyCode != nil) {
75 return fromKeyCode.unsignedLongLongValue;
76 }
77 return KeyOfPlane(hidCode, flutter::kMacosPlane);
78 }
79
80 /**
81 * Converts upper letters to lower letters in ASCII, and returns as-is
82 * otherwise.
83 *
84 * Independent of locale.
85 */
86 static uint64_t toLower(uint64_t n) {
87 constexpr uint64_t lowerA = 0x61;
88 constexpr uint64_t upperA = 0x41;
89 constexpr uint64_t upperZ = 0x5a;
90
91 constexpr uint64_t lowerAGrave = 0xe0;
92 constexpr uint64_t upperAGrave = 0xc0;
93 constexpr uint64_t upperThorn = 0xde;
94 constexpr uint64_t division = 0xf7;
95
96 // ASCII range.
97 if (n >= upperA && n <= upperZ) {
98 return n - upperA + lowerA;
99 }
100
101 // EASCII range.
102 if (n >= upperAGrave && n <= upperThorn && n != division) {
103 return n - upperAGrave + lowerAGrave;
104 }
105
106 return n;
107 }
108
109 // Decode a UTF-16 sequence to an array of char32 (UTF-32).
110 //
111 // See https://en.wikipedia.org/wiki/UTF-16#Description for the algorithm.
112 //
113 // The returned character array must be deallocated with delete[]. The length of
114 // the result is stored in `out_length`.
115 //
116 // Although NSString has a dataUsingEncoding method, we implement our own
117 // because dataUsingEncoding outputs redundant characters for unknown reasons.
118 static uint32_t* DecodeUtf16(NSString* target, size_t* out_length) {
119 // The result always has a length less or equal to target.
120 size_t result_pos = 0;
121 uint32_t* result = new uint32_t[target.length];
122 uint16_t high_surrogate = 0;
123 for (NSUInteger target_pos = 0; target_pos < target.length; target_pos += 1) {
124 uint16_t codeUnit = [target characterAtIndex:target_pos];
125 // BMP
126 if (codeUnit <= 0xD7FF || codeUnit >= 0xE000) {
127 result[result_pos] = codeUnit;
128 result_pos += 1;
129 // High surrogates
130 } else if (codeUnit <= 0xDBFF) {
131 high_surrogate = codeUnit - 0xD800;
132 // Low surrogates
133 } else {
134 uint16_t low_surrogate = codeUnit - 0xDC00;
135 result[result_pos] = (high_surrogate << 10) + low_surrogate + 0x10000;
136 result_pos += 1;
137 }
138 }
139 *out_length = result_pos;
140 return result;
141 }
142
143 /**
144 * Returns the logical key of a KeyUp or KeyDown event.
145 *
146 * For FlagsChanged event, use GetLogicalKeyForModifier.
147 */
148 static uint64_t GetLogicalKeyForEvent(NSEvent* event, uint64_t physicalKey) {
149 // Look to see if the keyCode can be mapped from keycode.
150 NSNumber* fromKeyCode = [flutter::keyCodeToLogicalKey objectForKey:@(event.keyCode)];
151 if (fromKeyCode != nil) {
152 return fromKeyCode.unsignedLongLongValue;
153 }
154
155 // Convert `charactersIgnoringModifiers` to UTF32.
156 NSString* keyLabelUtf16 = event.charactersIgnoringModifiers;
157
158 // Check if this key is a single character, which will be used to generate the
159 // logical key from its Unicode value.
160 //
161 // Multi-char keys will be minted onto the macOS plane because there are no
162 // meaningful values for them. Control keys and unprintable keys have been
163 // converted by `keyCodeToLogicalKey` earlier.
164 uint32_t character = 0;
165 if (keyLabelUtf16.length != 0) {
166 size_t keyLabelLength;
167 uint32_t* keyLabel = DecodeUtf16(keyLabelUtf16, &keyLabelLength);
168 if (keyLabelLength == 1) {
169 uint32_t keyLabelChar = *keyLabel;
170 FML_DCHECK(!IsControlCharacter(keyLabelChar) && !IsUnprintableKey(keyLabelChar))
171 << "Unexpected control or unprintable keylabel 0x" << std::hex << keyLabelChar;
172 FML_DCHECK(keyLabelChar <= 0x10FFFF)
173 << "Out of range keylabel 0x" << std::hex << keyLabelChar;
174 character = keyLabelChar;
175 }
176 delete[] keyLabel;
177 }
178 if (character != 0) {
179 return KeyOfPlane(toLower(character), flutter::kUnicodePlane);
180 }
181
182 // We can't represent this key with a single printable unicode, so a new code
183 // is minted to the macOS plane.
184 return KeyOfPlane(event.keyCode, flutter::kMacosPlane);
185 }
186
187 /**
188 * Converts NSEvent.timestamp to the timestamp for Flutter.
189 */
190 static double GetFlutterTimestampFrom(NSTimeInterval timestamp) {
191 // Timestamp in microseconds. The event.timestamp is in seconds with sub-ms precision.
192 return timestamp * 1000000.0;
193 }
194
195 /**
196 * Compute |modifierFlagOfInterestMask| out of |keyCodeToModifierFlag|.
197 *
198 * This is equal to the bitwise-or of all values of |keyCodeToModifierFlag| as
199 * well as NSEventModifierFlagCapsLock.
200 */
201 static NSUInteger computeModifierFlagOfInterestMask() {
202 __block NSUInteger modifierFlagOfInterestMask = NSEventModifierFlagCapsLock;
203 [flutter::keyCodeToModifierFlag
204 enumerateKeysAndObjectsUsingBlock:^(NSNumber* keyCode, NSNumber* flag, BOOL* stop) {
205 modifierFlagOfInterestMask = modifierFlagOfInterestMask | [flag unsignedLongValue];
206 }];
207 return modifierFlagOfInterestMask;
208 }
209
210 /**
211 * The C-function sent to the embedder's |SendKeyEvent|, wrapping
212 * |FlutterEmbedderKeyResponder.handleResponse|.
213 *
214 * For the reason of this wrap, see |FlutterKeyPendingResponse|.
215 */
216 void HandleResponse(bool handled, void* user_data);
217
218 /**
219 * Converts NSEvent.characters to a C-string for FlutterKeyEvent.
220 */
221 const char* getEventString(NSString* characters) {
222 if ([characters length] == 0) {
223 return nullptr;
224 }
225 unichar utf16Code = [characters characterAtIndex:0];
226 if (utf16Code >= 0xf700 && utf16Code <= 0xf7ff) {
227 // Some function keys are assigned characters with codepoints from the
228 // private use area. These characters are filtered out since they're
229 // unprintable.
230 //
231 // The official documentation reserves 0xF700-0xF8FF as private use area
232 // (https://developer.apple.com/documentation/appkit/1535851-function-key_unicodes?language=objc).
233 // But macOS seems to only use a reduced range of it. The official doc
234 // defines a few constants, all of which are within 0xF700-0xF747.
235 // (https://developer.apple.com/documentation/appkit/1535851-function-key_unicodes?language=objc).
236 // This mostly aligns with the experimentation result, except for 0xF8FF,
237 // which is used for the "Apple logo" character (Option-Shift-K on a US
238 // keyboard.)
239 //
240 // Assume that non-printable function keys are defined from
241 // 0xF700 upwards, and printable private keys are defined from 0xF8FF
242 // downwards. This function filters out 0xF700-0xF7FF in order to keep
243 // the printable private keys.
244 return nullptr;
245 }
246 return [characters UTF8String];
247 }
248 } // namespace
249
250 /**
251 * The invocation context for |HandleResponse|, wrapping
252 * |FlutterEmbedderKeyResponder.handleResponse|.
253 */
254 struct FlutterKeyPendingResponse {
255 FlutterEmbedderKeyResponder* responder;
256 uint64_t responseId;
257 };
258
259 /**
260 * Guards a |FlutterAsyncKeyCallback| to make sure it's handled exactly once
261 * throughout |FlutterEmbedderKeyResponder.handleEvent|.
262 *
263 * A callback can either be handled with |pendTo:withId:|, or with |resolveTo:|.
264 * Either way, the callback cannot be handled again, or an assertion will be
265 * thrown.
266 */
267 @interface FlutterKeyCallbackGuard : NSObject
268 - (nonnull instancetype)initWithCallback:(FlutterAsyncKeyCallback)callback;
269
270 /**
271 * Handle the callback by storing it to pending responses.
272 */
273 - (void)pendTo:(nonnull NSMutableDictionary<NSNumber*, FlutterAsyncKeyCallback>*)pendingResponses
274 withId:(uint64_t)responseId;
275
276 /**
277 * Handle the callback by calling it with a result.
278 */
279 - (void)resolveTo:(BOOL)handled;
280
281 @property(nonatomic) BOOL handled;
282 @property(nonatomic) BOOL sentAnyEvents;
283 /**
284 * A string indicating how the callback is handled.
285 *
286 * Only set in debug mode. Nil in release mode, or if the callback has not been
287 * handled.
288 */
289 @property(nonatomic, copy) NSString* debugHandleSource;
290 @end
291
292 @implementation FlutterKeyCallbackGuard {
293 // The callback is declared in the implemnetation block to avoid being
294 // accessed directly.
295 FlutterAsyncKeyCallback _callback;
296 }
297 - (nonnull instancetype)initWithCallback:(FlutterAsyncKeyCallback)callback {
298 self = [super init];
299 if (self != nil) {
300 _callback = callback;
301 _handled = FALSE;
302 _sentAnyEvents = FALSE;
303 }
304 return self;
305 }
306
307 - (void)pendTo:(nonnull NSMutableDictionary<NSNumber*, FlutterAsyncKeyCallback>*)pendingResponses
308 withId:(uint64_t)responseId {
309 NSAssert(!_handled, @"This callback has been handled by %@.", _debugHandleSource);
310 if (_handled) {
311 return;
312 }
313 pendingResponses[@(responseId)] = _callback;
314 _handled = TRUE;
315 NSAssert(
316 ((_debugHandleSource = [NSString stringWithFormat:@"pending event %llu", responseId]), TRUE),
317 @"");
318 }
319
320 - (void)resolveTo:(BOOL)handled {
321 NSAssert(!_handled, @"This callback has been handled by %@.", _debugHandleSource);
322 if (_handled) {
323 return;
324 }
325 _callback(handled);
326 _handled = TRUE;
327 NSAssert(((_debugHandleSource = [NSString stringWithFormat:@"resolved with %d", _handled]), TRUE),
328 @"");
329 }
330 @end
331
332 @interface FlutterEmbedderKeyResponder ()
333
334 /**
335 * The function to send converted events to.
336 *
337 * Set by the initializer.
338 */
339 @property(nonatomic, copy) FlutterSendEmbedderKeyEvent sendEvent;
340
341 /**
342 * A map of presessd keys.
343 *
344 * The keys of the dictionary are physical keys, while the values are the logical keys
345 * of the key down event.
346 */
347 @property(nonatomic) NSMutableDictionary<NSNumber*, NSNumber*>* pressingRecords;
348
349 /**
350 * A constant mask for NSEvent.modifierFlags that Flutter synchronizes with.
351 *
352 * Flutter keeps track of the last |modifierFlags| and compares it with the
353 * incoming one. Any bit within |modifierFlagOfInterestMask| that is different
354 * (except for the one that corresponds to the event key) indicates that an
355 * event for this modifier was missed, and Flutter synthesizes an event to make
356 * up for the state difference.
357 *
358 * It is computed by computeModifierFlagOfInterestMask.
359 */
360 @property(nonatomic) NSUInteger modifierFlagOfInterestMask;
361
362 /**
363 * The modifier flags of the last received key event, excluding uninterested
364 * bits.
365 *
366 * This should be kept synchronized with the last |NSEvent.modifierFlags|
367 * after masking with |modifierFlagOfInterestMask|. This should also be kept
368 * synchronized with the corresponding keys of |pressingRecords|.
369 *
370 * This is used by |synchronizeModifiers| to quickly find
371 * out modifier keys that are desynchronized.
372 */
373 @property(nonatomic) NSUInteger lastModifierFlagsOfInterest;
374
375 /**
376 * A self-incrementing ID used to label key events sent to the framework.
377 */
378 @property(nonatomic) uint64_t responseId;
379
380 /**
381 * A map of unresponded key events sent to the framework.
382 *
383 * Its values are |responseId|s, and keys are the callback that was received
384 * along with the event.
385 */
386 @property(nonatomic) NSMutableDictionary<NSNumber*, FlutterAsyncKeyCallback>* pendingResponses;
387
388 /**
389 * Compare the last modifier flags and the current, and dispatch synthesized
390 * key events for each different modifier flag bit.
391 *
392 * The flags compared are all flags after masking with
393 * |modifierFlagOfInterestMask| and excluding |ignoringFlags|.
394 *
395 * The |guard| is basically a regular guarded callback, but instead of being
396 * called, it is only used to record whether an event is sent.
397 */
398 - (void)synchronizeModifiers:(NSUInteger)currentFlags
399 ignoringFlags:(NSUInteger)ignoringFlags
400 timestamp:(NSTimeInterval)timestamp
401 guard:(nonnull FlutterKeyCallbackGuard*)guard;
402
403 /**
404 * Update the pressing state.
405 *
406 * If `logicalKey` is not 0, `physicalKey` is pressed as `logicalKey`.
407 * Otherwise, `physicalKey` is released.
408 */
409 - (void)updateKey:(uint64_t)physicalKey asPressed:(uint64_t)logicalKey;
410
411 /**
412 * Send an event to the framework, expecting its response.
413 */
414 - (void)sendPrimaryFlutterEvent:(const FlutterKeyEvent&)event
415 callback:(nonnull FlutterKeyCallbackGuard*)callback;
416
417 /**
418 * Send a synthesized key event, never expecting its event result.
419 *
420 * The |guard| is basically a regular guarded callback, but instead of being
421 * called, it is only used to record whether an event is sent.
422 */
423 - (void)sendSynthesizedFlutterEvent:(const FlutterKeyEvent&)event
424 guard:(FlutterKeyCallbackGuard*)guard;
425
426 /**
427 * Send a CapsLock down event, then a CapsLock up event.
428 *
429 * If synthesizeDown is TRUE, then both events will be synthesized. Otherwise,
430 * the callback will be used as the callback for the down event, which is not
431 * synthesized, while the up event will always be synthesized.
432 */
433 - (void)sendCapsLockTapWithTimestamp:(NSTimeInterval)timestamp
434 synthesizeDown:(bool)synthesizeDown
435 callback:(nonnull FlutterKeyCallbackGuard*)callback;
436
437 /**
438 * Send a key event for a modifier key.
439 */
440 - (void)sendModifierEventOfType:(BOOL)isDownEvent
441 timestamp:(NSTimeInterval)timestamp
442 keyCode:(unsigned short)keyCode
443 synthesized:(bool)synthesized
444 callback:(nonnull FlutterKeyCallbackGuard*)callback;
445
446 /**
447 * Processes a down event from the system.
448 */
449 - (void)handleDownEvent:(nonnull NSEvent*)event callback:(nonnull FlutterKeyCallbackGuard*)callback;
450
451 /**
452 * Processes an up event from the system.
453 */
454 - (void)handleUpEvent:(nonnull NSEvent*)event callback:(nonnull FlutterKeyCallbackGuard*)callback;
455
456 /**
457 * Processes an event from the system for the CapsLock key.
458 */
459 - (void)handleCapsLockEvent:(nonnull NSEvent*)event
460 callback:(nonnull FlutterKeyCallbackGuard*)callback;
461
462 /**
463 * Processes a flags changed event from the system, where modifier keys are pressed or released.
464 */
465 - (void)handleFlagEvent:(nonnull NSEvent*)event callback:(nonnull FlutterKeyCallbackGuard*)callback;
466
467 /**
468 * Processes the response from the framework.
469 */
470 - (void)handleResponse:(BOOL)handled forId:(uint64_t)responseId;
471
472 @end
473
474 @implementation FlutterEmbedderKeyResponder
475
476 @synthesize layoutMap;
477
478 - (nonnull instancetype)initWithSendEvent:(FlutterSendEmbedderKeyEvent)sendEvent {
479 self = [super init];
480 if (self != nil) {
481 _sendEvent = sendEvent;
482 _pressingRecords = [NSMutableDictionary dictionary];
483 _pendingResponses = [NSMutableDictionary dictionary];
484 _responseId = 1;
485 _lastModifierFlagsOfInterest = 0;
486 _modifierFlagOfInterestMask = computeModifierFlagOfInterestMask();
487 }
488 return self;
489 }
490
491 - (void)handleEvent:(NSEvent*)event callback:(FlutterAsyncKeyCallback)callback {
492 // The conversion algorithm relies on a non-nil callback to properly compute
493 // `synthesized`.
494 NSAssert(callback != nil, @"The callback must not be nil.");
495 FlutterKeyCallbackGuard* guardedCallback =
496 [[FlutterKeyCallbackGuard alloc] initWithCallback:callback];
497 switch (event.type) {
498 case NSEventTypeKeyDown:
499 [self handleDownEvent:event callback:guardedCallback];
500 break;
501 case NSEventTypeKeyUp:
502 [self handleUpEvent:event callback:guardedCallback];
503 break;
504 case NSEventTypeFlagsChanged:
505 [self handleFlagEvent:event callback:guardedCallback];
506 break;
507 default:
508 NSAssert(false, @"Unexpected key event type: |%@|.", @(event.type));
509 }
510 NSAssert(guardedCallback.handled, @"The callback is returned without being handled.");
511 if (!guardedCallback.sentAnyEvents) {
512 FlutterKeyEvent flutterEvent = {
513 .struct_size = sizeof(FlutterKeyEvent),
514 .timestamp = 0,
515 .type = kFlutterKeyEventTypeDown,
516 .physical = 0,
517 .logical = 0,
518 .character = nil,
519 .synthesized = false,
520 };
521 _sendEvent(flutterEvent, nullptr, nullptr);
522 }
523 NSAssert(_lastModifierFlagsOfInterest == (event.modifierFlags & _modifierFlagOfInterestMask),
524 @"The modifier flags are not properly updated: recorded 0x%lx, event with mask 0x%lx",
525 _lastModifierFlagsOfInterest, event.modifierFlags & _modifierFlagOfInterestMask);
526 }
527
528 #pragma mark - Private
529
530 - (void)synchronizeModifiers:(NSUInteger)currentFlags
531 ignoringFlags:(NSUInteger)ignoringFlags
532 timestamp:(NSTimeInterval)timestamp
533 guard:(FlutterKeyCallbackGuard*)guard {
534 const NSUInteger updatingMask = _modifierFlagOfInterestMask & ~ignoringFlags;
535 const NSUInteger currentFlagsOfInterest = currentFlags & updatingMask;
536 const NSUInteger lastFlagsOfInterest = _lastModifierFlagsOfInterest & updatingMask;
537 NSUInteger flagDifference = currentFlagsOfInterest ^ lastFlagsOfInterest;
538 if (flagDifference & NSEventModifierFlagCapsLock) {
539 [self sendCapsLockTapWithTimestamp:timestamp synthesizeDown:true callback:guard];
540 flagDifference = flagDifference & ~NSEventModifierFlagCapsLock;
541 }
542 while (true) {
543 const NSUInteger currentFlag = lowestSetBit(flagDifference);
544 if (currentFlag == 0) {
545 break;
546 }
547 flagDifference = flagDifference & ~currentFlag;
548 NSNumber* keyCode = [flutter::modifierFlagToKeyCode objectForKey:@(currentFlag)];
549 NSAssert(keyCode != nil, @"Invalid modifier flag 0x%lx", currentFlag);
550 if (keyCode == nil) {
551 continue;
552 }
553 BOOL isDownEvent = (currentFlagsOfInterest & currentFlag) != 0;
554 [self sendModifierEventOfType:isDownEvent
555 timestamp:timestamp
556 keyCode:[keyCode unsignedShortValue]
557 synthesized:true
558 callback:guard];
559 }
560 _lastModifierFlagsOfInterest =
561 (_lastModifierFlagsOfInterest & ~updatingMask) | currentFlagsOfInterest;
562 }
563
564 - (void)updateKey:(uint64_t)physicalKey asPressed:(uint64_t)logicalKey {
565 if (logicalKey == 0) {
566 [_pressingRecords removeObjectForKey:@(physicalKey)];
567 } else {
568 _pressingRecords[@(physicalKey)] = @(logicalKey);
569 }
570 }
571
572 - (void)sendPrimaryFlutterEvent:(const FlutterKeyEvent&)event
573 callback:(FlutterKeyCallbackGuard*)callback {
574 _responseId += 1;
575 uint64_t responseId = _responseId;
576 // The `pending` is released in `HandleResponse`.
577 FlutterKeyPendingResponse* pending = new FlutterKeyPendingResponse{self, responseId};
578 [callback pendTo:_pendingResponses withId:responseId];
579 _sendEvent(event, HandleResponse, pending);
580 callback.sentAnyEvents = TRUE;
581 }
582
583 - (void)sendSynthesizedFlutterEvent:(const FlutterKeyEvent&)event
584 guard:(FlutterKeyCallbackGuard*)guard {
585 _sendEvent(event, nullptr, nullptr);
586 guard.sentAnyEvents = TRUE;
587 }
588
589 - (void)sendCapsLockTapWithTimestamp:(NSTimeInterval)timestamp
590 synthesizeDown:(bool)synthesizeDown
591 callback:(FlutterKeyCallbackGuard*)callback {
592 // MacOS sends a down *or* an up when CapsLock is tapped, alternatively on
593 // even taps and odd taps. A CapsLock down or CapsLock up should always be
594 // converted to a down *and* an up, and the up should always be a synthesized
595 // event, since the FlutterEmbedderKeyResponder will never know when the
596 // button is released.
597 FlutterKeyEvent flutterEvent = {
598 .struct_size = sizeof(FlutterKeyEvent),
599 .timestamp = GetFlutterTimestampFrom(timestamp),
600 .type = kFlutterKeyEventTypeDown,
601 .physical = flutter::kCapsLockPhysicalKey,
602 .logical = flutter::kCapsLockLogicalKey,
603 .character = nil,
604 .synthesized = synthesizeDown,
605 };
606 if (!synthesizeDown) {
607 [self sendPrimaryFlutterEvent:flutterEvent callback:callback];
608 } else {
609 [self sendSynthesizedFlutterEvent:flutterEvent guard:callback];
610 }
611
612 flutterEvent.type = kFlutterKeyEventTypeUp;
613 flutterEvent.synthesized = true;
614 [self sendSynthesizedFlutterEvent:flutterEvent guard:callback];
615 }
616
617 - (void)sendModifierEventOfType:(BOOL)isDownEvent
618 timestamp:(NSTimeInterval)timestamp
619 keyCode:(unsigned short)keyCode
620 synthesized:(bool)synthesized
621 callback:(FlutterKeyCallbackGuard*)callback {
622 uint64_t physicalKey = GetPhysicalKeyForKeyCode(keyCode);
623 uint64_t logicalKey = GetLogicalKeyForModifier(keyCode, physicalKey);
624 if (physicalKey == 0 || logicalKey == 0) {
625 NSLog(@"Unrecognized modifier key: keyCode 0x%hx, physical key 0x%llx", keyCode, physicalKey);
626 [callback resolveTo:TRUE];
627 return;
628 }
629 FlutterKeyEvent flutterEvent = {
630 .struct_size = sizeof(FlutterKeyEvent),
631 .timestamp = GetFlutterTimestampFrom(timestamp),
632 .type = isDownEvent ? kFlutterKeyEventTypeDown : kFlutterKeyEventTypeUp,
633 .physical = physicalKey,
634 .logical = logicalKey,
635 .character = nil,
636 .synthesized = synthesized,
637 };
638 [self updateKey:physicalKey asPressed:isDownEvent ? logicalKey : 0];
639 if (!synthesized) {
640 [self sendPrimaryFlutterEvent:flutterEvent callback:callback];
641 } else {
642 [self sendSynthesizedFlutterEvent:flutterEvent guard:callback];
643 }
644 }
645
646 - (void)handleDownEvent:(NSEvent*)event callback:(FlutterKeyCallbackGuard*)callback {
647 uint64_t physicalKey = GetPhysicalKeyForKeyCode(event.keyCode);
648 NSNumber* logicalKeyFromMap = self.layoutMap[@(event.keyCode)];
649 uint64_t logicalKey = logicalKeyFromMap != nil ? [logicalKeyFromMap unsignedLongLongValue]
650 : GetLogicalKeyForEvent(event, physicalKey);
651 [self synchronizeModifiers:event.modifierFlags
652 ignoringFlags:0
653 timestamp:event.timestamp
654 guard:callback];
655
656 bool isARepeat = event.isARepeat;
657 NSNumber* pressedLogicalKey = _pressingRecords[@(physicalKey)];
658 if (pressedLogicalKey != nil && !isARepeat) {
659 // This might happen in add-to-app scenarios if the focus is changed
660 // from the native view to the Flutter view amid the key tap.
661 //
662 // This might also happen when a key event is forged (such as by an
663 // IME) using the same keyCode as an unreleased key. See
664 // https://github.com/flutter/flutter/issues/82673#issuecomment-988661079
665 FlutterKeyEvent flutterEvent = {
666 .struct_size = sizeof(FlutterKeyEvent),
667 .timestamp = GetFlutterTimestampFrom(event.timestamp),
668 .type = kFlutterKeyEventTypeUp,
669 .physical = physicalKey,
670 .logical = [pressedLogicalKey unsignedLongLongValue],
671 .character = nil,
672 .synthesized = true,
673 };
674 [self sendSynthesizedFlutterEvent:flutterEvent guard:callback];
675 pressedLogicalKey = nil;
676 }
677
678 if (pressedLogicalKey == nil) {
679 [self updateKey:physicalKey asPressed:logicalKey];
680 }
681
682 FlutterKeyEvent flutterEvent = {
683 .struct_size = sizeof(FlutterKeyEvent),
684 .timestamp = GetFlutterTimestampFrom(event.timestamp),
685 .type = pressedLogicalKey == nil ? kFlutterKeyEventTypeDown : kFlutterKeyEventTypeRepeat,
686 .physical = physicalKey,
687 .logical = pressedLogicalKey == nil ? logicalKey : [pressedLogicalKey unsignedLongLongValue],
688 .character = getEventString(event.characters),
689 .synthesized = false,
690 };
691 [self sendPrimaryFlutterEvent:flutterEvent callback:callback];
692 }
693
694 - (void)handleUpEvent:(NSEvent*)event callback:(FlutterKeyCallbackGuard*)callback {
695 NSAssert(!event.isARepeat, @"Unexpected repeated Up event: keyCode %d, char %@, charIM %@",
696 event.keyCode, event.characters, event.charactersIgnoringModifiers);
697 [self synchronizeModifiers:event.modifierFlags
698 ignoringFlags:0
699 timestamp:event.timestamp
700 guard:callback];
701
702 uint64_t physicalKey = GetPhysicalKeyForKeyCode(event.keyCode);
703 NSNumber* pressedLogicalKey = _pressingRecords[@(physicalKey)];
704 if (pressedLogicalKey == nil) {
705 // Normally the key up events won't be missed since macOS always sends the
706 // key up event to the window where the corresponding key down occurred.
707 // However this might happen in add-to-app scenarios if the focus is changed
708 // from the native view to the Flutter view amid the key tap.
709 [callback resolveTo:TRUE];
710 return;
711 }
712 [self updateKey:physicalKey asPressed:0];
713
714 FlutterKeyEvent flutterEvent = {
715 .struct_size = sizeof(FlutterKeyEvent),
716 .timestamp = GetFlutterTimestampFrom(event.timestamp),
717 .type = kFlutterKeyEventTypeUp,
718 .physical = physicalKey,
719 .logical = [pressedLogicalKey unsignedLongLongValue],
720 .character = nil,
721 .synthesized = false,
722 };
723 [self sendPrimaryFlutterEvent:flutterEvent callback:callback];
724 }
725
726 - (void)handleCapsLockEvent:(NSEvent*)event callback:(FlutterKeyCallbackGuard*)callback {
727 [self synchronizeModifiers:event.modifierFlags
728 ignoringFlags:NSEventModifierFlagCapsLock
729 timestamp:event.timestamp
730 guard:callback];
731 if ((_lastModifierFlagsOfInterest & NSEventModifierFlagCapsLock) !=
732 (event.modifierFlags & NSEventModifierFlagCapsLock)) {
733 [self sendCapsLockTapWithTimestamp:event.timestamp synthesizeDown:false callback:callback];
734 _lastModifierFlagsOfInterest = _lastModifierFlagsOfInterest ^ NSEventModifierFlagCapsLock;
735 } else {
736 [callback resolveTo:TRUE];
737 }
738 }
739
740 - (void)handleFlagEvent:(NSEvent*)event callback:(FlutterKeyCallbackGuard*)callback {
741 NSNumber* targetModifierFlagObj = flutter::keyCodeToModifierFlag[@(event.keyCode)];
742 NSUInteger targetModifierFlag =
743 targetModifierFlagObj == nil ? 0 : [targetModifierFlagObj unsignedLongValue];
744 uint64_t targetKey = GetPhysicalKeyForKeyCode(event.keyCode);
745 if (targetKey == flutter::kCapsLockPhysicalKey) {
746 return [self handleCapsLockEvent:event callback:callback];
747 }
748
749 [self synchronizeModifiers:event.modifierFlags
750 ignoringFlags:targetModifierFlag
751 timestamp:event.timestamp
752 guard:callback];
753
754 NSNumber* pressedLogicalKey = [_pressingRecords objectForKey:@(targetKey)];
755 BOOL lastTargetPressed = pressedLogicalKey != nil;
756 NSAssert(targetModifierFlagObj == nil ||
757 (_lastModifierFlagsOfInterest & targetModifierFlag) != 0 == lastTargetPressed,
758 @"Desynchronized state between lastModifierFlagsOfInterest (0x%lx) on bit 0x%lx "
759 @"for keyCode 0x%hx, whose pressing state is %@.",
760 _lastModifierFlagsOfInterest, targetModifierFlag, event.keyCode,
761 lastTargetPressed
762 ? [NSString stringWithFormat:@"0x%llx", [pressedLogicalKey unsignedLongLongValue]]
763 : @"empty");
764
765 BOOL shouldBePressed = (event.modifierFlags & targetModifierFlag) != 0;
766 if (lastTargetPressed == shouldBePressed) {
767 [callback resolveTo:TRUE];
768 return;
769 }
770 _lastModifierFlagsOfInterest = _lastModifierFlagsOfInterest ^ targetModifierFlag;
771 [self sendModifierEventOfType:shouldBePressed
772 timestamp:event.timestamp
773 keyCode:event.keyCode
774 synthesized:false
775 callback:callback];
776 }
777
778 - (void)handleResponse:(BOOL)handled forId:(uint64_t)responseId {
779 FlutterAsyncKeyCallback callback = _pendingResponses[@(responseId)];
780 callback(handled);
781 [_pendingResponses removeObjectForKey:@(responseId)];
782 }
783
784 - (void)syncModifiersIfNeeded:(NSEventModifierFlags)modifierFlags
785 timestamp:(NSTimeInterval)timestamp {
786 FlutterAsyncKeyCallback replyCallback = ^(BOOL handled) {
787 // Do nothing.
788 };
789 FlutterKeyCallbackGuard* guardedCallback =
790 [[FlutterKeyCallbackGuard alloc] initWithCallback:replyCallback];
791 [self synchronizeModifiers:modifierFlags
792 ignoringFlags:0
793 timestamp:timestamp
794 guard:guardedCallback];
795 }
796
797 - (nonnull NSDictionary*)getPressedState {
798 return [NSDictionary dictionaryWithDictionary:_pressingRecords];
799 }
800 @end
801
802 namespace {
803 void HandleResponse(bool handled, void* user_data) {
804 // Use unique_ptr to release on leaving.
805 auto pending = std::unique_ptr<FlutterKeyPendingResponse>(
806 reinterpret_cast<FlutterKeyPendingResponse*>(user_data));
807 [pending->responder handleResponse:handled forId:pending->responseId];
808 }
809 } // namespace
flutter::kCapsLockPhysicalKey
const uint64_t kCapsLockPhysicalKey
Definition: KeyCodeMap.g.mm:245
flutter::keyCodeToLogicalKey
const NSDictionary * keyCodeToLogicalKey
Definition: KeyCodeMap.g.mm:149
flutter::keyCodeToPhysicalKey
const NSDictionary * keyCodeToPhysicalKey
Definition: KeyCodeMap.g.mm:26
user_data
void * user_data
Definition: texture_registrar_unittests.cc:27
-[FlutterEmbedderKeyResponder getPressedState]
nonnull NSDictionary * getPressedState()
Definition: FlutterEmbedderKeyResponder.mm:797
-[FlutterKeyCallbackGuard pendTo:withId:]
void pendTo:withId:(nonnull NSMutableDictionary< NSNumber *, FlutterAsyncKeyCallback > *pendingResponses,[withId] uint64_t responseId)
Definition: FlutterEmbedderKeyResponder.mm:307
FlutterKeyCallbackGuard::handled
BOOL handled
Definition: FlutterEmbedderKeyResponder.mm:281
FlutterSendEmbedderKeyEvent
void(^ FlutterSendEmbedderKeyEvent)(const FlutterKeyEvent &, _Nullable FlutterKeyEventCallback, void *_Nullable)
Definition: FlutterEmbedderKeyResponder.h:13
FlutterEmbedderKeyResponder.h
flutter::kValueMask
const uint64_t kValueMask
Definition: KeyCodeMap.g.mm:22
FlutterAsyncKeyCallback
void(^ FlutterAsyncKeyCallback)(BOOL handled)
Definition: FlutterKeyPrimaryResponder.h:10
-[FlutterKeyCallbackGuard resolveTo:]
void resolveTo:(BOOL handled)
Definition: FlutterEmbedderKeyResponder.mm:320
flutter::keyCodeToModifierFlag
const NSDictionary * keyCodeToModifierFlag
Definition: KeyCodeMap.g.mm:223
FlutterCodecs.h
FlutterKeyPrimaryResponder-p::layoutMap
NSMutableDictionary< NSNumber *, NSNumber * > * layoutMap
Definition: FlutterKeyPrimaryResponder.h:46
flutter::kCapsLockLogicalKey
const uint64_t kCapsLockLogicalKey
Definition: KeyCodeMap.g.mm:246
FlutterKeyPendingResponse::responder
FlutterEmbedderKeyResponder * responder
Definition: FlutterEmbedderKeyResponder.mm:255
FlutterViewController_Internal.h
FlutterKeyCallbackGuard::debugHandleSource
NSString * debugHandleSource
Definition: FlutterEmbedderKeyResponder.mm:289
KeyCodeMap_Internal.h
FlutterKeyCallbackGuard::sentAnyEvents
BOOL sentAnyEvents
Definition: FlutterEmbedderKeyResponder.mm:282
FlutterKeyCallbackGuard
Definition: FlutterEmbedderKeyResponder.mm:267
flutter::kMacosPlane
const uint64_t kMacosPlane
Definition: KeyCodeMap.g.mm:24
FlutterEmbedderKeyResponder
Definition: FlutterEmbedderKeyResponder.h:23
flutter::kUnicodePlane
const uint64_t kUnicodePlane
Definition: KeyCodeMap.g.mm:23
FlutterKeyPendingResponse::responseId
uint64_t responseId
Definition: FlutterEmbedderKeyResponder.mm:256
FlutterKeyPendingResponse
Definition: FlutterEmbedderKeyResponder.mm:254