UIControllerView.java

Overview

`UIControllerView` is a custom Android UI component extending `FrameLayout` that provides an interactive playback control panel for media content. It serves as the visual container for user controls such as play/pause buttons, seek bars, and other playback-related UI elements, which are data-bound to a `UserController` instance representing the current playback state and user interaction logic.

The primary responsibilities of `UIControllerView` include:

• Binding the playback control UI layout (ui_controller_view.xml) to a UserController instance via Android Data Binding.

• Managing the visibility of the control panel, showing it on user interaction and auto-hiding it after a timeout.

• Handling touch events to toggle the visibility of playback controls, enhancing user experience by minimizing UI clutter when not in use.

• Providing a fluent API to set the associated UserController, enabling dynamic control over playback through the UI.

This class encapsulates UI visibility logic and binds the playback state model to the control panel, making it an essential component for user interaction within the media playback interface.

Class: UIControllerView

Package

`com.tubitv.media.views`

Inheritance

• Extends: android.widget.FrameLayout

Properties

Constructors

1. UIControllerView(Context context)

   • Calls the two-parameter constructor with null attributes.

   • Initializes the view.

2. UIControllerView(Context context, @Nullable AttributeSet attrs)

   • Calls the three-parameter constructor with a default style attribute of 0.

   • Initializes the view.

3. UIControllerView(Context context, @Nullable AttributeSet attrs, int defStyleAttr)

   • Main constructor.

   • Calls initLayout(context) to inflate and bind the layout, initialize handler.

Methods

setUserController(UserController userController) : UIControllerView

• Description:
  Associates a UserController instance with this view for data binding.
  Updates UI bindings if the layout is already inflated.

• Parameters:
  userController — A non-null instance of UserController that manages playback state and user interaction logic.

• Returns:
  this for method chaining, or null if the passed parameter is null.

• Usage Example:

UIControllerView controllerView = new UIControllerView(context);
controllerView.setUserController(myUserController);

• Notes:
  Logs a warning if a null UserController is passed and does not set it.

onDetachedFromWindow() : void

• Description:
  Lifecycle callback invoked when the view is detached from the window.
  Cleans up by removing any pending hide UI callbacks to prevent memory leaks or unexpected behavior.

• Overrides:
  FrameLayout.onDetachedFromWindow()

• Implementation Details:
  Calls countdownHandler.removeCallbacks(hideUIAction) to cancel any pending auto-hide runnable.

onTouchEvent(MotionEvent event) : boolean

• Description:
  Handles touch events on the control panel's area.
  Toggles the visibility of the control panel on user touch and resets the auto-hide timer.

• Parameters:
  event — The MotionEvent triggered by user interaction.

• Returns:
  The result of the superclass's onTouchEvent method.

• Behavior:

  • Cancels any pending hide UI actions immediately upon touch.

  • If the control panel is visible, hides it.

  • If hidden, shows the control panel only if the player is not idle, and restarts the auto-hide timer.

• Usage Example:

@Override
public boolean onTouchEvent(MotionEvent event) {
    countdownHandler.removeCallbacks(hideUIAction);

    if (binding.controllerPanel.getVisibility() == VISIBLE) {
        binding.controllerPanel.setVisibility(GONE);
    } else {
        if (userController.playerPlaybackState.get() != Player.STATE_IDLE) {
            binding.controllerPanel.setVisibility(VISIBLE);
            hideUiTimeout();
        }
    }

    return super.onTouchEvent(event);
}

initLayout(Context context) : void

• Description:
  Internal helper method to inflate the layout XML (R.layout.ui_controller_view) and initialize data binding and handler.

• Parameters:
  context — The Android context used to inflate the layout.

• Implementation Details:

  • Uses DataBindingUtil.inflate to bind the layout to this FrameLayout.

  • Initializes countdownHandler for UI hide scheduling.

hideUiTimeout() : void

• Description:
  Schedules the hideUIAction runnable to execute after TIME_TO_HIDE_CONTROL milliseconds, which hides the control panel.

• Usage:
  Called to initiate the automatic hiding of the playback controls after a period of inactivity.

Important Implementation Details

• Auto-hide Mechanism:
  The class employs a Handler and Runnable to automatically hide the playback controls 3 seconds after the last user interaction, improving the viewing experience by reducing visual distractions.

• Data Binding Integration:
  Uses Android Data Binding (UiControllerViewBinding) to link UI elements directly to the UserController observable properties, enabling automatic UI updates based on playback state changes.

• Touch Event Handling:
  Overrides onTouchEvent to toggle the control panel's visibility on user gestures, ensuring intuitive user control over playback UI visibility.

• Safety on Detachment:
  Removes callbacks on onDetachedFromWindow to avoid leaks or crashes due to handler messages after the view lifecycle ends.

Interaction With Other Components

• UserController:
  UIControllerView depends on an instance of UserController for playback state data and control logic. The UserController provides observable fields for playback state, metadata, and user actions that the UI binds to.

• Layout Resource (ui_controller_view.xml):
  The UI layout inflated and bound to this view defines the actual visual components (buttons, sliders, panels) for playback control.

• ExoPlayer Playback State:
  Uses the playerPlaybackState observable in UserController to decide when to show/hide the control panel.

• Hosting Activity/View:
  Typically embedded inside a larger player view hierarchy (e.g., TubiExoPlayerView or a playback activity layout) to provide on-screen playback controls.

Usage Example

// In Activity or custom Player View initialization:

UIControllerView controlView = new UIControllerView(context);

// Assuming userController is already instantiated and configured
controlView.setUserController(userController);

// Add to your player layout hierarchy
playerContainer.addView(controlView);

// The controls will auto-hide after 3 seconds of inactivity
// and toggle visibility upon user touch.

Mermaid Class Diagram

classDiagram
    class UIControllerView {
        - static final String TAG
        - static final int TIME_TO_HIDE_CONTROL = 3000
        - UserController userController
        - UiControllerViewBinding binding
        - Handler countdownHandler
        - Runnable hideUIAction
        + UIControllerView(Context)
        + UIControllerView(Context, AttributeSet)
        + UIControllerView(Context, AttributeSet, int)
        + UIControllerView setUserController(UserController)
        + void onDetachedFromWindow()
        + boolean onTouchEvent(MotionEvent)
        - void initLayout(Context)
        - void hideUiTimeout()
    }

Summary

`UIControllerView` acts as the user-facing playback control interface within the media player UI. By seamlessly integrating Android Data Binding with `UserController`, it allows the UI to reflect playback state changes in real-time. Its touch handling and auto-hide logic ensure an unobtrusive and user-friendly control experience. This component is typically embedded into the playback view hierarchy and interacts closely with playback state models and UI layouts to provide a responsive media control panel.

Appendix: Layout Binding Assumption

The `UiControllerViewBinding` class is generated from a layout XML named `ui_controller_view.xml` which contains a root view with an ID `controllerPanel`. This panel is the container whose visibility is toggled to show or hide the controls.

End of Documentation for UIControllerView.java