docs/concepts/ui/input/hit_testing.md

# Hit Testing

## Overview

A hit is the point of interaction between a pointer event and a graphical view.

Hit testing is the process where Scenic determines which hits should be routed
to which clients.

### Hit regions

Client-submitted graphical content is not in and of itself hittable. Rather, it
is the rectangular hit regions attached to Flatland transforms that enable
content views to receive input events.

To ease the use of the Flatland API for developers, each view has a default hit
region. These hit regions act as normal hit regions but are added implicitly to
the root transform in the SetRootView() call. See the
[default hit regions](#default-hit-regions) section for more information.

### Semantic visibility

There are two types of hit regions Flatland clients may attach to transforms:
semantically visible and semantically invisible hit regions. The property of
semantic visibility can be ignored by most clients, as its only used in rare
accessibility-specific use cases. See the
[semantic visibility](/docs/concepts/ui/input/semantic_visibility.md#semantic-visibility)
page for more information.

## High level overview of algorithm

Given a hit at point (x,y), the View containing the geographically top-most
(topologically *last*) semantically-compatible hit region which intersects (x,y)
receives the hit. Let’s break down the requirements into its component parts.

#### Top most

Given a parent and child transform with content, the child transform is drawn on
top of the parent transform, and is also topologically after the parent.

Given two sibling transforms with the same parent, the child added *last* via
AddChild() is topologically after its sibling.

#### Semantic compatibility

Semantic hit tests do not interact with semantically invisible hit regions.

See the [semantic visibility](/docs/concepts/ui/input/semantic_visibility.md)
page for more information.

#### Overlap

A hit that is on the border of a hit region is considered to be included in that
hit region.

If two or more transforms share a border, the tie-breaker goes to the
topologically last transform.

## Default hit regions {#default-hit-regions}

While a View itself is not by default hittable, API clients tend to expect
content to be interactable when created, so Flatland creates a full screen
default hit region (DHR) for Views when they install their root transform via a
SetRootTransform() call, unless the client manually specifies their own hit
region.

DHRs are maximally sized, so resizing the View to be larger should not lead to a
part of the screen becoming unhittable.

The semantics of default hit regions can be summarized in the following rules:

1.  A DHR is added to the root transform, T, during a SetRootTransform(T) call
    if and only if no SetHitRegions(T) calls were made *prior*.
2.  Calling SetHitRegions(T, hit\_region\_vector) *after* a SetRootTransform(T)
    call overrides the DHR, even if |hit\_region\_vector| is empty.
3.  A DHR is only installed for a given root transform so long as it is the root
    View.
4.  A DHR for a given transform T is unaffected by any hit region operation on
    any other transform, U.

To help illustrate the semantics, let’s consider some examples.

### Scenario 1

```
SetRootTransform(T)
```

End state: T has a DHR.

### Scenario 2

```
SetRootTransform(T)

SetRootTransform(U)
```

End state: T has no hit regions, U has a DHR.

### Scenario 3

#### Scenario 3A

```
SetRootTransform(T)

SetHitRegions(T, {HR1})
```

#### Scenario 3B

```
SetHitRegions(T, {HR1})

SetRootTransform(T)
```

End state for 3A and 3B: T has one hit region, HR1. There is no DHR.

### Scenario 4

```
SetRootTransform(T)

SetHitRegions(T, { {} })
```

End state: T has no hit regions

### Scenario 5

```
SetRootTransform(T)

SetRootTransform(U)

SetHitRegions(T, {HR1, HR2})
```

End state: T has two hit regions, HR1 and HR2. U has a DHR.