Merge "Improve documentation of VirtualTouchEvent"
diff --git a/core/java/android/hardware/input/VirtualTouchEvent.java b/core/java/android/hardware/input/VirtualTouchEvent.java
index ad51eb8..9b1e6e8 100644
--- a/core/java/android/hardware/input/VirtualTouchEvent.java
+++ b/core/java/android/hardware/input/VirtualTouchEvent.java
@@ -33,6 +33,11 @@
* 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 @@
/**
* 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 3f504a0..100aba5 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 @@
.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()