高级触控笔功能

Android 和 ChromeOS 提供各种 API，可帮助您构建为用户提供出色触控笔体验的应用。MotionEvent 类公开有关触控笔与屏幕交互的信息，包括触控笔压力、方向、倾斜、悬停和手掌检测。低延迟图形和运动预测库增强了触控笔屏幕渲染，提供了自然、类似笔和纸的体验。

MotionEvent

MotionEvent 类表示用户输入交互，例如触摸指针在屏幕上的位置和移动。对于触控笔输入，MotionEvent 还公开压力、方向、倾斜和悬停数据。

事件数据

要访问MotionEvent 数据，请设置一个onTouchListener

val onTouchListener = View.OnTouchListener { view, event ->
  // Process motion event.
}

View.OnTouchListener listener = (view, event) -> {
  // Process motion event.
};

侦听器从系统接收MotionEvent 对象，因此您的应用可以处理它们。

MotionEvent 对象提供与 UI 事件的以下方面相关的数据

• 操作：与设备的物理交互——触摸屏幕，将指针移动到屏幕表面上，将指针悬停在屏幕表面上
• 指针：与屏幕交互的对象标识符——手指、触控笔、鼠标
• 轴：数据类型——x 和 y 坐标、压力、倾斜、方向和悬停（距离）

操作

要实现触控笔支持，您需要了解用户正在执行的操作。

MotionEvent 提供各种ACTION 常量，这些常量定义运动事件。对于触控笔而言，最重要的操作包括以下内容

当ACTION_DOWN发生时，您的应用可以执行诸如启动新笔画之类的任务，使用ACTION_MOVE绘制笔画，并在触发ACTION_UP时完成笔画。

给定指针的从ACTION_DOWN到ACTION_UP的MotionEvent操作集称为运动集。

指针

大多数屏幕都是多点触控：系统为与屏幕交互的每个手指、触控笔、鼠标或其他指向对象分配一个指针。指针索引使您可以获取特定指针的轴信息，例如触摸屏幕的第一个手指或第二个手指的位置。

指针索引范围从零到MotionEvent#pointerCount()返回的指针数减 1。

可以使用getAxisValue(axis, pointerIndex)方法访问指针的轴值。当省略指针索引时，系统将返回第一个指针（指针零 (0)）的值。

MotionEvent 对象包含有关所用指针类型的信息。您可以通过迭代指针索引并调用getToolType(pointerIndex)方法来获取指针类型。

要了解有关指针的更多信息，请参阅处理多点触控手势。

触控笔输入

您可以使用TOOL_TYPE_STYLUS筛选触控笔输入

val isStylus = TOOL_TYPE_STYLUS == event.getToolType(pointerIndex)

boolean isStylus = TOOL_TYPE_STYLUS == event.getToolType(pointerIndex);

触控笔还可以报告它用作橡皮擦，方法是使用TOOL_TYPE_ERASER

val isEraser = TOOL_TYPE_ERASER == event.getToolType(pointerIndex)

boolean isEraser = TOOL_TYPE_ERASER == event.getToolType(pointerIndex);

触控笔轴数据

ACTION_DOWN和ACTION_MOVE提供有关触控笔的轴数据，即 x 和 y 坐标、压力、方向、倾斜和悬停。

为了能够访问此数据，MotionEvent API 提供了getAxisValue(int)，其中参数是以下任何轴标识符

例如，MotionEvent.getAxisValue(AXIS_X)返回第一个指针的 x 坐标。

另请参阅处理多点触控手势。

位置

您可以使用以下调用检索指针的 x 和 y 坐标

• MotionEvent#getAxisValue(AXIS_X)或MotionEvent#getX()
• MotionEvent#getAxisValue(AXIS_Y)或MotionEvent#getY()

压力

您可以使用MotionEvent#getAxisValue(AXIS_PRESSURE)或对于第一个指针，使用MotionEvent#getPressure()检索指针压力。

触摸屏或触摸板的压力值介于 0（无压力）和 1 之间，但根据屏幕校准，可能会返回更高的值。

方向

方向指示触控笔指向哪个方向。

可以使用 getAxisValue(AXIS_ORIENTATION) 或 getOrientation()（针对第一个指针）来获取指针方向。

对于触控笔，方向以弧度值返回，顺时针方向为 0 到 π (𝛑)，逆时针方向为 0 到 -π。

方向使您可以实现真实的笔刷效果。例如，如果触控笔代表扁平笔刷，则扁平笔刷的宽度取决于触控笔的方向。

倾斜度

倾斜度测量触控笔相对于屏幕的倾斜角度。

倾斜度以弧度返回触控笔的正角度，其中零表示垂直于屏幕，π/2 表示平放在表面上。

可以使用 getAxisValue(AXIS_TILT) 获取倾斜角度（第一个指针没有快捷方式）。

倾斜度可用于尽可能逼真地再现现实生活中的工具，例如模拟用倾斜的铅笔进行阴影。

悬停

可以使用 getAxisValue(AXIS_DISTANCE) 获取触控笔距离屏幕的距离。该方法返回一个值，从 0.0（接触屏幕）到更高的值，随着触控笔远离屏幕而增加。屏幕和触控笔笔尖（点）之间的悬停距离取决于屏幕和触控笔的制造商。由于实现可能有所不同，因此不要依赖精确值来实现应用关键功能。

触控笔悬停可用于预览笔刷大小或指示将要选择的按钮。

手掌拒绝、导航和意外输入

有时多点触控屏幕可能会注册意外触摸，例如，当用户在手写时自然地将手放在屏幕上以支撑时。手掌拒绝是一种检测此行为并通知您应该取消上次 MotionEvent 集的机制。

因此，您必须保留用户输入的历史记录，以便可以从屏幕上删除意外触摸并重新渲染合法的用户输入。

ACTION_CANCEL 和 FLAG_CANCELED

ACTION_CANCEL 和 FLAG_CANCELED 都旨在通知您应该从上次 ACTION_DOWN 取消之前的 MotionEvent 集，例如，您可以为给定指针的绘图应用程序撤消上次笔划。

ACTION_CANCEL

添加到 Android 1.0（API 级别 1）

ACTION_CANCEL 指示应取消之前的运动事件集。

ACTION_CANCEL 在检测到以下任何情况时触发

• 导航手势
• 手掌拒绝

当触发 ACTION_CANCEL 时，您应该使用 getPointerId(getActionIndex()) 识别活动指针。然后从输入历史记录中删除使用该指针创建的笔划，并重新渲染场景。

FLAG_CANCELED

添加到 Android 13（API 级别 33）

FLAG_CANCELED 指示向上移动的指针是无意的用户触摸。当用户意外触摸屏幕时，例如握住设备或将手掌放在屏幕上时，通常会设置此标志。

您可以按如下方式访问标志值

val cancel = (event.flags and FLAG_CANCELED) == FLAG_CANCELED

boolean cancel = (event.getFlags() & FLAG_CANCELED) == FLAG_CANCELED;

如果设置了标志，则需要撤消上次 MotionEvent 集，从该指针的上次 ACTION_DOWN 开始。

与 ACTION_CANCEL 一样，可以使用 getPointerId(actionIndex) 找到指针。

全屏、边缘到边缘和导航手势

如果应用程序是全屏显示，并且在边缘附近有可操作的元素，例如绘图或笔记应用程序的画布，则从屏幕底部向上滑动以显示导航或将应用程序移动到后台可能会导致对画布的意外触摸。

为了防止手势触发应用程序中的意外触摸，您可以利用 insets 和 ACTION_CANCEL。

另请参见 手掌拒绝、导航和意外输入 部分。

使用 setSystemBarsBehavior() 方法和 BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE WindowInsetsController 防止导航手势导致意外触摸事件

// Configure the behavior of the hidden system bars.
windowInsetsController.systemBarsBehavior =
    WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE

// Configure the behavior of the hidden system bars.
windowInsetsController.setSystemBarsBehavior(
    WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
);

要了解有关内嵌和手势管理的更多信息，请参阅

• 隐藏系统栏以实现沉浸式模式
• 确保与手势导航兼容
• 在您的应用中边缘到边缘显示内容

低延迟

延迟是硬件、系统和应用程序处理和渲染用户输入所需的时间。

延迟 = 硬件和操作系统输入处理 + 应用处理 + 系统合成

• 硬件渲染

延迟的来源

• 使用触摸屏注册触控笔（硬件）：触控笔和操作系统进行通信以注册和同步时的初始无线连接。
• 触摸采样率（硬件）：触摸屏每秒检查指针是否接触表面的次数，范围从 60 Hz 到 1000 Hz。
• 输入处理（应用程序）：对用户输入应用颜色、图形效果和变换。
• 图形渲染（操作系统 + 硬件）：缓冲区交换、硬件处理。

低延迟图形

Jetpack 低延迟图形库 减少了用户输入和屏幕渲染之间的处理时间。

该库通过避免多缓冲渲染并利用前缓冲渲染技术（这意味着直接写入屏幕）来减少处理时间。

前缓冲渲染

前缓冲是屏幕用于渲染的内存。它是应用程序能够最接近直接绘制到屏幕的方式。低延迟库使应用程序能够直接渲染到前缓冲区。这通过防止缓冲区交换来提高性能，缓冲区交换可能会发生在常规多缓冲渲染或双缓冲渲染（最常见的情况）中。

虽然前缓冲渲染是渲染屏幕小区域的出色技术，但它并非设计用于刷新整个屏幕。使用前缓冲渲染时，应用程序正在将内容渲染到显示器从中读取的缓冲区中。因此，可能会出现渲染伪像或 撕裂（见下文）。

低延迟库适用于 Android 10（API 级别 29）及更高版本以及运行 Android 10（API 级别 29）及更高版本的 ChromeOS 设备。

依赖项

低延迟库提供前缓冲渲染实现的组件。该库作为依赖项添加到应用程序的模块 build.gradle 文件中

dependencies {
    implementation "androidx.graphics:graphics-core:1.0.0-alpha03"
}

GLFrontBufferRenderer 回调

低延迟库包含 GLFrontBufferRenderer.Callback 接口，该接口定义了以下方法

• onDrawFrontBufferedLayer()
  • onDrawDoubleBufferedLayer()

低延迟库对您与 GLFrontBufferRenderer 一起使用的数据类型没有明确规定。

但是，该库会将数据处理为数百个数据点的流；因此，请设计您的数据以优化内存使用和分配。

回调

要启用渲染回调，请实现 GLFrontBufferedRenderer.Callback 并覆盖 onDrawFrontBufferedLayer() 和 onDrawDoubleBufferedLayer()。GLFrontBufferedRenderer 使用回调以尽可能优化的方式渲染您的数据。

val callback = object: GLFrontBufferedRenderer.Callback<DATA_TYPE> {
   override fun onDrawFrontBufferedLayer(
       eglManager: EGLManager,
       bufferInfo: BufferInfo,
       transform: FloatArray,
       param: DATA_TYPE
   ) {
       // OpenGL for front buffer, short, affecting small area of the screen.
   }
   override fun onDrawMultiDoubleBufferedLayer(
       eglManager: EGLManager,
       bufferInfo: BufferInfo,
       transform: FloatArray,
       params: Collection<DATA_TYPE>
   ) {
       // OpenGL full scene rendering.
   }
}

GLFrontBufferedRenderer.Callback<DATA_TYPE> callbacks =
    new GLFrontBufferedRenderer.Callback<DATA_TYPE>() {
        @Override
        public void onDrawFrontBufferedLayer(@NonNull EGLManager eglManager,
            @NonNull BufferInfo bufferInfo,
            @NonNull float[] transform,
            DATA_TYPE data_type) {
                // OpenGL for front buffer, short, affecting small area of the screen.
        }

    @Override
    public void onDrawDoubleBufferedLayer(@NonNull EGLManager eglManager,
        @NonNull BufferInfo bufferInfo,
        @NonNull float[] transform,
        @NonNull Collection<? extends DATA_TYPE> collection) {
            // OpenGL full scene rendering.
    }
};

声明 GLFrontBufferedRenderer 的实例

通过提供您之前创建的 SurfaceView 和回调来准备 GLFrontBufferedRenderer。GLFrontBufferedRenderer 使用您的回调优化对前缓冲区和双缓冲区的渲染

var glFrontBufferRenderer = GLFrontBufferedRenderer<DATA_TYPE>(surfaceView, callbacks)

GLFrontBufferedRenderer<DATA_TYPE> glFrontBufferRenderer =
    new GLFrontBufferedRenderer<DATA_TYPE>(surfaceView, callbacks);

渲染

当您调用触发 onDrawFrontBufferedLayer() 回调的 renderFrontBufferedLayer() 方法时，前缓冲渲染开始。

当您调用触发 onDrawMultiDoubleBufferedLayer() 回调的 commit() 函数时，双缓冲渲染恢复。

在下面的示例中，当用户开始在屏幕上绘图 (ACTION_DOWN) 并移动指针 (ACTION_MOVE) 时，该过程会渲染到前缓冲区（快速渲染）。当指针离开屏幕表面 (ACTION_UP) 时，该过程会渲染到双缓冲区。

您可以使用 requestUnbufferedDispatch() 请求输入系统不批量处理运动事件，而是尽快传递它们。

when (motionEvent.action) {
   MotionEvent.ACTION_DOWN -> {
       // Deliver input events as soon as they arrive.
       view.requestUnbufferedDispatch(motionEvent)
       // Pointer is in contact with the screen.
       glFrontBufferRenderer.renderFrontBufferedLayer(DATA_TYPE)
   }
   MotionEvent.ACTION_MOVE -> {
       // Pointer is moving.
       glFrontBufferRenderer.renderFrontBufferedLayer(DATA_TYPE)
   }
   MotionEvent.ACTION_UP -> {
       // Pointer is not in contact in the screen.
       glFrontBufferRenderer.commit()
   }
   MotionEvent.CANCEL -> {
       // Cancel front buffer; remove last motion set from the screen.
       glFrontBufferRenderer.cancel()
   }
}

switch (motionEvent.getAction()) {
   case MotionEvent.ACTION_DOWN: {
       // Deliver input events as soon as they arrive.
       surfaceView.requestUnbufferedDispatch(motionEvent);

       // Pointer is in contact with the screen.
       glFrontBufferRenderer.renderFrontBufferedLayer(DATA_TYPE);
   }
   break;
   case MotionEvent.ACTION_MOVE: {
       // Pointer is moving.
       glFrontBufferRenderer.renderFrontBufferedLayer(DATA_TYPE);
   }
   break;
   case MotionEvent.ACTION_UP: {
       // Pointer is not in contact in the screen.
       glFrontBufferRenderer.commit();
   }
   break;
   case MotionEvent.ACTION_CANCEL: {
       // Cancel front buffer; remove last motion set from the screen.
       glFrontBufferRenderer.cancel();
   }
   break;
}

渲染注意事项

屏幕的小部分区域、手写、绘画、素描。

全屏更新、平移、缩放。可能会导致撕裂。

撕裂

当屏幕在屏幕缓冲区同时被修改时刷新时，就会发生撕裂。屏幕的一部分显示新数据，而另一部分显示旧数据。

运动预测

Jetpack 运动预测库 通过估计用户的笔划路径并向渲染器提供临时的、人工的点来减少感知到的延迟。

运动预测库将真实的用户的输入作为 MotionEvent 对象获取。这些对象包含有关 x 和 y 坐标、压力和时间的信息，运动预测器利用这些信息来预测未来的 MotionEvent 对象。

预测的 MotionEvent 对象只是估计值。预测的事件可以减少感知到的延迟，但是一旦收到实际的 MotionEvent 数据，就必须用实际的 MotionEvent 数据替换预测的数据。

运动预测库适用于 Android 4.4（API 级别 19）及更高版本以及运行 Android 9（API 级别 28）及更高版本的 ChromeOS 设备。

依赖项

运动预测库提供了预测的实现。该库作为依赖项添加到应用的模块build.gradle文件中

dependencies {
    implementation "androidx.input:input-motionprediction:1.0.0-beta01"
}

实现

运动预测库包含MotionEventPredictor接口，该接口定义了以下方法

• record()：存储MotionEvent对象作为用户操作的记录
• predict()：返回预测的MotionEvent

声明MotionEventPredictor的实例

var motionEventPredictor = MotionEventPredictor.newInstance(view)

MotionEventPredictor motionEventPredictor = MotionEventPredictor.newInstance(surfaceView);

用数据馈送预测器

motionEventPredictor.record(motionEvent)

motionEventPredictor.record(motionEvent);

预测

when (motionEvent.action) {
   MotionEvent.ACTION_MOVE -> {
       val predictedMotionEvent = motionEventPredictor?.predict()
       if(predictedMotionEvent != null) {
            // use predicted MotionEvent to inject a new artificial point
       }
   }
}

switch (motionEvent.getAction()) {
   case MotionEvent.ACTION_MOVE: {
       MotionEvent predictedMotionEvent = motionEventPredictor.predict();
       if(predictedMotionEvent != null) {
           // use predicted MotionEvent to inject a new artificial point
       }
   }
   break;
}

运动预测的注意事项

添加新的预测点时，删除之前的预测点。

不要将预测点用于最终渲染。

笔记应用

ChromeOS允许您的应用声明一些笔记记录操作。

要将应用注册为ChromeOS上的笔记应用，请参见输入兼容性。

要将应用注册为Android上的笔记应用，请参见创建笔记应用。

Android 14（API 级别 34）引入了ACTION_CREATE_NOTE意图，使您的应用能够在锁屏上启动笔记记录活动。

使用ML Kit进行数字墨迹识别

使用ML Kit数字墨迹识别，您的应用可以识别数百种语言的数字表面上的手写文本。您还可以对草图进行分类。

ML Kit提供Ink.Stroke.Builder类来创建Ink对象，这些对象可以由机器学习模型处理，以将手写内容转换为文本。

除了手写识别，该模型还可以识别手势，例如删除和圈选。

请参见数字墨迹识别了解更多信息。

其他资源

开发者指南

• 创建笔记应用

• 在Android上使用ML Kit识别数字墨迹

Codelabs

• 增强Android应用中的手写笔支持