NotificationCompat.Metric.TimeDifference

public final class NotificationCompat.Metric.TimeDifference extends NotificationCompat.Metric.MetricValue

java.lang.Object
   ↳ androidx.core.app.NotificationCompat.Metric.MetricValue
     ↳ androidx.core.app.NotificationCompat.Metric.TimeDifference

This represents a timer, a stopwatch, or a countdown to an event.

When representing a running timer (or stopwatch, etc), this value specifies a reference instant for when that timer will hit zero (or the stopwatch was at zero, respectively), called the "zero time". In this case the time displayed is defined as the difference between the "zero time" and the current time, meaning it will show a live-updated timer.

The zero time can be specified as an Instant (in which case it corresponds to a "real-world" point in time, from system), or as milliseconds since boot (from elapsedRealtime). The latter might be suitable when the timer is tied to an ELAPSED_REALTIME alarm in android.app.AlarmManager.

When representing a paused timer (or stopwatch, etc), this value specifies the duration as a fixed value.

This value can also specify its formatting, whether as a "chronometer" (e.g. 43:21) or an adaptive time (e.g. 1h 43m).

Summary

Constants
static final int

Formatting option: adaptive (e.g. 1h 5m; 15m; 1m 30s; 5s).
static final int

Formatting option: chronometer-style, (e.g. two hours = "2:00:00").

Public methods
boolean
static @NonNull NotificationCompat.Metric.TimeDifference
@RequiresApi(value = 37)
forPausedStopwatch(@NonNull Duration elapsedTime, int format)

Creates a "paused stopwatch" metric, showing the elapsedTime.
static @NonNull NotificationCompat.Metric.TimeDifference
@RequiresApi(value = 37)
forPausedTimer(@NonNull Duration remainingTime, int format)

Creates a "paused timer" metric, showing the remainingTime.
static @NonNull NotificationCompat.Metric.TimeDifference
@RequiresApi(value = 37)
forStopwatch(@NonNull Instant startTime, int format)

Creates a "running stopwatch" metric, which will show the time elapsed since startTime.
static @NonNull NotificationCompat.Metric.TimeDifference
@RequiresApi(value = 37)
forStopwatch(long startTime, int format)

Creates a "running stopwatch" metric, which will show the time elapsed since startTime, specified in the elapsedRealtime frame of reference.
static @NonNull NotificationCompat.Metric.TimeDifference
@RequiresApi(value = 37)
forTimer(@NonNull Instant endTime, int format)

Creates a "running timer" metric, which will show a countdown to endTime.
static @NonNull NotificationCompat.Metric.TimeDifference
@RequiresApi(value = 37)
forTimer(long endTime, int format)

Creates a "running timer" metric, which will show a countdown to endTime, specified in the elapsedRealtime frame of reference.
int

Formatting option for the timer/stopwatch.
@Nullable Duration

The fixed time difference, for a paused timer or stopwatch.
@Nullable Long

The elapsed realtime at which the time difference is zero.
@Nullable Instant

The Instant at which the time difference is zero.
int
boolean

Whether this TimeDifference value represents a stopwatch -- when running, it counts up from getZeroTime (or getZeroElapsedRealtime).
boolean

Whether this TimeDifference value represents a timer -- when running, it counts down to getZeroTime (or getZeroElapsedRealtime).
@NonNull String

Constants

FORMAT_ADAPTIVE

public static final int FORMAT_ADAPTIVE = 1

Formatting option: adaptive (e.g. 1h 5m; 15m; 1m 30s; 5s).

FORMAT_CHRONOMETER

public static final int FORMAT_CHRONOMETER = 2

Formatting option: chronometer-style, (e.g. two hours = "2:00:00").

Public methods

equals

public boolean equals(Object obj)

forPausedStopwatch

@RequiresApi(value = 37)
public static @NonNull NotificationCompat.Metric.TimeDifference forPausedStopwatch(@NonNull Duration elapsedTime, int format)

Creates a "paused stopwatch" metric, showing the elapsedTime.

forPausedTimer

@RequiresApi(value = 37)
public static @NonNull NotificationCompat.Metric.TimeDifference forPausedTimer(@NonNull Duration remainingTime, int format)

Creates a "paused timer" metric, showing the remainingTime.

forStopwatch

@RequiresApi(value = 37)
public static @NonNull NotificationCompat.Metric.TimeDifference forStopwatch(@NonNull Instant startTime, int format)

Creates a "running stopwatch" metric, which will show the time elapsed since startTime.

Parameters
@NonNull Instant startTime

instant at which the stopwatch started
int format

formatting option

forStopwatch

@RequiresApi(value = 37)
public static @NonNull NotificationCompat.Metric.TimeDifference forStopwatch(long startTime, int format)

Creates a "running stopwatch" metric, which will show the time elapsed since startTime, specified in the elapsedRealtime frame of reference.

Parameters
long startTime

elapsed realtime at which the stopwatch started
int format

formatting option

forTimer

@RequiresApi(value = 37)
public static @NonNull NotificationCompat.Metric.TimeDifference forTimer(@NonNull Instant endTime, int format)

Creates a "running timer" metric, which will show a countdown to endTime.

Parameters
@NonNull Instant endTime

instant at which the timer reaches zero
int format

formatting option

forTimer

@RequiresApi(value = 37)
public static @NonNull NotificationCompat.Metric.TimeDifference forTimer(long endTime, int format)

Creates a "running timer" metric, which will show a countdown to endTime, specified in the elapsedRealtime frame of reference.

Parameters
long endTime

elapsed realtime at which the timer reaches zero
int format

formatting option

getFormat

public int getFormat()

Formatting option for the timer/stopwatch.

getPausedDuration

public @Nullable Duration getPausedDuration()

The fixed time difference, for a paused timer or stopwatch.

  • For a paused timer this is the remainingTime supplied to forPausedTimer.
  • For a paused stopwatch this is the elapsedTime supplied to forPausedStopwatch.
  • For running timers or stopwatches this is null.

getZeroElapsedRealtime

public @Nullable Long getZeroElapsedRealtime()

The elapsed realtime at which the time difference is zero. Only valid for an elapsedRealtime-based TimeDifference.

  • For a running timer this is the endTime supplied to forTimer.
  • For a running stopwatch this is the startTime supplied to forStopwatch.
  • For running timers or stopwatches based on Instant (as well as paused timers and stopwatches), this is null.

getZeroTime

public @Nullable Instant getZeroTime()

The Instant at which the time difference is zero. Only valid for an Instant-based TimeDifference.

  • For a running timer this is the endTime supplied to forTimer.
  • For a running stopwatch this is the startTime supplied to forStopwatch.
  • For running timers or stopwatches based on elapsed realtime (as well as paused timers and stopwatches), this is null.

hashCode

public int hashCode()

isStopwatch

public boolean isStopwatch()

Whether this TimeDifference value represents a stopwatch -- when running, it counts up from getZeroTime (or getZeroElapsedRealtime).

isTimer

public boolean isTimer()

Whether this TimeDifference value represents a timer -- when running, it counts down to getZeroTime (or getZeroElapsedRealtime).

toString

public @NonNull String toString()