ComplicationTextFormatting

Artifact: androidx.wear.watchface:watchface-complications-data

Kotlin |Java

public final class ComplicationTextFormatting

A utility for finding optimal, locale-aware date and time format patterns that are guaranteed to fit within the strict character limits of a ComplicationType.SHORT_TEXT field.

The primary challenge in formatting text for complications is that the length of formatted date/time strings can vary (e.g., "May" vs. "September"). This class solves this by systematically testing a set of preferred format skeletons against a range of date and time values. It determines the "worst-case" (longest) output for a given pattern and locale, ensuring the chosen pattern is always safe to use.

It also includes hardcoded overrides for specific locales where standard patterns are known to be too long.

Summary

Public constructors
`ComplicationTextFormatting(@NonNull Locale locale)` Creates a new instance of `ComplicationTextFormatting` for the given locale.

Public methods
`final String`	`getBestShortTextDateFormat(@NonNull String[] skeletons, String fallback)` Finds the best date format pattern from a prioritized list of skeletons that consistently produces strings short enough for `SHORT_TEXT` fields.
`final String`	`getFormattedDayOfWeekForShortText(long timeInMillis, TimeZone timeZone)` Applies the short day-of-week formatting logic to a specific time.
`final String`	`getFormattedTimeForShortText( long timeInMillis, TimeZone timeZone, boolean use24Hour )` Applies the short text time formatting logic to a specific time.
`final @NonNull String`	`getFullTextDayOfWeekFormat()` Returns a date format pattern for the full day-of-week name (e.g., "Tuesday").
`final String`	`getShortTextDayMonthFormat()` Returns a date format pattern for a short day-and-month representation (e.g., "Dec 25").
`final String`	`getShortTextDayOfMonthFormat()` Returns a date format pattern for the day of the month (e.g., "25").
`final String`	`getShortTextDayOfWeekFormat()` Returns a date format pattern for a short day-of-week representation (e.g., "Tue").
`final String`	`getShortTextMonthFormat()` Returns a date format pattern for a short month representation (e.g., "Dec").
`final String`	`getShortTextTimeFormat12Hour()` Returns a 12-hour time format pattern suitable for a short text field (e.g., "1:37").
`final String`	`getShortTextTimeFormat12HourWithoutAmPmShortening()` Returns a 12-hour time format pattern suitable for a short text field (e.g., "1:37 a.m.").
`final String`	`getShortTextTimeFormat24Hour()` Returns a 24-hour time format pattern suitable for a short text field (e.g., "13:37").
`final String`	`getShortTextTimeFormat24HourWithoutAmPmShortening()` Returns a 24-hour time format pattern suitable for a short text field (e.g., "13:37").

Public constructors

ComplicationTextFormatting

Added in 1.3.0-beta01

public ComplicationTextFormatting(@NonNull Locale locale)

Creates a new instance of ComplicationTextFormatting for the given locale.

Parameters
`@NonNull Locale locale`	The `Locale` that defines the formatting conventions.

Public methods

getBestShortTextDateFormat

Added in 1.3.0-beta01

public final String getBestShortTextDateFormat(@NonNull String[] skeletons, String fallback)

Finds the best date format pattern from a prioritized list of skeletons that consistently produces strings short enough for SHORT_TEXT fields.

It iterates through the provided skeletons in order. The first skeleton that passes the length-check across multiple date/time samples is selected. If no skeletons in the list produce a sufficiently short result, the fallback pattern is returned.

Parameters
`@NonNull String[] skeletons`	An array of date format skeletons to test, in order of preference. For example, `["MMMd", "MMd"]` would try a three-letter month first before a two-digit month.
`String fallback`	The non-validated pattern to return if no skeleton in `skeletons` is suitable.

Returns
`String`	The best-fitting date pattern string, or the `fallback`.

getFormattedDayOfWeekForShortText

Added in 1.3.0-beta01

public final String getFormattedDayOfWeekForShortText(long timeInMillis, TimeZone timeZone)

Applies the short day-of-week formatting logic to a specific time.

Parameters
`long timeInMillis`	The UTC time to format, in milliseconds since the epoch.
`TimeZone timeZone`	The target `TimeZone` for the output string. `null` uses the system default.

Returns
`String`	The final, formatted day-of-week string, ready for display.

getFormattedTimeForShortText

Added in 1.3.0-beta01

public final String getFormattedTimeForShortText(
    long timeInMillis,
    TimeZone timeZone,
    boolean use24Hour
)

Applies the short text time formatting logic to a specific time.

Parameters
`long timeInMillis`	The UTC time to format, in milliseconds since the epoch.
`TimeZone timeZone`	The target `TimeZone` for the output string. `null` uses the system default.
`boolean use24Hour`	If `true`, formats in 24-hour time; otherwise, 12-hour.

Returns
`String`	The final, formatted time string, ready for display.

getFullTextDayOfWeekFormat

Added in 1.3.0-beta01

public final @NonNull String getFullTextDayOfWeekFormat()

Returns a date format pattern for the full day-of-week name (e.g., "Tuesday"). This is intended for LONG_TEXT fields and is not length-checked.

getShortTextDayMonthFormat

Added in 1.3.0-beta01

public final String getShortTextDayMonthFormat()

Returns a date format pattern for a short day-and-month representation (e.g., "Dec 25"). Tries skeletons in the order of MMMd, MMd, and Md. Falls back to d/MM.

getShortTextDayOfMonthFormat

Added in 1.3.0-beta01

public final String getShortTextDayOfMonthFormat()

Returns a date format pattern for the day of the month (e.g., "25"). Tries skeletons dd and d. Falls back to dd.

getShortTextDayOfWeekFormat

Added in 1.3.0-beta01

public final String getShortTextDayOfWeekFormat()

Returns a date format pattern for a short day-of-week representation (e.g., "Tue"). Tries skeletons EEE (abbreviation), EEEEEE (2-letter), and EEEEE (1-letter). Falls back to EEEEE.

getShortTextMonthFormat

Added in 1.3.0-beta01

public final String getShortTextMonthFormat()

Returns a date format pattern for a short month representation (e.g., "Dec"). Tries skeletons in the order of MMM, MM, and M. Falls back to MM.

getShortTextTimeFormat12Hour

Added in 1.3.0-beta01

public final String getShortTextTimeFormat12Hour()

Returns a 12-hour time format pattern suitable for a short text field (e.g., "1:37"). This version may shorten the AM/PM marker (e.g., from "a.m." to "am") to meet length constraints.

getShortTextTimeFormat12HourWithoutAmPmShortening

Added in 1.3.0-beta01

public final String getShortTextTimeFormat12HourWithoutAmPmShortening()

Returns a 12-hour time format pattern suitable for a short text field (e.g., "1:37 a.m.").

This version preserves the full, locale-specific AM/PM marker (e.g., "a.m." with periods) and does not attempt to shorten it to save space.

getShortTextTimeFormat24Hour

Added in 1.3.0-beta01

public final String getShortTextTimeFormat24Hour()

Returns a 24-hour time format pattern suitable for a short text field (e.g., "13:37").

getShortTextTimeFormat24HourWithoutAmPmShortening

Added in 1.3.0-beta01

public final String getShortTextTimeFormat24HourWithoutAmPmShortening()

Returns a 24-hour time format pattern suitable for a short text field (e.g., "13:37").

Note: This is functionally identical to shortTextTimeFormat24Hour, as AM/PM shortening is not applicable to 24-hour formats.