<link rel="stylesheet" href="../style.css" />

[TOC]
# fuchsia.ui.pointer.augment

<p>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:</p>
<ul>
<li>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.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
<li>Synchronicity. The augmentation-specific data is synchronous with the
original protocol's data.</li>
<li>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, <a class='link' href='#MouseEventWithGlobalMouse'>MouseEventWithGlobalMouse</a>
can be extended without consequences for
<a class='link' href='#fuchsia.ui.pointer.MouseEvent'>fuchsia.ui.pointer.MouseEvent</a>.</li>
<li>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 <a class='link' href='#GlobalMouse'>GlobalMouse</a>
requires additional fields that are really about view-local hit data, it
would be reasonable to mint a new augmentation.</li>
</ul>
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 7</span></div>

## **PROTOCOLS**

## GlobalMouse {#GlobalMouse}
*Defined in [fuchsia.ui.pointer.augment/augment.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.pointer.augment/augment.fidl;l=63)*
<p>A method for a client to receive view-global visibility for mouse behavior.</p>
<ul>
<li>The augmented data are scoped to the view of the client.</li>
</ul>

### Upgrade {#GlobalMouse.Upgrade}

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

#### Request {#GlobalMouse.Upgrade_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>original</code></td>
            <td>
                <code><a class='link' href='../fuchsia.ui.pointer/'>fuchsia.ui.pointer</a>/<a class='link' href='../fuchsia.ui.pointer/#MouseSource'>MouseSource</a></code>
            </td>
        </tr>
</table>


#### Response {#GlobalMouse.Upgrade_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>augmented</code></td>
            <td>
                <code><a class='link' href='#MouseSourceWithGlobalMouse'>MouseSourceWithGlobalMouse</a>?</code>
            </td>
        </tr>
        <tr>
            <td><code>error</code></td>
            <td>
                <code><a class='link' href='#ErrorForGlobalMouse'>ErrorForGlobalMouse</a>?</code>
            </td>
        </tr>
</table>

## LocalHit {#LocalHit}
*Defined in [fuchsia.ui.pointer.augment/augment.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.pointer.augment/augment.fidl;l=128)*
<p>A method for a client to upgrade its touch event protocol to additionally
receive local-hit data for touch events.</p>

### Upgrade {#LocalHit.Upgrade}

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

#### Request {#LocalHit.Upgrade_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>original</code></td>
            <td>
                <code><a class='link' href='../fuchsia.ui.pointer/'>fuchsia.ui.pointer</a>/<a class='link' href='../fuchsia.ui.pointer/#TouchSource'>TouchSource</a></code>
            </td>
        </tr>
</table>


#### Response {#LocalHit.Upgrade_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>augmented</code></td>
            <td>
                <code><a class='link' href='#TouchSourceWithLocalHit'>TouchSourceWithLocalHit</a>?</code>
            </td>
        </tr>
        <tr>
            <td><code>error</code></td>
            <td>
                <code><a class='link' href='#ErrorForLocalHit'>ErrorForLocalHit</a>?</code>
            </td>
        </tr>
</table>

## MouseSourceWithGlobalMouse {#MouseSourceWithGlobalMouse}
*Defined in [fuchsia.ui.pointer.augment/augment.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.pointer.augment/augment.fidl;l=81)*
<p>Like <a class='link' href='#fuchsia.ui.pointer.MouseSource'>fuchsia.ui.pointer.MouseSource</a>, but with additional information
about the global position of mouse events, and otherwise identical in
operation. See <a class='link' href='#fuchsia.ui.pointer.MouseSource'>fuchsia.ui.pointer.MouseSource</a> for regular usage
information.</p>

### Watch {#MouseSourceWithGlobalMouse.Watch}

<p>Identical usage to <a class='link' href='#fuchsia.ui.pointer.MouseSource.Watch'>fuchsia.ui.pointer.MouseSource.Watch</a>, but with
augmented data.</p>

#### Request {#MouseSourceWithGlobalMouse.Watch_Request}

&lt;EMPTY&gt;


#### Response {#MouseSourceWithGlobalMouse.Watch_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>events</code></td>
            <td>
                <code>vector&lt;<a class='link' href='#MouseEventWithGlobalMouse'>MouseEventWithGlobalMouse</a>&gt;[128]</code>
            </td>
        </tr>
</table>

## TouchSourceWithLocalHit {#TouchSourceWithLocalHit}
*Defined in [fuchsia.ui.pointer.augment/augment.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.pointer.augment/augment.fidl;l=146)*
<p>Like <a class='link' href='#fuchsia.ui.pointer.TouchSource'>fuchsia.ui.pointer.TouchSource</a>, but with additional information
about the local-hit position of touch events, and otherwise identical in
operation. See <a class='link' href='#fuchsia.ui.pointer.TouchSource'>fuchsia.ui.pointer.TouchSource</a> for regular usage
information.</p>

### UpdateResponse {#TouchSourceWithLocalHit.UpdateResponse}

<p>Identical usage to <a class='link' href='#fuchsia.ui.pointer.TouchSource.UpdateResponse'>fuchsia.ui.pointer.TouchSource.UpdateResponse</a>.</p>

#### Request {#TouchSourceWithLocalHit.UpdateResponse_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>interaction</code></td>
            <td>
                <code><a class='link' href='../fuchsia.ui.pointer/'>fuchsia.ui.pointer</a>/<a class='link' href='../fuchsia.ui.pointer/#TouchInteractionId'>TouchInteractionId</a></code>
            </td>
        </tr>
        <tr>
            <td><code>response</code></td>
            <td>
                <code><a class='link' href='../fuchsia.ui.pointer/'>fuchsia.ui.pointer</a>/<a class='link' href='../fuchsia.ui.pointer/#TouchResponse'>TouchResponse</a></code>
            </td>
        </tr>
</table>


#### Response {#TouchSourceWithLocalHit.UpdateResponse_Response}

&lt;EMPTY&gt;

### Watch {#TouchSourceWithLocalHit.Watch}

<p>Identical usage to <a class='link' href='#fuchsia.ui.pointer.TouchSource.Watch'>fuchsia.ui.pointer.TouchSource.Watch</a>, but with
augmented data.</p>

#### Request {#TouchSourceWithLocalHit.Watch_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>responses</code></td>
            <td>
                <code>vector&lt;<a class='link' href='../fuchsia.ui.pointer/'>fuchsia.ui.pointer</a>/<a class='link' href='../fuchsia.ui.pointer/#TouchResponse'>TouchResponse</a>&gt;[128]</code>
            </td>
        </tr>
</table>


#### Response {#TouchSourceWithLocalHit.Watch_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>events</code></td>
            <td>
                <code>vector&lt;<a class='link' href='#TouchEventWithLocalHit'>TouchEventWithLocalHit</a>&gt;[128]</code>
            </td>
        </tr>
</table>


## **STRUCTS**

### ErrorForGlobalMouse [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ErrorForGlobalMouse data-text="ErrorForGlobalMouse"}
*Defined in [fuchsia.ui.pointer.augment/augment.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.pointer.augment/augment.fidl;l=53)*
<p>Abnormal return for global mouse.</p>

<table>
    <tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
        <tr id="ErrorForGlobalMouse.error_reason">
            <td><code>error_reason</code></td>
            <td>
                <code><a class='link' href='#ErrorReason'>ErrorReason</a></code>
            </td>
            <td><p>Abnormal reason for return.</p>
</td>
            <td>No default</td>
        </tr>
        <tr id="ErrorForGlobalMouse.original">
            <td><code>original</code></td>
            <td>
                <code><a class='link' href='../fuchsia.ui.pointer/'>fuchsia.ui.pointer</a>/<a class='link' href='../fuchsia.ui.pointer/#MouseSource'>MouseSource</a></code>
            </td>
            <td><p>Original protocol endpoint for client use.</p>
</td>
            <td>No default</td>
        </tr>
</table>

### ErrorForLocalHit [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#ErrorForLocalHit data-text="ErrorForLocalHit"}
*Defined in [fuchsia.ui.pointer.augment/augment.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.pointer.augment/augment.fidl;l=117)*

<table>
    <tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
        <tr id="ErrorForLocalHit.error_reason">
            <td><code>error_reason</code></td>
            <td>
                <code><a class='link' href='#ErrorReason'>ErrorReason</a></code>
            </td>
            <td><p>Abnormal reason for return.</p>
</td>
            <td>No default</td>
        </tr>
        <tr id="ErrorForLocalHit.original">
            <td><code>original</code></td>
            <td>
                <code><a class='link' href='../fuchsia.ui.pointer/'>fuchsia.ui.pointer</a>/<a class='link' href='../fuchsia.ui.pointer/#TouchSource'>TouchSource</a></code>
            </td>
            <td><p>Original protocol endpoint for client use.</p>
</td>
            <td>No default</td>
        </tr>
</table>

### TouchEventWithLocalHit  {#TouchEventWithLocalHit data-text="TouchEventWithLocalHit"}
*Defined in [fuchsia.ui.pointer.augment/augment.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.pointer.augment/augment.fidl;l=172)*
<p>An augmentation of <a class='link' href='#fuchsia.ui.pointer.TouchEvent'>fuchsia.ui.pointer.TouchEvent</a> to provide local-hit
data for a touch event.</p>
<p>For a given touch event <code>e</code>, consider the ordered list of intersections with
graphical content: its &quot;hits&quot; from top to bottom. The &quot;local hit&quot; of <code>e</code> is
the location of <code>e</code> in the coordinate system of the view in which <code>e</code> has
the top-most intersection.</p>

<table>
    <tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
        <tr id="TouchEventWithLocalHit.touch_event">
            <td><code>touch_event</code></td>
            <td>
                <code><a class='link' href='../fuchsia.ui.pointer/'>fuchsia.ui.pointer</a>/<a class='link' href='../fuchsia.ui.pointer/#TouchEvent'>TouchEvent</a></code>
            </td>
            <td><p>Identical usage to <a class='link' href='#fuchsia.ui.pointer.TouchEvent'>fuchsia.ui.pointer.TouchEvent</a>.</p>
</td>
            <td>No default</td>
        </tr>
        <tr id="TouchEventWithLocalHit.local_viewref_koid">
            <td><code>local_viewref_koid</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#koid'>koid</a></code>
            </td>
            <td><p>Augmented data for <code>touch_event</code> that describes the top-most client
KOID that it hits.</p>
</td>
            <td>No default</td>
        </tr>
        <tr id="TouchEventWithLocalHit.local_point">
            <td><code>local_point</code></td>
            <td>
                <code><a class='link' href='#Point2'>Point2</a></code>
            </td>
            <td><p>Augmented data for <code>touch_event</code> that describes its local coordinates in
the coordinate space for <code>local_viewref_koid</code>.</p>
</td>
            <td>No default</td>
        </tr>
</table>


## **ENUMS**

### ErrorReason [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#ErrorReason data-text="ErrorReason"}
Type: <code>uint32</code>

*Defined in [fuchsia.ui.pointer.augment/augment.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.pointer.augment/augment.fidl;l=45)*
<p>Abnormal conditions for augmentation protocols.</p>

<table>
    <tr><th>Name</th><th>Value</th><th>Description</th></tr>
        <tr id="ErrorReason.DENIED">
<td><h3 id="ErrorReason.DENIED" class="add-link hide-from-toc">DENIED</h3></td>
            <td><code>1</code></td>
            <td><p>The augmentation attempt was denied.</p>
</td>
        </tr>
</table>


## **TABLES**

### MouseEventWithGlobalMouse  {#MouseEventWithGlobalMouse data-text="MouseEventWithGlobalMouse"}


*Defined in [fuchsia.ui.pointer.augment/augment.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.pointer.augment/augment.fidl;l=100)*
<p>An augmentation of <a class='link' href='#fuchsia.ui.pointer.MouseEvent'>fuchsia.ui.pointer.MouseEvent</a> to provide global
visibility for mouse behavior in the injection subtree.</p>
<ul>
<li>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).</li>
<li>Augmented data is only produced for events injected either into or above
the view in the scene graph.
<ul>
<li>This means that local events ~= global events when the view is the
root of the injection subtree.</li>
<li>Otherwise the client will see all events up to root of the injection
subtree.</li>
</ul>
</li>
</ul>

<table>
    <tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
        <tr id="MouseEventWithGlobalMouse.mouse_event">
<td><h3 id="MouseEventWithGlobalMouse.mouse_event" class="add-link hide-from-toc">1</h3></td>
            <td><code>mouse_event</code></td>
            <td>
                <code><a class='link' href='../fuchsia.ui.pointer/'>fuchsia.ui.pointer</a>/<a class='link' href='../fuchsia.ui.pointer/#MouseEvent'>MouseEvent</a></code>
            </td>
            <td><p>Identical usage to <a class='link' href='#fuchsia.ui.pointer.MouseEvent'>fuchsia.ui.pointer.MouseEvent</a>. In particular, if
the client's view is obscured, <code>mouse_event</code> will be empty.</p>
</td>
        </tr>
        <tr id="MouseEventWithGlobalMouse.global_position">
<td><h3 id="MouseEventWithGlobalMouse.global_position" class="add-link hide-from-toc">2</h3></td>
            <td><code>global_position</code></td>
            <td>
                <code><a class='link' href='../fuchsia.ui.pointer/'>fuchsia.ui.pointer</a>/<a class='link' href='../fuchsia.ui.pointer/#MousePointerSample'>MousePointerSample</a></code>
            </td>
            <td><p>Augmented data that describes the position of a <code>mouse_event</code> within the
client's view, regardless of obscuring or latching.</p>
</td>
        </tr>
        <tr id="MouseEventWithGlobalMouse.global_stream_info">
<td><h3 id="MouseEventWithGlobalMouse.global_stream_info" class="add-link hide-from-toc">3</h3></td>
            <td><code>global_stream_info</code></td>
            <td>
                <code><a class='link' href='../fuchsia.ui.pointer/'>fuchsia.ui.pointer</a>/<a class='link' href='../fuchsia.ui.pointer/#MouseEventStreamInfo'>MouseEventStreamInfo</a></code>
            </td>
            <td><p>Augmented data that describes when the mouse stream enters or exits
the client's view.</p>
</td>
        </tr>
</table>


## **TYPE ALIASES**

<table>
    <tr><th>Name</th><th>Value</th><th>Description</th></tr>
        <tr id="Point2">
            <td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.ui.pointer.augment/augment.fidl;l=163">Point2</a></td>
            <td>
                <code>array</code>[<code>2</code>]</td>
            <td><p>A floating point two-dimensional point.</p>
<ul>
<li>The values are placed in (x, y) order.</li>
</ul>
</td>
        </tr>
</table>