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
diff --git a/core/java/android/hardware/input/VirtualTouchEvent.java b/core/java/android/hardware/input/VirtualTouchEvent.java
index c7450d8..e0845f8 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()