Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 554dbcb8 authored by Prabir Pradhan's avatar Prabir Pradhan
Browse files

InputManager: Update docs for pilferPointers 

Pilfer pointers from a window based on the current gesture stream. If any new pointers go down within the touchable region of the pilfering window and are part of the same gesture, those new pointers will be pilfered as well, and will not be sent to any other windows.

Pilfering is designed to be used only once per gesture. Once the gesture is complete (i.e. on ACTION_UP, ACTION_CANCEL, or ACTION_HOVER_EXIT), the system will resume dispatching pointers to the appropriately touched windows.

NOTE: This method should be used with caution as unexpected pilfering can break fundamental user interactions.

NOTE: Since this method pilfers pointers based on gesture stream that is currently active for the window, the behavior will depend on the state of the system, and is inherently racy. For example, a pilfer request on a quick tap may not be successful if the tap is already complete by the time the pilfer request is received by the system.

Bug: 347700797
Bug: 245989146
Change-Id: I33a7cf7bdf69a171c82b887bdaa3922c311467ce
Test: None
Flag: DOCS_ONLY
parent 732fe397

core/java/android/hardware/input/InputManager.java

+16 −2
Original line number Diff line number Diff line
@@ -1251,8 +1251,22 @@ public final class InputManager { 
     * canceled. Only the pilfering window will continue to receive events for the affected pointers

     * until the pointer is lifted.

     *

     * This method should be used with caution as unexpected pilfering can break fundamental user

     * interactions.

     * Furthermore, if any new pointers go down within the touchable region of the pilfering window

     * and are part of the same gesture, those new pointers will be pilfered as well, and will not

     * be sent to any other windows.

     *

     * Pilfering is designed to be used only once per gesture. Once the gesture is complete

     * (i.e. on {@link MotionEvent#ACTION_UP}, {@link MotionEvent#ACTION_CANCEL},

     * or {@link MotionEvent#ACTION_HOVER_EXIT}), the system will resume dispatching pointers

     * to the appropriately touched windows.

     *

     * NOTE: This method should be used with caution as unexpected pilfering can break fundamental

     * user interactions.

     *

     * NOTE: Since this method pilfers pointers based on gesture stream that is

     * currently active for the window, the behavior will depend on the state of the system, and

     * is inherently racy. For example, a pilfer request on a quick tap may not be successful if

     * the tap is already complete by the time the pilfer request is received by the system.

     *

     * @see android.os.InputConfig#SPY

     * @hide

core/java/android/view/InputMonitor.java

+6 −7
Original line number Diff line number Diff line
@@ -50,13 +50,12 @@ public final class InputMonitor implements Parcelable { 
    private final SurfaceControl mSurface;



    /**

     * Takes all of the current pointer events streams that are currently being sent to this

     * monitor and generates appropriate cancellations for the windows that would normally get

     * them.

     * Pilfer pointers from this input monitor.

     *

     * This method should be used with caution as unexpected pilfering can break fundamental user

     * interactions.

     * @see android.hardware.input.InputManager#pilferPointers(IBinder)

     * @deprecated

     */

    @Deprecated

    public void pilferPointers() {

        try {

            mHost.pilferPointers();
@@ -197,10 +196,10 @@ public final class InputMonitor implements Parcelable { 
    };



    @DataClass.Generated(

            time = 1679692514588L,

            time = 1720819824835L,

            codegenVersion = "1.0.23",

            sourceFile = "frameworks/base/core/java/android/view/InputMonitor.java",

            inputSignatures = "private static final  java.lang.String TAG\nprivate static final  boolean DEBUG\nprivate final @android.annotation.NonNull android.view.InputChannel mInputChannel\nprivate final @android.annotation.NonNull android.view.IInputMonitorHost mHost\nprivate final @android.annotation.NonNull android.view.SurfaceControl mSurface\npublic  void pilferPointers()\npublic  void dispose()\nclass InputMonitor extends java.lang.Object implements [android.os.Parcelable]\n@com.android.internal.util.DataClass(genToString=true)")

            inputSignatures = "private static final  java.lang.String TAG\nprivate static final  boolean DEBUG\nprivate final @android.annotation.NonNull android.view.InputChannel mInputChannel\nprivate final @android.annotation.NonNull android.view.IInputMonitorHost mHost\nprivate final @android.annotation.NonNull android.view.SurfaceControl mSurface\npublic @java.lang.Deprecated void pilferPointers()\npublic  void dispose()\nclass InputMonitor extends java.lang.Object implements [android.os.Parcelable]\n@com.android.internal.util.DataClass(genToString=true)")

    @Deprecated

    private void __metadata() {}