ComplicationText.TimeDifferenceBuilder

public static final class ComplicationText.TimeDifferenceBuilder
extends Object

java.lang.Object
   ↳ android.support.wearable.complications.ComplicationText.TimeDifferenceBuilder

Builder for a ComplicationText object that displays a text representation of the difference between the given time and the specified time period, within a surrounding string if required.

If the time passed in to getText(Context, ComplicationText, long) on the resulting object is between referencePeriodStart and referencePeriodEnd, then the text will be "now" (localised to the default locale).

If the time t passed in to getText(Context, ComplicationText, long) is before referencePeriodStart, then the text shown will represent the time difference between referencePeriodStart and t.

If the time t passed in to getText(Context, ComplicationText, long) is after referencePeriodEnd, then the text shown will represent the time difference between t and referencePeriodEnd.

The way the time difference is represented depends on the style. See DIFFERENCE_STYLE_SHORT_SINGLE_UNIT, DIFFERENCE_STYLE_SHORT_DUAL_UNIT, DIFFERENCE_STYLE_STOPWATCH and DIFFERENCE_STYLE_WORDS_SINGLE_UNIT.

Summary

Public constructors

ComplicationText.TimeDifferenceBuilder()

Public methods

ComplicationText build()

Returns ComplicationText representing the time difference as specified.

ComplicationText.TimeDifferenceBuilder setMinimumUnit(TimeUnit minimumUnit)

Sets the smallest unit that may be shown in the time difference text.

ComplicationText.TimeDifferenceBuilder setReferencePeriodEnd(long refPeriodEnd)

Sets the end of the reference period from which the time difference will be calculated.

ComplicationText.TimeDifferenceBuilder setReferencePeriodStart(long refPeriodStart)

Sets the start of the reference period from which the time difference will be calculated.

ComplicationText.TimeDifferenceBuilder setShowNowText(boolean showNowText)

Sets whether text saying "now" (appropriately localized) should be shown when the given time is within the reference period.

ComplicationText.TimeDifferenceBuilder setStyle(int style)

Sets the style in which the time difference will be displayed.

ComplicationText.TimeDifferenceBuilder setSurroundingText(CharSequence surroundingText)

Sets the text within which the time difference will be displayed.

Inherited methods

From class java.lang.Object

Public constructors

ComplicationText.TimeDifferenceBuilder

ComplicationText.TimeDifferenceBuilder ()

Public methods

build

ComplicationText build ()

Returns ComplicationText representing the time difference as specified.

Returns
ComplicationText

setMinimumUnit

ComplicationText.TimeDifferenceBuilder setMinimumUnit (TimeUnit minimumUnit)

Sets the smallest unit that may be shown in the time difference text. If specified, units smaller than this minimum will not be included.

For example, if this is set to HOURS, and the style is DIFFERENCE_STYLE_SHORT_SINGLE_UNIT then "12d" or "5h" would be shown as normal, but "35m" would be shown as "1h".

This is optional. If not specified, or if set to null, the style will determine the smallest unit that will be shown.

If the specified minimum is smaller than the smallest unit supported by the style, then the minimum will be ignored. For example, if the style is DIFFERENCE_STYLE_SHORT_SINGLE_UNIT, then a minimum unit of SECONDS will have no effect.

Parameters
minimumUnit TimeUnit

Returns
ComplicationText.TimeDifferenceBuilder

setReferencePeriodEnd

ComplicationText.TimeDifferenceBuilder setReferencePeriodEnd (long refPeriodEnd)

Sets the end of the reference period from which the time difference will be calculated. Defaults to Long.MAX_VALUE, effectively making the period unbounded at the end.

Parameters
refPeriodEnd long: the end of the reference period, given as UTC milliseconds since the epoch.
Returns
ComplicationText.TimeDifferenceBuilder this builder for chaining.

setReferencePeriodStart

ComplicationText.TimeDifferenceBuilder setReferencePeriodStart (long refPeriodStart)

Sets the start of the reference period from which the time difference will be calculated. Defaults to 0, effectively making the period unbounded at the start.

Parameters
refPeriodStart long: the end of the reference period, given as UTC milliseconds since the epoch.
Returns
ComplicationText.TimeDifferenceBuilder this builder for chaining.

setShowNowText

ComplicationText.TimeDifferenceBuilder setShowNowText (boolean showNowText)

Sets whether text saying "now" (appropriately localized) should be shown when the given time is within the reference period. If showNowText is false, then text representing zero (e.g. "0 mins" or "00:00") will be shown instead.

The default is true for all styles except for DIFFERENCE_STYLE_STOPWATCH.

Parameters
showNowText boolean

Returns
ComplicationText.TimeDifferenceBuilder

setStyle

ComplicationText.TimeDifferenceBuilder setStyle (int style)

Sets the style in which the time difference will be displayed. If not set, defaults to DIFFERENCE_STYLE_SHORT_DUAL_UNIT.

Parameters
style int

Returns
ComplicationText.TimeDifferenceBuilder this builder for chaining.

setSurroundingText

ComplicationText.TimeDifferenceBuilder setSurroundingText (CharSequence surroundingText)

Sets the text within which the time difference will be displayed. This is optional.

Within the text, ^1 will be replaced with the time difference, so for example to show a result like "2 mins: meeting" the surrounding text would be "^1: meeting".

To use the ^ character within the text, escape it as ^^.

Parameters
surroundingText CharSequence: text within which the time difference value will be displayed, with ^1 in place of the time difference.
Returns
ComplicationText.TimeDifferenceBuilder this builder for chaining.