Status

public final class Status implements TimeDependentText

Base class to represent the status of an Ongoing Activity and render it.

A status is composed of Parts, and they are joined together with a template.

Note that for backwards compatibility reasons the code rendering this status message may not have all of the [Part] classes that are available in later versions of the library. Templates that do not have values for all of the named parts will not be used. The template list will be iterated through looking for the first template with all matching named parts available, this will be selected for rendering the status.

To provide for backwards compatibility, you should provide one (or more) fallback templates which use status parts from earlier versions of the API. e.g. TextPart, TimerPart & StopwatchPart

The status and part classes here use timestamps for updating the displayed representation of the status, in cases when this is needed (chronometers), as returned by elapsedRealtime

Summary

Nested types
Status.Builder

Helper to Build OngoingActivityStatus instances.
Status.Part

Abstract class to represent An Ongoing activity status or part of it.
Status.StopwatchPart

An Ongoing activity status (or part of it) representing a stopwatch

Status.TextPart

An Ongoing activity status (or part of it) representing a plain, static text.
Status.TimerOrStopwatchPart

Base class for TimerPart and StopwatchPart, defines the getters but can't be created directly, create one of those instead.
Status.TimerPart

An Ongoing activity status (or part of it) representing a timer.

Public methods
static @NonNull Status

Convenience method for creating a Status with no template and a single Part.
@Override @NonNull long
getNextChangeTimeMillis(@NonNull long fromTimeMillis)

Returns the next time this status could have a different rendering.
@Nullable Status.Part

Returns the value of the part with the given name.
@NonNull Set<@NonNull String>
@NonNull List<@NonNull CharSequence>
@NonNull @Override CharSequence
getText(@NonNull Context context, @NonNull long timeNowMillis)

Returns a textual representation of this status at the given time.

Public methods

forPart

@NonNull
public static Status forPart(@NonNull Status.Part part)

Convenience method for creating a Status with no template and a single Part.

Parameters
@NonNull Status.Part part

The only Part that composes this status.
Returns
Status

A new Status with just one Part.

getNextChangeTimeMillis

@Override
@NonNull
public @Override long getNextChangeTimeMillis(@NonNull long fromTimeMillis)

Returns the next time this status could have a different rendering. There is no guarantee that the rendering will change at the returned time (for example, if some information in the status is not rendered).

Parameters
@NonNull long fromTimeMillis

current time, usually now as returned by elapsedRealtime. In most cases {@code getText} and {@code getNextChangeTimeMillis} should be called with the exact same timestamp, so changes are not missed.
Returns
@Override long

the next time (counting from fromTimeMillis) that this status may produce a different result when calling getText().

getPart

@Nullable
@NonNull
public Status.Part getPart(@NonNull String name)

Returns the value of the part with the given name.

Parameters
@NonNull String name

the name to lookup.
Returns
Status.Part

the part with the given name, can be null.

getPartNames

@NonNull
public Set<@NonNull String> getPartNames()
Returns
Set<@NonNull String>

the names of the parts provide to this status.

getTemplates

@NonNull
public List<@NonNull CharSequence> getTemplates()
Returns
List<@NonNull CharSequence>

the list of templates that this status has.

getText

@NonNull
@Override
public @Override CharSequence getText(@NonNull Context context, @NonNull long timeNowMillis)

Returns a textual representation of this status at the given time. The first template that has all required information will be used, and each part will be used in their respective placeholder/s.

Parameters
@NonNull Context context

may be used for internationalization. Only used while this method executed.
@NonNull long timeNowMillis

the timestamp of the time we want to display, usually now, as
Returns
@Override CharSequence

the rendered text, for best compatibility, display using a TextView.