1# Pointer Capture in InputFlinger
2
3## Introduction
4
5[Pointer Capture](https://developer.android.com/training/gestures/movement#pointer-capture) is a feature that was introduced to the Android input pipeline in Android 8.0 (Oreo). Pointer Capture can be enabled or disabled for an `InputWindow` through requests to `InputManagerService`. Enabling Pointer Capture performs the following changes related to the mouse cursor and the devices that control it:
6
7- The position of the mouse cursor is fixed to its location before Pointer Capture was enabled.
8- The mouse cursor is hidden.
9- Events from a mouse will be delivered with the source `SOURCE_MOUSE_RELATIVE`, and their `AXIS_X` and `AXIS_Y` will report relative position changes.
10- Events from a touchpad will be delivered with the source `SOURCE_TOUCHPAD`, and their `AXIS_X` and `AXIS_Y` will report the absolute position of each of the pointers on the touchpad.
11- Events from mouse and touchpad devices are dispatched to the focused `InputWindow`.
12- Events from devices that do not normally control the mouse cursor are not affected.
13
14`InputWindow`s can only gain Pointer Capture if they have window focus. If a window with Pointer Capture loses focus, Pointer Capture is disabled.
15
16## Pointer Capture pipeline in InputFlinger
17
18`InputDispatcher` is responsible for controlling the state of Pointer Capture. Since the feature requires changes to how events are generated, Pointer Capture is configured in `InputReader`.
19
20We use a sequence number to synchronize different requests to enable Pointer Capture between InputReader and InputDispatcher.
21
22### Enabling Pointer Capture
23
24There are four key steps that take place when Pointer Capture is enabled:
25
261. Requests to enable Pointer Capture are forwarded from `InputManagerService` to `InputDispatcher`.
272. If the window that makes the request has focus, `InputDispatcher` enables the Pointer Capture state in `InputReader` through the `InputDispatcherPolicy`.
283. When `InputReader` is successfully configured, it notifies `InputDispatcher` through the `InputListener` interface.
294. `InputDispatcher` then notifies the `InputWindow` that Pointer Capture has been enabled by sending a special `CAPTURE` event through the `InputChannel`.
30
31### Disabling Pointer Capture
32
33Pointer Capture can be disabled in two ways: by a request through `InputManagerService`, and as a result of the `InputWindow` losing focus.
34
35When Pointer Capture is disabled by a request from the application, it follows the same pipeline as when Pointer Capture is enabled.
36
37#### Window loses Pointer Capture when it loses focus
38
39When an `InputWindow` with Pointer Capture loses focus, Pointer Capture is disabled immediately. The `InputWindow` receives a `CAPTURE` event through the `InputChannel`, followed by a `FOCUS` event to notify loss of focus.
40
41## Pointer Capture in `InputDispatcher`
42
43`InputDispatcher` tracks two pieces of state information regarding Pointer Capture:
44
45- `mCurrentPointerCaptureRequest`: The sequence number of the current Pointer Capture request. This request is enabled iff the focused window has requested Pointer Capture. This is updated whenever the Dispatcher receives requests from `InputManagerService`.
46- `mWindowTokenWithPointerCapture`: The Binder token of the `InputWindow` that currently has Pointer Capture. This is only updated during the dispatch cycle. If it is not `nullptr`, it signifies that the window was notified that it has Pointer Capture.
47