FlutterEmbedderKeyResponder Class Reference

#include <FlutterEmbedderKeyResponder.h>

Inheritance diagram for FlutterEmbedderKeyResponder:

Instance Methods
(nonnull instancetype)	- initWithSendEvent:
(nonnull instancetype)	- initWithSendEvent:
(void)	- syncModifiersIfNeeded:timestamp:
(nonnull NSDictionary *)	- getPressedState
(nonnull instancetype)	- initWithSendEvent: [implementation]
(void)	- handlePress:callback: [implementation]
(void)	- synchronizeModifiers: [implementation]
(void)	- synthesizeCapsLockTapWithTimestamp: [implementation]
(void)	- updateKey:asPressed: [implementation]
(void)	- sendPrimaryFlutterEvent:callback: [implementation]
(void)	- sendEmptyEvent [implementation]
(void)	- synthesizeModifierEventOfType:timestamp:keyCode: [implementation]
(void)	- handlePressBegin:callback: [implementation]
(void)	- handlePressEnd:callback: [implementation]
(void)	- handleResponse:forId: [implementation]
(UInt32)	- fixSidedFlags:withLeftFlag:withRightFlag:withLeftKey:withRightKey:withKeyCode:keyDown:forFlags: [implementation]
(UInt32)	- adjustModifiers: [implementation]
(void)	- handleEvent:callback: [implementation]
(void)	- synchronizeModifiers:ignoringFlags:timestamp:guard: [implementation]
(void)	- sendSynthesizedFlutterEvent:guard: [implementation]
(void)	- sendCapsLockTapWithTimestamp:synthesizeDown:callback: [implementation]
(void)	- sendModifierEventOfType:timestamp:keyCode:synthesized:callback: [implementation]
(void)	- handleDownEvent:callback: [implementation]
(void)	- handleUpEvent:callback: [implementation]
(void)	- handleCapsLockEvent:callback: [implementation]
(void)	- handleFlagEvent:callback: [implementation]
Instance Methods inherited from <FlutterKeyPrimaryResponder>
(void)	- handleEvent:callback:

Properties
FlutterSendKeyEvent	sendEvent [implementation]
FlutterSendEmbedderKeyEvent	sendEvent [implementation]
NSMutableDictionary< NSNumber *, NSNumber * > *	pressingRecords [implementation]
NSUInteger	modifierFlagOfInterestMask [implementation]
NSUInteger	lastModifierFlagsOfInterest [implementation]
uint64_t	responseId [implementation]
NSMutableDictionary< NSNumber *, FlutterAsyncKeyCallback > *	pendingResponses [implementation]
Properties inherited from <FlutterKeyPrimaryResponder>
NSMutableDictionary< NSNumber *, NSNumber * > *	layoutMap

Detailed Description

A primary responder of |FlutterKeyboardManager| that handles events by sending the converted events through a Dart hook to the framework.

This class interfaces with the HardwareKeyboard API in the framework.

A primary responder of |FlutterKeyboardManager| that handles events by sending the converted events through the embedder API.

This class communicates with the HardwareKeyboard API in the framework.

Definition at line 23 of file FlutterEmbedderKeyResponder.h.

Method Documentation

adjustModifiers:

- (UInt32) adjustModifiers: (ios(13.4))  API_AVAILABLE

implementation

Because iOS differs from other platforms in that the modifier flags still contain the flag for the key that is being released on the keyup event, we adjust the modifiers when the released key is a matching modifier key.

Definition at line 405 of file FlutterEmbedderKeyResponder.mm.

                         :(nonnull FlutterUIPressProxy*)press API_AVAILABLE(ios(13.4)) {
  if (@available(iOS 13.4, *)) {
    // no-op
  } else {
    return press.key.modifierFlags;
  }
 
  bool keyDown = isKeyDown(press);
 
  // Start with the current modifier flags, along with any sided flags that we
  // already know are down.
  UInt32 pressedModifiers =
      press.key.modifierFlags | (_lastModifierFlagsOfInterest & kModifierFlagSidedMask);
 
  pressedModifiers = [self fixSidedFlags:kModifierFlagShiftAny
                            withLeftFlag:kModifierFlagShiftLeft
                           withRightFlag:kModifierFlagShiftRight
                             withLeftKey:UIKeyboardHIDUsageKeyboardLeftShift
                            withRightKey:UIKeyboardHIDUsageKeyboardRightShift
                             withKeyCode:press.key.keyCode
                                 keyDown:keyDown
                                forFlags:pressedModifiers];
  pressedModifiers = [self fixSidedFlags:kModifierFlagControlAny
                            withLeftFlag:kModifierFlagControlLeft
                           withRightFlag:kModifierFlagControlRight
                             withLeftKey:UIKeyboardHIDUsageKeyboardLeftControl
                            withRightKey:UIKeyboardHIDUsageKeyboardRightControl
                             withKeyCode:press.key.keyCode
                                 keyDown:keyDown
                                forFlags:pressedModifiers];
  pressedModifiers = [self fixSidedFlags:kModifierFlagAltAny
                            withLeftFlag:kModifierFlagAltLeft
                           withRightFlag:kModifierFlagAltRight
                             withLeftKey:UIKeyboardHIDUsageKeyboardLeftAlt
                            withRightKey:UIKeyboardHIDUsageKeyboardRightAlt
                             withKeyCode:press.key.keyCode
                                 keyDown:keyDown
                                forFlags:pressedModifiers];
  pressedModifiers = [self fixSidedFlags:kModifierFlagMetaAny
                            withLeftFlag:kModifierFlagMetaLeft
                           withRightFlag:kModifierFlagMetaRight
                             withLeftKey:UIKeyboardHIDUsageKeyboardLeftGUI
                            withRightKey:UIKeyboardHIDUsageKeyboardRightGUI
                             withKeyCode:press.key.keyCode
                                 keyDown:keyDown
                                forFlags:pressedModifiers];
 
  if (press.key.keyCode == UIKeyboardHIDUsageKeyboardCapsLock) {
    // The caps lock modifier needs to be unset only if it was already on
    // and this is a key up. This is because it indicates the lock state, and
    // not the key press state. The caps lock state should be on between the
    // first down, and the second up (i.e. while the lock in effect), and
    // this code turns it off at the second up event. The OS leaves it on still
    // because of iOS's weird late processing of modifier states. Synthesis of
    // the appropriate synthesized key events happens in synchronizeModifiers.
    if (!keyDown && _lastModifierFlagsOfInterest & kModifierFlagCapsLock) {
      pressedModifiers &= ~kModifierFlagCapsLock;
    }
  }
  return pressedModifiers;
}

fixSidedFlags:withLeftFlag:withRightFlag:withLeftKey:withRightKey:withKeyCode:keyDown:forFlags:

- (UInt32) fixSidedFlags: (ModifierFlag)  anyFlag withLeftFlag: (ModifierFlag)  leftSide withRightFlag: (ModifierFlag)  rightSide withLeftKey: (UInt16)  leftKeyCode withRightKey: (UInt16)  rightKeyCode withKeyCode: (UInt16)  keyCode keyDown: (BOOL)  isKeyDown forFlags: (ios(13.4))  API_AVAILABLE

implementation

Fix up the modifiers for a particular type of modifier key.

Definition at line 405 of file FlutterEmbedderKeyResponder.mm.

                       :(ModifierFlag)anyFlag
           withLeftFlag:(ModifierFlag)leftSide
          withRightFlag:(ModifierFlag)rightSide
            withLeftKey:(UInt16)leftKeyCode
           withRightKey:(UInt16)rightKeyCode
            withKeyCode:(UInt16)keyCode
                keyDown:(BOOL)isKeyDown
               forFlags:(UInt32)modifiersPressed API_AVAILABLE(ios(13.4)) {
  UInt32 newModifiers = modifiersPressed;
  if (isKeyDown) {
    // Add in the modifier flags that correspond to this key code, if any.
    if (keyCode == leftKeyCode) {
      newModifiers |= leftSide | anyFlag;
    } else if (keyCode == rightKeyCode) {
      newModifiers |= rightSide | anyFlag;
    }
  } else {
    // If this is a key up, then remove any modifier that matches the keycode in
    // the event from the flags, and the anyFlag if the other side isn't also
    // pressed.
    if (keyCode == leftKeyCode) {
      newModifiers &= ~leftSide;
      if (!(newModifiers & rightSide)) {
        newModifiers &= ~anyFlag;
      }
    } else if (keyCode == rightKeyCode) {
      newModifiers &= ~rightSide;
      if (!(newModifiers & leftSide)) {
        newModifiers &= ~anyFlag;
      }
    }
  }
 
  if (!(newModifiers & anyFlag)) {
    // Turn off any sided flags, since the "any" flag is gone.
    newModifiers &= ~(leftSide | rightSide);
  }
 
  return newModifiers;
}

getPressedState

- (nonnull NSDictionary *) getPressedState

Returns the keyboard pressed state.

Returns the keyboard pressed state. The dictionary contains one entry per pressed keys, mapping from the logical key to the physical key.

Definition at line 385 of file FlutterEmbedderKeyResponder.mm.

                                         {
  return [NSDictionary dictionaryWithDictionary:_pressingRecords];
}

handleCapsLockEvent:callback:

- (void) handleCapsLockEvent: (NSEvent*)  event callback: (FlutterKeyCallbackGuard*)  callback

implementation

Definition at line 385 of file FlutterEmbedderKeyResponder.mm.

                           :(NSEvent*)event callback:(FlutterKeyCallbackGuard*)callback {
  [self synchronizeModifiers:event.modifierFlags
               ignoringFlags:NSEventModifierFlagCapsLock
                   timestamp:event.timestamp
                       guard:callback];
  if ((_lastModifierFlagsOfInterest & NSEventModifierFlagCapsLock) !=
      (event.modifierFlags & NSEventModifierFlagCapsLock)) {
    [self sendCapsLockTapWithTimestamp:event.timestamp synthesizeDown:false callback:callback];
    _lastModifierFlagsOfInterest = _lastModifierFlagsOfInterest ^ NSEventModifierFlagCapsLock;
  } else {
    [callback resolveTo:TRUE];
  }
}

handleDownEvent:callback:

- (void) handleDownEvent: (NSEvent*)  event callback: (FlutterKeyCallbackGuard*)  callback

implementation

Definition at line 385 of file FlutterEmbedderKeyResponder.mm.

                       :(NSEvent*)event callback:(FlutterKeyCallbackGuard*)callback {
  uint64_t physicalKey = GetPhysicalKeyForKeyCode(event.keyCode);
  NSNumber* logicalKeyFromMap = self.layoutMap[@(event.keyCode)];
  uint64_t logicalKey = logicalKeyFromMap != nil ? [logicalKeyFromMap unsignedLongLongValue]
                                                 : GetLogicalKeyForEvent(event, physicalKey);
  [self synchronizeModifiers:event.modifierFlags
               ignoringFlags:0
                   timestamp:event.timestamp
                       guard:callback];
 
  bool isARepeat = event.isARepeat;
  NSNumber* pressedLogicalKey = _pressingRecords[@(physicalKey)];
  if (pressedLogicalKey != nil && !isARepeat) {
    // This might happen in add-to-app scenarios if the focus is changed
    // from the native view to the Flutter view amid the key tap.
    //
    // This might also happen when a key event is forged (such as by an
    // IME) using the same keyCode as an unreleased key. See
    // https://github.com/flutter/flutter/issues/82673#issuecomment-988661079
    FlutterKeyEvent flutterEvent = {
        .struct_size = sizeof(FlutterKeyEvent),
        .timestamp = GetFlutterTimestampFrom(event.timestamp),
        .type = kFlutterKeyEventTypeUp,
        .physical = physicalKey,
        .logical = [pressedLogicalKey unsignedLongLongValue],
        .character = nil,
        .synthesized = true,
    };
    [self sendSynthesizedFlutterEvent:flutterEvent guard:callback];
    pressedLogicalKey = nil;
  }
 
  if (pressedLogicalKey == nil) {
    [self updateKey:physicalKey asPressed:logicalKey];
  }
 
  FlutterKeyEvent flutterEvent = {
      .struct_size = sizeof(FlutterKeyEvent),
      .timestamp = GetFlutterTimestampFrom(event.timestamp),
      .type = pressedLogicalKey == nil ? kFlutterKeyEventTypeDown : kFlutterKeyEventTypeRepeat,
      .physical = physicalKey,
      .logical = pressedLogicalKey == nil ? logicalKey : [pressedLogicalKey unsignedLongLongValue],
      .character = getEventString(event.characters),
      .synthesized = false,
  };
  [self sendPrimaryFlutterEvent:flutterEvent callback:callback];
}

handleEvent:callback:

- (void) handleEvent: (NSEvent*)  event callback: (FlutterAsyncKeyCallback)  callback

implementation

Definition at line 385 of file FlutterEmbedderKeyResponder.mm.

                   :(NSEvent*)event callback:(FlutterAsyncKeyCallback)callback {
  // The conversion algorithm relies on a non-nil callback to properly compute
  // `synthesized`.
  NSAssert(callback != nil, @"The callback must not be nil.");
  FlutterKeyCallbackGuard* guardedCallback =
      [[FlutterKeyCallbackGuard alloc] initWithCallback:callback];
  switch (event.type) {
    case NSEventTypeKeyDown:
      [self handleDownEvent:event callback:guardedCallback];
      break;
    case NSEventTypeKeyUp:
      [self handleUpEvent:event callback:guardedCallback];
      break;
    case NSEventTypeFlagsChanged:
      [self handleFlagEvent:event callback:guardedCallback];
      break;
    default:
      NSAssert(false, @"Unexpected key event type: |%@|.", @(event.type));
  }
  NSAssert(guardedCallback.handled, @"The callback is returned without being handled.");
  if (!guardedCallback.sentAnyEvents) {
    FlutterKeyEvent flutterEvent = {
        .struct_size = sizeof(FlutterKeyEvent),
        .timestamp = 0,
        .type = kFlutterKeyEventTypeDown,
        .physical = 0,
        .logical = 0,
        .character = nil,
        .synthesized = false,
    };
    _sendEvent(flutterEvent, nullptr, nullptr);
  }
  NSAssert(_lastModifierFlagsOfInterest == (event.modifierFlags & _modifierFlagOfInterestMask),
           @"The modifier flags are not properly updated: recorded 0x%lx, event with mask 0x%lx",
           _lastModifierFlagsOfInterest, event.modifierFlags & _modifierFlagOfInterestMask);
}

handleFlagEvent:callback:

- (void) handleFlagEvent: (NSEvent*)  event callback: (FlutterKeyCallbackGuard*)  callback

implementation

Definition at line 385 of file FlutterEmbedderKeyResponder.mm.

                       :(NSEvent*)event callback:(FlutterKeyCallbackGuard*)callback {
  NSNumber* targetModifierFlagObj = flutter::keyCodeToModifierFlag[@(event.keyCode)];
  NSUInteger targetModifierFlag =
      targetModifierFlagObj == nil ? 0 : [targetModifierFlagObj unsignedLongValue];
  uint64_t targetKey = GetPhysicalKeyForKeyCode(event.keyCode);
  if (targetKey == flutter::kCapsLockPhysicalKey) {
    return [self handleCapsLockEvent:event callback:callback];
  }
 
  [self synchronizeModifiers:event.modifierFlags
               ignoringFlags:targetModifierFlag
                   timestamp:event.timestamp
                       guard:callback];
 
  NSNumber* pressedLogicalKey = [_pressingRecords objectForKey:@(targetKey)];
  BOOL lastTargetPressed = pressedLogicalKey != nil;
  NSAssert(targetModifierFlagObj == nil ||
               (_lastModifierFlagsOfInterest & targetModifierFlag) != 0 == lastTargetPressed,
           @"Desynchronized state between lastModifierFlagsOfInterest (0x%lx) on bit 0x%lx "
           @"for keyCode 0x%hx, whose pressing state is %@.",
           _lastModifierFlagsOfInterest, targetModifierFlag, event.keyCode,
           lastTargetPressed
               ? [NSString stringWithFormat:@"0x%llx", [pressedLogicalKey unsignedLongLongValue]]
               : @"empty");
 
  BOOL shouldBePressed = (event.modifierFlags & targetModifierFlag) != 0;
  if (lastTargetPressed == shouldBePressed) {
    [callback resolveTo:TRUE];
    return;
  }
  _lastModifierFlagsOfInterest = _lastModifierFlagsOfInterest ^ targetModifierFlag;
  [self sendModifierEventOfType:shouldBePressed
                      timestamp:event.timestamp
                        keyCode:event.keyCode
                    synthesized:false
                       callback:callback];
}

handlePress:callback:

- (void) handlePress: (nonnull FlutterUIPressProxy *)  press callback: (ios(13.4))  API_AVAILABLE

implementation

Process the event.

The |callback| should be called with a value that indicates whether the responder has handled the given press event. The |callback| must be called exactly once, and can be called before the return of this method, or after.

Reimplemented from <FlutterKeyPrimaryResponder>.

Definition at line 405 of file FlutterEmbedderKeyResponder.mm.

                   :(nonnull FlutterUIPressProxy*)press
           callback:(FlutterAsyncKeyCallback)callback API_AVAILABLE(ios(13.4)) {
  if (@available(iOS 13.4, *)) {
  } else {
    return;
  }
  // The conversion algorithm relies on a non-nil callback to properly compute
  // `synthesized`.
  NSAssert(callback != nil, @"The callback must not be nil.");
 
  FlutterKeyCallbackGuard* guardedCallback = nil;
  switch (press.phase) {
    case UIPressPhaseBegan:
      guardedCallback = [[FlutterKeyCallbackGuard alloc] initWithCallback:callback];
      [self handlePressBegin:press callback:guardedCallback];
      break;
    case UIPressPhaseEnded:
      guardedCallback = [[FlutterKeyCallbackGuard alloc] initWithCallback:callback];
      [self handlePressEnd:press callback:guardedCallback];
      break;
    case UIPressPhaseChanged:
    case UIPressPhaseCancelled:
      // TODO(gspencergoog): Handle cancelled events as synthesized up events.
    case UIPressPhaseStationary:
      NSAssert(false, @"Unexpected press phase receieved in handlePress");
      return;
  }
  NSAssert(guardedCallback.handled, @"The callback returned without being handled.");
  NSAssert(
      (_lastModifierFlagsOfInterest & ~kModifierFlagCapsLock) ==
          ([self adjustModifiers:press] & (_modifierFlagOfInterestMask & ~kModifierFlagCapsLock)),
      @"The modifier flags are not properly updated: recorded 0x%lx, event with mask 0x%lx",
      static_cast<unsigned long>(_lastModifierFlagsOfInterest & ~kModifierFlagCapsLock),
      static_cast<unsigned long>([self adjustModifiers:press] &
                                 (_modifierFlagOfInterestMask & ~kModifierFlagCapsLock)));
}

handlePressBegin:callback:

- (void) handlePressBegin: (nonnull FlutterUIPressProxy *)  press callback: (ios(13.4))  API_AVAILABLE

implementation

Processes a down event from the system.

Definition at line 405 of file FlutterEmbedderKeyResponder.mm.

                        :(nonnull FlutterUIPressProxy*)press
                callback:(nonnull FlutterKeyCallbackGuard*)callback API_AVAILABLE(ios(13.4)) {
  if (@available(iOS 13.4, *)) {
  } else {
    return;
  }
  uint64_t physicalKey = GetPhysicalKeyForKeyCode(press.key.keyCode);
  // Some unprintable keys on iOS have literal names on their key label, such as
  // @"UIKeyInputEscape". They are called the "special keys" and have predefined
  // logical keys and empty characters.
  NSNumber* specialKey = [specialKeyMapping objectForKey:press.key.charactersIgnoringModifiers];
  uint64_t logicalKey = GetLogicalKeyForEvent(press, specialKey);
  [self synchronizeModifiers:press];
 
  NSNumber* pressedLogicalKey = nil;
  if ([_pressingRecords count] > 0) {
    pressedLogicalKey = _pressingRecords[@(physicalKey)];
    if (pressedLogicalKey != nil) {
      // Normally the key up events won't be missed since iOS always sends the
      // key up event to the view where the corresponding key down occurred.
      // However this might happen in add-to-app scenarios if the focus is changed
      // from the native view to the Flutter view amid the key tap.
      [callback resolveTo:TRUE];
      [self sendEmptyEvent];
      return;
    }
  }
 
  if (pressedLogicalKey == nil) {
    [self updateKey:physicalKey asPressed:logicalKey];
  }
 
  FlutterKeyEvent flutterEvent = {
      .struct_size = sizeof(FlutterKeyEvent),
      .timestamp = GetFlutterTimestampFrom(press.timestamp),
      .type = kFlutterKeyEventTypeDown,
      .physical = physicalKey,
      .logical = pressedLogicalKey == nil ? logicalKey : [pressedLogicalKey unsignedLongLongValue],
      .character =
          specialKey != nil ? nil : getEventCharacters(press.key.characters, press.key.keyCode),
      .synthesized = false,
      .device_type = kFlutterKeyEventDeviceTypeKeyboard,
  };
  [self sendPrimaryFlutterEvent:flutterEvent callback:callback];
}

handlePressEnd:callback:

- (void) handlePressEnd: (nonnull FlutterUIPressProxy *)  press callback: (ios(13.4))  API_AVAILABLE

implementation

Processes an up event from the system.

Definition at line 405 of file FlutterEmbedderKeyResponder.mm.

                      :(nonnull FlutterUIPressProxy*)press
              callback:(nonnull FlutterKeyCallbackGuard*)callback API_AVAILABLE(ios(13.4)) {
  if (@available(iOS 13.4, *)) {
  } else {
    return;
  }
  [self synchronizeModifiers:press];
 
  uint64_t physicalKey = GetPhysicalKeyForKeyCode(press.key.keyCode);
  NSNumber* pressedLogicalKey = _pressingRecords[@(physicalKey)];
  if (pressedLogicalKey == nil) {
    // Normally the key up events won't be missed since iOS always sends the
    // key up event to the view where the corresponding key down occurred.
    // However this might happen in add-to-app scenarios if the focus is changed
    // from the native view to the Flutter view amid the key tap.
    [callback resolveTo:TRUE];
    [self sendEmptyEvent];
    return;
  }
  [self updateKey:physicalKey asPressed:0];
 
  FlutterKeyEvent flutterEvent = {
      .struct_size = sizeof(FlutterKeyEvent),
      .timestamp = GetFlutterTimestampFrom(press.timestamp),
      .type = kFlutterKeyEventTypeUp,
      .physical = physicalKey,
      .logical = [pressedLogicalKey unsignedLongLongValue],
      .character = nil,
      .synthesized = false,
      .device_type = kFlutterKeyEventDeviceTypeKeyboard,
  };
  [self sendPrimaryFlutterEvent:flutterEvent callback:callback];
}

handleResponse:forId:

- (void) handleResponse: (BOOL)  handled forId: (uint64_t)  responseId

implementation

Processes the response from the framework.

Definition at line 405 of file FlutterEmbedderKeyResponder.mm.

                      :(BOOL)handled forId:(uint64_t)responseId {
  FlutterAsyncKeyCallback callback = _pendingResponses[@(responseId)];
  callback(handled);
  [_pendingResponses removeObjectForKey:@(responseId)];
}

handleUpEvent:callback:

- (void) handleUpEvent: (NSEvent*)  event callback: (FlutterKeyCallbackGuard*)  callback

implementation

Definition at line 385 of file FlutterEmbedderKeyResponder.mm.

                     :(NSEvent*)event callback:(FlutterKeyCallbackGuard*)callback {
  NSAssert(!event.isARepeat, @"Unexpected repeated Up event: keyCode %d, char %@, charIM %@",
           event.keyCode, event.characters, event.charactersIgnoringModifiers);
  [self synchronizeModifiers:event.modifierFlags
               ignoringFlags:0
                   timestamp:event.timestamp
                       guard:callback];
 
  uint64_t physicalKey = GetPhysicalKeyForKeyCode(event.keyCode);
  NSNumber* pressedLogicalKey = _pressingRecords[@(physicalKey)];
  if (pressedLogicalKey == nil) {
    // Normally the key up events won't be missed since macOS always sends the
    // key up event to the window where the corresponding key down occurred.
    // However this might happen in add-to-app scenarios if the focus is changed
    // from the native view to the Flutter view amid the key tap.
    [callback resolveTo:TRUE];
    return;
  }
  [self updateKey:physicalKey asPressed:0];
 
  FlutterKeyEvent flutterEvent = {
      .struct_size = sizeof(FlutterKeyEvent),
      .timestamp = GetFlutterTimestampFrom(event.timestamp),
      .type = kFlutterKeyEventTypeUp,
      .physical = physicalKey,
      .logical = [pressedLogicalKey unsignedLongLongValue],
      .character = nil,
      .synthesized = false,
  };
  [self sendPrimaryFlutterEvent:flutterEvent callback:callback];
}

initWithSendEvent: [1/3]

- (nonnull instancetype) initWithSendEvent:

(_Nonnull FlutterSendEmbedderKeyEvent)

sendEvent

Create an instance by specifying the function to send converted events to.

The |sendEvent| is typically |FlutterEngine|'s |sendKeyEvent|.

initWithSendEvent: [2/3]

- (nonnull instancetype) initWithSendEvent: (FlutterSendKeyEvent)  sendEvent

implementation

Definition at line 405 of file FlutterEmbedderKeyResponder.mm.

                                         :(FlutterSendKeyEvent)sendEvent {
  self = [super init];
  if (self != nil) {
    _sendEvent = [sendEvent copy];
    _pressingRecords = [[NSMutableDictionary alloc] init];
    _pendingResponses = [[NSMutableDictionary alloc] init];
    _responseId = 1;
    _lastModifierFlagsOfInterest = 0;
    _modifierFlagOfInterestMask = computeModifierFlagOfInterestMask();
  }
  return self;
}

initWithSendEvent: [3/3]

- (nonnull instancetype) initWithSendEvent:

(nonnull FlutterSendKeyEvent)

sendEvent

Create an instance by specifying the function to send converted events to.

The |sendEvent| is typically |FlutterEngine|'s |sendKeyEvent|.

sendCapsLockTapWithTimestamp:synthesizeDown:callback:

- (void) sendCapsLockTapWithTimestamp: (NSTimeInterval)  timestamp synthesizeDown: (bool)  synthesizeDown callback: (FlutterKeyCallbackGuard*)  callback

implementation

Definition at line 385 of file FlutterEmbedderKeyResponder.mm.

                                    :(NSTimeInterval)timestamp
                      synthesizeDown:(bool)synthesizeDown
                            callback:(FlutterKeyCallbackGuard*)callback {
  // MacOS sends a down *or* an up when CapsLock is tapped, alternatively on
  // even taps and odd taps. A CapsLock down or CapsLock up should always be
  // converted to a down *and* an up, and the up should always be a synthesized
  // event, since the FlutterEmbedderKeyResponder will never know when the
  // button is released.
  FlutterKeyEvent flutterEvent = {
      .struct_size = sizeof(FlutterKeyEvent),
      .timestamp = GetFlutterTimestampFrom(timestamp),
      .type = kFlutterKeyEventTypeDown,
      .physical = flutter::kCapsLockPhysicalKey,
      .logical = flutter::kCapsLockLogicalKey,
      .character = nil,
      .synthesized = synthesizeDown,
  };
  if (!synthesizeDown) {
    [self sendPrimaryFlutterEvent:flutterEvent callback:callback];
  } else {
    [self sendSynthesizedFlutterEvent:flutterEvent guard:callback];
  }
 
  flutterEvent.type = kFlutterKeyEventTypeUp;
  flutterEvent.synthesized = true;
  [self sendSynthesizedFlutterEvent:flutterEvent guard:callback];
}

sendEmptyEvent

- (void) sendEmptyEvent

implementation

Send an empty key event.

The event is never synthesized, and never expects an event result. An empty event is sent when no other events should be sent, such as upon back-to-back keydown events of the same key.

Definition at line 405 of file FlutterEmbedderKeyResponder.mm.

                       {
  FlutterKeyEvent event = {
      .struct_size = sizeof(FlutterKeyEvent),
      .timestamp = 0,
      .type = kFlutterKeyEventTypeDown,
      .physical = 0,
      .logical = 0,
      .character = nil,
      .synthesized = false,
      .device_type = kFlutterKeyEventDeviceTypeKeyboard,
  };
  _sendEvent(event, nil, nil);
}

sendModifierEventOfType:timestamp:keyCode:synthesized:callback:

- (void) sendModifierEventOfType: (BOOL)  isDownEvent timestamp: (NSTimeInterval)  timestamp keyCode: (unsigned short)  keyCode synthesized: (bool)  synthesized callback: (FlutterKeyCallbackGuard*)  callback

implementation

Definition at line 385 of file FlutterEmbedderKeyResponder.mm.

                               :(BOOL)isDownEvent
                      timestamp:(NSTimeInterval)timestamp
                        keyCode:(unsigned short)keyCode
                    synthesized:(bool)synthesized
                       callback:(FlutterKeyCallbackGuard*)callback {
  uint64_t physicalKey = GetPhysicalKeyForKeyCode(keyCode);
  uint64_t logicalKey = GetLogicalKeyForModifier(keyCode, physicalKey);
  if (physicalKey == 0 || logicalKey == 0) {
    NSLog(@"Unrecognized modifier key: keyCode 0x%hx, physical key 0x%llx", keyCode, physicalKey);
    [callback resolveTo:TRUE];
    return;
  }
  FlutterKeyEvent flutterEvent = {
      .struct_size = sizeof(FlutterKeyEvent),
      .timestamp = GetFlutterTimestampFrom(timestamp),
      .type = isDownEvent ? kFlutterKeyEventTypeDown : kFlutterKeyEventTypeUp,
      .physical = physicalKey,
      .logical = logicalKey,
      .character = nil,
      .synthesized = synthesized,
  };
  [self updateKey:physicalKey asPressed:isDownEvent ? logicalKey : 0];
  if (!synthesized) {
    [self sendPrimaryFlutterEvent:flutterEvent callback:callback];
  } else {
    [self sendSynthesizedFlutterEvent:flutterEvent guard:callback];
  }
}

sendPrimaryFlutterEvent:callback:

- (void) sendPrimaryFlutterEvent: (const FlutterKeyEvent&)  event callback: (FlutterKeyCallbackGuard*)  callback

implementation

Definition at line 405 of file FlutterEmbedderKeyResponder.mm.

                               :(const FlutterKeyEvent&)event
                       callback:(FlutterKeyCallbackGuard*)callback {
  _responseId += 1;
  uint64_t responseId = _responseId;
  FlutterKeyPendingResponse* pending =
      [[FlutterKeyPendingResponse alloc] initWithHandler:self responseId:responseId];
  [callback pendTo:_pendingResponses withId:responseId];
  _sendEvent(event, HandleResponse, (__bridge_retained void* _Nullable)pending);
}

sendSynthesizedFlutterEvent:guard:

- (void) sendSynthesizedFlutterEvent: (const FlutterKeyEvent &)  event guard: (FlutterKeyCallbackGuard *)  guard

implementation

Send a synthesized key event, never expecting its event result.

The |guard| is basically a regular guarded callback, but instead of being called, it is only used to record whether an event is sent.

Definition at line 385 of file FlutterEmbedderKeyResponder.mm.

                                   :(const FlutterKeyEvent&)event
                              guard:(FlutterKeyCallbackGuard*)guard {
  _sendEvent(event, nullptr, nullptr);
  guard.sentAnyEvents = TRUE;
}

synchronizeModifiers:

- (void) synchronizeModifiers: (ios(13.4))  API_AVAILABLE

implementation

Compare the last modifier flags and the current, and dispatch synthesized key events for each different modifier flag bit.

The flags compared are all flags after masking with |modifierFlagOfInterestMask| and excluding |ignoringFlags|.

Definition at line 405 of file FlutterEmbedderKeyResponder.mm.

                            :(nonnull FlutterUIPressProxy*)press API_AVAILABLE(ios(13.4)) {
  if (@available(iOS 13.4, *)) {
  } else {
    return;
  }
 
  const UInt32 lastFlagsOfInterest = _lastModifierFlagsOfInterest & _modifierFlagOfInterestMask;
  const UInt32 pressedModifiers = [self adjustModifiers:press];
  const UInt32 currentFlagsOfInterest = pressedModifiers & _modifierFlagOfInterestMask;
  UInt32 flagDifference = currentFlagsOfInterest ^ lastFlagsOfInterest;
  if (flagDifference & kModifierFlagCapsLock) {
    // If the caps lock changed, and we didn't expect that, then send a
    // synthesized down and an up to simulate a toggle of the state.
    if (press.key.keyCode != UIKeyboardHIDUsageKeyboardCapsLock) {
      [self synthesizeCapsLockTapWithTimestamp:press.timestamp];
    }
    flagDifference &= ~kModifierFlagCapsLock;
  }
  while (true) {
    const UInt32 currentFlag = lowestSetBit(flagDifference);
    if (currentFlag == 0) {
      break;
    }
    flagDifference &= ~currentFlag;
    if (currentFlag & kModifierFlagAnyMask) {
      // Skip synthesizing keys for the "any" flags, since their synthesis will
      // be handled when we do the sided flags. We still want them in the flags
      // of interest, though, so we can keep their state.
      continue;
    }
    auto keyCode = modifierFlagToKeyCode.find(static_cast<ModifierFlag>(currentFlag));
    NSAssert(keyCode != modifierFlagToKeyCode.end(), @"Invalid modifier flag of interest 0x%lx",
             static_cast<unsigned long>(currentFlag));
    if (keyCode == modifierFlagToKeyCode.end()) {
      continue;
    }
    // If this press matches the modifier key in question, then don't synthesize
    // it, because it's already a "real" keypress.
    if (keyCode->second == static_cast<UInt32>(press.key.keyCode)) {
      continue;
    }
    BOOL isDownEvent = currentFlagsOfInterest & currentFlag;
    [self synthesizeModifierEventOfType:isDownEvent
                              timestamp:press.timestamp
                                keyCode:keyCode->second];
  }
  _lastModifierFlagsOfInterest =
      (_lastModifierFlagsOfInterest & ~_modifierFlagOfInterestMask) | currentFlagsOfInterest;
}

synchronizeModifiers:ignoringFlags:timestamp:guard:

- (void) synchronizeModifiers: (NSUInteger)  currentFlags ignoringFlags: (NSUInteger)  ignoringFlags timestamp: (NSTimeInterval)  timestamp guard: (FlutterKeyCallbackGuard*)  guard

implementation

Definition at line 385 of file FlutterEmbedderKeyResponder.mm.

                            :(NSUInteger)currentFlags
               ignoringFlags:(NSUInteger)ignoringFlags
                   timestamp:(NSTimeInterval)timestamp
                       guard:(FlutterKeyCallbackGuard*)guard {
  const NSUInteger updatingMask = _modifierFlagOfInterestMask & ~ignoringFlags;
  const NSUInteger currentFlagsOfInterest = currentFlags & updatingMask;
  const NSUInteger lastFlagsOfInterest = _lastModifierFlagsOfInterest & updatingMask;
  NSUInteger flagDifference = currentFlagsOfInterest ^ lastFlagsOfInterest;
  if (flagDifference & NSEventModifierFlagCapsLock) {
    [self sendCapsLockTapWithTimestamp:timestamp synthesizeDown:true callback:guard];
    flagDifference = flagDifference & ~NSEventModifierFlagCapsLock;
  }
  while (true) {
    const NSUInteger currentFlag = lowestSetBit(flagDifference);
    if (currentFlag == 0) {
      break;
    }
    flagDifference = flagDifference & ~currentFlag;
    NSNumber* keyCode = [flutter::modifierFlagToKeyCode objectForKey:@(currentFlag)];
    NSAssert(keyCode != nil, @"Invalid modifier flag 0x%lx", currentFlag);
    if (keyCode == nil) {
      continue;
    }
    BOOL isDownEvent = (currentFlagsOfInterest & currentFlag) != 0;
    [self sendModifierEventOfType:isDownEvent
                        timestamp:timestamp
                          keyCode:[keyCode unsignedShortValue]
                      synthesized:true
                         callback:guard];
  }
  _lastModifierFlagsOfInterest =
      (_lastModifierFlagsOfInterest & ~updatingMask) | currentFlagsOfInterest;
}

syncModifiersIfNeeded:timestamp:

- (void) syncModifiersIfNeeded:		(NSEventModifierFlags)	modifierFlags
timestamp:		(NSTimeInterval)	timestamp

Synthesize modifier keys events.

If needed, synthesize modifier keys up and down events by comparing their current pressing states with the given modifier flags.

Reimplemented from <FlutterKeyPrimaryResponder>.

Definition at line 385 of file FlutterEmbedderKeyResponder.mm.

                             :(NSEventModifierFlags)modifierFlags
                    timestamp:(NSTimeInterval)timestamp {
  FlutterAsyncKeyCallback replyCallback = ^(BOOL handled) {
    // Do nothing.
  };
  FlutterKeyCallbackGuard* guardedCallback =
      [[FlutterKeyCallbackGuard alloc] initWithCallback:replyCallback];
  [self synchronizeModifiers:modifierFlags
               ignoringFlags:0
                   timestamp:timestamp
                       guard:guardedCallback];
}

synthesizeCapsLockTapWithTimestamp:

- (void) synthesizeCapsLockTapWithTimestamp: (NSTimeInterval)  timestamp

implementation

Synthesize a CapsLock down event, then a CapsLock up event.

Definition at line 405 of file FlutterEmbedderKeyResponder.mm.

                                          :(NSTimeInterval)timestamp {
  // The assumption when the app starts is that caps lock is off, but if that
  // turns out to be untrue (according to the modifier flags), then this is used
  // to simulate a key down and a key up of the caps lock key, to simulate
  // toggling of that state in the framework.
  FlutterKeyEvent flutterEvent = {
      .struct_size = sizeof(FlutterKeyEvent),
      .timestamp = GetFlutterTimestampFrom(timestamp),
      .type = kFlutterKeyEventTypeDown,
      .physical = kCapsLockPhysicalKey,
      .logical = kCapsLockLogicalKey,
      .character = nil,
      .synthesized = true,
      .device_type = kFlutterKeyEventDeviceTypeKeyboard,
  };
  _sendEvent(flutterEvent, nullptr, nullptr);
 
  flutterEvent.type = kFlutterKeyEventTypeUp;
  _sendEvent(flutterEvent, nullptr, nullptr);
}

synthesizeModifierEventOfType:timestamp:keyCode:

- (void) synthesizeModifierEventOfType: (BOOL)  isDownEvent timestamp: (NSTimeInterval)  timestamp keyCode: (UInt32)  keyCode

implementation

Send a key event for a modifier key.

Definition at line 405 of file FlutterEmbedderKeyResponder.mm.

                                     :(BOOL)isDownEvent
                            timestamp:(NSTimeInterval)timestamp
                              keyCode:(UInt32)keyCode {
  uint64_t physicalKey = GetPhysicalKeyForKeyCode(keyCode);
  uint64_t logicalKey = GetLogicalKeyForModifier(keyCode, physicalKey);
  if (physicalKey == 0 || logicalKey == 0) {
    return;
  }
  FlutterKeyEvent flutterEvent = {
      .struct_size = sizeof(FlutterKeyEvent),
      .timestamp = GetFlutterTimestampFrom(timestamp),
      .type = isDownEvent ? kFlutterKeyEventTypeDown : kFlutterKeyEventTypeUp,
      .physical = physicalKey,
      .logical = logicalKey,
      .character = nil,
      .synthesized = true,
      .device_type = kFlutterKeyEventDeviceTypeKeyboard,
  };
  [self updateKey:physicalKey asPressed:isDownEvent ? logicalKey : 0];
  _sendEvent(flutterEvent, nullptr, nullptr);
}

updateKey:asPressed:

- (void) updateKey: (uint64_t)  physicalKey asPressed: (uint64_t)  logicalKey

implementation

Update the pressing state.

If logicalKey is not 0, physicalKey is pressed as logicalKey. Otherwise, physicalKey is released.

Definition at line 405 of file FlutterEmbedderKeyResponder.mm.

                 :(uint64_t)physicalKey asPressed:(uint64_t)logicalKey {
  if (logicalKey == 0) {
    [_pressingRecords removeObjectForKey:@(physicalKey)];
  } else {
    _pressingRecords[@(physicalKey)] = @(logicalKey);
  }
}

Property Documentation

lastModifierFlagsOfInterest

- (NSUInteger) lastModifierFlagsOfInterest

readwritenonatomicassignimplementation

The modifier flags of the last received key event, excluding uninterested bits.

This should be kept synchronized with the last |NSEvent.modifierFlags| after masking with |modifierFlagOfInterestMask|. This should also be kept synchronized with the corresponding keys of |pressingRecords|.

This is used by |synchronizeModifiers| to quickly find out modifier keys that are desynchronized.

Provided by category FlutterEmbedderKeyResponder().

Definition at line 391 of file FlutterEmbedderKeyResponder.mm.

modifierFlagOfInterestMask

- (NSUInteger) modifierFlagOfInterestMask

readwritenonatomicassignimplementation

A constant mask for NSEvent.modifierFlags that Flutter synchronizes with.

Flutter keeps track of the last |modifierFlags| and compares it with the incoming one. Any bit within |modifierFlagOfInterestMask| that is different (except for the one that corresponds to the event key) indicates that an event for this modifier was missed, and Flutter synthesizes an event to make up for the state difference.

It is computed by computeModifierFlagOfInterestMask.

Provided by category FlutterEmbedderKeyResponder().

Definition at line 378 of file FlutterEmbedderKeyResponder.mm.

pendingResponses

- (NSMutableDictionary<NSNumber*, FlutterAsyncKeyCallback>*) pendingResponses

readwritenonatomicassignimplementation

A map of unresponded key events sent to the framework.

Its values are |responseId|s, and keys are the callback that was received along with the event.

Provided by category FlutterEmbedderKeyResponder().

Definition at line 405 of file FlutterEmbedderKeyResponder.mm.

pressingRecords

- (NSMutableDictionary<NSNumber*, NSNumber*>*) pressingRecords

readwritenonatomicassignimplementation

A map of pressed keys.

The keys of the dictionary are physical keys, while the values are the logical keys of the key down event.

A map of presessd keys.

The keys of the dictionary are physical keys, while the values are the logical keys of the key down event.

Provided by category FlutterEmbedderKeyResponder().

Definition at line 365 of file FlutterEmbedderKeyResponder.mm.

responseId

- (uint64_t) responseId

readwritenonatomicassignimplementation

A self-incrementing ID used to label key events sent to the framework.

Provided by category FlutterEmbedderKeyResponder().

Definition at line 396 of file FlutterEmbedderKeyResponder.mm.

sendEvent [1/2]

- (FlutterSendKeyEvent) sendEvent

readnonatomiccopyimplementation

The function to send converted events to.

Set by the initializer.

Provided by category FlutterEmbedderKeyResponder(Tests).

Definition at line 357 of file FlutterEmbedderKeyResponder.mm.

sendEvent [2/2]

- (FlutterSendEmbedderKeyEvent) sendEvent

readwritenonatomiccopyimplementation

The function to send converted events to.

Set by the initializer.

Provided by category FlutterEmbedderKeyResponder().

Definition at line 338 of file FlutterEmbedderKeyResponder.mm.

---

The documentation for this class was generated from the following files:

• shell/platform/darwin/ios/framework/Source/FlutterEmbedderKeyResponder.h
• shell/platform/darwin/macos/framework/Source/FlutterEmbedderKeyResponder.h
• shell/platform/darwin/ios/framework/Source/FlutterEmbedderKeyResponder.mm
• shell/platform/darwin/macos/framework/Source/FlutterEmbedderKeyResponder.mm