Skip to content

feat: Add Android TV D-pad navigation support with tvOptions#2173

Open
TheNoumanDev wants to merge 61 commits into
mainfrom
android_TV_implementation
Open

feat: Add Android TV D-pad navigation support with tvOptions#2173
TheNoumanDev wants to merge 61 commits into
mainfrom
android_TV_implementation

Conversation

@TheNoumanDev

@TheNoumanDev TheNoumanDev commented Mar 6, 2026

Copy link
Copy Markdown
Member

Summary

Add D-pad focus navigation system for Android TV with coordinate-based tvOptions in YAML. All TV code gated behind Device().isTV check.

Key Changes

Core TV Framework

  • tv_focus_widget.dart - Built-in D-pad navigation with grid-based focus traversal
  • tv_focus_provider.dart - Interface for host app focus integration
  • tv_focus_order.dart - Coordinate system (row, order, isRowEntryPoint)
  • tv_focus_theme.dart - Focus styling resolution (theme > provider > primary color)
  • tv_scrollbar_widget.dart - Focusable scrollbar for ListView on TV

Widget Support

  • box_wrapper.dart - TV focus for BoxController widgets (~30 widgets)
  • form_helper.dart + input_wrapper.dart - TV focus for form widgets (~10 widgets)
  • controllers.dart - TVOptionsComposite with focus styling

Layout Support

  • list_view.dart - Scrollbar with scrollbarOptions.autoFocus
  • carousel.dart - delegateHorizontalNavigation, interceptHorizontalNav
  • tab_bar.dart + base_tab_bar.dart - TV tab navigation with tabWidget support
  • grid_view.dart - TV focus coordinates
  • bracket - TV D-pad navigation for tournaments

Theme Integration

  • theme_loader.dart - Parse Tokens.TV.* for focus styling
  • device.dart - isTV getter for Android TV detection

Focus Styling Properties

row, order, isRowEntryPoint, focusBorderColor, focusBorderWidth, focusBorderRadius, focusBackgroundColor, focusScale, focusOpacity, focusElevation

Example

Button:
  label: Play
  styles:
    tvOptions:
      row: 1
      order: 0
      isRowEntryPoint: true
      focusScale: 1.05

Developer docs

Comprehensive developer guide: modules/ensemble/doc/tv_developer_guide.md

Vide Demo:
Link: https://drive.google.com/file/d/1mZfg8hNFv9m0QkUy0S3P1C4Xkt287tfc/view?usp=sharing

@TheNoumanDev
TheNoumanDev force-pushed the android_TV_implementation branch from 0ec7c68 to 30b28fa Compare April 6, 2026 08:46
@TheNoumanDev
TheNoumanDev force-pushed the android_TV_implementation branch from 9761dfb to 59a05bc Compare April 6, 2026 09:35
@TheNoumanDev
TheNoumanDev force-pushed the android_TV_implementation branch from 93bef64 to 7fd5f77 Compare April 6, 2026 09:43
Muhammad Usman and others added 30 commits July 1, 2026 04:03
When a TabItem has a tabWidget defined, _TVTabButton now renders
it instead of the default icon+label, consistent with the non-TV
TabBar behavior.
…bility

Replace MediaQuery screen size with scrollable viewport bounds when
calculating whether a focused item is above/below the visible area.
This correctly handles scrollables that don't span the full screen.

Also fixes verticalPadding usage: it's now a positioning inset within
the viewport rather than a threshold relative to screen edges,
preventing horizontal navigation jitter.
 - ensemble@1.2.48-beta.1
 - ensemble@1.2.48-beta.2
 - ensemble@1.2.49-beta.1
- Removed an empty line in the camera module's pubspec.yaml.
- Refactored the ensemble changelog by removing outdated beta versions and consolidating entries for clarity.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants