Improved TV Back Button UX (extension content -> extension selection Bttn -> home nav Bttn -> exit dialog)

[okibcn]

Pull Request: Improved TV Back Button Navigation

Summary

This PR implements a custom back button navigation flow for Android TV interface in HomeFragment, improving the user experience by providing logical focus transitions instead of immediately showing the exit dialog. The Back button transitions focus from and to the following items:

extension content -> extension selection Button -> home button -> exit dialog

the Phone interface remains unaffected by this change.

Problem

Previously, when navigating plugin content on Android TV, pressing the back button would immediately show the "exit app" dialog regardless of the current focus position. This created a poor user experience as users couldn't easily navigate back to the plugin selector or home navigation without dismissing the dialog.

Solution

Implemented a three-step back button navigation sequence specifically for TV interface:

1. First Back Press (when focus is on plugin content): Focuses the plugin selector button and Scrolls to top. In that order to avoid race conditions.
2. Second Back Press (when focus is on plugin selector): Moves focus to the Home icon in the navigation bar
3. Third Back Press (when focus is on navigation bar): Shows the standard exit app dialog (default behavior)

Changes Made

Modified Files

• app/src/main/java/com/lagradost/cloudstream3/ui/home/HomeFragment.kt

Implementation Details

1. Added Back Press Callback Registration

In onBindingCreated():

(activity as? ComponentActivity)?.attachBackPressedCallback("HomeFragment_BackPress") {
    handleTvBackPress(this)
}

2. Created Custom Back Press Handler

New method handleTvBackPress() that:

• Only activates on TV layout (isLayout(TV))
• Detects current focus position by traversing view hierarchy
• Implements the three-step navigation logic
• Falls back to default behavior for mobile devices and edge cases

3. Added Callback Cleanup

In onDestroyView():

(activity as? ComponentActivity)?.detachBackPressedCallback("HomeFragment_BackPress")

Key Features

• ✅ TV-only: Uses isLayout(TV) check to ensure mobile interface is unaffected
• ✅ Safe: Falls back to default behavior when conditions aren't met
• ✅ Memory-safe: Properly detaches callback on view destruction
• ✅ Focus-aware: Traverses view hierarchy to detect if focus is within content RecyclerView

Testing

• ✅ Compiles successfully
• ✅ Tested on Android TV - navigation works as expected
• ✅ Mobile interface confirmed unaffected (uses default back button behavior)

Technical Notes

Uses Cloudstream's existing BackPressedCallbackHelper system to hook into the back press dispatcher, ensuring compatibility with the app's architecture.

Related Issues

Resolves user-reported navigation issues on TV interface where back button behavior was unintuitive for plugin content browsing.

[fire-light42]

Everything looks good, will merge after testing.

[okibcn]

Everything looks good, will merge after testing.

@fire-light42 Any update?

[fire-light42]

When testing I found that the back button does not always scroll to the top and focus the plugin selection button. Sometimes it only scrolls to one of the top two rows. I suspect this is a race condition in the smooth scrolling and focus request.

[okibcn]

When testing I found that the back button does not always scroll to the top and focus the plugin selection button. Sometimes it only scrolls to one of the top two rows. I suspect this is a race condition in the smooth scrolling and focus request.

@fire-light42 Great catch on that race condition. You were absolutely right to flag it. What was happening is that smoothScrollToPosition(0) kicks off a scroll animation that takes a bit of time to finish. But I was immediately requesting focus on the button right after that. So the moment the focus changed mid‑scroll it ended up interrupting the scroll animation. That’s why it sometimes stopped at row 1 or 2 instead of going all the way to the top.

The fix ended up being surprisingly simple: swap the two calls. By moving the focus request first, we avoid any scroll interruption. With no focused child to protect, the scroll can complete cleanly every time.

Now it always works as intended.

[okibcn]

@fire-light42 Any update?

[fire-light42]

I both tested, and looked over your code again.

This did not fix the race condition, as it still takes several clicks to scroll up. Swapping the order did not solve it as requestFocus should only be done after the full animation, not before nor imminently after.

[okibcn]

I both tested, and looked over your code again.

This did not fix the race condition, as it still takes several clicks to scroll up. Swapping the order did not solve it as requestFocus should only be done after the full animation, not before nor imminently after.

I couldn't replicate the issue when focusing first and then scrolling. Nonetheless with the last revision it should follow your preference of scroll first then request focus. To avoid race condition I have deferred focus request until after scroll ends:

    // Case 1: Focus is within plugin content -> Move to plugin selector
    isInsideRecycler -> {
        binding?.homeMasterRecycler?.scrollToPosition(0)
        // Defer focus request until after scroll animation is complete
        binding?.homeChangeApi?.post {
            binding?.homeChangeApi?.requestFocus()
        }
    }

I hope this works for you too. I am testing in both the Google TV 4K dongle and Homatics Box R Plus without issues.

In other words, it is ready for your review.