Deprecate InputMethodService#onViewClicked()

This CL marks InputMethodService#onViewClicked() deprecated.  There is
no actual implementation change at this moment, but developers should
avoid relying on this callback in general not only on futuer versions
of Android but also on existing devices.

Since this API was implemented in Android 4.0 ICS [1] it never worked
well for WebView and any other UI libraries that expose themselves as
a giant "Canvas", which can host their own UI hierarchy and sub focus
state.

If IME developers want consistent and reliable user interaction across
devices and applicactions, implementing IMEs' own UI on top of
CursorAnchorInfo API would be a good choice.

If IME developers just want to be notified an existing input
connection is interrupted, they can just monitor
InputMethodService#onFinishInput().

 [1]: Ia71ad325e50a20e9e1001def662ef992bb50a9d0
      863fcd62171e55bc9f2105d9fb5877df982454d8

Fix: 123245358
Test: make -j checkbuild
Change-Id: I37a6c6d82d4a424f0df84633b09bca4881efbf02

3 files changed, 17 insertions, 2 deletions

diff --git a/api/current.txt b/api/current.txt
index 1520a01a3965..b5be7c7bb903 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -22253,7 +22253,7 @@ package android.inputmethodservice {
     method public void onUpdateExtractingViews(android.view.inputmethod.EditorInfo);
     method public void onUpdateExtractingVisibility(android.view.inputmethod.EditorInfo);
     method public void onUpdateSelection(int, int, int, int, int, int);
-    method public void onViewClicked(boolean);
+    method @Deprecated public void onViewClicked(boolean);
     method public void onWindowHidden();
     method public void onWindowShown();
     method public void requestHideSelf(int);
@@ -52976,7 +52976,7 @@ package android.view.inputmethod {
     method public void updateCursorAnchorInfo(android.view.View, android.view.inputmethod.CursorAnchorInfo);
     method public void updateExtractedText(android.view.View, int, android.view.inputmethod.ExtractedText);
     method public void updateSelection(android.view.View, int, int, int, int);
-    method public void viewClicked(android.view.View);
+    method @Deprecated public void viewClicked(android.view.View);
     field public static final int HIDE_IMPLICIT_ONLY = 1; // 0x1
     field public static final int HIDE_NOT_ALWAYS = 2; // 0x2
     field public static final int RESULT_HIDDEN = 3; // 0x3
diff --git a/core/java/android/inputmethodservice/InputMethodService.java b/core/java/android/inputmethodservice/InputMethodService.java
index d3509d5eb289..38ddc169f527 100644
--- a/core/java/android/inputmethodservice/InputMethodService.java
+++ b/core/java/android/inputmethodservice/InputMethodService.java
@@ -2087,7 +2087,14 @@ public class InputMethodService extends AbstractInputMethodService {
      * protocol, so applications with custom text editing written before this method appeared will
      * not call to inform the IME of this interaction.
      * @param focusChanged true if the user changed the focused view by this click.
+     * @see InputMethodManager#viewClicked(View)
+     * @deprecated The method may not be called for composite {@link View} that works as a giant
+     *             "Canvas", which can host its own UI hierarchy and sub focus state.
+     *             {@link android.webkit.WebView} is a good example. Application / IME developers
+     *             should not rely on this method. If your goal is just being notified when an
+     *             on-going input is interrupted, simply monitor {@link #onFinishInput()}.
      */
+    @Deprecated
     public void onViewClicked(boolean focusChanged) {
         // Intentionally empty
     }
diff --git a/core/java/android/view/inputmethod/InputMethodManager.java b/core/java/android/view/inputmethod/InputMethodManager.java
index 10b99eca0fa8..14a5e3bd1417 100644
--- a/core/java/android/view/inputmethod/InputMethodManager.java
+++ b/core/java/android/view/inputmethod/InputMethodManager.java
@@ -1881,7 +1881,15 @@ public final class InputMethodManager {
 
     /**
      * Notify the event when the user tapped or clicked the text view.
+     *
+     * @param view {@link View} which is being clicked.
+     * @see InputMethodService#onViewClicked(boolean)
+     * @deprecated The semantics of this method can never be defined well for composite {@link View}
+     *             that works as a giant "Canvas", which can host its own UI hierarchy and sub focus
+     *             state. {@link android.webkit.WebView} is a good example. Application / IME
+     *             developers should not rely on this method.
      */
+    @Deprecated
     public void viewClicked(View view) {
         // Re-dispatch if there is a context mismatch.
         final InputMethodManager fallbackImm = getFallbackInputMethodManagerIfNecessary(view);