Utils.java

Overview

`Utils.java` is a utility class within the [com.tubitv.media.utilities](/projects/288/68383) package, designed to provide a collection of static helper methods commonly used in media-related Android applications. This class centralizes functionality related to:

• Time formatting for media playback progress display

• Conversion between screen pixels (px) and density-independent pixels (dp)

• Managing system UI visibility for immersive fullscreen experiences

• Utility checks, such as string emptiness

• Conversion between SeekBar progress and media playback time in milliseconds

These utilities simplify common tasks and ensure consistent behavior across the app's media playback and UI components.

Class: Utils

Description

A final utility class containing only static methods and fields. It is not intended to be instantiated.

Fields

Methods

1. public static String getProgressTime(long timeMs, boolean remaining)

Formats a time duration in milliseconds into a human-readable string suitable for display in media controls.

• Parameters:

  • timeMs - The time duration in milliseconds. If C.TIME_UNSET (-9223372036854775807L), it is treated as zero.

  • remaining - If true and timeMs is not zero, the formatted time will be prefixed with a minus sign (-), indicating remaining time.

• Returns:

  • A string formatted as either H:MM:SS or MM:SS depending on the duration.

• Usage Example:

  long currentPosition = 125000; // 2 minutes 5 seconds
  String formattedTime = Utils.getProgressTime(currentPosition, false); // "02:05"
  
  long duration = 3605000; // 1 hour 0 minutes 5 seconds
  String remainingTime = Utils.getProgressTime(duration, true); // "-1:00:05"
  

• Implementation details:

  • Rounds milliseconds to the nearest second.

  • Uses Formatter for locale-sensitive formatting.

  • Chooses between H:MM:SS and MM:SS format based on whether hours > 0.

2. public static long progressToMilli(long playerDurationMs, SeekBar seekBar)

Converts the current progress of a `SeekBar` into the corresponding playback time in milliseconds.

• Parameters:

  • playerDurationMs - Total duration of the media in milliseconds.

  • seekBar - The SeekBar UI component controlling playback position.

• Returns:

  • Playback time in milliseconds corresponding to the SeekBar progress.

  • Returns 0 if the duration is unset (C.TIME_UNSET) or invalid.

• Usage Example:

  long duration = 300000; // 5 minutes
  SeekBar seekBar = findViewById(R.id.seekBar);
  long seekTime = Utils.progressToMilli(duration, seekBar);
  

• Implementation details:

  • Protects against invalid duration by treating durations less than 1 as unset.

  • Uses integer arithmetic to map progress proportionally.

3. public static void hideSystemUI(@NonNull final Activity activity, final boolean immediate)

Hides the system bars (navigation and status bars) for an immersive fullscreen experience.

• Parameters:

  • activity - The current Activity whose UI should be modified.

  • immediate - If true, hides the system UI immediately; otherwise, it may be delayed.

• Usage Example:

  Utils.hideSystemUI(myActivity, true);
  

• Implementation details:

  • Calls the overloaded method with a default delay of 5000 milliseconds.

4. public static void hideSystemUI(@NonNull final Activity activity, final boolean immediate, final int delayMs)

Overloaded method providing control over the delay before hiding system UI.

• Parameters:

  • activity - The current Activity.

  • immediate - Whether to hide UI immediately or after delay.

  • delayMs - Delay in milliseconds before hiding UI (ignored if immediate is true).

• Usage Example:

  Utils.hideSystemUI(myActivity, false, 3000); // hides after 3 seconds unless system UI becomes visible again
  

• Implementation details:

  • Uses View.SYSTEM_UI_FLAG_* flags to configure immersive fullscreen mode.

  • For SDK versions above 18, applies IMMERSIVE and IMMERSIVE_STICKY flags.

  • For older versions, sets a listener on system UI visibility changes to re-hide UI when needed.

  • Uses a Handler to post delayed or immediate runnables for hiding UI.

5. public static boolean isEmpty(@Nullable String text)

Checks if a given string is null or empty (ignoring case).

• Parameters:

  • text - The string to check.

• Returns:

  • true if text is null or equal to an empty string "" (case-insensitive).

  • false otherwise.

• Usage Example:

  boolean emptyCheck = Utils.isEmpty(null); // true
  boolean emptyCheck2 = Utils.isEmpty("");  // true
  boolean emptyCheck3 = Utils.isEmpty("Hello"); // false
  

6. public static float dpFromPx(final Context context, final float px)

Converts pixel units (`px`) to density-independent pixels (`dp`), useful for consistent UI sizing across devices.

• Parameters:

  • context - Android context to access resources.

  • px - Pixel value to convert.

• Returns:

  • Equivalent size in dp units as a float.

• Usage Example:

  float dpValue = Utils.dpFromPx(context, 48f); // converts 48px to dp units
  

7. public static float pxFromDp(final Context context, final float dp)

Converts density-independent pixels (`dp`) to pixel units (`px`).

• Parameters:

  • context - Android context to access resources.

  • dp - DP value to convert.

• Returns:

  • Equivalent size in pixels as a float.

• Usage Example:

  float pxValue = Utils.pxFromDp(context, 24f); // converts 24dp to px units
  

Important Implementation Details

• The class uses static StringBuilder and Formatter instances to avoid repeated memory allocations and improve performance when formatting time strings.

• The time formatting method properly handles the special C.TIME_UNSET constant from ExoPlayer, treating it as zero.

• The system UI hiding methods support backward compatibility by providing alternative behavior for SDK versions below 19.

• Conversion methods for dp/px rely on the device's display metrics density to ensure UI layouts are consistent across screens with different densities.

Interaction with Other Parts of the System

• The class depends on Android framework classes such as Activity, Context, SeekBar, and View.

• It uses constants from the ExoPlayer library (com.google.android.exoplayer2.C) for time unset values.

• The hideSystemUI methods are intended to be used by UI components or activities that require fullscreen immersive experience, such as video players.

• The time formatting and progress conversion methods integrate tightly with media player UI components to display playback progress and allow user interaction.

Visual Diagram

flowchart TD
    A[getProgressTime(timeMs, remaining)] -->|formats| B[Formatted time string]
    C[progressToMilli(playerDurationMs, seekBar)] -->|calculates| D[Playback time in ms]
    E[hideSystemUI(activity, immediate, delayMs)] -->|modifies| F[System UI visibility flags]
    G[isEmpty(text)] -->|checks| H[Boolean result]
    I[dpFromPx(context, px)] -->|converts| J[dp value]
    K[pxFromDp(context, dp)] -->|converts| L[px value]

Summary

`Utils.java` is a foundational utility class that provides essential helper methods for media playback UI, time formatting, UI scaling, and immersive mode management in an Android media application. Its static methods promote code reuse and consistency, simplifying the implementation of common tasks related to media controls and user interface behavior.