From bebf16c4948fb8dd890690c548a1f373f75b8e0e Mon Sep 17 00:00:00 2001
From: Yohei Yukawa <yukawa@google.com>
Date: Tue, 3 Aug 2021 18:32:03 -0700
Subject: [PATCH] Clarify how Handler is used in IC#getHandler()

Since its beginning [1] the system has been using

  InputConnection#getHandler()

only for retrieving Looper associated with it.  Although it has been
intentional, it'd be probably helpful for app developers if we can
clarify a bit more on this, because most likely the current behavior
is not going to change.

This CL also annotates the API with @Nullable as it should have been.

 [1]: Id9e579bb3e2966986cdcb1c34bc8cacfeca2e1a9
      612cce92ad96eda1146c3abd2afa7aaa4d4f2b3f

Bug: 26945674
Fix: 195434171
Test: presubmit
Change-Id: I14910c6f0cc43feec505b2951625d0c00203ac92
---
 core/api/current.txt                               |  2 +-
 .../android/view/inputmethod/InputConnection.java  | 14 ++++++++++----
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/core/api/current.txt b/core/api/current.txt
index 4c1476cc3b33f..5435f5ef97263 100644
--- a/core/api/current.txt
+++ b/core/api/current.txt
@@ -51933,7 +51933,7 @@ package android.view.inputmethod {
     method public boolean finishComposingText();
     method public int getCursorCapsMode(int);
     method public android.view.inputmethod.ExtractedText getExtractedText(android.view.inputmethod.ExtractedTextRequest, int);
-    method public android.os.Handler getHandler();
+    method @Nullable public android.os.Handler getHandler();
     method public CharSequence getSelectedText(int);
     method @Nullable public default android.view.inputmethod.SurroundingText getSurroundingText(@IntRange(from=0) int, @IntRange(from=0) int, int);
     method @Nullable public CharSequence getTextAfterCursor(@IntRange(from=0) int, int);
diff --git a/core/java/android/view/inputmethod/InputConnection.java b/core/java/android/view/inputmethod/InputConnection.java
index 5f036a3488083..abcb38fa44bd4 100644
--- a/core/java/android/view/inputmethod/InputConnection.java
+++ b/core/java/android/view/inputmethod/InputConnection.java
@@ -927,14 +927,20 @@ public interface InputConnection {
     boolean requestCursorUpdates(int cursorUpdateMode);
 
     /**
-     * Called by the {@link InputMethodManager} to enable application developers to specify a
-     * dedicated {@link Handler} on which incoming IPC method calls from input methods will be
-     * dispatched.
+     * Called by the system to enable application developers to specify a dedicated thread on which
+     * {@link InputConnection} methods are called back.
      *
-     * <p>Note: This does nothing when called from input methods.</p>
+     * <p><strong>Editor authors</strong>: although you can return your custom subclasses of
+     * {@link Handler}, the system only uses {@link android.os.Looper} returned from
+     * {@link Handler#getLooper()}.  You cannot intercept or cancel {@link InputConnection}
+     * callbacks by implementing this method.</p>
+     *
+     * <p><strong>IME authors</strong>: This method is not intended to be called from the IME.  You
+     * will always receive {@code null}.</p>
      *
      * @return {@code null} to use the default {@link Handler}.
      */
+    @Nullable
     Handler getHandler();
 
     /**