Google is committed to advancing racial equity for Black communities. See how.

fuchsia.ui.pointer.augment

These augmentation protocols represent powerful introspection capabilities into the view hierarchy, and must be individually routed to specific target components. Most clients should not have access to these protocols. Some commonalities:

  • Theory of operation. These augmentation protocols accept a standard protocol endpoint and return an augmented protocol endpoint. In case of error, the original endpoint is returned.
  • View hierarchy scope. The reach of the augmented protocols are inherently bound to the original protocols they augment. That is, if the original protocol has power over only one view, the augmented protocol gives access to only that view.
  • Security warning. These protocols enable a form of clickjacking! While the view hierarchy prevents clickjacking of arbitrary views, care must be taken to route these augmentation protocols to the intended view's component.
  • Security guarantees. These protocols offer Confidentiality, Integrity, and Availability of the augmented data to authorized components. That is, non-authorized components cannot snoop on this data, modify its contents, or prevent its dispatch to authorized components.
  • Append semantics. Each augmentation provides augmentation-specific data to the protocol's regular event, but otherwise is not intended to modify the original protocol's basic functionality.
  • Synchronicity. The augmentation-specific data is synchronous with the original protocol's data.
  • API evolution. Server-side can introduce new methods to these protocols, and new fields to these tables, without breaking existing clients of the original or augmented protocol. For example, MouseEventWithGlobalMouse can be extended without consequences for fuchsia.ui.pointer.MouseEvent.
  • API evolution. When clients require substantially different augmentation, new augmentation protocols representing those capabilities can (and should) be introduced. For example, if one client of GlobalMouse requires additional fields that are really about view-local hit data, it would be reasonable to mint a new augmentation.

PROTOCOLS

GlobalMouse

Defined in fuchsia.ui.pointer.augment/augment.fidl

A method for a client to receive view-global visibility for mouse behavior.

  • The augmented data are scoped to the view of the client.

Upgrade

An exchange from an original mouse protocol endpoint to an augmented mouse protocol endpoint. If successful, error is empty, original is consumed, and augmented is returned for the client's use. Otherwise, the error carries back original for the client's use, and augmented is null.

Request

NameType
original fuchsia.ui.pointer/MouseSource

Response

NameType
augmented MouseSourceWithGlobalMouse?
error ErrorForGlobalMouse?

LocalHit

Defined in fuchsia.ui.pointer.augment/augment.fidl

A method for a client to upgrade its touch event protocol to additionally receive local-hit data for touch events.

Upgrade

An exchange from an original touch protocol endpoint to an augmented touch protocol endpoint. If successful, error is empty, original is consumed, and augmented is returned for the client's use. Otherwise, the error carries back original for the client's use, and augmented is null.

Request

NameType
original fuchsia.ui.pointer/TouchSource

Response

NameType
augmented TouchSourceWithLocalHit?
error ErrorForLocalHit?

MouseSourceWithGlobalMouse

Defined in fuchsia.ui.pointer.augment/augment.fidl

Like fuchsia.ui.pointer.MouseSource, but with additional information about the global position of mouse events, and otherwise identical in operation. See fuchsia.ui.pointer.MouseSource for regular usage information.

Watch

Identical usage to fuchsia.ui.pointer.MouseSource.Watch, but with augmented data.

Request

NameType

Response

NameType
events vector<MouseEventWithGlobalMouse>[128]

TouchSourceWithLocalHit

Defined in fuchsia.ui.pointer.augment/augment.fidl

Like fuchsia.ui.pointer.TouchSource, but with additional information about the local-hit position of touch events, and otherwise identical in operation. See fuchsia.ui.pointer.TouchSource for regular usage information.

UpdateResponse

Identical usage to fuchsia.ui.pointer.TouchSource.UpdateResponse.

Request

NameType
interaction fuchsia.ui.pointer/TouchInteractionId
response fuchsia.ui.pointer/TouchResponse

Response

NameType

Watch

Identical usage to fuchsia.ui.pointer.TouchSource.Watch, but with augmented data.

Request

NameType
responses vector<fuchsia.ui.pointer/TouchResponse>[128]

Response

NameType
events vector<TouchEventWithLocalHit>[128]

STRUCTS

ErrorForGlobalMouse

Defined in fuchsia.ui.pointer.augment/augment.fidl

Abnormal return for global mouse.

NameTypeDescriptionDefault
error_reason ErrorReason

Abnormal reason for return.

No default
original fuchsia.ui.pointer/MouseSource

Original protocol endpoint for client use.

No default

ErrorForLocalHit

Defined in fuchsia.ui.pointer.augment/augment.fidl

NameTypeDescriptionDefault
error_reason ErrorReason

Abnormal reason for return.

No default
original fuchsia.ui.pointer/TouchSource

Original protocol endpoint for client use.

No default

TouchEventWithLocalHit

Defined in fuchsia.ui.pointer.augment/augment.fidl

An augmentation of fuchsia.ui.pointer.TouchEvent to provide local-hit data for a touch event.

For a given touch event e, consider the ordered list of intersections with graphical content: its "hits" from top to bottom. The "local hit" of e is the location of e in the coordinate system of the view in which e has the top-most intersection.

NameTypeDescriptionDefault
touch_event fuchsia.ui.pointer/TouchEvent

Identical usage to fuchsia.ui.pointer.TouchEvent.

No default
local_viewref_koid zx/koid

Augmented data for touch_event that describes the top-most client KOID that it hits.

No default
local_point Point2

Augmented data for touch_event that describes its local coordinates in the coordinate space for local_viewref_koid.

No default

ENUMS

ErrorReason

Type: uint32

Defined in fuchsia.ui.pointer.augment/augment.fidl

Abnormal conditions for augmentation protocols.

NameValueDescription
DENIED 1

The augmentation attempt was denied.

TABLES

MouseEventWithGlobalMouse

Defined in fuchsia.ui.pointer.augment/augment.fidl

An augmentation of fuchsia.ui.pointer.MouseEvent to provide view-global visibility for mouse behavior.

  • The augmented data are scoped to the view of the client.
OrdinalNameTypeDescription
1 mouse_event fuchsia.ui.pointer/MouseEvent

Identical usage to fuchsia.ui.pointer.MouseEvent. In particular, if the client's view is obscured, mouse_event will be empty.

2 global_position fuchsia.ui.pointer/MousePointerSample

Augmented data that describes the position of a mouse_event within the client's view, regardless of obscuring or latching.

3 global_stream_info fuchsia.ui.pointer/MouseEventStreamInfo

Augmented data that describes when the mouse stream enters or exits the client's view.

TYPE ALIASES

NameValueDescription
Point2 array[2]

A floating point two-dimensional point.

  • The values are placed in (x, y) order.