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

Commit 70ef8a99 authored by Sandro Meier's avatar Sandro Meier
Browse files

Improve documentation of VirtualTouchEvent 

VirtualTouchEvent.Builder raises an exception during build() that is not
obvious why it is raised. Adding documentation with explanation.

Test: pure documentation change
Change-Id: I877fd17dd8325ff614ea056aa005740c1a25da1f
parent a5450530

core/java/android/hardware/input/VirtualTouchEvent.java

+9 −0
Original line number Diff line number Diff line
@@ -33,6 +33,11 @@ import java.lang.annotation.RetentionPolicy; 
 * The pointer id, tool type, action, and location are required; pressure and main axis size are

 * optional.

 *

 * Note: A VirtualTouchEvent with ACTION_CANCEL can only be created with TOOL_TYPE_PALM (and vice

 * versa). Events are injected into the uinput kernel module, which has no concept of cancelling

 * an action. The only way to state the intention that a pointer should not be handled as a pointer

 * is to change its tool type to TOOL_TYPE_PALM.

 *

 * @hide

 */

@SystemApi
@@ -186,6 +191,10 @@ public final class VirtualTouchEvent implements Parcelable { 


        /**

         * Creates a {@link VirtualTouchEvent} object with the current builder configuration.

         *

         * @throws IllegalArgumentException if one of the required arguments is missing or if

         * ACTION_CANCEL is not set in combination with TOOL_TYPE_PALM. See

         * {@link VirtualTouchEvent} for a detailed explanation.

         */

        public @NonNull VirtualTouchEvent build() {

            if (mToolType == TOOL_TYPE_UNKNOWN || mPointerId == MotionEvent.INVALID_POINTER_ID

core/tests/coretests/src/android/hardware/input/VirtualTouchEventTest.java

+6 −0
Original line number Diff line number Diff line
@@ -136,6 +136,12 @@ public class VirtualTouchEventTest { 
                .build());

    }



    /**

     * The combination of TOOL_TYPE_PALM with anything else than ACTION_CANCEL should throw an

     * exception. This is due to an underlying implementation detail. See documentation of {@link

     * VirtualTouchEvent}

     * for details.

     */

    @Test

    public void touchEvent_palmUsedImproperly() {

        assertThrows(IllegalArgumentException.class, () -> new VirtualTouchEvent.Builder()