Skip to content

Android form factors: common behaviour

Part of Android form factors.

  • Matching. The vocabulary is phone | tablet | foldable | tv | watch | automotive | xr-headset | xr-glasses | unknown (src/models/DeviceMatchCriteria.ts). Binding family takes the same values except unknown (BINDING_DEVICE_FAMILIES, src/utils/provisionDeviceSpecSchemas.ts). formFactorFrom (src/models/formFactor.ts) classifies tv, watch and automotive from the system-image tag first (android-tv, android-wear, android-automotive), then the avdmanager profile id, then geometry. Geometry detects fold/flip by profile name and treats a diagonal >= 7in as a tablet, else a phone, so a TV never matches as a tablet. iOS accepts only phone and tablet. The startDevice formFactor, the broker binding deviceFamily and the device description accept these values; getAndroid has no formFactor input. A startDevice call with createIfMissing creates tv, watch and automotive AVDs.
  • Watch. A watch request picks only installed android-wear-signed, android-wear and android-wear-cn images, in that order, behind API level and host ABI. It creates the AVD with wearos_small_round, or wearos_square when requires.screenRound is false. With no Wear image installed it fails naming the sdkmanager command. The requires.screenRound field also restricts matching, stopped or booted, to a Wear profile whose id names that shape (wearProfileScreenRound), so a square request never reuses a round watch. Creation refuses it outside an Android watch request. A physical watch has no profile id, so it never satisfies requires.screenRound; physical watches stay out of scope.
  • Automotive. An automotive request picks only installed android-automotive-playstore / android-automotive images (Play first, behind API level and host ABI, with the CtrlProxy minSdk floor). It creates the AVD with automotive_1024p_landscape, and with no car image installed it fails with the exact sdkmanager command. A repeated request reuses the AVD because those tags classify it as automotive. requires.vehicle.motion: "supported" restricts matching and creation to non-Play android-automotive images (isMotionCapableAutomotiveTag). Play car images are user builds whose car service refuses driving-state injection. A booted automotive device’s traits carry vehicle, derived from ro.build.type (then ro.debuggable). Both are unsupported unless ro.kernel.qemu marks an emulator. AutoMobile reads them only when ro.build.characteristics announces automotive, with no probe that changes car state. The tag and profile names are still unconfirmed on real images.
  • Android XR. xr-headset classifies the google-xr, android-xr-v3-playstore and android-xr-preview-playstore tags and xr_headset* profiles. xr-glasses classifies the ai-glasses tag and xr_glasses_* / ai_glasses_* profiles. A request for either picks only its own images in that order (behind API level and host ABI). It creates the AVD with xr_headset_device or ai_glasses_device (the profile avdmanager list device tags ai-glasses). With none installed it fails naming the sdkmanager package and --channel=3. requires.playStore on a headset picks only the Play variants; glasses have no known Play image.
  • XR glasses input. Booted-device traits read xr (headset) or glasses in ro.build.characteristics. The 450×450 ai-glasses emulator reports nosdcard,watch, so glassesInput also uses profile/runtime form-factor identity. It injects DPAD_CENTER for tap, DOWN/UP for vertical forward/back and RIGHT/LEFT for horizontal forward/back without read-back. Long press and two-finger gestures stay unsupported. touchnavigation swipes can emit only motion after idle, touchpad motion does not move focus, and key holds produce no long click. Raw touchpad injection requires adb root, and unpaired glasses system UI swallows it.
  • XR headset taps. Runtime XR behaviour (tapOn and tapAny node clicks, no ghost-tap retry) does not use that form factor: it asks the shared predicate described below. Headset home-space input uses screenshot pixels for tapAt, including normalized, percent and image inputs. Android input and task bounds use display pixels. The API 34 google-xr headset’s 2560×2558 display produces a 2558×2558 composed-eye screenshot. At the default pose the panel projection is shot = (shotWidth/2, 0.552*shotHeight) + (61/64)*(display - taskCentre), with task centre derived from its bounds. The tapAt tool inverts this projection for task-aligned app panels before dispatch and reports the selected task and display point in xrPanel.
  • XR headset swipes. When the foreground app has an application window extending outside its task bounds, with or without a task-aligned host window, its embedded SpatialPanel cannot receive display touches: tapAt refuses display input. The swipeOn tool (including explicit-display and scroll-search routes) uses accessibility scroll-forward/backward on the supplied scrollable container. Without one, it uses the largest visible scroll-action node in a foreground application window. Unique captured exact bounds plus the requested action verify a target without a native selector. CtrlProxy rechecks uniqueness, bounds, visibility and action availability. Refusal or an unacknowledged dispatch never falls back to a display gesture.
  • XR bounds capabilities. Bounds-only scrolls and checkable click hints require node_selector_bounds_v2; plain bounds clicks retain the v1 capability requirement. A checkable hint verifies isCheckable, independently of the changing toggle state. Without a scrollable node, swipes refuse with guidance to use tapOn/tapAny or keyboard focus keys. XR automatic scroll targeting excludes scrollables explicitly marked visible-to-user: false, including hidden system UI lists, even for ordinary task-aligned panels. It refuses points outside the projected panel, including XR system UI. The tool-by-tool result on the headset emulator is in Android XR headset: tool baseline.
  • XR detection. XR detection is one shared predicate (isAndroidXr, src/utils/android-cmdline-tools/androidXrDevice.ts) for tapOn, tapAny, tapAt, swipeOn (screen swipes, the scroll-search screen fallback and the default-pose check) and sendKeys routing. It reads the android.software.xr.api.spatial system feature (the signal CtrlProxy uses) once per device and caches it for five minutes. Only without a device handle, or when the probe fails, does it fall back, uncached, to the xr-* form factor or XR System UI task/activity names in the observation back stack. That back-stack check is private to the predicate; panel geometry only receives the predicate’s answer.
  • XR hidden System UI taps. On XR, tapAny excludes System UI nodes whose extractor visible-to-user flag is false. tapOn permits such a node only for a tap, and only when the node itself advertises click. Its stable selector (resource ID, test tag or unique ID) must also identify one captured source at the selected bounds in a complete hierarchy. Activation uses the XR accessibility node-click path with request_action.allowInvisible: true only for the hidden target itself, never an ancestor. Hidden nodes never use the bounds-only fallback. This additive flag defaults to false and has no effect on non-click actions. Selector clicks still require one match at the exact expected bounds with positive width and height.
  • XR hidden click confirmation. CtrlProxy accepting ACTION_CLICK on such a hidden node does not prove the drawn control activated. Some hidden nodes, such as the recents-strip launcher_button, accept the click with no effect. So when the post-tap observation shows the screen unchanged, tapOn fails instead of succeeding. The failure names any approved hidden System UI control whose label shares a word with the target’s resource ID as the text selector to use. Other hidden System UI matches still refuse with guidance to observe the visible control or use screenshot coordinates with tapAt. Ownership comes from the node resource ID or its window package name.
  • XR tapAny windows. Unconstrained tapAny starts in the captured foreground app window when available. Every Android tapAny selection asks that predicate, whether or not the capture has hidden System UI. Unconstrained XR tapAny keeps the capture package’s windows plus other packages’ application windows that overlap one of them (a permission dialog). A separate panel beside the app therefore cannot win. A window with no package name counts as another package, so tapAny drops a package-less IME window. XR candidates prefer the topmost window, then complete sibling rows and top/left/capture order.
  • XR tap owners. A leaf container with no clickable descendant uses its nearest clickable owner within three ancestors. The search stops at a nested selector’s outer container, which may itself be the owner. It also stops before window roots, full-window ancestors, and ancestors containing other tap-actionable descendants outside the leaf-to-owner chain. It stops too before ancestors exceeding 25% of the area of the leaf’s owning window root (or viewport area when that root has no bounds). Hidden nodes do not count as covering application windows for taps or observation occlusion. Window covers exclude XR SystemUI home and caption windows; same-app and other-app dialogs still cover rows.
  • XR observe. When the active-window app (or current back-stack task if absent) has any application window in the capture, observe excludes SystemUI nodes explicitly marked visible-to-user: false from elements, visible texts and the skeleton. It preserves visible captions and the raw action hierarchy; home-space output is unchanged. On the default XR display, observe reconciles hierarchy dimensions with wm size (override size first), rotated to match the capture. It does this because IME process bounds can shrink the reported hierarchy size. Each observe re-reads wm size, so an override set mid-instance (displayConfig or raw adb) reaches the next observe. Recaptures and tap refreshes within it reuse that read, keyed by device and rotation parity, and a fresh read drops the other parity’s entry.
  • XR node clicks. tapOn and tapAny click the accessibility node (or refuse) instead of sending panel-space coordinates. Compose owners without native selectors use unique captured bounds plus identity hints from their own fields or a hoisted descendant label. The match links merged and window roots before checking uniqueness. They skip the ghost-tap retry, because an unchanged hierarchy does not prove a node click missed and a second click would toggle a switch back.
  • XR unanswered clicks. A node click that CtrlProxy received but never answered is not a refusal. This happens when its reply outlives the client request timeout, because CtrlProxy replies only after the post-click settle and extraction. tapOn decides such a click from the post-tap observation. It succeeds with a warning when the screen changed, and otherwise fails as unconfirmed with guidance to observe before retrying. tapAny fails it as unconfirmed. Only an explicit CtrlProxy refusal, or a click that was never sent, returns the panel-coordinate error.
  • XR panel bounds. The first freeform app task in top-first order supplies the panel bounds, skipping System UI and the environment task. Screen swipes (including the scroll-search screen fallback) use these display bounds, already below the status bar. A full-display swipe can start below the panel, focus the System UI visibility barrier and dismiss the panel. AutoMobile therefore refuses missing-panel and edge gestures. This measured projection supports home space at the default headset pose only; it does not infer moved-panel poses or immersive layouts. This mapping does not convert observe node bounds.
  • XR bounds spaces. For an embedded SpatialPanel, xrPanelSpace identifies the application window and its bounds. Elements and skeleton/context rows declare boundsSpace: "panel" for that panel window or boundsSpace: "window" for other owning windows. These spaces are not comparable across windows or usable as screenshot coordinates. Observe omits both fields without an identified embedded SpatialPanel or on non-XR observations. Internal callers that tap a hierarchy element centre (exploration, setUIState’s bounds-centre fallback) pass the internal pointSpace: "native" option, which skips the panel mapping. The public tapAt tool always uses screenshot space. XR glasses are outside this coordinate model.
  • XR text input. On the headset emulator the default keyboard (Gboard) stays the active editor connection, and the observed hierarchy has no readable focused field. So on an XR device (the shared predicate above), an Auto sendKeys type routes to a11y when a keyboard other than the AutoMobile IME is shown with no readable focused editable field. The command’s warning says so. Phones always keep the AutoMobile IME as the Auto default, even with Gboard shown and no readable focus (a WebView or Compose field).
  • Provisioning. provisionDevice takes runtime as a system-image package id. parseAndroidSystemImageRuntime accepts any tag between API level and ABI (only google_apis_playstore is special-cased). Default creation (pickAndroidSystemImage, src/devices/deviceProvisioning.ts) picks an image family from the requested form factor (androidImageFamilyFor). It picks handheld tags for phone, tablet, foldable or none (#14900). For tv it picks only the TV tags, ranked android-tv, google-tv, google-tv-ps16k behind API level and host ABI. The android-tv tag leads because Play Store builds usually refuse adb root; this ordering rationale concerns Play Store images only and does not guarantee root on android-tv. The verified android-tv user build also refuses adb root. A TV AVD gets the tv_1080p profile. The tag lists and default profiles live once in src/models/formFactor.ts and the broker’s family defaults read them. With no TV image in range the error names the sdkmanager command; nothing is downloaded.
  • CtrlProxy. minSdk 24 (android/gradle/libs.versions.toml) is not a blocker. The manifest declares no <uses-feature> and only a LAUNCHER category (no LEANBACK_LAUNCHER). The accessibility config requests window content, interactive windows and gesture dispatch.
  • Input. sendKeys supports arrows (KEYCODE_DPAD_*), enter, tab, escape, backspace, delete (INPUT_KEY_CODE_MAP, src/features/action/InputKey.ts). There is no D-pad centre, menu or media key. pressButton sends back/home/recent as global actions with ADB fallback, plus volume/power via ADB.
  • Focus. observe returns focusedElement (ActiveWindowAttribution.ts, HierarchyFocus.ts) from the focused property; TalkBack focus is separate (accessibility-focused).
  • observe reports isScreenRound and, when identifiable, surface only for watch devices. surface requires an active window and hierarchy. Non-Wear-SystemUI apps are app, and Wear SystemUI’s experiences.globallauncher.* activities are launcher. Its mainui.activity.SysUiActivity is tile when the hierarchy contains com.google.android.clockwork.sysui:id/carousel_tile_container. Otherwise it is watchface when the hierarchy contains watch_face_fallthrough or com.google.android.clockwork.sysui:id/watchface_overlay. Other captures omit surface: SystemUI hosts the watch face, tile and notification tray, so its package and activity alone cannot distinguish them. ambient changes power state and reads the watch face’s inAmbient back from dumpsys wear_service.