#include <FlutterKeyboardManager.h>

Inheritance diagram for FlutterKeyboardManager:

Instance Methods
(void)	- addPrimaryResponder:

(void)	- addSecondaryResponder:

(void)	- handlePress:nextAction:

(nonnull instancetype)	- initWithViewDelegate:

(void)	- handleEvent:

(BOOL)	- isDispatchingKeyEvent:

(void)	- syncModifiersIfNeeded:timestamp:

(nonnull NSDictionary *)	- getPressedState

(nonnull instancetype)	- init `[implementation]`

(void)	- dispatchToSecondaryResponders:complete: `[implementation]`

(void)	- handleKeyboardMethodCall:result: `[implementation]`

(BOOL)	- isDispatchingKeyEvent: `[implementation]`

(void)	- processNextEvent `[implementation]`

(void)	- performProcessEvent:onFinish: `[implementation]`

(void)	- dispatchTextEvent: `[implementation]`

(void)	- buildLayout `[implementation]`

Properties
NSMutableArray< id< FlutterKeyPrimaryResponder > > *	primaryResponders `[implementation]`

NSMutableArray< id< FlutterKeySecondaryResponder > > *	secondaryResponders `[implementation]`

id< FlutterKeyboardViewDelegate >	viewDelegate `[implementation]`

NSMutableArray< NSEvent * > *	pendingEvents `[implementation]`

BOOL	processingEvent `[implementation]`

NSMutableDictionary< NSNumber , NSNumber > *	layoutMap `[implementation]`

NSEvent *	eventBeingDispatched `[implementation]`

Detailed Description

A hub that manages how key events are dispatched to various Flutter key responders, and propagates it to the superclass if the Flutter key responders do not handle it.

This class manages one or more primary responders, as well as zero or more secondary responders.

An event that is received by |handlePresses| is first dispatched to all primary responders. Each primary responder responds asynchronously with a boolean, indicating whether it handles the event.

An event that is not handled by any primary responders is then passed to to the first secondary responder (in the chronological order of addition), which responds synchronously with a boolean, indicating whether it handles the event. If not, the event is passed to the next secondary responder, and so on.

The event is then handed back to the |completeCallback| from the original call to |handlePresses| so that it can respond synchronously to the OS if the event was not handled by the responders. The |completeCallback| is called on the platform thread because the platform thread is blocked by a nested event loop while the response from the framework is being collected, and it needs to be called on the platform thread to unblock the thread by exiting the nested event loop.

Preventing primary responders from receiving events is not supported, because in reality this class only supports two hardcoded responders (FlutterChannelKeyResponder and FlutterEmbedderKeyResponder), where the only purpose of supporting two is to maintain the legacy channel API during the deprecation window, after which the channel responder should be removed, and only one primary responder will exist.

Processes keyboard events and cooperate with |TextInputPlugin|.

A keyboard event goes through a few sections, each can choose to handled the event, and only unhandled events can move to the next section:

Pre-filtering: Events during IME are sent to the system immediately.
Keyboard: Dispatch to the embedder responder and the channel responder simultaneously. After both responders have responded (asynchronously), the event is considered handled if either responder handles.
Text input: Events are sent to |TextInputPlugin| and are handled synchronously.
Next responder: Events are sent to the next responder as specified by |viewDelegate|.

Definition at line 53 of file FlutterKeyboardManager.h.

Method Documentation

◆ addPrimaryResponder:

- (void) addPrimaryResponder: (nonnull id<FlutterKeyPrimaryResponder>) responder

Add a primary responder, which asynchronously decides whether to handle an event.

Definition at line 26 of file FlutterKeyboardManager.mm.

                           :(nonnull id<FlutterKeyPrimaryResponder>)responder {
  [_primaryResponders addObject:responder];
}

◆ addSecondaryResponder:

- (void) addSecondaryResponder: (nonnull id<FlutterKeySecondaryResponder>) responder

Add a secondary responder, which synchronously decides whether to handle an event in order if no earlier responders handle.

Definition at line 26 of file FlutterKeyboardManager.mm.

                             :(nonnull id<FlutterKeySecondaryResponder>)responder {
  [_secondaryResponders addObject:responder];
}

◆ buildLayout

- (void) buildLayout

implementation

Clears the current layout and build a new one based on the current layout.

Definition at line 73 of file FlutterKeyboardManager.mm.

                    {
  [_layoutMap removeAllObjects];
 
  std::map<uint32_t, LayoutGoal> mandatoryGoalsByChar;
  std::map<uint32_t, LayoutGoal> usLayoutGoalsByKeyCode;
  for (const LayoutGoal& goal : flutter::kLayoutGoals) {
    if (goal.mandatory) {
      mandatoryGoalsByChar[goal.keyChar] = goal;
    } else {
      usLayoutGoalsByKeyCode[goal.keyCode] = goal;
    }
  }
 
  // Derive key mapping for each key code based on their layout clues.
  // Key code 0x00 - 0x32 are typewriter keys (letters, digits, and symbols.)
  // See keyCodeToPhysicalKey.
  const uint16_t kMaxKeyCode = 0x32;
#ifdef DEBUG_PRINT_LAYOUT
  NSString* debugLayoutData = @"";
#endif
  for (uint16_t keyCode = 0; keyCode <= kMaxKeyCode; keyCode += 1) {
    std::vector<LayoutClue> thisKeyClues = {
        [_viewDelegate lookUpLayoutForKeyCode:keyCode shift:false],
        [_viewDelegate lookUpLayoutForKeyCode:keyCode shift:true]};
#ifdef DEBUG_PRINT_LAYOUT
    debugLayoutData =
        debugFormatLayoutData(debugLayoutData, keyCode, thisKeyClues[0], thisKeyClues[1]);
#endif
    // The logical key should be the first available clue from below:
    //
    //  - Mandatory goal, if it matches any clue. This ensures that all alnum
    //    keys can be found somewhere.
    //  - US layout, if neither clue of the key is EASCII. This ensures that
    //    there are no non-latin logical keys.
    //  - Derived on the fly from keyCode & characters.
    for (const LayoutClue& clue : thisKeyClues) {
      uint32_t keyChar = clue.isDeadKey ? 0 : clue.character;
      auto matchingGoal = mandatoryGoalsByChar.find(keyChar);
      if (matchingGoal != mandatoryGoalsByChar.end()) {
        // Found a key that produces a mandatory char. Use it.
        NSAssert(_layoutMap[@(keyCode)] == nil, @"Attempting to assign an assigned key code.");
        _layoutMap[@(keyCode)] = @(keyChar);
        mandatoryGoalsByChar.erase(matchingGoal);
        break;
      }
    }
    bool hasAnyEascii = isEascii(thisKeyClues[0]) || isEascii(thisKeyClues[1]);
    // See if any produced char meets the requirement as a logical key.
    auto foundUsLayoutGoal = usLayoutGoalsByKeyCode.find(keyCode);
    if (foundUsLayoutGoal != usLayoutGoalsByKeyCode.end() && _layoutMap[@(keyCode)] == nil &&
        !hasAnyEascii) {
      _layoutMap[@(keyCode)] = @(foundUsLayoutGoal->second.keyChar);
    }
  }
#ifdef DEBUG_PRINT_LAYOUT
  NSLog(@"%@", debugLayoutData);
#endif
 
  // Ensure all mandatory goals are assigned.
  for (auto mandatoryGoalIter : mandatoryGoalsByChar) {
    const LayoutGoal& goal = mandatoryGoalIter.second;
    _layoutMap[@(goal.keyCode)] = @(goal.keyChar);
  }
}

◆ dispatchTextEvent:

- (void) dispatchTextEvent: (NSEvent*) event

implementation

Definition at line 73 of file FlutterKeyboardManager.mm.

                         :(NSEvent*)event {
  if ([_viewDelegate onTextInputKeyEvent:event]) {
    return;
  }
  NSResponder* nextResponder = _viewDelegate.nextResponder;
  if (nextResponder == nil) {
    return;
  }
  NSAssert(_eventBeingDispatched == nil, @"An event is already being dispached.");
  _eventBeingDispatched = event;
  switch (event.type) {
    case NSEventTypeKeyDown:
      if ([nextResponder respondsToSelector:@selector(keyDown:)]) {
        [nextResponder keyDown:event];
      }
      break;
    case NSEventTypeKeyUp:
      if ([nextResponder respondsToSelector:@selector(keyUp:)]) {
        [nextResponder keyUp:event];
      }
      break;
    case NSEventTypeFlagsChanged:
      if ([nextResponder respondsToSelector:@selector(flagsChanged:)]) {
        [nextResponder flagsChanged:event];
      }
      break;
    default:
      NSAssert(false, @"Unexpected key event type (got %lu).", event.type);
  }
  NSAssert(_eventBeingDispatched != nil, @"_eventBeingDispatched was cleared unexpectedly.");
  _eventBeingDispatched = nil;
}

◆ dispatchToSecondaryResponders:complete:

- (void) dispatchToSecondaryResponders:	(nonnull FlutterUIPressProxy*)	press
complete:	(ios(13.4))	API_AVAILABLE

implementation

Definition at line 26 of file FlutterKeyboardManager.mm.

                                     :(nonnull FlutterUIPressProxy*)press
                             complete:(nonnull KeyEventCompleteCallback)callback
    API_AVAILABLE(ios(13.4)) {
  if (@available(iOS 13.4, *)) {
    // no-op
  } else {
    callback(false, press);
    return;
  }
 
  for (id<FlutterKeySecondaryResponder> responder in _secondaryResponders) {
    if ([responder handlePress:press]) {
      callback(true, press);
      return;
    }
  }
  callback(false, press);
}

◆ 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 73 of file FlutterKeyboardManager.mm.

                                         {
  // The embedder responder is the first element in _primaryResponders.
  FlutterEmbedderKeyResponder* embedderResponder =
      (FlutterEmbedderKeyResponder*)_primaryResponders[0];
  return [embedderResponder getPressedState];
}

◆ handleEvent:

- (void) handleEvent: (nonnull NSEvent*) event

Processes a key event.

Unhandled events will be dispatched to the text input system, and possibly the next responder afterwards.

Definition at line 73 of file FlutterKeyboardManager.mm.

                   :(nonnull NSEvent*)event {
  // The `handleEvent` does not process the event immediately, but instead put
  // events into a queue. Events are processed one by one by `processNextEvent`.
 
  // Be sure to add a handling method in propagateKeyEvent when allowing more
  // event types here.
  if (event.type != NSEventTypeKeyDown && event.type != NSEventTypeKeyUp &&
      event.type != NSEventTypeFlagsChanged) {
    return;
  }
 
  [_pendingEvents addObject:event];
  [self processNextEvent];
}

◆ handleKeyboardMethodCall:result:

- (void) handleKeyboardMethodCall:	(FlutterMethodCall*)	call
result:	(FlutterResult)	result

implementation

Definition at line 73 of file FlutterKeyboardManager.mm.

                                :(FlutterMethodCall*)call result:(FlutterResult)result {
  if ([[call method] isEqualToString:@"getKeyboardState"]) {
    result([self getPressedState]);
  } else {
    result(FlutterMethodNotImplemented);
  }
}

◆ handlePress:nextAction:

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

Dispatches a key press event to all responders, gathering their responses, and then calls the |nextAction| if the event was not handled.

Definition at line 26 of file FlutterKeyboardManager.mm.

                   :(nonnull FlutterUIPressProxy*)press
         nextAction:(nonnull void (^)())next API_AVAILABLE(ios(13.4)) {
  if (@available(iOS 13.4, *)) {
    // no-op
  } else {
    return;
  }
 
  bool __block wasHandled = false;
  KeyEventCompleteCallback completeCallback = ^void(bool handled, FlutterUIPressProxy* press) {
    wasHandled = handled;
    CFRunLoopStop(CFRunLoopGetCurrent());
  };
  switch (press.phase) {
    case UIPressPhaseBegan:
    case UIPressPhaseEnded: {
      // Having no primary responders requires extra logic, but Flutter hard-codes
      // all primary responders, so this is a situation that Flutter will never
      // encounter.
      NSAssert([_primaryResponders count] >= 0, @"At least one primary responder must be added.");
 
      __block __weak __typeof(self) weakSelf = self;
      __block NSUInteger unreplied = [self.primaryResponders count];
      __block BOOL anyHandled = false;
      FlutterAsyncKeyCallback replyCallback = ^(BOOL handled) {
        unreplied--;
        NSAssert(unreplied >= 0, @"More primary responders replied than expected.");
        anyHandled = anyHandled || handled;
        if (unreplied == 0) {
          if (!anyHandled && weakSelf) {
            [weakSelf dispatchToSecondaryResponders:press complete:completeCallback];
          } else {
            completeCallback(true, press);
          }
        }
      };
      for (id<FlutterKeyPrimaryResponder> responder in _primaryResponders) {
        [responder handlePress:press callback:replyCallback];
      }
      // Create a nested run loop while we wait for a response from the
      // framework. Once the completeCallback is called, this run loop will exit
      // and the main one will resume. The completeCallback MUST be called, or
      // the app will get stuck in this run loop indefinitely.
      //
      // We need to run in this mode so that UIKit doesn't give us new
      // events until we are done processing this one.
      CFRunLoopRunInMode(fml::MessageLoopDarwin::kMessageLoopCFRunLoopMode, kDistantFuture, NO);
      break;
    }
    case UIPressPhaseChanged:
    case UIPressPhaseCancelled:
    case UIPressPhaseStationary:
      break;
  }
  if (!wasHandled) {
    next();
  }
}

◆ init

- (nonnull instancetype) init

implementation

Definition at line 26 of file FlutterKeyboardManager.mm.

                             {
  self = [super init];
  if (self != nil) {
    _primaryResponders = [[NSMutableArray alloc] init];
    _secondaryResponders = [[NSMutableArray alloc] init];
  }
  return self;
}

◆ initWithViewDelegate:

- (nonnull instancetype) initWithViewDelegate: (nonnull id<FlutterKeyboardViewDelegate>) viewDelegate

Initial value:

{

NextResponderProvider _getNextResponder

Create a keyboard manager.

The |viewDelegate| is a weak reference, typically implemented by |FlutterViewController|.

Definition at line 73 of file FlutterKeyboardManager.mm.

                                            :(nonnull id<FlutterKeyboardViewDelegate>)viewDelegate {
  self = [super init];
  if (self != nil) {
    _processingEvent = FALSE;
    _viewDelegate = viewDelegate;
 
    FlutterMethodChannel* keyboardChannel =
        [FlutterMethodChannel methodChannelWithName:@"flutter/keyboard"
                                    binaryMessenger:[_viewDelegate getBinaryMessenger]
                                              codec:[FlutterStandardMethodCodec sharedInstance]];
 
    [keyboardChannel setMethodCallHandler:^(FlutterMethodCall* call, FlutterResult result) {
      [self handleKeyboardMethodCall:call result:result];
    }];
 
    _primaryResponders = [[NSMutableArray alloc] init];
 
    __weak __typeof__(self) weakSelf = self;
    [self addPrimaryResponder:[[FlutterEmbedderKeyResponder alloc]
                                  initWithSendEvent:^(const FlutterKeyEvent& event,
                                                      FlutterKeyEventCallback callback,
                                                      void* userData) {
                                    __strong __typeof__(weakSelf) strongSelf = weakSelf;
                                    [strongSelf.viewDelegate sendKeyEvent:event
                                                                 callback:callback
                                                                 userData:userData];
                                  }]];
 
    [self
        addPrimaryResponder:[[FlutterChannelKeyResponder alloc]
                                initWithChannel:[FlutterBasicMessageChannel
                                                    messageChannelWithName:@"flutter/keyevent"
                                                           binaryMessenger:[_viewDelegate
                                                                               getBinaryMessenger]
                                                                     codec:[FlutterJSONMessageCodec
                                                                               sharedInstance]]]];
 
    _pendingEvents = [[NSMutableArray alloc] init];
    _layoutMap = [NSMutableDictionary<NSNumber*, NSNumber*> dictionary];
    [self buildLayout];
    for (id<FlutterKeyPrimaryResponder> responder in _primaryResponders) {
      responder.layoutMap = _layoutMap;
    }
 
    [_viewDelegate subscribeToKeyboardLayoutChange:^() {
      [weakSelf buildLayout];
    }];
  }
  return self;
}

◆ isDispatchingKeyEvent: [1/2]

- (BOOL) isDispatchingKeyEvent: (nonnull NSEvent *) event

Returns yes if is event currently being redispatched.

In some instances (i.e. emoji shortcut) the event may be redelivered by cocoa as key equivalent to FlutterTextInput, in which case it shouldn't be processed again.

◆ isDispatchingKeyEvent: [2/2]

- (BOOL) isDispatchingKeyEvent: (NSEvent*) event

implementation

Definition at line 73 of file FlutterKeyboardManager.mm.

                             :(NSEvent*)event {
  return _eventBeingDispatched == event;
}

◆ performProcessEvent:onFinish:

- (void) performProcessEvent:	(NSEvent*)	event
onFinish:	(VoidBlock)	onFinish

implementation

Definition at line 73 of file FlutterKeyboardManager.mm.

                           :(NSEvent*)event onFinish:(VoidBlock)onFinish {
  // Having no primary responders require extra logic, but Flutter hard-codes
  // all primary responders, so this is a situation that Flutter will never
  // encounter.
  NSAssert([_primaryResponders count] >= 0, @"At least one primary responder must be added.");
 
  __weak __typeof__(self) weakSelf = self;
  __block int unreplied = [_primaryResponders count];
  __block BOOL anyHandled = false;
 
  FlutterAsyncKeyCallback replyCallback = ^(BOOL handled) {
    unreplied -= 1;
    NSAssert(unreplied >= 0, @"More primary responders replied than possible.");
    anyHandled = anyHandled || handled;
    if (unreplied == 0) {
      if (!anyHandled) {
        [weakSelf dispatchTextEvent:event];
      }
      onFinish();
    }
  };
 
  for (id<FlutterKeyPrimaryResponder> responder in _primaryResponders) {
    [responder handleEvent:event callback:replyCallback];
  }
}

◆ processNextEvent

- (void) processNextEvent

implementation

Start processing the next event if not started already.

This function might initiate an async process, whose callback calls this function again.

Definition at line 73 of file FlutterKeyboardManager.mm.

                         {
  @synchronized(self) {
    if (_processingEvent || [_pendingEvents count] == 0) {
      return;
    }
    _processingEvent = TRUE;
  }
 
  NSEvent* pendingEvent = [_pendingEvents firstObject];
  [_pendingEvents removeObjectAtIndex:0];
 
  __weak __typeof__(self) weakSelf = self;
  VoidBlock onFinish = ^() {
    weakSelf.processingEvent = FALSE;
    [weakSelf processNextEvent];
  };
  [self performProcessEvent:pendingEvent onFinish:onFinish];
}

◆ 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.

Definition at line 73 of file FlutterKeyboardManager.mm.

                             :(NSEventModifierFlags)modifierFlags
                    timestamp:(NSTimeInterval)timestamp {
  for (id<FlutterKeyPrimaryResponder> responder in _primaryResponders) {
    [responder syncModifiersIfNeeded:modifierFlags timestamp:timestamp];
  }
}