From 70ef8a99fb710824062034bde5026c12b9644c1c Mon Sep 17 00:00:00 2001 From: Sandro Meier Date: Fri, 11 Nov 2022 09:27:24 +0000 Subject: [PATCH] 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 --- core/java/android/hardware/input/VirtualTouchEvent.java | 9 +++++++++ .../android/hardware/input/VirtualTouchEventTest.java | 6 ++++++ 2 files changed, 15 insertions(+) diff --git a/core/java/android/hardware/input/VirtualTouchEvent.java b/core/java/android/hardware/input/VirtualTouchEvent.java index c7450d8fa65d7..e0845f8d641a0 100644 --- a/core/java/android/hardware/input/VirtualTouchEvent.java +++ b/core/java/android/hardware/input/VirtualTouchEvent.java @@ -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 diff --git a/core/tests/coretests/src/android/hardware/input/VirtualTouchEventTest.java b/core/tests/coretests/src/android/hardware/input/VirtualTouchEventTest.java index 3f504a00773ce..100aba5ab362c 100644 --- a/core/tests/coretests/src/android/hardware/input/VirtualTouchEventTest.java +++ b/core/tests/coretests/src/android/hardware/input/VirtualTouchEventTest.java @@ -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()