D-pad-only operation (no touchscreen required)¶
Vela works with five keys (up, down, left, right, OK) plus Back, and no touchscreen. That covers keypad phones, Android TV boxes, and any phone with a remote, a game controller or a keyboard attached. Touch behavior is unchanged by any of it.
SPEC 10.3 has the short version of this page.
Rules¶
- Every screen, sheet and dialog opens with something focused. Attach
rememberDpadAutoFocus()to its primary control, orModifier.dpadAutoFocus(requester)when the target may be off screen. Compose's own focus recovery is nondeterministic, and an unfocused screen wastes the first key press. The bare map is the one exception (see Traps). - Every control is focusable and shows a ring. Put
Modifier.dpadHighlight(shape)on everyclickable,toggleableandselectable. Material's own focus tint is too faint to see on the sheets. - Every gesture has a key path. A drag, swipe, pinch or long press needs a focusable control or a key handler that does the same thing, or a keypad user cannot reach it.
- D-pad code calls the touch paths. Key handlers call the lambdas, flags and state the gesture
handlers use (
handleTap,gestureMove,navUserZoom), so a fix to touch applies to keys. - D-pad affordances are gated on
rememberDpadMode()orrememberDpadFirstDevice(), so a touch phone with no key input looks and behaves as before. - Menus and dialogs are
VelaMenuandVelaDialog. A ComposeDropdownMenuorAlertDialogcannot be focused before the first key press. Any other window is a rawDialogthat focuses an explicit.focusable()element.
dpad_test_suite/audit_static.sh checks rules 2, 3 and 6, and CI fails a build that breaks one.
How it is built¶
Detection¶
rememberDpadFirstDevice() (detectDpadFirst) is true only when the device has no touchscreen
(FEATURE_TOUCHSCREEN absent) or a physical, non-virtual InputDevice reports SOURCE_DPAD. On
such a device focus is placed before any input and rings show from the first frame.
rememberDpadMode() is dpadFirst || inputMode == InputMode.Keyboard. On any other device it
turns on at the first key press and off at the next tap.
Some keypad phones report a touchscreen and expose their D-pad only through the framework's
virtual device, so nothing at startup separates them from an ordinary phone. They get rings, the
map target and the key paths on the first key press, but no pre-placed focus and the stock
DropdownMenu: the auto-focus helpers and the VelaMenu chooser act on D-pad-first devices only.
Helpers¶
All in app/src/main/java/app/vela/ui/DpadFocus.kt.
| Helper | Use |
|---|---|
rememberDpadAutoFocus(vararg keys) |
Returns a FocusRequester for a screen's primary control and requests focus when the screen appears. Retries 20 times, 50 ms apart, because a new focus node is often not attached on the first frame. keys request again when the content swaps |
Modifier.dpadAutoFocus(requester) |
Requests every 50 ms for up to 2 s until onFocusEvent confirms focus landed. The no-argument form makes its own requester |
Modifier.dpadHighlight(shape, ringColor) |
A 3 dp orange ring (0xFFFF6D00) while the element or a descendant has focus and input is key-driven. Orange because a teal ring vanished on a switch that is on. ringColor is for a control whose own fill would hide the orange |
Modifier.dpadClickable |
clickable without Material's gray focus fill while input is key-driven. A plain clickable shows the fill and the ring together. Pair it with dpadHighlight |
DpadRingBox(shape) |
Rings a Material button or chip at its visible height. dpadHighlight on the control itself rings its padded 48 dp box |
VelaSwitch |
A Switch whose ring hugs the track |
Modifier.dpadFieldEscape() |
Up and down leave a text field for the control above or below |
Modifier.dpadSwallowHorizontal(), Modifier.dpadContainVertical() |
Consume a left or right press that no child handled, and stop up and down from leaving a scroll container |
Modifier.dpadRowSibling(requesters, index) |
Left and right across a row of siblings by requestFocus |
rememberDpadFocusKeeper(), Modifier.dpadFocusKept, DpadFocusHandoff |
Keep focus on a row whose control replaces itself (Download, then progress, then Delete) |
The map¶
app/src/main/java/app/vela/ui/map/MapDpadController.kt is the key-to-camera seam: panBy,
zoomBy, selectAtCenter and longPressAtCenter. VelaMapView wires its callbacks to the tap
lambda, the long-press path, the gestureMove flag and the navigation zoom override, so a key
pan detaches the follow camera and arms "Search this area" as a finger pan does.
MapScreen puts a 140 dp focusable target at the center of the screen. Focused, it shows a pill
reading "OK: move the map" and the arrows keep moving focus. OK engages it, which draws a
crosshair and a ring at the screen edge:
| Key | While engaged |
|---|---|
| Arrows | Pan by 22% of the view, repeating while held |
| OK | Tap whatever is under the crosshair. In Choose on map, confirm the pick |
| OK held 500 ms | Long press at the crosshair: drop a pin, or set the Choose on map point |
| Plus, minus, zoom keys | Zoom one level |
| Back | Disengage. Focus stays on the target |
The target is mounted only while the map is the primary surface (SearchGates.mapTargetHidden).
It unmounts under search, a place sheet, directions, the step list, the arrival card or an open
results sheet, and stays during a drive and over a minimized results bar. Choose on map keeps it
mounted and, on a D-pad-first device, focuses and engages it at once. ChooseOnMapOverlay draws
the pin and banner there in place of the pill and crosshair.
Settings > Navigation > "Zoom in key" and "Zoom out key" give zoom to two keys of the user's
choice, such as 2 and 5 on a keypad (ui/ZoomKeys.kt). They zoom one level from anywhere on
the map, engaged or not, and rest while a Settings page is open. MainActivity.dispatchKeyEvent
offers a key that types only after nothing else took it, so the same key still types in a text
field, and offers a key that does not type (volume, camera) first. The arrows, OK and Back
cannot be assigned.
A plus and minus pill sits in the bottom-right stack above the parking button, in D-pad mode or
with Settings > Navigation > "Prefer buttons over swipes" on. It shows only on the bare map and
in the area picker (AreaPickOverlay).
Key paths for gestures¶
| Gesture | Key path |
|---|---|
| Sheet drag (place, results, classic directions) | OK on the handle steps or toggles the sheet |
| Maneuver banner swipe | Left and right on the focused banner step through upcoming turns. OK returns to live guidance |
| Drag the navigation bar up for the step list | OK on the handle above the figures. Also a list button when "Prefer buttons over swipes" is on or the device is D-pad-first |
Long press to mute (NavHoldControls) |
The first OK slides the three voice choices out beside the button (on, alerts only, off); Left and Right move across them, OK picks one and focus returns to the button. A second OK on the button pauses |
Tap the speaker button (NavVoiceButton, Pause in the bar) |
OK slides the same three choices out; Left, Right and OK as above |
| Photo viewer swipe | Left and right |
| Long press on a suggestion row | The trailing overflow button opens the same menu |
Drag to reorder stops (StopsEditorSheet) |
Up and down buttons on each row in D-pad mode |
Swipe a list row to delete or edit, drag its handle to reorder (ListsSheet) |
Right from the row reaches its handle and Left returns. On the handle, Up and Down move the list and OK opens the editor, which has Delete. Down from the row goes to the next row |
| Drag a chip's handle to reorder (Settings > Search > Quick search buttons) | Right from the row's switch reaches its handle and Left returns. On the handle, Up and Down move the chip and OK flips the switch. Down from the switch goes to the next row's switch |
| Long press a list row to select several | Hold OK on the row. While selecting, OK on a row toggles it; the trash and the close button sit in the title row |
| Swipe a recent search row to remove it | The trailing overflow button has Remove from history, but a key cannot reach it from the row yet (ROADMAP.md) |
| Street View drag | OK engages look-around: arrows turn the view, plus and minus zoom, OK moves to the nearest link ahead |
Long press on the parking button (ParkingControl) |
OK on the button. With no spot saved and a history to open, it asks: Save parking spot, or Parking history. With a spot saved, the menu has Earlier spots |
Settings¶
Every Settings page, hub and spokes, renders through SettingsScaffold
(ui/settings/SettingsScaffold.kt). Build a new page on it. It does three things:
- Focuses the Back button on open, and requests again every 50 ms while nothing on the page has
focus and no key has been pressed, because focus can be taken away after it first lands. The
hub passes
autoFocusBack = falsewhen returning from a spoke and focuses that spoke's row. - Bridges the top bar and the content. Directional search cannot cross from a
TopAppBarto the column and clears focus, so down from Back and up from the first row go byrequestFocus. The content lambda receives atopRowmodifier. Attach it to the page's first focusable control or the bridges dead-end. - Applies
dpadSwallowHorizontalto the column and the Back button, anddpadContainVerticalto the column.
The rows are in SettingsComponents.kt: SettingsGroup, ToggleRow, SelectableRow,
GroupDivider, PageIntro, Hint, CollapsibleSectionTitle. Each interactive row is one focus
stop. SPEC 10.4 covers the hub, the routes and the search.
Small screens¶
AdaptiveDensity.wrap runs first in both attachBaseContext calls (MainActivity, VelaApp).
On a screen narrower than MIN_WIDTH_DP (360 dp) it lowers the density until the screen reports
360 dp of width, so standard Material layouts fit a 240 px keypad phone. At 360 dp and above it
returns the context untouched.
Traps¶
Detection:
- Do not count the framework's virtual input device or
KeyCharacterMap.deviceHasKey(DPAD_CENTER). Both say D-pad on nearly every phone. Counting the virtual device (KEYBOARD | DPAD) put ordinary phones in keypad mode: a tap no longer opened the search field and the zoom buttons appeared.
Focus:
- Before anything in the window has held focus,
requestFocusdoes nothing, and neithermoveFocusnor a synthetic key event can put focus on the search bar. So after a touch the bare map opens with nothing focused, and the first arrow lands on the search bar, the first focusable. When the last input was a key, which is always so on a keypad phone, Android focuses the search bar itself as the window opens. rememberDpadAutoFocusstops as soon asrequestFocusdoes not throw, which can be before focus lands. For a target below the fold usedpadAutoFocus(requester).- When the focused control leaves composition, Compose clears focus and recovers somewhere
arbitrary, often the top of the screen. Request focus on the replacement (
DpadFocusKeeper). - In a
Column(verticalScroll)a directional move with no target clears focus, and no arrow brings it back.focusGroup()alone does not help. UsedpadSwallowHorizontalanddpadContainVertical, anddpadRowSiblingalong a row:moveFocusclears focus at the ends,requestFocusdoes not. - A clickable row with a focusable
RadioButtonorSwitchinside is two focus stops, and a sideways move into the inner one clears focus. Make the inner control display-only (onClick = null, as inSelectableRow) or make it the only stop (ToggleRow,VelaSwitch). - A text field consumes up and down as cursor moves, so nothing below it is reachable. Add
dpadFieldEscape(). The search bar handles down inline, beside its Back handling. - A focusable that consumes arrows must be a mode entered with OK and left with Back. The first map target panned whenever it held focus, and nothing else on the screen could be reached.
- On a small screen a fixed layout pushes the primary button off the bottom. Welcome scrolls,
and on a D-pad-first device opens scrolled to the bottom so Get started can take focus.
VelaDialog(90% of screen height),VelaMenu(85% as a chooser, 70% as a touch menu) and the classic directions panel's body (58%) cap their height and scroll.
Search bar (SearchBar.kt, MapScreen):
- Focusing the text field opens the search overlay, so walking focus across the bar opened search. In D-pad mode the field is disabled and cannot take focus until armed. OK on the text region arms and focuses it, and losing focus disarms it. A field that was only unfocusable swallowed taps on phones with both a touchscreen and a keypad.
- A focused field counts as armed, however it got its focus. A tap focuses it with no arming, and the first key typed on a physical keyboard turns D-pad mode on: unarmed, the field was disabled under the cursor and everything after the first character was lost.
- The arming
clickableis on the text region. On the whole card it made the bar one focus stop and the Settings gear unreachable. - The overlay is open while
searchExpandedis set or the field has focus (SearchGates). A state derived from focus inside the overlay never cleared, and Back could not close search. - Back on the field is caught in
onPreviewKeyEventon key-down, beforeBasicTextFieldclears focus on it. With the soft keyboard up, the first Back hides the keyboard and the second closes. - The soft keyboard follows the live input mode at arming: hidden after a key press, shown after a tap. Hardware keys type into the focused field, and a shown keyboard swallows Back.
- The text region insets its content 10 dp inside the ring. Without the inset the ring crosses the first typed letter.
Map:
- MapLibre's
MapViewtakes focus and handles the arrow and center keys itself, so no key reaches Compose.VelaMapViewsets it and its descendants non-focusable on every update, because MapLibre turns focus back on when the surface is recreated. - The map target and the zoom buttons must not sit over a panel. As focus stops over the results list they took the down press from the header, and the first result was unreachable.
- Choose on map opens with directions still open underneath, so
mapTargetHiddenstarts withpickOnMap == null. Without it the arrows only reach the cancel button and the pin cannot move.
Menus, dialogs and web pages:
- A
DropdownMenupopup or anAlertDialogopens with window focus and no focused content until the first key event.requestFocuson an item,moveFocusand synthetic key events all fail. Only a rawDialogholding an explicit.focusable()element takes focus on open. - Inside a dialog window
requestFocusdoes not land on a Material button or on the focus node nested in.clickable.VelaDialogbuttons andVelaMenuitems are.focusable()with OK in.onKeyEventand touch inpointerInput. Adding.clickablewould add a second focus stop. The Welcome button is built the same way. - A WebView's own key handling hops between links. The full-screen reviews page maps up and down to page scrolling and requests focus when the page finishes loading.
adb:
adb shell input textandinput keyeventflip the input mode to Keyboard, as a physical keyboard does:rememberDpadModeturns on and the focus rings appear. Typing into a field that already has focus keeps working.
Surfaces¶
"Focused on open" applies on a D-pad-first device.
| Surface | Focused on open | Leave |
|---|---|---|
| Bare map | The search bar when the last input was a key. After a touch, nothing, and the first arrow lands on the search bar | Back disengages an engaged map |
| Search overlay | The armed field. Down reaches the rows | Back |
| Results sheet | The search bar keeps focus. Down reaches the filter chips and rows | Back clears the search |
| Place sheet | The drag handle | Back |
Route chooser (GoogleStyleDirectionsPanel, the default) and the classic panel (DirectionsPanel) |
The Drive tab | Back |
| Choose on map | The map target, engaged | OK confirms, Back cancels |
| Step list | The first step, or the current step during a drive | Back |
Transit route detail (RouteDetailSheet) |
The back arrow | Back |
| Navigation | The map stays primary. The banner, bar handle and buttons are focus stops | Back asks to end the drive |
Driving mode (DrivingChrome) |
As the bare map. The bar's X, the locate and voice buttons and the credit are focus stops | Back, as on the bare map; OK on the X leaves the mode |
Search along the route (NavSearchChips) |
The close button | Back |
| Photo viewer | The viewer | Back |
| Full-screen reviews | The back arrow, then the page once it loads | Back |
| Street View | The panorama | Back disengages, then leaves full screen, then closes |
| Settings hub | The Back button, or the row of the page just left | Back, to the map |
| Settings page | The Back button | Back, to the hub |
| Welcome, then the Google choice page | Get started, then Continue | OK. Back on the choice page returns to Welcome |
| The first run's "What Google is used for" list | The Back button, as on a Settings page | Back, to the choice page |
VelaDialog |
The dismiss button. Arrows reach confirm | Back |
VelaMenu |
The first item | Back |
Layers panel (LayersPanel) |
The first map type tile. Arrows move across the tile rows and down to the switch row, OK picks or toggles and keeps the panel open; OK on the Driving mode row closes it | Back |
Time and date picker (PickerDialog), Your lists (ListsSheet), voice capture (VoiceCaptureDialog) |
Their OK, New list and Done buttons | Back |
List editor (ListEditorDialog) |
The name field. Down reaches the icons, the colors and the buttons | Back |
Place icon (PlaceIconDialog), parking history (ParkingHistorySheet) |
Cancel, and the newest spot | Back |
Known limitations¶
- Photo pinch zoom and map tilt have no key path.
- With key input the soft keyboard stays hidden, so typing needs hardware keys.
- The key scrolling of the full-screen reviews page has not been checked against a loaded page.
Testing¶
The suite is in dpad_test_suite/. Run all three scripts after any change that touches focus.
audit_static.sh needs no device. The other two press keys on a connected device with
adb shell input keyevent and read the focused element from uiautomator dump.
| Script | Checks |
|---|---|
audit_static.sh |
Scans every .kt under :app. Fails on a clickable, toggleable or selectable with no dpadHighlight, a gesture modifier with no key path nearby, a bare DropdownMenu or AlertDialog, and isSystemInDarkTheme(). A gesture whose key path is in another composable passes with a // dpad-ok: <where> comment above it. Lists bare .focusable(), sliders, raw dialogs, unescaped text fields and those comments for a manual look. CI runs it |
run_all.sh |
Runs setup.sh, then the tests in tests/ in order. Arguments select tests by prefix: ./run_all.sh 01 02 |
audit_dynamic.sh |
Tours the bare map, search, Settings, the place sheet, directions and Choose on map. Each must open focused (the bare map unfocused), keep focus through a run of down presses, and close on Back |
The tests assert, in order: the bare map opens with the map target unfocused and the search bar at most one press away (01); Settings opens on Back (02); Welcome opens on Get started and the first onboarding dialog on "Not now" (03); the place sheet opens on its handle and its overflow menu on the first item (04); Choose on map opens engaged (05); the Directions pill and the From row are reachable (06).
- The device must be D-pad-first. On a touch phone run
adb shell settings put global vela_force_dpad 1before launch, and put it back to 0 afterward. - Tests 04 to 06 and most of the dynamic audit need live search results and skip without them.
- Tests 01 and 02 measure positions as a share of the screen and find the Settings button by its description, so they pass on any screen. Tests 04 to 06 and the dynamic audit still count key presses for a small keypad screen. On a tall phone, where the results sheet has more filter chips, they land on the wrong control and fail.
- Test 03 runs
pm clearon the package. On a phone whose data matters, install a side-by-side build and setVELA_PKG=app.vela.dev. setup.shgrants location and adds agpstest provider (VELA_LATandVELA_LNGset the fix). Remove the provider when done.ADB="adb -s <serial>"picks a device.
Fork and merge policy¶
The Settings hub and SettingsScaffold, AdaptiveDensity, the orange ring and Street View by
D-pad were ported from the vela-dpad fork by alltechdev and ars18. Work from the fork lands by
cherry-pick with the author kept, after it is read and tested like any other pull request. To
keep the two trees easy to exchange, D-pad behavior goes in its own files where it can, and an
edit to a shared file is a small insertion with a comment naming docs/dpad.md.