split AndroidKeyProcessor into different classes

Author: LongCatIsLooong

shell/platform/android/io/flutter/embedding/android/AndroidKeyProcessor.java

@@ -5,46 +5,11 @@
 package io.flutter.embedding.android;
 
 import android.view.KeyCharacterMap;
-import androidx.annotation.Nullable;
 
-/**
- * A class to process key events from Android, passing them to the framework as messages using
- * {@link KeyEventChannel}.
- *
- * <p>A class that sends Android key events to the framework, and re-dispatches those not handled by
- * the framework.
- *
- * <p>Flutter uses asynchronous event handling to avoid blocking the UI thread, but Android requires
- * that events are handled synchronously. So, when a key event is received by Flutter, it tells
- * Android synchronously that the key has been handled so that it won't propagate to other
- * components. Flutter then uses "delayed event synthesis", where it sends the event to the
- * framework, and if the framework responds that it has not handled the event, then this class
- * synthesizes a new event to send to Android, without handling it this time.
- */
+/** A class for handling combining characters in a {@link KeyEvent} stream. */
 class AndroidKeyProcessor {
   private int combiningCharacter;
 
-  /**
-   * Constructor for AndroidKeyProcessor.
-   *
-   * <p>The view is used as the destination to send the synthesized key to. This means that the the
-   * next thing in the focus chain will get the event when the framework returns false from
-   * onKeyDown/onKeyUp
-   *
-   * <p>It is possible that that in the middle of the async round trip, the focus chain could
-   * change, and instead of the native widget that was "next" when the event was fired getting the
-   * event, it may be the next widget when the event is synthesized that gets it. In practice, this
-   * shouldn't be a huge problem, as this is an unlikely occurrence to happen without user input,
-   * and it may actually be desired behavior, but it is possible.
-   *
-   * @param view takes the activity to use for re-dispatching of events that were not handled by the
-   *     framework.
-   * @param keyEventChannel the event channel to listen to for new key events.
-   * @param textInputPlugin a plugin, which, if set, is given key events before the framework is,
-   *     and if it has a valid input connection and is accepting text, then it will handle the event
-   *     and the framework will not receive it.
-   */
-
   /**
    * Applies the given Unicode character in {@code newCharacterCodePoint} to a previously entered
    * Unicode combining character and returns the combination of these characters if a combination
@@ -72,7 +37,6 @@ class AndroidKeyProcessor {
    * <p>The following reference explains the concept of a "combining character":
    * https://en.wikipedia.org/wiki/Combining_character
    */
-  @Nullable
   Character applyCombiningCharacterToBaseCharacter(int newCharacterCodePoint) {
     char complexCharacter = (char) newCharacterCodePoint;
     boolean isNewCodePointACombiningCharacter =

shell/platform/android/io/flutter/embedding/android/KeyChannelResponder.java

@@ -4,9 +4,7 @@
 import androidx.annotation.NonNull;
 import io.flutter.embedding.engine.systemchannels.KeyEventChannel;
 
-/**
- * A light wrapper around a {@link KeyEventChannel} that turns it into a {@link PrimaryResponder}.
- */
+/** A light wrapper around a {@link KeyEventChannel}, turning it into a {@link PrimaryResponder}. */
 class KeyChannelResponder implements KeyboardManager.PrimaryResponder {
   private static final String TAG = "KeyChannelResponder";
 
@@ -39,6 +37,5 @@ public void handleEvent(
         flutterEvent,
         isKeyUp,
         (isEventHandled) -> onKeyEventHandledCallback.onKeyEventHandled(isEventHandled));
-    return;
   }
 }

shell/platform/android/io/flutter/embedding/android/KeyboardManager.java

@@ -14,10 +14,11 @@
 import java.util.HashSet;
 
 /**
- * A class to process {@link KeyEvent}s dispatched to a {@link FlutterView}.
+ * A class to process {@link KeyEvent}s dispatched to a {@link FlutterView}, either from a hardware
+ * keyboard or an IME event.
  *
- * <p>A class that sends Android key events to the currently registered {@link PrimaryResponder}s,
- * and re-dispatches those not handled by the primary responders.
+ * <p>A class that sends Android {@link KeyEvent} to the currently registered {@link
+ * PrimaryResponder}s, and re-dispatches those not handled by the primary responders.
  *
  * <p>Flutter uses asynchronous event handling to avoid blocking the UI thread, but Android requires
  * that events are handled synchronously. So, when a key event is received by Flutter, it tells
@@ -26,19 +27,25 @@
  * framework, and if the framework responds that it has not handled the event, then this class
  * synthesizes a new event to send to Android, without handling it this time.
  *
- * <p>A new {@link KeyEvent} sent to a {@link KeyboardManager} may be processed by 3 different types
- * of "responder"s:
+ * <p>A new {@link KeyEvent} sent to a {@link KeyboardManager} can be propagated to 3 different
+ * types of "responder"s:
  *
  * <ul>
- *   <li>{@link PrimaryResponder}s: the {@link KeyboardManager} calls the {@link
- *       PrimaryResponder#handleEvent(KeyEvent, OnKeyEventHandledCallback)} method on the currently
- *       registered {@link PrimaryResponder}s. When each {@link PrimaryResponder} has decided wether
- *       to handle the key event, it must call the supplied {@link OnKeyEventHandledCallback}
+ *   <li>{@link PrimaryResponder}s: An immutable list of key responders in a {@link KeyboardManager}
+ *       that each implements the {@link PrimaryResponder} interface. a {@link PrimaryResponder} is
+ *       capable of handling {@link KeyEvent}s asynchronously.
+ *       <p>When a new {@link KeyEvent} is received, {@link KeyboardManager} calls the {@link
+ *       PrimaryResponder#handleEvent(KeyEvent, OnKeyEventHandledCallback)} method on its {@link
+ *       PrimaryResponder}s. Each {@link PrimaryResponder} must call the supplied {@link
+ *       OnKeyEventHandledCallback} exactly once, when it has decided wether to handle the key event
  *       callback. More than one {@link PrimaryResponder} is allowed to reply true and handle the
  *       same {@link KeyEvent}.
+ *       <p>Typically a {@link KeyboardManager} uses a {@link KeyChannelResponder} as its only
+ *       {@link PrimaryResponder}.
  *   <li>{@link TextInputPlugin}: if every {@link PrimaryResponder} has replied false to a {@link
- *       KeyEvent}, the {@link KeyEvent} will be sent to the currently focused editable text field
- *       in {@link TextInputPlugin}, if any.
+ *       KeyEvent}, or if the {@link KeyboardManager} has zero {@link PrimaryResponder}s, the {@link
+ *       KeyEvent} will be sent to the currently focused editable text field in {@link
+ *       TextInputPlugin}, if any.
  *   <li><b>"Redispatch"</b>: if there's no currently focused text field in {@link TextInputPlugin},
  *       or the text field does not handle the {@link KeyEvent} either, the {@link KeyEvent} will be
  *       sent back to the top of the activity's view hierachy, allowing the {@link KeyEvent} to be
@@ -56,6 +63,27 @@ public class KeyboardManager {
     this.primaryResponders = primaryResponders;
   }
 
+  /**
+   * Constructor for {@link KeyboardManager} that uses a {@link KeyChannelResponder} as its only
+   * {@link PrimaryResponder}.
+   *
+   * <p>The view is used as the destination to send the synthesized key to. This means that the the
+   * next thing in the focus chain will get the event when the {@link KeyChannelResponder} returns
+   * false from onKeyDown/onKeyUp.
+   *
+   * <p>It is possible that that in the middle of the async round trip, the focus chain could
+   * change, and instead of the native widget that was "next" when the event was fired getting the
+   * event, it may be the next widget when the event is synthesized that gets it. In practice, this
+   * shouldn't be a huge problem, as this is an unlikely occurrence to happen without user input,
+   * and it may actually be desired behavior, but it is possible.
+   *
+   * @param view takes the activity to use for re-dispatching of events that were not handled by the
+   *     framework.
+   * @param textInputPlugin a plugin, which, if set, is given key events before the framework is,
+   *     and if it has a valid input connection and is accepting text, then it will handle the event
+   *     and the framework will not receive it.
+   * @param keyEventChannel the event channel to listen to for new key events.
+   */
   public KeyboardManager(
       View view, @NonNull TextInputPlugin textInputPlugin, KeyEventChannel keyEventChannel) {
     this(
@@ -67,12 +95,14 @@ public KeyboardManager(
   /**
    * The interface for responding to a {@link KeyEvent} asynchronously.
    *
-   * <p>Implementers of this interface should be added to a {@link KeyboardManager} using the {@link
-   * KeyboardManager#addPrimaryResponder(PrimaryResponder)}, in order to receive key events.
+   * <p>Implementers of this interface should be owned by a {@link KeyboardManager}, in order to
+   * receive key events.
    *
    * <p>After receiving a {@link KeyEvent}, the {@link PrimaryResponder} must call the supplied
-   * {@link OnKeyEventHandledCallback} to inform the {@link KeyboardManager} whether it is capable
-   * of handling the {@link KeyEvent}.
+   * {@link OnKeyEventHandledCallback} exactly once, to inform the {@link KeyboardManager} whether
+   * it wishes to handle the {@link KeyEvent}. The {@link KeyEvent} will not be propagated to the
+   * {@link TextInputPlugin} or be redispatched to the view hierachy if the key responder answered
+   * yes.
    *
    * <p>If a {@link PrimaryResponder} fails to call the {@link OnKeyEventHandledCallback} callback,
    * the {@link KeyEvent} will never be sent to the {@link TextInputPlugin}, and the {@link
@@ -88,7 +118,7 @@ interface OnKeyEventHandledCallback {
      *
      * @param keyEvent the new {@link KeyEvent} this {@link PrimaryResponder} may be interested in.
      * @param onKeyEventHandledCallback the method to call when this {@link PrimaryResponder} has
-     *     decided whether to handle {@link keyEvent}.
+     *     decided whether to handle the {@link keyEvent}.
      */
     void handleEvent(
         @NonNull KeyEvent keyEvent, @NonNull OnKeyEventHandledCallback onKeyEventHandledCallback);