From e8258fdf7baed41ac6bf7c6386379eefb270d1ee Mon Sep 17 00:00:00 2001
From: Prabir Pradhan <prabirmsp@google.com>
Date: Thu, 14 Apr 2022 17:23:44 +0000
Subject: [PATCH] Advise use of InputDeviceListener when using pointer capture

InputDevices can be reconfigured when pointer capture changes, but the
app will be notified via InputManager when the updated device
information is available. This races with the onPointerCaptureChange
callback, so advise the use of InputDeviceListener in the pointer
capture documentation for developers to get around this.

Bug: 226425883
Test: None
Change-Id: I7aeb23722dc40b8fd37cb9667a4f23a336e8b5f1
---
 core/java/android/view/View.java | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 8b9a86b9eec63..d6332196ed633 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -28722,7 +28722,7 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
      *     {@link InputDevice#SOURCE_MOUSE_RELATIVE}, and relative position changes will be
      *     available through {@link MotionEvent#getX} and {@link MotionEvent#getY}.</li>
      *
-     *     <li>Events from a touchpad will be delivered with the source
+     *     <li>Events from a touchpad or trackpad will be delivered with the source
      *     {@link InputDevice#SOURCE_TOUCHPAD}, where the absolute position of each of the pointers
      *     on the touchpad will be available through {@link MotionEvent#getX(int)} and
      *     {@link MotionEvent#getY(int)}, and their relative movements are stored in
@@ -28731,6 +28731,12 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
      *     <li>Events from other types of devices, such as touchscreens, will not be affected.</li>
      * </ul>
      * <p>
+     * When pointer capture changes, connected mouse and trackpad devices may be reconfigured,
+     * and their properties (such as their sources or motion ranges) may change. Use an
+     * {@link android.hardware.input.InputManager.InputDeviceListener} to be notified when a device
+     * changes (which may happen after enabling or disabling pointer capture), and use
+     * {@link InputDevice#getDevice(int)} to get the updated {@link InputDevice}.
+     * <p>
      * Events captured through pointer capture will be dispatched to
      * {@link OnCapturedPointerListener#onCapturedPointer(View, MotionEvent)} if an
      * {@link OnCapturedPointerListener} is set, and otherwise to