# ComplicationTextFormatting

Artifact: [androidx.wear.watchface:watchface-complications-data](https://developer.android.com/jetpack/androidx/releases/wear-watchface) [View Source](https://cs.android.com/search?q=file:androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting.kt+class:androidx.wear.watchface.complications.data.formatting.ComplicationTextFormatting) Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0)

*** ** * ** ***

<br />

```
public final class ComplicationTextFormatting
```

<br />

*** ** * ** ***

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 |
|---|
| `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting#ComplicationTextFormatting(java.util.Locale)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Locale.html locale)` Creates a new instance of `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting` for the given locale. |

| ### Public methods |
|---|---|
| `final https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting#getBestShortTextDateFormat(kotlin.Array,kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull String[] skeletons, https://developer.android.com/reference/java/lang/String.html fallback)` Finds the best date format pattern from a prioritized list of skeletons that consistently produces strings short enough for `SHORT_TEXT` fields. |
| `final https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting#getFormattedDayOfWeekForShortText(kotlin.Long,android.icu.util.TimeZone)(long timeInMillis, https://developer.android.com/reference/android/icu/util/TimeZone.html timeZone)` Applies the short day-of-week formatting logic to a specific time. |
| `final https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting#getFormattedTimeForShortText(kotlin.Long,android.icu.util.TimeZone,kotlin.Boolean)( long timeInMillis, https://developer.android.com/reference/android/icu/util/TimeZone.html timeZone, boolean use24Hour )` Applies the short text time formatting logic to a specific time. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting#getFullTextDayOfWeekFormat()()` Returns a date format pattern for the full day-of-week name (e.g., "Tuesday"). |
| `final https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting#getShortTextDayMonthFormat()()` Returns a date format pattern for a short day-and-month representation (e.g., "Dec 25"). |
| `final https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting#getShortTextDayOfMonthFormat()()` Returns a date format pattern for the day of the month (e.g., "25"). |
| `final https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting#getShortTextDayOfWeekFormat()()` Returns a date format pattern for a short day-of-week representation (e.g., "Tue"). |
| `final https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting#getShortTextMonthFormat()()` Returns a date format pattern for a short month representation (e.g., "Dec"). |
| `final https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting#getShortTextTimeFormat12Hour()()` Returns a 12-hour time format pattern suitable for a short text field (e.g., "1:37"). |
| `final https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting#getShortTextTimeFormat12HourWithoutAmPmShortening()()` Returns a 12-hour time format pattern suitable for a short text field (e.g., "1:37 a.m."). |
| `final https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting#getShortTextTimeFormat24Hour()()` Returns a 24-hour time format pattern suitable for a short text field (e.g., "13:37"). |
| `final https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting#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](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0)

```
public ComplicationTextFormatting(@NonNull Locale locale)
```

Creates a new instance of `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting` for the given locale.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Locale.html locale` | The `https://developer.android.com/reference/java/util/Locale.html` that defines the formatting conventions. |

## Public methods

### getBestShortTextDateFormat

Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0)

```
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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/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. |
| `https://developer.android.com/reference/java/lang/String.html fallback` | The non-validated pattern to return if no skeleton in `skeletons` is suitable. |

| Returns |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html` | The best-fitting date pattern string, or the `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting#getBestShortTextDateFormat(kotlin.Array,kotlin.String)`. |

### getFormattedDayOfWeekForShortText

Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0)

```
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. |
| `https://developer.android.com/reference/android/icu/util/TimeZone.html timeZone` | The target `https://developer.android.com/reference/android/icu/util/TimeZone.html` for the output string. `null` uses the system default. |

| Returns |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html` | The final, formatted day-of-week string, ready for display. |

### getFormattedTimeForShortText

Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0)

```
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. |
| `https://developer.android.com/reference/android/icu/util/TimeZone.html timeZone` | The target `https://developer.android.com/reference/android/icu/util/TimeZone.html` for the output string. `null` uses the system default. |
| `boolean use24Hour` | If `true`, formats in 24-hour time; otherwise, 12-hour. |

| Returns |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html` | The final, formatted time string, ready for display. |

### getFullTextDayOfWeekFormat

Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0)

```
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](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0)

```
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](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0)

```
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](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0)

```
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](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0)

```
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](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0)

```
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](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0)

```
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](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0)

```
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](https://developer.android.com/jetpack/androidx/releases/wear-watchface#1.3.0)

```
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 `https://developer.android.com/reference/androidx/wear/watchface/complications/data/formatting/ComplicationTextFormatting#shortTextTimeFormat24Hour()`, as AM/PM shortening is not applicable to 24-hour formats.