Deprecate InputMethodService#getInputMethodWindowRecommendedHeight()

InputMethodService#getInputMethodWindowRecommendedHeight() was added
with an assumption that some IMEs may want to call this API in
InputMethodService#onCreate() to adjust its IME window height to be
the same as the previous IME's window height [1], but in reality for
IME developers this API is quite difficult to use because relying on
this API means user-visible behavior is no longer deterministic.
Basically "Recommended" is too vague to rely on.

Let's deprecate this API before we end up having to define what is the
"recommended" height for more complicated scenarios such as
multi-displays and multi-profiles.

With this CL, IMS##getInputMethodWindowRecommendedHeight() always
returns 0.  Basically doing this would not likely to cause
compatibility issues because the possibility of returning 0 has been
clearly mentioned in the API document.  In practice this must have
returned 0 when the previous IME did not show the software keyboard
(e.g. AOSP keyboard with a hardware keyboard).  Therefore IMEs that
have correctly used this API should be able to fall back to a safe
default behavior even if this API returns 0.

 [1]: I0e920ee79c526c3aea6872b063cf294e2ab081c8
      658c7b896a751b971db1292d86655dbb97f00067

Fix: 116502957
Test: atest CtsInputMethodTestCases CtsInputMethodServiceHostTestCases
Change-Id: Ia2cde031a0e67d45a3631e54226f9b5a0698dd61

1 files changed, 14 insertions, 10 deletions

diff --git a/core/java/android/inputmethodservice/InputMethodService.java b/core/java/android/inputmethodservice/InputMethodService.java
index ae12f93285a8..f7f627ebedc2 100644
--- a/core/java/android/inputmethodservice/InputMethodService.java
+++ b/core/java/android/inputmethodservice/InputMethodService.java
@@ -2803,18 +2803,22 @@ public class InputMethodService extends AbstractInputMethodService {
     }
 
     /**
-     * @return The recommended height of the input method window.
-     * An IME author can get the last input method's height as the recommended height
-     * by calling this in
-     * {@link android.inputmethodservice.InputMethodService#onStartInputView(EditorInfo, boolean)}.
-     * If you don't need to use a predefined fixed height, you can avoid the window-resizing of IME
-     * switching by using this value as a visible inset height. It's efficient for the smooth
-     * transition between different IMEs. However, note that this may return 0 (or possibly
-     * unexpectedly low height). You should thus avoid relying on the return value of this method
-     * all the time. Please make sure to use a reasonable height for the IME.
+     * Aimed to return the previous input method's {@link Insets#contentTopInsets}, but its actual
+     * semantics has never been well defined.
+     *
+     * <p>Note that the previous document clearly mentioned that this method could return {@code 0}
+     * at any time for whatever reason.  Now this method is just always returning {@code 0}.</p>
+     *
+     * @return on Android {@link android.os.Build.VERSION_CODES#Q} and later devices this method
+     *         always returns {@code 0}
+     * @deprecated the actual behavior of this method has never been well defined.  You cannot use
+     *             this method in a reliable and predictable way
      */
+    @Deprecated
     public int getInputMethodWindowRecommendedHeight() {
-        return mImm.getInputMethodWindowVisibleHeight();
+        Log.w(TAG, "getInputMethodWindowRecommendedHeight() is deprecated and now always returns 0."
+                + " Do not use this method.");
+        return 0;
     }
 
     /**