Android form factors: Android TV (go)¶
Part of Android form factors.
TV navigation is a focus problem: D-pad keys can be sent and the focused element comes back in every observation. The focusNavigate loop connects them. When LAUNCHER resolution finds no activity, launchApp tries MAIN/LEANBACK_LAUNCHER, including activity-query and package-dump fallbacks. On devices with formFactor: "tv", listApps includes Leanback entry points in launchability.
- Activate focused item. On the verified image,
enteractivates the focused item. The image does not needKEYCODE_DPAD_CENTER, and noselectkey exists. If a future TV image shows thatenterdoes not activate, addselect(KEYCODE_DPAD_CENTER) to bothSUPPORTED_INPUT_KEYSandINPUT_KEY_CODE_MAP. TheInputKeyNametype derives from the first and the second is checked against it, so one entry alone does not compile. focusNavigate({ until, direction?, maxSteps?, settleMs?, select? })(src/features/action/FocusNavigate.ts). On tvOS,src/features/tvos/TvosFocusNavigate.tsreuses the loop, mapping arrows to Siri Remote directions andentertoselect. The loop observes and stops if the focused element itself or a label it owns matchesuntil. Otherwise it presses one D-pad key and repeats. It returns the path of focused elements.- Match: a descendant cannot supply a match when the focused element is scrollable, or when a separately focusable/clickable control inside it contains that descendant. A card can still match its static child title. The loop matches
untilontext,contentDescandresourceId. Given alone,labelorelementIdnames the target astapOndoes and pins it withDpadTargetResolver(pinnedFocusOptions). A focused parent row then cannot stand in for an independently actionable child. Combined with other fields, the loop matches it and checks every field. - Select: with
select, afocusedresult also pressesenterand reportsselected: true, and a refused key throws. The tool always reportsselected, which its output schema requires, so a spilled response keeps it inline. The tool records navigation liketapOn(recordsNavigation), so a public select that changes screen becomes a replayable edge. The tool reports the select press as the call’s dispatch (ToolDispatchContext). The navigation graph therefore times a recordedfocusNavigatefrom the key that navigates, not from the first arrow. - Direction: the loop uses
directionwhen given. Otherwise it presses the arrow from the focused element’s bounds centre toward the nearestuntilmatch. With no match on screen, it pressesarrow_rightonce per focused Leanback row header (arow_headerinside thebrowse_headersgrid) to enter its content pane, otherwisearrow_down. A scrollable headers grid can hide the target header below. There the loop scans the headers down first and pressesarrow_rightoncearrow_downis refused at the last header. - Fallback: with a match on screen, the loop never presses a direction twice from the same element in one call. Once the directions toward the target are spent, it tries the others: perpendicular to the dominant axis, then away from the target. Focus can then leave a container that traps it (#17209).
- Stalled direction: three consecutive presses in one direction can move focus without closing distance to the nearest match (a list scrolling under a fixed slot, a slider changing value). That direction then goes after the sideways escapes until focus moves another way or gets closer. Backing away from the target comes after it. Once every escape from an element fails, the loop presses the direction again and stops demoting it for the rest of the call. A list with no side exit therefore still scrolls to the footer.
- Row header: with no match on screen, a Leanback row header first tries
arrow_rightonce to reveal its content pane. If focus does not move, the scan continues down the headers. - Lazy row: when no read has held the target yet, the loop can take a horizontal row of cards as the lazily composed row that holds it (#18027). The card labels must have as many words and differ only in the last (
Trending card 1…5forTrending card 8,src/features/action/FocusRowSearch.ts). The walk plans toward that row, then sweeps right until a press does not move focus, then left, never leaving the row. It sweeps rather than keeping per-element memory, because a scrolling row moves every card’s bounds. If both ends refuse, the stuck message says the target was in no read and names the row and the focused element. A vertical list, a grid or a single matching card has no such row. Otherwise the absent target scans down, and its stuck ormaxStepsmessage also says the target was in no read. - Stops: the loop stops on match,
maxSteps(default 30), or when no untried direction is left on the current element. An explicitdirectionstops after two unchanged presses. When a focused container holds the target, the loop re-reads it after the settle delay up to twice per press. If it persists, the last direction continues withinmaxSteps. Those container reads do not update stuck/stall tracking or borrow a card label for the path. - Unchanged focus: focus counts as unchanged only when the focused element’s identity fields, bounds and its descendant label all repeat. A recycler row can keep fixed bounds while the list scrolls under it.
- In-place label: the exception is a control that changes its own label in place (#17739), such as a slider announcing its value. Without it, such a control would read as fresh focus on every value and run to
maxSteps. The press counts as unchanged, and the loop keys the control without its label for the rest of the call, when all of these hold:- the press changes the focused element’s label but leaves its resource-id, class and bounds unchanged;
- the screen around it stays put: the same nodes at the same bounds, and no label that was already on screen shown somewhere else;
- the screen shows the new value: some node outside focus with a different resource-id shows a new label in place while another keeps its label.
- Range round trip: with no such readout on screen, a press and its opposite can count as an in-place change too (#17209). They must change the label and the control’s
range-info(a slider’s current value) and then bring both back. A label round trip alone does not count, because a one-slot recycler scrolled to another item and back reads the same way (#18255). - Readouts: value readouts beside the control (a
Slider Value: 51%text, a progress bar’s description) show new values in place, so they do not count as the screen moving. A fixed-slot recycler row still reads as moving: its neighbours shift by one slot, share its resource-id when they repage in place, or are absent when only one row is visible. - Tab escape: when such a control has no untried direction left, the loop presses tab once and retries the walk. A
stuckresult after that names the control and the directions it consumed. That label is the first contained text or content-desc, falling back to a resource-id only when none has one. Every card in a row shares a resource-id such as a Leanback card’smain_image. Statuses:focused,max_steps,stuck. - Explore (
src/features/navigation/focusDrivenInput.ts). It resolves an input mode once per call: D-pad when the device’s form factor orro.build.characteristicssaystv, touch otherwise. An unreadable trait falls back to touch.- Taps: in D-pad mode
explorereplaces each tap withfocusNavigate { until, select: true }. Hereuntilis the element’s tap selector aselementIdorlabel, pinned to the elementtapOnwould tap, so a focused row cannot stand in for a chosen child control. Explore skips an element whose selector needs an occurrenceindex, sinceuntilcannot tell duplicates apart. It records that call, sonavigateToreplays the edge as the same D-pad walk. - Scrollable containers: explore does not swipe or select a newly found scrollable container, since moving focus is what scrolls it. It advances the container instead (
src/features/action/FocusListAdvance.ts) and does not record the advance. Discovery picks the list, not what holds focus, so when focus is elsewhere the advance first steers focus toward the container. - Advance: it then presses down a list whose visible rows are stacked, or right along a rail whose rows sit side by side. It judges the layout from the row-level nodes only, not the labels inside them, and uses the container’s long axis without two rows. It presses until a named row that was not on the first read appears inside the container. The list counts as exhausted when focus does not move for two presses, leaves the list after entering it, or 12 presses pass along it. Steering in has its own 12-press bound. Rows already seen never count, so a wrapping list ends on the bound.
- Revealed rail cards: explore records the walk to a card that an advance revealed in a horizontal rail with the rail’s
direction: "right". On replay the rail is back at its first cards, and the default absent-target scan within the rail presses down. The modulesrc/features/navigation/RevealedListRows.tskeeps each advanced list’s revealed row identities for the exploration. A card counts as revealed when its own identity or any one of its names was among the advance’s new rows. Explore labels an unlabelled card from its child, while the advance reports the two separately. - Rail direction scope: explore adds the direction only while focus is in that rail on the card’s row at or before it, so the live walk also reaches it. A control below the cards keeps the default walk. A row revealed in a vertical list also keeps the default walk, whose downward scan already scrolls the list.
- Recorded edges: a recorded
focusNavigatethat targets a scrollable container still replays. Validate mode skips a recorded edge it cannot act on this way (aswipeOn, or an element with no focus target) rather than retrying it. Like a tap, the walk flushes pending post-action captures first. A successful select waits a bounded settle (1 s) while its record is live, so the navigation it causes is attributed to it. - Validate: validate mode replays a recorded
focusNavigateedge as a focus walk on any device, touch included. It uses the recordeduntil, walk options andselect, and a call that navigated on focus alone presses no enter. It finds the on-screen element the way the replay will. A lonelabelorelementIdgoes through the same resolver the walk pins it with. A resolved static child maps to the smallest candidate containing it, as focus on that owner counts. Any other target goes throughfocusNavigate’s matcher: everyuntilfield on one element, exact labels first. A match only on a static descendant in the hierarchy maps to the candidate containing it. When the target is a label inside a clickable row, matching falls back to the label fields alone. - Cancel: the abort signal reaches each key press, so a cancelled run sends no further keys. It also ends the waits between them: the input-mode probe, each walk’s or advance’s per-press settle, and the select settle. A cancel therefore waits at most for the key press or hierarchy read in flight. A recorded
tapOnedge replays astapOn, which takes the D-pad path itself on a device without a touchscreen.
- Taps: in D-pad mode
focusedElement follows Leanback’s focus ring (focused: true). The swipeOn tool works on the android-tv image, which reports a touchscreen though getevent -pl lists no touch input device (only gpio-keys).
A device counts as touchless when pm has-feature android.hardware.touchscreen is false. It also counts as touchless when that feature is true but android.software.leanback or android.hardware.type.television is true, since TV emulator images declare the touchscreen anyway. An unreadable TV-feature probe keeps touch, and the host does not cache it. For a missing feature, pm has-feature prints false and exits 1, so the probe reads that rejected output as the answer. The host caches the probe answer per device incarnation for five minutes and drops it when the serial’s device is replaced or killed. Another AVD booted on the same serial therefore gets a fresh probe. A failed probe keeps the touch path. The leanback rule holds on both emulator images; real touchless hardware remains unverified.
On a touchless device, tapOn with a text or elementId selector and a plain tap runs focusNavigate to the match and presses enter (src/features/action/DpadTapOn.ts). It returns inputMethod: "dpad" and the focus walk. It skips the enter press when the caller cancelled the request during navigation. On each focus read, src/features/action/DpadTargetResolver.ts resolves the target with the touch path’s own ElementSelector and options. Placeholder (hint-text) fallback, exact-before-contains, ranking, actionable-ancestor promotion and synthetic view-ids therefore pick the same element for D-pad and touch. Focus then steers to that element’s bounds. A resolved target that is itself clickable or focusable must hold focus: a focused parent row does not count for an independently actionable child inside it.
Only when a read carries no hierarchy does FocusNavigate match itself. It matches text against text or content-desc after the resolver’s normalization, exact matches first, and pins the first-ranked match (smallest area, then hierarchy order). It matches elementId against the native resource-id or synthetic view-id.
On a touchless device, tapOn refuses a request that only a touch tap can serve. Such requests include sibling, container, index, searchUntil, ensureChecked with either value, layer, display, exactText, a non-first selection strategy, a testTag or textAny selector, or another action. The ActionableError names each such part and the plain-selector D-pad form, because an injected touch tap there is a silent no-op that would report success. The probe therefore runs before that check, and a device with a touchscreen still takes the touch path. Semantic-link requests (selector.accessibilityLink, owner-scoped subtext) skip both the probe and the refusal. The accessibility service invokes the span’s click handler, so the host injects no touch. This mirrors tvOS, where tapOn already selects by focus.
focusNavigate accepts a static child label owned by the focused control, but continues navigating when a focused container merely holds a separately actionable target. D-pad focus cannot reach prototype overlay buttons.