Fuchsia.ui.pointer

添加时间：7

协议

MouseSource

在 fuchsia.ui.pointer/mouse.fidl 中定义

供客户端接收鼠标指针事件的方法。

指针事件的位置是在视口的上下文中定义的， 位于视图中视图和视口的尺寸及其 空间关系（用转换矩阵定义）的 在 |ViewParameter| 中同步表格。视图可以检索指针的 通过对视口应用 viewport-to-view 转换矩阵。

视口嵌入在一个独立且稳定的坐标系中， 适合以与缩放无关的方式解释指针事件； 都会以恒定的尺度观察鼠标移动，即使在诸如 放大或平移。但是，还有一些其他影响，例如放大 视图的裁剪边界时，可能会触发视口范围的变化。

观看

供客户端接收鼠标指针事件的方法。

此调用以“挂起获取”的形式表示模式：客户端要求 一组最近的事件，并通过回调来接收这些事件。这个 基于拉取的方法确保客户端能够自行处理事件 pace;事件不会无限堵塞通道。

流控制。在乘坐飞机时，来电者最多只能有一个通话 |观看|致电 一次；同时调用 |Watch| 是逻辑错误。 否则，频道将被停用。

客户端投放安排。服务器会将事件分派给 FIFO 上的调用方， 尽最大努力保证无损，但调用方必须分配足够的时间来 及时了解新活动

事件时间。事件矢量中每个事件的时间戳不是 保证单调可能会将来自不同设备的事件注入到 不同时期的风景。通常，来自单一设备的事件 预计时间戳单调递增。

查看参数。有时，更改视图或视口 通知客户端如果一个 |MouseEvent|带有 |ViewParameters|，这些 参数会应用于连续的 |MousePointerSample|s，直到下一个 |ViewParameters|。

请求

<空>

响应

名称类型
events vector<MouseEvent>[128]

TouchSource

在 fuchsia.ui.pointer/touch.fidl 中定义

可让客户端在全局范围内接收触摸事件并做出响应的方法 手势消除歧义协议。

触摸事件的位置是在视口的上下文中定义的， 位于视图中视图和视口的尺寸及其 空间关系（用转换矩阵定义）的 在 |ViewParameter| 中同步表格。视图可以检索指针的 通过对视口应用 viewport-to-view 转换矩阵。

视口嵌入在一个独立且稳定的坐标系中， 适合以独立于缩放的方式解释触摸事件；一 都会以恒定的尺度观察到滑动，即使在诸如 放大或平移。但是，还有一些其他影响，例如放大 视图的裁剪边界时，可能会触发视口范围的变化。

UpdateResponse

手势协议允许客户端执行“暂停”操作打开 触摸事件交互；它会阻止互动的 （即使在互动结束后也是如此）。此方法会更新 客户之前的“保全”只需将其替换为一个响应即可 继续进行所有权解析。

请参阅 |TouchInteractionId|如何将视频流的结构 互动。

流控制。调用方最多只能有一个 |UpdateResponse|致电 并且必须是封闭式互动。这是一种逻辑 调用 |UpdateResponse| 时出错使用 |观看|调用。

有效性。此 TouchResponse 不能是另一个“保全”和 覆盖的响应预计为“保全”响应。

请求

名称类型
interaction TouchInteractionId
response TouchResponse

响应

<空>

观看

供客户端接收触摸指针事件的方法。

这种调用方式为“挂起获取”模式：客户端要求 一组最近的事件，并通过回调来接收这些事件。这个 基于拉取的方法确保客户端能够自行处理事件 pace;事件不会无限堵塞通道。

流控制。在乘坐飞机时，来电者最多只能有一个通话 |观看|致电 一次；同时调用 |Watch| 是逻辑错误。 否则，频道将被停用。

客户端投放安排。服务器会将事件分派给 FIFO 上的调用方， 尽最大努力保证无损，但调用方必须分配足够的时间来 及时了解新活动无响应的客户端可分为 “应用无响应”并且是针对渠道关闭的目标

响应。手势消除歧义方案依赖于服务器 收到 |TouchResponse|每个 |TouchEvent|.|TouchPointerSample|; 非示例事件应返回空的 |TouchResponse|添加到 服务器。先前事件的响应被馈送到 |Watch|的下次调用[1]。|响应|中的每个元素向量为 解释为上一成对的事件， |events|vector;向量长度必须匹配。请注意，客户端的 响应事件的合同即会开始， 端点，而不是在首次调用 Watch() 时。

初步回应。对 |Watch| 的第一次调用必须是空矢量。

事件时间。事件矢量中每个事件的时间戳不是 保证单调来自不同设备的触摸事件 在不同时间注入到风景中。通常，单个事件发生的事件 时间戳单调递增。

查看参数。有时，更改视图或视口 通知客户端如果一个 |TouchEvent|带有 |ViewParameters|，这些 参数会应用于连续的 |TouchPointerSample|s，直到 |ViewParameters|。

[1] 挂起的 get 模式支持简单的 API 演变， 很遗憾， 不支持与事件响应的惯用匹配。

请求

名称类型
responses vector<TouchResponse>[128]

响应

名称类型
events vector<TouchEvent>[128]

结构体

MouseEventStreamInfo

在 fuchsia.ui.pointer/mouse.fidl 中定义

从服务器发送到客户端的鼠标事件流的状态。

不变：客户端的鼠标事件用 MouseViewStatus.ENTERED 和 MouseViewStatus.EXITED。

字段类型说明默认
device_id uint32

发出鼠标事件流的鼠标设备的标识符。

 无默认设置
status MouseViewStatus

从服务器发送到客户端的鼠标事件流的进入/退出状态。

 无默认设置

矩形

在 fuchsia.ui.pointer/view.fidl 中定义

与轴对齐的矩形。它由极限和最大程度定义 以坐标系表示

字段类型说明默认
min Point2

此矩形的最小范围（包括范围）。

  • 其坐标成对小于最大范围的 坐标。
 无默认设置
max Point2

此矩形的最大范围（含边界值）。

  • 其坐标成对大于最小范围的 坐标。
 无默认设置

TouchInteractionId

在 fuchsia.ui.pointer/touch.fidl 中定义

“互动”的唯一标识符事件流中的触摸事件。 触摸事件会在手指接触时被观察为一系列互动 并停止与显示屏互动

遵循 EventPhase 状态的有限序列指针事件 从初始状态 ADD 开始，称为互动。 结束（或过去）的互动是指已到达终端的互动 状态（REMOVE 或 CANCEL）；开放式（或当前）互动是指 没有。

对于给定的设备指针，系统会将事件流视为连续观察到 零次或多次已关闭的互动（之前的用户互动记录）； 最多随后会发生一次公开互动（当前用户互动）。

由于我们需要按指针事件对指针事件进行分组，因此触摸事件 包含在该指针流中唯一的互动 ID。这个 共同引用使您可以在封闭式互动中进行操作， 也是开放的互动方式

另请参阅 EventPhase，了解鼠标事件流的相关讨论。

字段类型说明默认
device_id uint32

发出触摸事件流的指针设备的标识符。 一个设备可能拥有多个指针，每个指针都有自己的 |pointer_id|。

 无默认设置
pointer_id uint32

发出此事件的指针的标识符。它是唯一的 特定的 |device_id|。每个 (device_id, point_id) 对问题在 一次最多进行一次打开的互动。

 无默认设置
interaction_id uint32

互动的标识符。只有某个特定的 （device_id, pointer_id）对。

 无默认设置

TouchInteractionResult

在 fuchsia.ui.pointer/touch.fidl 中定义

发送触摸事件交互的手势消除歧义结果 从服务器到客户端

字段类型说明默认
interaction TouchInteractionId

此指针样本所属的互动。

 无默认设置
status TouchInteractionStatus

从服务器发送到客户端的交互处置。

 无默认设置

ViewParameters

在 fuchsia.ui.pointer/view.fidl 中定义

关联视图和视口的参数，足以正确 解释分派给此视图的指针事件的位置和缩放比例。

订购。这些参数到达的渠道与指针事件相同， 提供同步上下文以解释指针位置 事件发生。

协议间冗余。其中一些参数也可以通过 专用于观看控制的独立频道；由客户负责 正确使用异步接收的参数。

TODO(https://fxbug.dev/42162292)：重命名视口，在 Flatland 中使用。

字段类型说明默认
view Rectangle

视图的内容区域，位于视图的坐标系中。

矩形是由父视图对此裁剪裁剪的 视图。

 无默认设置
viewport Rectangle

视口的互动区域，放置在独立的坐标中 系统。

指针事件的位置是在 视口。

视口范围的变化意味着指针互动的区域 自身移动和/或大小发生变化。

 无默认设置
viewport_to_view_transform Mat3

与视口的 坐标系在视图坐标系中的位置。

 无默认设置

精英

EventPhase 严格

类型：uint32

在 fuchsia.ui.pointer/state.fidl 中定义

指针事件的可能状态。数据流中的事件阶段 遵循以 ADD 阶段开始，后跟 0 或 更多 CHANGE 阶段，最终以 REMOVE 或 CANCEL 终止 阶段。

ADD ---> CHANGE* -+-> REMOVE
                  |
                  +-> CANCEL

遵循此状态机的有限序列指针事件， 从初始状态开始，就称为一次互动。关闭（或 过往）互动是指已达到终止状态的互动；打开 （或当前）的互动。

对于给定的设备指针，系统会将事件流视为连续观察到 零次或多次已关闭的互动（之前的用户互动记录）； 最多随后会发生一次公开互动（当前用户互动）。

当我们需要按指针事件对指针事件进行分组时，事件会带有 互动 ID，该 ID 在该指针流中具有唯一性。这种公共 可以通过引用来对封闭式互动进行操作， 开放的互动

例如，触摸事件通常被观察为一系列 因为手指与显示屏接触和断开连接。

名称值说明
1

设备已开始追踪指针。
2

设备报告了指针状态更新。
3

设备已停止追踪指针。
4

指针已无法使用。

MouseViewStatus 严格

类型：uint32

在 fuchsia.ui.pointer/mouse.fidl 中定义

关于鼠标事件流与此视图的关系的说明。

名称值说明
1

视频流会定向至此视图。
2

视频流会离开此视图。

TouchInteractionStatus 严格

类型：uint32

在 fuchsia.ui.pointer/touch.fidl 中定义

有关互动与此客户之间关系的说明。

名称值说明
1

客户已拒绝获得互动的所有权。
2

客户已获得互动的所有权。

TouchResponseType strict

类型：uint32

在 fuchsia.ui.pointer/touch.fidl 中定义

客户端可响应 给定 |TouchPointerSample|。用作手势消除歧义方案的一部分。

回应的依据是对互动的所有权声明。 客户可以对公开互动主张所有权，但只能 客户端的声明由服务器授予；其他客户的都会被拒绝。

名称值说明
1

客户不再对此次互动感兴趣；拒绝 互动所有权。客户端将停止接收以下事件的事件： 此互动。
2

客户对这次互动感兴趣，但需要进一步了解 事件进行决定；该客户尚未声明对此内容的所有权 互动
3

客户对这次互动感兴趣，但需要进一步了解 事件进行决定；该客户尚未声明对 互动在解决所有权问题期间，它的优先级高于 优先级较低的“不确定”但总是输给“是”声明。
4

客户对这次互动感兴趣，但需要进一步了解 事件进行决定；该客户尚未声明对 互动此外，它还会阻止试图 解析互动所有权。
5

客户对这次互动感兴趣，但需要进一步了解 事件进行决定；该客户尚未声明对 互动此外，它还会阻止试图 解析互动所有权。在解决所有权问题时， 其优先级高于优先级较低的“不确定”但总会输给 “是”声明。
6

客户对这种互动感兴趣，但需要看到一个 以便做出决定；该客户尚未声明所有权 此互动的所有权。它会阻止在 互动关闭。
7

客户对这种互动感兴趣，但需要看到一个 以便做出决定；该客户尚未声明所有权 此互动的所有权。它会阻止在 互动关闭。此外，它还会阻止具有以下特征的低优先级声明： 尝试解决互动所有权问题。
8

客户希望对此 中的其余事件进行独家访问 互动；它会声明对此互动的所有权（但该声明可能会 是同意还是拒绝）。在转让所有权的过程中， 将优先级更改为“是”声明。
9

客户希望对此 中的其余事件进行独家访问 互动；它会声明对此互动的所有权（但该声明可能会 是同意还是拒绝）。在解决所有权问题时， 优先级高于优先级较低的“是”声明。

表格

MouseDeviceInfo

在 fuchsia.ui.pointer/mouse.fidl 中定义

发出鼠标事件流的设备的相关信息。

Ordinal字段类型说明
id uint32

发出鼠标事件流的鼠标设备的标识符。 必填。
scroll_v_range fuchsia.input.report/Axis

设备发出的垂直滚动值的范围。
scroll_h_range fuchsia.input.report/Axis

设备发出的水平滚动值的范围。
buttons vector<uint8>[32]

设备发出的按钮标识符（按优先级顺序）。
relative_motion_range RelativeMotionRange

设备发出的相对移动值的范围。

MouseEvent

在 fuchsia.ui.pointer/mouse.fidl 中定义

自行收集指针相关数据的自给自足、自洽的收集； 从服务器发送到客户端

Ordinal字段类型说明
timestamp zx/Time

观察到此事件的时间。 必填。
view_parameters ViewParameters

关联视图和视口的参数，足以 正确解释方位、方位、震级和 分派给视图的指针事件的事件间距离。

  • 它会在连接和更改时发出。
device_info MouseDeviceInfo

对鼠标设备的说明，足以正确解读 设备的功能和使用意图

  • 系统会为每台设备发出一次该标识符。
pointer_sample MousePointerSample

鼠标事件流中每个采样数据点的说明。

发布政策。有两种调度模式：“悬停”以及“已锁存”。 悬停模式为默认模式，且音频流以片段形式分派给 每个鼠标事件悬停在上面的可见客户端。锁存模式定向 流式传输到单个客户端（无论视图边界如何），直到 已开锁。锁存模式通常在用户按下 但归根结底是针对产品的政策。
stream_info MouseEventStreamInfo

悬停模式下视图进入/退出信号。

  • 当鼠标悬停到视图中时，从视图上退出时，系统会发出该函数。
trace_flow_id uint64

一个标识符，用于将此事件的发送/接收事件 组件边界或抽象层。

MousePointerSample

在 fuchsia.ui.pointer/mouse.fidl 中定义

鼠标事件流中每个采样数据点的说明。

MousePointerSample 可以将多个状态更改捆绑到一个事件中。 例如，如果用户滚动鼠标滚轮并按下左手腕 客户端可能会收到滚动和按钮状态变化 或接收按钮更改和滚动更改 事件。

Ordinal字段类型说明
device_id uint32

发出鼠标事件流的鼠标设备的标识符。 必填。
position_in_viewport Point2

该事件在视口坐标系中的位置。 必填。
scroll_v int64

按定位点计算的相对垂直滚动位移。
scroll_h int64

按定位点划分的相对水平滚动位移。
pressed_buttons vector<uint8>[32]

当前按下按钮的标识符。
relative_motion RelativeMotion

执行的相对移动，与视口的 坐标系
scroll_v_physical_pixel float64

建议按物理像素的垂直滚动位移，为 通过加速器、定位点 / 毫米与像素比等进行计算。
scroll_h_physical_pixel float64

建议按物理像素水平滚动位移， 通过加速器、定位点 / 毫米与像素比等进行计算。
is_precision_scroll bool

指明滚动事件是否来自精确滚动设备 (HI_RES) 鼠标或触控板）。客户端可能想要播放插值动画 实现流畅滚动。

TouchDeviceInfo

在 fuchsia.ui.pointer/touch.fidl 中定义

有关发出触摸事件流的设备的信息。

Ordinal字段类型说明
id uint32

发出触摸事件流的触摸设备的标识符。 一个设备可能拥有多个指针，每个指针都有自己的指针 ID 和 自己的触摸事件流 必填。

TouchEvent

在 fuchsia.ui.pointer/touch.fidl 中定义

自行收集指针相关数据的自给自足、自洽的收集； 从服务器发送到客户端

Ordinal字段类型说明
timestamp zx/Time

观察到此事件的时间。 必填。
view_parameters ViewParameters

关联视图和视口的参数，足以 正确解释方位、方位、震级和 分派给视图的触摸事件的事件间距离。

  • 它会在连接和更改时发出。
device_info TouchDeviceInfo

指针设备的说明，足以正确解读 设备的功能和使用意图

  • 系统会为每台设备发出一次该标识符。
pointer_sample TouchPointerSample

触摸交互中每个采样数据点的说明 事件。

  • 它针对互动中的每个样本发出。
interaction_result TouchInteractionResult

针对触摸事件交互的手势消除歧义结果。

  • 每次互动都会发出一次该消息。
trace_flow_id uint64

一个标识符，用于将此事件的发送/接收事件 组件边界或抽象层。

TouchPointerSample

在 fuchsia.ui.pointer/touch.fidl 中定义

触摸事件流中每个采样数据点的说明。 所有字段均为必填字段。

Ordinal字段类型说明
interaction TouchInteractionId

此指针样本所属的互动。
phase EventPhase

该事件在互动的状态机中的状态。
position_in_viewport Point2

该事件在视口坐标系中的位置。

TouchResponse

在 fuchsia.ui.pointer/touch.fidl 中定义

从客户端发送到服务器的每个 |Event| 反馈事件。

仅 |TouchPointerSample|需要 |TouchResponseType|；其他事件 服务器需要空的 |TouchResponse|表格。

Ordinal字段类型说明
response_type TouchResponseType

客户端针对给定事件响应的交互处置 |TouchPointerSample|。
trace_flow_id uint64

一个标识符，用于将此响应的发送/接收事件 组件边界或抽象层。

常量

名称值类型说明
MOUSE_MAX_EVENT 128 uint32
TOUCH_MAX_EVENT 128 uint32

ALIASES

名称值说明
Mat3 array[9]

一个浮点 3x3 矩阵。

  • 这些值按列主顺序排列。
Point2 array[2]

浮点二维点。

  • 这些值按 (x, y) 顺序排列。
RelativeMotion array[2]

鼠标设备执行的相对运动。
RelativeMotionRange array[2]

鼠标设备的相对运动的有效值。

  • 范围会按 (x, y) 顺序排列。