TimeDifference

---

Kotlin |Java

class TimeDifference : Notification.Metric.MetricValue

kotlin.Any
↳	android.app.Notification.Metric.MetricValue
	↳	android.app.Notification.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 InstantSource.system), or as milliseconds since boot (from SystemClock.elapsedRealtime()). The latter might be suitable when the timer is tied to an AlarmManager.ELAPSED_REALTIME alarm in 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 Int	FORMAT_ADAPTIVE Formatting option: adaptive (e.g. 1h 5m; 15m; 1m 30s; 5s).
static Int	FORMAT_CHRONOMETER Formatting option: chronometer-style, (e.g. two hours = "2:00:00").

Public methods
Boolean	equals(other: Any?)
static Notification.Metric.TimeDifference	forPausedStopwatch(elapsedTime: Duration, format: Int) Creates a "paused stopwatch" metric, showing the elapsedTime.
static Notification.Metric.TimeDifference	forPausedTimer(remainingTime: Duration, format: Int) Creates a "paused timer" metric, showing the remainingTime.
static Notification.Metric.TimeDifference	forStopwatch(startTime: Instant, format: Int) Creates a "running stopwatch" metric, which will show the time elapsed since startTime.
static Notification.Metric.TimeDifference	forStopwatch(startTime: Long, format: Int) Creates a "running stopwatch" metric, which will show the time elapsed since startTime, specified in the SystemClock.elapsedRealtime() frame of reference.
static Notification.Metric.TimeDifference	forTimer(endTime: Instant, format: Int) Creates a "running timer" metric, which will show a countdown to endTime.
static Notification.Metric.TimeDifference	forTimer(endTime: Long, format: Int) Creates a "running timer" metric, which will show a countdown to endTime, specified in the SystemClock.elapsedRealtime() frame of reference.
Int	getFormat() Formatting option for the timer/stopwatch.
Duration?	getPausedDuration() The fixed time difference, for a paused timer or stopwatch.
Long?	getZeroElapsedRealtime() The elapsed realtime at which the time difference is zero.
Instant?	getZeroTime() The Instant at which the time difference is zero.
Int	hashCode()
Boolean	isStopwatch() Whether this TimeDifference value represents a stopwatch -- when running, it counts up from getZeroTime() (or getZeroElapsedRealtime()).
Boolean	isTimer() Whether this TimeDifference value represents a timer -- when running, it counts down to getZeroTime() (or getZeroElapsedRealtime()).
String	toString()

Constants

FORMAT_ADAPTIVE

static val FORMAT_ADAPTIVE: Int

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

Value: 1

FORMAT_CHRONOMETER

static val FORMAT_CHRONOMETER: Int

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

Value: 2

Public methods

equals

fun equals(other: Any?): Boolean

forPausedStopwatch

static fun forPausedStopwatch(
    elapsedTime: Duration, 
    format: Int
): Notification.Metric.TimeDifference

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

Parameters
elapsedTime	Duration: This value cannot be null.
format	Int: Value is one of the following: FORMAT_ADAPTIVE FORMAT_CHRONOMETER

Return
Notification.Metric.TimeDifference	This value cannot be null.

forPausedTimer

static fun forPausedTimer(
    remainingTime: Duration, 
    format: Int
): Notification.Metric.TimeDifference

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

Parameters
remainingTime	Duration: This value cannot be null.
format	Int: Value is one of the following: FORMAT_ADAPTIVE FORMAT_CHRONOMETER

Return
Notification.Metric.TimeDifference	This value cannot be null.

forStopwatch

static fun forStopwatch(
    startTime: Instant, 
    format: Int
): Notification.Metric.TimeDifference

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

Parameters
startTime	Instant: instant at which the stopwatch started. This value cannot be null.
format	Int: Value is one of the following: FORMAT_ADAPTIVE FORMAT_CHRONOMETER

Return
Notification.Metric.TimeDifference	This value cannot be null.

forStopwatch

static fun forStopwatch(
    startTime: Long, 
    format: Int
): Notification.Metric.TimeDifference

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

Parameters
startTime	Long: elapsed realtime at which the stopwatch started. Value is a non-negative timestamp in the android.os.SystemClock#elapsedRealtime() time base.
format	Int: Value is one of the following: FORMAT_ADAPTIVE FORMAT_CHRONOMETER

Return
Notification.Metric.TimeDifference	This value cannot be null.

forTimer

static fun forTimer(
    endTime: Instant, 
    format: Int
): Notification.Metric.TimeDifference

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

Parameters
endTime	Instant: instant at which the timer reaches zero. This value cannot be null.
format	Int: Value is one of the following: FORMAT_ADAPTIVE FORMAT_CHRONOMETER

Return
Notification.Metric.TimeDifference	This value cannot be null.

forTimer

static fun forTimer(
    endTime: Long, 
    format: Int
): Notification.Metric.TimeDifference

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

Parameters
endTime	Long: elapsed realtime at which the timer reaches zero. Value is a non-negative timestamp in the android.os.SystemClock#elapsedRealtime() time base.
format	Int: Value is one of the following: FORMAT_ADAPTIVE FORMAT_CHRONOMETER

Return
Notification.Metric.TimeDifference	This value cannot be null.

getFormat

fun getFormat(): Int

Formatting option for the timer/stopwatch.

Return
Int	Value is one of the following: FORMAT_ADAPTIVE FORMAT_CHRONOMETER

getPausedDuration

fun getPausedDuration(): Duration?

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

fun getZeroElapsedRealtime(): Long?

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

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

.
Value is a non-negative timestamp in the android.os.SystemClock#elapsedRealtime() time base.

Return
Long?	Value is a non-negative timestamp in the android.os.SystemClock#elapsedRealtime() time base.

getZeroTime

fun getZeroTime(): Instant?

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(Instant,int).
• For a running stopwatch this is the startTime supplied to forStopwatch(Instant,int).
• For running timers or stopwatches based on elapsed realtime (as well as paused timers and stopwatches), this is null.

hashCode

fun hashCode(): Int

isStopwatch

fun isStopwatch(): Boolean

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

isTimer

fun isTimer(): Boolean

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

toString

fun toString(): String