Fuchsia.ui.pointer

新增日期：7

通訊協定

MouseSource

定義於 fuchsia.ui.pointer/mouse.fidl

供用戶端接收滑鼠指標事件的方法。

指標事件的位置是在檢視畫面中的可視區域結構定義中定義。檢視畫面和可視區域的維度及其空間關係 (以轉換矩陣定義) 會在 |ViewParameter| 資料表中同步提供。檢視畫面可套用可視區域至檢視畫面的轉換矩陣，藉此擷取指標在本機座標系統中的位置。

可視區域會嵌入在獨立且穩定的座標系統中，適合以與縮放比例獨立的方式解讀指標事件；在縮放或平移等效果下，仍會以固定比例觀察滑鼠移動。但是，其他效果 (例如放大檢視區塊的裁剪範圍) 也可能會觸發可視區域範圍變更。

觀看

供用戶端接收滑鼠指標事件的方法。

這項呼叫的公式為「掛斷」模式：用戶端會要求一組近期事件，並透過回呼接收這些事件。這種提取式方法可確保用戶端按照自身步調使用事件；事件不會以無限的方式累積管道。

流量控制。每次最多只能有一個進行中的 |Watch| 呼叫呼叫端；同時對 |Watch| 發出並行呼叫屬於邏輯錯誤。 違反規定會導致管道關閉。

客戶放送速度：伺服器會依照 FIFO 盡可能避免、盡力而將事件分派給呼叫端，但呼叫端必須分配足夠的時間來因應新事件。

活動時間。在事件向量中，每個事件的時間戳記「並非」保證一致；不同裝置的事件可能會在不同時間插入 Snic。一般來說，單一裝置的事件預期具有單調遞增的時間戳記。

查看參數。有時候，檢視或可視區域的變更需要通知用戶端。如果 |MouseEvent| 包含 |ViewParameters|，這些參數會套用至連續的 |MousePointerSample|s 直到下一個 |ViewParameters|。

要求

<EMPTY>

回應

名稱類型
events vector<MouseEvent>[128]

TouchSource

定義於 fuchsia.ui.pointer/Touch.fidl

讓用戶端接收觸控事件並回應全域手勢消歧通訊協定的方法。

觸控事件的位置是在檢視區塊的可視區域中定義。檢視畫面和可視區域的維度及其空間關係 (以轉換矩陣定義) 會在 |ViewParameter| 資料表中同步提供。檢視畫面可套用可視區域至檢視畫面的轉換矩陣，藉此擷取指標在本機座標系統中的位置。

可視區域會嵌入在獨立且穩定的座標系統中，適合以與縮放比例獨立的方式解讀觸控事件；在放大或平移等效果下，仍會以固定比例觀察滑動。但是，其他效果 (例如放大檢視區塊的裁剪範圍) 也可能會觸發可視區域範圍變更。

UpdateResponse

手勢通訊協定可讓用戶端對觸控事件的開放式互動行為進行「保留」操作；即使在互動結束之後，手勢通訊協定仍會防止系統解析互動擁有權。這個方法會以回應 (可繼續解決擁有權問題) 取代用戶端先前的「訴訟保留」。

如要瞭解串流轉換為互動的方式，請參閱 |TouchInteractionId|。

流量控制。每次互動中，呼叫端最多只能有一次 |UpdateResponse| 呼叫，而且必須在封閉互動中。使用 |Watch| 呼叫進行一般回應時，就呼叫 |UpdateResponse| 是邏輯錯誤。

有效性。這個 TouchResponse 不得為另一個「保留」回應，且遭覆寫的回應應為「保留」回應。

要求

名稱類型
interaction TouchInteractionId
response TouchResponse

回應

<EMPTY>

觀看

供用戶端接收觸控指標事件的方法。

這項呼叫的公式為「掛斷」模式：用戶端會要求一組近期事件，並透過回呼接收這些事件。這種提取式方法可確保用戶端按照自身步調使用事件；事件不會以無限的方式累積管道。

流量控制。每次最多只能有一個進行中的 |Watch| 呼叫呼叫端；同時對 |Watch| 發出並行呼叫屬於邏輯錯誤。 違反規定會導致管道關閉。

客戶放送速度：伺服器會依照 FIFO 盡可能避免、盡力而將事件分派給呼叫端，但呼叫端必須分配足夠的時間來因應新事件。系統可能會將無回應的用戶端歸類為「應用程式無回應」，並以管道關閉為目標。

回覆。手勢消歧配置必須仰賴伺服器接收每個 |TouchEvent|.|TouchPointerSample| 的 |TouchResponse|。非範例事件應將空白的 |TouchResponse| 資料表傳回給伺服器。系統會在 |Watch| [1] 的「下一個」呼叫中，將「先前」事件的回應傳送至伺服器。|responses| 向量中的每個元素都會解釋為對前一個|事件| 向量中的事件的配對回應；向量長度必須相符。請注意，用戶端對事件的回應合約會在註冊端點後立即開始，而不是首次呼叫 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

發出滑鼠事件串流的滑鼠裝置 ID。

 無預設
status MouseViewStatus

滑鼠事件串流的進入/結束狀態，從伺服器傳送至用戶端。

 無預設

Rectangle

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

軸對齊的矩形。這是由座標系統中最小和最大範圍所定義。

欄位類型說明預設
min Point2

這個矩形的最小範圍 (含首尾)。

  • 其座標小於最大範圍的座標。
 無預設
max Point2

這個矩形的最大範圍 (含首尾)。

  • 其座標會大於最低程度的座標。
 無預設

TouchInteractionId

定義於 fuchsia.ui.pointer/Touch.fidl

適用於事件串流中觸控事件「互動」的專屬 ID。 系統會將觸控事件視為連續的互動，例如手指與螢幕的互動。

遵循 EventPhase 狀態機器的有限序列指標事件，從初始狀態 ADD 開始稱為「互動」。已關閉 (或過往) 互動是指已到達終端機狀態 (REMOVE 或 CANCEL) 的互動；公開 (或當前) 互動則沒有。

針對特定裝置指標，系統會將一個事件串流視為連續零或多個關閉互動 (使用者參與度的過往記錄)，接著最多發生一次公開互動 (目前的使用者參與度)。

我們需要根據指標事件將指標事件分組，因此觸控事件會採用該指標串流中不重複的「互動 ID」。這個常見的參照能讓您針對封閉互動和開放式互動進行操作。

另請參閱 EventPhase，這是關於滑鼠事件串流的討論。

欄位類型說明預設
device_id uint32

核發觸控事件串流的指標裝置 ID。裝置可能會有多個指標，每個指標都有專屬的 |pointer_id|。

 無預設
pointer_id uint32

核發這個事件的指標 ID。這個 ID 專屬於特定的 |device_id|。每對 (device_id、metrics_id) 配對，一次最多只會出現一個開放式互動問題。

 無預設
interaction_id uint32

互動的 ID。此 ID 僅適用於特定 (device_id, 指標_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

轉換矩陣，與可視區域座標系統中點的位置有關，與檢視畫面座標系統中的位置有關。

 無預設

ENUMS

事件階段嚴格

類型：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 strict

類型：uint32

定義於 fuchsia.ui.pointer/Touch.fidl

用戶端可以回應特定 |TouchPointerSample| 的可能互動配置。做為手勢消歧配置的一部分。

回應是根據互動擁有權聲明的概念而產生。用戶端可以在開放式互動中斷言擁有權聲明，但伺服器只會授予一個用戶端的擁有權聲明，其他用戶端的宣告會遭到拒絕。

名稱值說明
1

用戶端對這次互動沒有進一步興趣，拒絕互動的擁有權。用戶端就不會再收到這次互動的事件。
2

用戶端想要進行這項互動，但需要查看更多事件才能決定；用戶端尚未聲明這項互動的擁有權。
3

用戶端想要進行這項互動，但需要查看更多事件才能決定；用戶端尚未聲明互動的擁有權。在擁有權解析期間，系統會將其優先順序高於較低優先順序的「或許」憑證附加資訊，但永遠會失去「是」憑證附加資訊。
4

用戶端想要進行這項互動，但需要查看更多事件才能決定；用戶端尚未聲明互動的擁有權。此外，這也會略過試圖解析互動擁有權的較低優先順序憑證附加資訊。
5

用戶端想要進行這項互動，但需要查看更多事件才能決定；用戶端尚未聲明互動的擁有權。此外，這也會略過試圖解析互動擁有權的較低優先順序憑證附加資訊。在擁有權解析期間，系統會比優先順序較低的「也許」憑證附加資訊優先執行其優先順序，但永遠會失去「是」憑證附加資訊。
6

用戶端想要進行這項互動，但需要查看後續互動才能決定；用戶端尚未聲明互動的擁有權。防止在互動關閉時解決擁有權。
7

用戶端想要進行這項互動，但需要查看後續互動才能決定；用戶端尚未聲明互動的擁有權。防止在互動關閉時解決擁有權。此外，也會略過嘗試解析互動擁有權的較低優先順序聲明。
8

用戶端希望獲得此互動中其餘事件的專屬存取權；它會聲明此互動的擁有權 (但該聲明可能會授予或拒絕)。在擁有權解析期間，這會讓優先順序較低的「是」憑證附加資訊獲得優先處理。
9

用戶端希望獲得此互動中其餘事件的專屬存取權；它會聲明此互動的擁有權 (但該聲明可能會授予或拒絕)。在擁有權解析期間，系統會勝過優先順序較低的「是」憑證附加資訊。

資料表

MouseDeviceInfo

定義於 fuchsia.ui.pointer/mouse.fidl

發出滑鼠事件串流的裝置相關資訊。

序數欄位類型說明
id uint32

發出滑鼠事件串流的滑鼠裝置 ID。必填。
scroll_v_range fuchsia.input.report/Axis

裝置核發的垂直捲動值範圍。
scroll_h_range fuchsia.input.report/Axis

裝置核發的水平捲動值範圍。
buttons vector<uint8>[32]

裝置核發的按鈕 ID (優先順序)。
relative_motion_range RelativeMotionRange

裝置核發的相對移動值範圍。

MouseEvent

定義於 fuchsia.ui.pointer/mouse.fidl

足夠的自我一致性指標相關資料收集作業，從伺服器傳送至用戶端。

序數欄位類型說明
timestamp zx/Time

觀察到這個事件的時間。 必填。
view_parameters ViewParameters

相關聯檢視區塊和可視區域的參數，足以正確解讀分派至檢視畫面的指標事件的位置、方向、規模和事件間隔距離。

  • 系統會在連線與變更時核發該號碼。
device_info MouseDeviceInfo

滑鼠裝置的說明，充分解讀裝置的功能和使用意圖。

  • 每部裝置核發一次。
pointer_sample MousePointerSample

滑鼠事件串流中每個取樣資料點的說明。

核發政策。「滑鼠懸停」和「閂鎖」兩種分派模式有兩種。懸停模式為預設模式，而每個滑鼠事件懸停在上方，串流都會分派至片段中的可見用戶端。閂鎖模式會將串流導向單一用戶端 (不論檢視畫面邊界為何)，直到解除鎖狀態為止。延遲模式通常會在使用者按下滑鼠主要按鈕時切換，但最終是產品專屬的政策。
stream_info MouseEventStreamInfo

懸停模式下的檢視畫面進入/結束信號。

  • 系統會在遊標懸停在檢視畫面上時發出，並且將滑鼠遊標懸停在檢視畫面上。
trace_flow_id uint64

這個 ID 會關聯此事件在元件邊界或抽象層之間的傳送/接收發生情況。

MousePointerSample

定義於 fuchsia.ui.pointer/mouse.fidl

滑鼠事件串流中每個取樣資料點的說明。

MousePointerSample 可將多個狀態變更組合成單一事件。舉例來說，如果使用者同時捲動滑鼠滾輪並按下左方托頓按鈕，用戶端可能會在 1 個事件中一併收到捲動和按鈕狀態變更，或在不同的事件中接收按鈕變更和捲動變更。

序數欄位類型說明
device_id uint32

發出滑鼠事件串流的滑鼠裝置 ID。必填。
position_in_viewport Point2

此事件在可視區域的座標系統中的位置。必填。
scroll_v int64

垂直捲動的相對垂直捲動偏移。
scroll_h int64

相對水平捲動位移位移。
pressed_buttons vector<uint8>[32]

目前所按下按鈕的 ID。
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。 裝置可能會有多個指標，每個指標都有專屬的指標 ID 和自身的觸控事件串流。必填。

TouchEvent

定義於 fuchsia.ui.pointer/Touch.fidl

足夠的自我一致性指標相關資料收集作業，從伺服器傳送至用戶端。

序數欄位類型說明
timestamp zx/Time

觀察到這個事件的時間。 必填。
view_parameters ViewParameters

相關聯檢視區塊和可視區域的參數，足以正確解讀分派給檢視畫面的觸控事件的位置、方向、規模和事件間隔距離。

  • 系統會在連線與變更時核發該號碼。
device_info TouchDeviceInfo

指標裝置的說明，充分解讀裝置的功能和使用意圖。

  • 每部裝置核發一次。
pointer_sample TouchPointerSample

觸控事件互動中每個取樣資料點的說明。

  • 系統會在互動中的每一個樣本中核發此參數。
interaction_result TouchInteractionResult

與觸控事件互動時的手勢消歧結果。

  • 每次互動只會發出一次。
trace_flow_id uint64

這個 ID 會關聯此事件在元件邊界或抽象層之間的傳送/接收發生情況。

TouchPointerSample

定義於 fuchsia.ui.pointer/Touch.fidl

觸控事件串流中每個取樣資料點的說明。所有欄位均為必填。

序數欄位類型說明
interaction TouchInteractionId

此指標範例所屬的互動。
phase EventPhase

在互動的狀態機器中，此事件的狀態。
position_in_viewport Point2

此事件在可視區域的座標系統中的位置。

TouchResponse

定義於 fuchsia.ui.pointer/Touch.fidl

每個 |事件| 從用戶端傳送至伺服器的意見回饋事件。

只有 |TouchPointerSample| 需要 |TouchResponseType|，伺服器預期伺服器會出現空白的 |TouchResponse| 資料表。

序數欄位類型說明
response_type TouchResponseType

用戶端針對指定的 |TouchPointerSample| 回應的互動配置。
trace_flow_id uint64

這個 ID 會在元件邊界或抽象層之間，關聯此回應傳送/接收發生情況的關聯。

業者

名稱值類型說明
MOUSE_MAX_EVENT 128 uint32
TOUCH_MAX_EVENT 128 uint32

別名

名稱值說明
Mat3 array[9]

浮點數 3x3 矩陣。

  • 這些值會以資料欄的順序排列。
Point2 array[2]

浮點 2D 點。

  • 值的排列順序為 (x, y)。
RelativeMotion array[2]

滑鼠裝置執行的相對動作。
RelativeMotionRange array[2]

滑鼠裝置相關動態的有效值。

  • 範圍的排列順序是 (x, y)，