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
| Name | Type |
|---|---|
original |
fuchsia.ui.pointer/MouseSource
|
Response
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
original |
fuchsia.ui.pointer/TouchSource
|
Response
| Name | Type |
|---|---|
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
<EMPTY>
Response
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
interaction |
fuchsia.ui.pointer/TouchInteractionId
|
response |
fuchsia.ui.pointer/TouchResponse
|
Response
<EMPTY>
Watch
Identical usage to fuchsia.ui.pointer.TouchSource.Watch, but with augmented data.
Request
| Name | Type |
|---|---|
responses |
vector<fuchsia.ui.pointer/TouchResponse>[128]
|
Response
| Name | Type |
|---|---|
events |
vector<TouchEventWithLocalHit>[128]
|
STRUCTS
ErrorForGlobalMouse resource
Defined in fuchsia.ui.pointer.augment/augment.fidl
Abnormal return for global mouse.
| Field | Type | Description | Default |
|---|---|---|---|
error_reason |
ErrorReason
|
Abnormal reason for return. |
No default |
original |
fuchsia.ui.pointer/MouseSource
|
Original protocol endpoint for client use. |
No default |
ErrorForLocalHit resource
Defined in fuchsia.ui.pointer.augment/augment.fidl
| Field | Type | Description | Default |
|---|---|---|---|
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.
| Field | Type | Description | Default |
|---|---|---|---|
touch_event |
fuchsia.ui.pointer/TouchEvent
|
Identical usage to fuchsia.ui.pointer.TouchEvent. |
No default |
local_viewref_koid |
zx/koid
|
Augmented data for |
No default |
local_point |
Point2
|
Augmented data for |
No default |
ENUMS
ErrorReason strict
Type: uint32
Defined in fuchsia.ui.pointer.augment/augment.fidl
Abnormal conditions for augmentation protocols.
| Name | Value | Description |
|---|---|---|
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 global visibility for mouse behavior in the injection subtree.
- The augmented data is scoped to the view of the client, meaning no events will be delivered when the mouse pointer is outside the view (even when the stream is latched to this view).
- Augmented data is only produced for events injected either into or above
the view in the scene graph.
- This means that local events ~= global events when the view is the root of the injection subtree.
- Otherwise the client will see all events up to root of the injection subtree.
| Ordinal | Field | Type | Description |
|---|---|---|---|
| 1 | mouse_event |
fuchsia.ui.pointer/MouseEvent
|
Identical usage to fuchsia.ui.pointer.MouseEvent. In particular, if
the client's view is obscured, |
| 2 | global_position |
fuchsia.ui.pointer/MousePointerSample
|
Augmented data that describes the position of a |
| 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
| Name | Value | Description |
|---|---|---|
| Point2 |
array[2] |
A floating point two-dimensional point.
|