ComplicationTextFormatting
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(locale: Locale)Creates a new instance of |
Public functions |
|
|---|---|
String? |
getBestShortTextDateFormat(skeletons: Array<String>, fallback: String?)Finds the best date format pattern from a prioritized list of skeletons that consistently produces strings short enough for |
String? |
getFormattedDayOfWeekForShortText(timeInMillis: Long, timeZone: TimeZone?)Applies the short day-of-week formatting logic to a specific time. |
String? |
getFormattedTimeForShortText(Applies the short text time formatting logic to a specific time. |
Public properties |
|
|---|---|
String |
Returns a date format pattern for the full day-of-week name (e.g., "Tuesday"). |
String? |
Returns a date format pattern for a short day-and-month representation (e.g., "Dec 25"). |
String? |
Returns a date format pattern for the day of the month (e.g., "25"). |
String? |
Returns a date format pattern for a short day-of-week representation (e.g., "Tue"). |
String? |
Returns a date format pattern for a short month representation (e.g., "Dec"). |
String? |
Returns a 12-hour time format pattern suitable for a short text field (e.g., "1:37"). |
String? |
Returns a 12-hour time format pattern suitable for a short text field (e.g., "1:37 a.m."). |
String? |
Returns a 24-hour time format pattern suitable for a short text field (e.g., "13:37"). |
String? |
Returns a 24-hour time format pattern suitable for a short text field (e.g., "13:37"). |
Public constructors
ComplicationTextFormatting
ComplicationTextFormatting(locale: Locale)
Creates a new instance of ComplicationTextFormatting for the given locale.
Public functions
getBestShortTextDateFormat
fun getBestShortTextDateFormat(skeletons: Array<String>, fallback: String?): String?
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.
getFormattedDayOfWeekForShortText
fun getFormattedDayOfWeekForShortText(timeInMillis: Long, timeZone: TimeZone?): String?
Applies the short day-of-week formatting logic to a specific time.
| Parameters | |
|---|---|
timeInMillis: Long |
The UTC time to format, in milliseconds since the epoch. |
timeZone: TimeZone? |
The target |
| Returns | |
|---|---|
String? |
The final, formatted day-of-week string, ready for display. |
getFormattedTimeForShortText
fun getFormattedTimeForShortText(
timeInMillis: Long,
timeZone: TimeZone?,
use24Hour: Boolean
): String?
Applies the short text time formatting logic to a specific time.
| Parameters | |
|---|---|
timeInMillis: Long |
The UTC time to format, in milliseconds since the epoch. |
timeZone: TimeZone? |
The target |
use24Hour: Boolean |
If |
| Returns | |
|---|---|
String? |
The final, formatted time string, ready for display. |
Public properties
fullTextDayOfWeekFormat
val fullTextDayOfWeekFormat: String
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.
shortTextDayMonthFormat
val shortTextDayMonthFormat: String?
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.
shortTextDayOfMonthFormat
val shortTextDayOfMonthFormat: String?
Returns a date format pattern for the day of the month (e.g., "25"). Tries skeletons dd and d. Falls back to dd.
shortTextDayOfWeekFormat
val shortTextDayOfWeekFormat: String?
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.
shortTextMonthFormat
val shortTextMonthFormat: String?
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.
shortTextTimeFormat12Hour
val shortTextTimeFormat12Hour: String?
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.
shortTextTimeFormat12HourWithoutAmPmShortening
val shortTextTimeFormat12HourWithoutAmPmShortening: String?
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.
shortTextTimeFormat24Hour
val shortTextTimeFormat24Hour: String?
Returns a 24-hour time format pattern suitable for a short text field (e.g., "13:37").
shortTextTimeFormat24HourWithoutAmPmShortening
val shortTextTimeFormat24HourWithoutAmPmShortening: String?
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.