Skip to content

Listview scrollbar with fallback focus support - #2329

Merged
TheNoumanDev merged 4 commits into
android_TV_implementationfrom
focusable-scrollbar
Jul 29, 2026
Merged

Listview scrollbar with fallback focus support#2329
TheNoumanDev merged 4 commits into
android_TV_implementationfrom
focusable-scrollbar

Conversation

@usmanvrtx

Copy link
Copy Markdown
Contributor

Description

This PR enhances the TV scrollbar widget and ListView to handle the case when a ListView has no focusable TV content targets (e.g., only plain text items). In such cases, the scrollbar becomes the primary focus target and handles D-pad navigation directly, including blocking scroll-at-boundary from edge handoff.

Related Issue

N/A

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update
  • Refactoring (no functional changes)

What Has Changed

  • Added TVScrollbarFallbackFocusConfig class to provide focus coordinates when a ListView has no focusable content targets
  • Added fallbackFocus parameter to TVScrollbarWidget to support fallback focus scenarios
  • Added content focus probing logic in ListViewState to detect whether the list content contains any focusable TV targets via TVFocusRegistry and FocusManager
  • Added ignoresTVFocus parameter to BoxWrapper to prevent double-focus wrapping when ListView uses internal scrollbar focus
  • Updated TVTabButton to use TVFocusProviderScope when available for consistent focus offset handling
  • Added _canScrollUp/_canScrollDown guards in TVScrollbarWidget to prevent scroll-at-boundary from being passed through to adjacent focusable elements
  • Added lockHorizontalNavigation support for scrollbar in fallback mode to prevent horizontal focus escape
  • Added comprehensive unit tests in tv_scrollbar_widget_test.dart covering fallback focus, scroll boundaries, and null content scenarios

How to Test

  1. Run the new scrollbar tests: flutter test modules/ensemble/test/widget/tv_scrollbar_widget_test.dart
  2. Verify that a ListView with only non-focusable items (e.g., plain Text widgets) correctly focuses the scrollbar and allows D-pad scrolling
  3. Verify that a ListView with focusable items behaves as before (scrollbar focus via edge handoff)
  4. Verify that scrollbar-at-boundary does not swallow navigation when in fallback mode

Screenshots / Videos

N/A

Checklist

  • I have run flutter analyze and addressed any new warnings
  • I have run flutter test and all tests pass
  • I have tested my changes on the relevant platform(s)
  • I have updated documentation if needed
  • My changes do not introduce new warnings or errors

@usmanvrtx
usmanvrtx force-pushed the focusable-scrollbar branch from 9ae7410 to 8d18209 Compare July 29, 2026 06:49
@usmanvrtx usmanvrtx changed the title fix: enhance TV scrollbar widget with fallback focus support for empty ListViews Listview scrollbar with fallback focus support Jul 29, 2026
@usmanvrtx
usmanvrtx requested a review from TheNoumanDev July 29, 2026 06:50
@usmanvrtx usmanvrtx self-assigned this Jul 29, 2026
@TheNoumanDev
TheNoumanDev merged commit 3c0007d into android_TV_implementation Jul 29, 2026
3 checks passed
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