Fuchsia.ui.pointer

添加次数：7

协议

MouseSource

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

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

指针事件的位置是在位于视图中的视口的上下文中定义的。|ViewParameter| 表中会同步提供视图和视口的尺寸及其空间关系（通过转换矩阵定义）。视图可以通过应用视口到视图的转换矩阵在其本地坐标系中检索指针的位置。

视口嵌入在独立且稳定的坐标系中，适合以独立于缩放的方式解释指针事件；即使在放大或平移等影响下，鼠标按恒定移动也会观察到。不过，其他效果（例如放大视图的裁剪边界）可能会触发视口范围的变化。

观看

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

此调用称为“挂起 get”模式：客户端请求一组最近的事件，并通过回调接收这些事件。这种基于拉取的方法可确保客户端按照自己的节奏处理事件；事件不会无限制地堵塞通道。

流控制。调用方一次最多只能进行一个进行中的 |Watch| 调用；并发调用 |Watch| 是一个逻辑错误。不合规会导致信道关闭。

客户进度。服务器将基于 FIFO 无损、尽力而为的 FIFO 将事件分派给调用方，但调用方必须分配足够的时间来跟上新事件。

事件时间。事件向量中每个事件的时间戳并非一定是单调的；来自不同设备的事件可能会在不同的时间注入到场景中。通常，来自单个设备的事件应具有单调递增的时间戳。

查看参数。有时，视图或视口发生变化时需要通知客户端。如果 |MouseEvent| 带有 |ViewParameters|，则这些参数将应用于连续的 |MousePointerSample|，直至下一个 |ViewParameters|。

请求

<EMPTY>

响应

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

TouchSource

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

一种可让客户端接收触摸事件并使用全局手势消除歧义协议进行响应的方法。

触摸事件的位置是在位于视图中的视口的上下文中定义的。|ViewParameter| 表中会同步提供视图和视口的尺寸及其空间关系（通过转换矩阵定义）。视图可以通过应用视口到视图的转换矩阵在其本地坐标系中检索指针的位置。

视口嵌入在独立且稳定的坐标系中，适合以独立于缩放的方式解释触摸事件；即使在放大或平移等效果下，也会以恒定的比例观察滑动操作。不过，其他效果（例如放大视图的裁剪边界）可能会触发视口范围的变化。

UpdateResponse

手势协议允许客户端对触摸事件的开放式互动执行“保持”操作；即使在互动关闭后，它也无法解析互动所有权。此方法会将客户端之前的“保全”替换为可让所有权解析继续执行的响应，从而更新该客户端。

如需了解如何将数据流构建为互动，请参阅 |TouchInteractionId|。

流控制。调用方每次最多只允许进行一次 |UpdateResponse| 调用，并且必须在封闭式互动中进行。如果可以通过 |Watch| 调用进行正常响应，那么调用 |UpdateResponse| 属于逻辑错误。

有效性。此 TouchResponse 不能是另一个“呼叫保持”响应，被覆盖的响应应为“呼叫保持”响应。

请求

名称类型
interaction TouchInteractionId
response TouchResponse

响应

<EMPTY>

观看

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

此调用称为“挂起 get”模式：客户端请求一组最近的事件，并通过回调接收这些事件。这种基于拉取的方法可确保客户端按照自己的节奏处理事件；事件不会无限制地堵塞通道。

流控制。调用方一次最多只能进行一个进行中的 |Watch| 调用；并发调用 |Watch| 是一个逻辑错误。不合规会导致信道关闭。

客户进度。服务器将基于 FIFO 无损、尽力而为的 FIFO 将事件分派给调用方，但调用方必须分配足够的时间来跟上新事件。无响应的客户端可能会被归类为“应用无响应”，并针对渠道关闭目标。

回复。手势消歧架构依赖于服务器为每个 |TouchEvent|.|TouchPointerSample| 接收 |TouchResponse|；非示例事件应向服务器返回一个空的 |TouchResponse| 表。之前事件的响应将在下一次调用 |Watch| [1] 时馈送到服务器。|responses| 向量中的每个元素都解释为对前面的 |events| 向量中事件的成对响应；向量长度必须匹配。请注意，在客户端使用景观注册其端点时（而不是在首次调用 Watch() 时），客户端响应事件的合约会立即开始。

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

事件时间。事件矢量中每个事件的时间戳并非一定是单调的；来自不同设备的触摸事件可能会在不同的时间注入到景观中。通常，来自单个设备的事件应具有单调递增的时间戳。

查看参数。有时，视图或视口发生变化时需要通知客户端。如果 |TouchEvent| 带有 |ViewParameters|，这些参数将应用于连续的 |TouchPointerSample|，直到下一个 |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

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

 无默认取景方式

Rectangle

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

轴对齐的矩形。它由坐标系中的最小和最大范围来定义。

字段类型说明默认
min Point2

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

  • 其坐标成对小于最大范围坐标。
 无默认取景方式
max Point2

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

  • 其坐标成对大于最小范围的坐标。
 无默认取景方式

TouchInteractionId

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

事件流中触摸事件“互动”的唯一标识符。系统会将触摸事件作为一系列互动观察到，例如手指与显示屏接触和离开。

从初始状态 ADD 开始，跟随 EventPhase 状态机的有限指针事件序列称为“互动”。封闭（或过去）互动是指已达到最终状态（REMOVE 或 CANCEL）的互动；开放式（或当前）互动是指尚未进入最终状态的互动。

对于给定的设备指针，系统会将事件流作为连续零次或多次关闭的互动（过去的用户互动历史记录）观察到的事件流，然后最多只允许有一个开放式互动（当前用户互动）。

由于我们需要按指针事件对事件进行分组，因此触摸事件会携带一个在该指针流中唯一的互动 ID。通过这种通用引用，可以在封闭式交互和开放式交互上运行。

如需了解关于鼠标按事件流进行的讨论，另请参阅 EventPhase。

字段类型说明默认
device_id uint32

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

 无默认取景方式
pointer_id uint32

发出此事件的指针的标识符。它仅对特定 |device_id| 唯一性。每个 (device_id, pointer_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 阶段开始，后跟零个或多个 CHANGE 阶段，最后以 REMOVE 或 CANCEL 阶段结束。

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

从初始状态开始，跟随此状态机的有限指针事件序列称为“互动”。关闭（或过去）互动是指已经达到终止状态的互动；进行（或当前）互动是指尚未进入终止状态的互动。

对于给定的设备指针，系统会将事件流作为连续零次或多次关闭的互动（过去的用户互动历史记录）观察到的事件流，然后最多只允许有一个开放式互动（当前用户互动）。

当我们需要按指针事件对事件进行分组时，事件会带有一个在该指针流中唯一的互动 ID。这种通用引用让您可以同时对封闭式互动和开放式互动执行操作。

例如，触摸事件通常作为一系列互动观察到，例如手指与显示屏接触和离开。

名称值说明
1

设备已开始跟踪指针。
2

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

设备已停止跟踪指针。
4

指针已不可用。

MouseViewStatus 严格

类型：uint32

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

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

名称值说明
1

视频流将定向到此视图。
2

系统会将视频流定向到此视图。

TouchInteractionStatus 严格

类型：uint32

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

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

名称值说明
1

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

客户已被授予互动的所有权。

TouchResponseType 严格

类型：uint32

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

客户端可对给定 |TouchPointerSample| 做出响应的可能互动处置。用作手势消除歧义方案的一部分。

这些响应基于对互动的所有权声明概念。客户端可以在开放式交互中声明所有权声明，但服务器只能授予一个客户端的声明；其他客户端的声明会被拒绝。

名称值说明
1

客户不再对这种互动感兴趣；因此会拒绝对互动的所有权。客户端将停止接收此互动的事件。
2

客户对此互动感兴趣，但需要查看更多事件才能做决定；客户尚未声明对此互动的所有权。
3

客户对此互动感兴趣，但需要查看更多事件才能做决定；客户尚未声明对该互动的所有权。在所有权解决过程中，它会优先于优先级较低的“不确定”声明的优先级，但始终会输给“是”声明。
4

客户对此互动感兴趣，但需要查看更多事件才能做决定；客户尚未声明对该互动的所有权。此外，它会抑制尝试解决互动所有权问题的优先级较低的声明。
5

客户对此互动感兴趣，但需要查看更多事件才能做决定；客户尚未声明对该互动的所有权。此外，它会抑制尝试解决互动所有权问题的优先级较低的声明。在所有权解决期间，它会优先于优先级较低的“不确定”声明的优先级，但始终会输给“是”声明。
6

客户对此互动感兴趣，但需要查看后续互动才能做出决定；客户尚未声明对此互动的所有权。它会阻止在互动结束时解决所有权问题。
7

客户对此互动感兴趣，但需要查看后续互动才能做出决定；客户尚未声明对此互动的所有权。它会阻止在互动结束时解决所有权问题。此外，它会抑制试图解决互动所有权问题的优先级较低的声明。
8

客户端希望独占访问此互动中的其余事件；它声明对此互动的所有权（但可能会同意或拒绝该声明）。在所有权解决过程中，它会让优先级较低的“yes”声明的优先级更高。
9

客户端希望独占访问此互动中的其余事件；它声明对此互动的所有权（但可能会同意或拒绝该声明）。在所有权解决期间，它会优先于优先级较低的“yes”声明。

表

MouseDeviceInfo

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

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

序数字段类型说明
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 中定义

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

序数字段类型说明
timestamp zx/Time

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

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

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

鼠标设备的说明，足以正确解释设备的功能和使用 intent。

  • 它会针对每台设备发出一次。
pointer_sample MousePointerSample

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

签发政策。有两种调度模式：“悬停”和“锁定”。系统将默认为悬停模式，数据流会以 fragment 的形式分派给每个鼠标事件在其之上悬停的可见客户端。锁定模式会将数据流定向到单个客户端（无论视图边界如何），直到解锁为止。锁定模式通常在用户按下鼠标主按钮时切换，但最终是特定于产品的政策。
stream_info MouseEventStreamInfo

用于在悬停模式下进入/退出观看的信号。

  • 该事件会在悬停进入视图时发出，在通过悬停鼠标退出视图时发出。
trace_flow_id uint64

用于关联此事件跨组件边界或抽象层的发送/接收情况的标识符。

MousePointerSample

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

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

MousePointerSample 可以将多项状态更改捆绑到一个事件中。例如，如果用户滚动鼠标滚轮并同时按下左按钮，客户端可能会在 1 个事件中同时接收滚动和按钮状态更改，或在单独的事件中接收按钮更改和滚动更改。

序数字段类型说明
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 中定义

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

序数字段类型说明
id uint32

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

TouchEvent

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

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

序数字段类型说明
timestamp zx/Time

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

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

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

指针设备的说明，足以正确解释设备的功能和使用 intent。

  • 它会针对每台设备发出一次。
pointer_sample TouchPointerSample

对触摸事件互动过程中每个采样数据点的说明。

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

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

  • 系统在每次互动时发出一次。
trace_flow_id uint64

用于关联此事件跨组件边界或抽象层的发送/接收情况的标识符。

TouchPointerSample

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

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

序数字段类型说明
interaction TouchInteractionId

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

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

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

TouchResponse

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

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

只有 |TouchPointerSample| 需要 |TouchResponseType|；对于其他事件，服务器需要一个空的 |TouchResponse| 表。

序数字段类型说明
response_type TouchResponseType

客户端针对指定的 |TouchPointerSample| 响应的互动处置。
trace_flow_id uint64

用于关联此响应跨组件边界或抽象层的发送/接收情况的标识符。

常量

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

别名

名称值说明
Mat3 array[9]

浮点 3x3 矩阵。

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

一个二维浮点数。

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

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

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

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