A collection of arithmetic functions and operations, which other Watch Face Format elements use to resolve real-time attribute values and gyroscopic effects. Introduced in Wear OS 4. ## Example An example expression for rotating a value up to 5 degrees in either direction, based on the $ x $-value of the Wear OS device's accelerometer: (5/90)*clamp([ACCELEROMETER_ANGLE_X],0,90) + (-5/90)*clamp([ACCELEROMETER_ANGLE_X],-90,0) ...which is equivalent to the following mathematical expression, where $ \\theta_x $ represents the accelerometer angle in the $ x $-direction: $$ \\frac{5}{90} \* max(min(\\theta_x, 90), -90) $$ ## Handle special characters in XML expressions Expressions can appear either as text within an [`Expression`](https://developer.android.com/reference/wear-os/wff/common/condition) or within an attribute such as the `value` attribute on [`Transform`](https://developer.android.com/reference/wear-os/wff/common/transform/transform). Verify that your expressions conform to the XML rules for reserved characters: - In `Expression` elements, use `CNAME` to avoid the need for special handling: 5000]] - In attributes, use character references for reserved characters: Use the character references `&`, `>`, `<`, `'` and `"` for `&`, `<`, `>`, `'` and `"` respectively. ## Functions The Watch Face Format recognizes the following string values as functions: Version 1 Version 2 Version 4 | Function | Description | Return type | Availability | |---|---|---|---| | `round()` | Converts the input value to a floating-point value, then performs the standard [`round()`](https://developer.android.com/reference/java/lang/Math#round(float)) mathematical operation. | Integer | Version 1 | | `floor()` | Performs the standard [`floor()`](https://developer.android.com/reference/java/lang/Math#floor(float)) mathematical operation. | Float | Version 1 | | `ceil()` | Performs the standard [`ceil()`](https://developer.android.com/reference/java/lang/Math#ceil(float)) mathematical operation. | Float | Version 1 | | `fract()` | Returns the fractional part of the input value; that is, the part of the floating-point value that appears to the right of the decimal point. | Float | Version 1 | | `sin()` | Performs the standard [`sin()`](https://developer.android.com/reference/java/lang/Math#sin(double)) trigonometric operation. | Float | Version 1 | | `cos()` | Performs the standard [`cos()`](https://developer.android.com/reference/java/lang/Math#cos(double)) trigonometric operation. | Float | Version 1 | | `tan()` | Performs the standard [`tan()`](https://developer.android.com/reference/java/lang/Math#tan(double)) trigonometric operation. | Float | Version 1 | | `asin()` | Performs the standard [`asin()`](https://developer.android.com/reference/java/lang/Math#asin(double)) trigonometric operation. The returned value is always in the range $ \[-\\frac{\\pi}{2}, \\frac{\\pi}{2}\] $. | Float | Version 1 | | `acos()` | Performs the standard [`acos()`](https://developer.android.com/reference/java/lang/Math#acos(double)) trigonometric operation. The returned value is always in the range $ \[0.0, \\pi\] $. | Float | Version 1 | | `atan()` | Performs the standard [`atan()`](https://developer.android.com/reference/java/lang/Math#atan(double)) trigonometric operation. The returned value is always in the range $ \[-\\frac{\\pi}{2}, \\frac{\\pi}{2}\] $. | Float | Version 1 | | `abs()` | Converts the input value to a floating-point value, then performs the standard [`abs()`](https://developer.android.com/reference/java/lang/Math#abs(double)) mathematical operation. | Float | Version 1 | | `clamp(,,)` | Converts the input values to floating-point values, then performs the [`clamp()`](https://developer.android.com/reference/androidx/core/math/MathUtils#clamp(float,float,float)) Jetpack operation to fit the first value in the range defined by the second and third values. | Float | Version 1 | | `rand(,)` | Generates a random floating-point value that fulfills the following conditions at the same time: - Greater than or equal to the first value. - Less than or equal to the second value. Assumes that the first value is less than or equal to the second value. | Float | Version 1 | | `log()` | Performs the standard base-$ e $ [`log()`](https://developer.android.com/reference/java/lang/Math#log(double)) mathematical operation. | Float | Version 1 | | `log2()` | Simulates a base-2 logarithm. This value is calculated by dividing the base-10 [`log()`](https://developer.android.com/reference/java/lang/Math#log10(double)) of the input value) by the base-10 logarithm of $ 2 $. | Float | Version 1 | | `log10()` | Performs the standard base-10 [`log()`](https://developer.android.com/reference/java/lang/Math#log10(double)) mathematical operation. | Float | Version 1 | | `sqrt()` | Performs the standard [`sqrt()`](https://developer.android.com/reference/java/lang/Math#sqrt(double)) mathematical operation. | Float | Version 1 | | `cbrt()` | Performs the standard [`cbrt()`](https://developer.android.com/reference/java/lang/Math#cbrt(double)) mathematical operation. | Float | Version 1 | | `exp()` | Performs the standard [`exp()`](https://developer.android.com/reference/java/lang/Math#exp(double)) mathematical operation. | Float | Version 1 | | `expm1()` | Directly calls the [`expm1()`](https://developer.android.com/reference/java/lang/Math#expm1(double)) mathematical operation if the input value is $ 1 $. For any other input value, simulates the function by performing the standard [`exp()`](https://developer.android.com/reference/java/lang/Math#exp(double)) mathematical operation, then subtracting 1. | Float | Version 1 | | `deg()` | Performs the standard [`toDegrees()`](https://developer.android.com/reference/java/lang/Math#toDegrees(double)) mathematical operation. $ \\frac{\\pi}{2} $ is defined as 90 degrees, and $ \\pi $ is defined as 180 degrees. | Float | Version 1 | | `rad()` | Performs the standard [`toRadians()`](https://developer.android.com/reference/java/lang/Math#toRadians(double)) mathematical operation. 90 degrees is defined as $ \\frac{\\pi}{2} $, and 180 degrees is defined as $ \\pi $. | Float | Version 1 | | `pow(,)` | Performs the standard [`pow()`](https://developer.android.com/reference/java/lang/Math#pow(double)) mathematical operation. The output value is always a floating-point number. | Float | Version 1 | | `numberFormat(,)` | Applies the number format in the first value to the second value. The first value can contain the following characters: - `#` -- represents a numeric digit. - `,` -- represents a comma separator in large numbers. - `.` -- represents a decimal point. For a full reference, see [`DecimalFormat`](https://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html). | String | Version 1 | | `icuText()` | Converts the [input date format string](https://unicode-org.github.io/icu/userguide/format_parse/datetime/#date-field-symbol-table) to a pattern that matches the expected locale format. If the parent [`PartText`](https://developer.android.com/training/wearables/wff/group/part/text/part-text) element includes a [`Localization`](https://developer.android.com/training/wearables/wff/common/localization) element, that locale's format is used. Otherwise, uses the Wear OS device's current locale. For example, if the device is being used in the United States, an input value of `EE, MMM d, yyyy h:mm a` yields the following output: `Tue, Mar 14, 2023 1:59 PM` | String | Version 1 | | `icuText(,)` | Converts the first argument [input date format string](https://unicode-org.github.io/icu/userguide/format_parse/datetime/#date-field-symbol-table) to a pattern that matches the expected locale format. The second argument is a timestamp string in milliseconds. If the parent [`PartText`](https://developer.android.com/training/wearables/wff/group/part/text/part-text) element includes a [`Localization`](https://developer.android.com/training/wearables/wff/common/localization) element, that locale's format is used. Otherwise, uses the Wear OS device's current locale. | String | Version 2 | | `icuBestText()` | Converts the [input date format string](https://unicode-org.github.io/icu/userguide/format_parse/datetime/#date-field-symbol-table) to the current time whose pattern matches the expected format. If the parent [`PartText`](https://developer.android.com/training/wearables/wff/group/part/text/part-text) element includes a [`Localization`](https://developer.android.com/training/wearables/wff/common/localization) element, that locale's format is used. Otherwise, uses the Wear OS device's current locale. For example, if the device is being used in the United States on March 14, 2023 at 1:59 PM, an input value of `yyyy MMM d EE a h:mm` yields the following output: `Tue, Mar 14, 2023, 1:59 PM` | String | Version 1 | | `icuBestText(,)` | Converts the first argument [input date format string](https://unicode-org.github.io/icu/userguide/format_parse/datetime/#date-field-symbol-table) to the current time whose pattern matches the expected format. The second argument is a timestamp string in milliseconds. If the parent [`PartText`](https://developer.android.com/training/wearables/wff/group/part/text/part-text) element includes a [`Localization`](https://developer.android.com/training/wearables/wff/common/localization) element, that locale's format is used. Otherwise, uses the Wear OS device's current locale. | String | Version 2 | | `subText(,,)` | Extracts a substring from the first value. The second value indicates the 0-based index into the first value where the substring should begin. The third value indicates the 0-based index into the first value where substring extraction should stop ("from the second value up to, but not including, the third value"). Examples: - `subText("abc def", 2, 5)` is `c d` - `subText("abc def", 2, 7)` is `c def` | String | Version 1 | | `textLength()` | Calculates the length of the input string. Examples: - `textLength("")` is `0` - `textLength("abcdef")` is `6` | String | Version 1 | | `colorRgb(,,)` | Calculates a color value from RGB values Examples: - `colorRgb(255,0,0)` is the color red. | Color | Version 4 | | `colorArgb(,,)` | Calculates a color value from ARGB values Examples: - `colorRgb(128,255,0,0)` is the color red, with 50% opacity. | Color | Version 4 | | `extractColorFromColors(,,)` | Extracts a color from a list of colors. The function takes three arguments: - List of color hex values - Whether to interpolate the resulting color - The value to be converted, in the range `0.0 - 1.0`
Examples: - `extractColorFromColors("FF0000 00FF00 0000FF", false, 0.2)` is the color red. - `extractColorFromColors( [COMPLICATION.GOAL_PROGRESS_COLORS], [COMPLICATION.GOAL_PROGRESS_COLOR_INTERPOLATE], [COMPLICATION.GOAL_PROGRESS_VALUE] / [COMPLICATION.GOAL_PROGRESS_TARGET_VALUE] )` is the color taken from a list supplied by a Goal Complication. | Color | Version 4 | | `extractColorFromWeightedColors(,,)` | Extracts a color from a list of colors. The function takes four arguments: - List of color hex values - Corresponding list of weights for each color - Whether to interpolate the resulting color - The value to be converted, in the range `0.0 - 1.0` Examples: - `extractColorFromWeightedColors( #97d700 #FCE300 #ff8200 #f65058 #9461c9, 3 3 2 3 1, false, 0.1)` is the color represented by #97d700 | Color | Version 4 | ## Operators The Watch Face Format recognizes the following string values as operators: `+` : Unary plus, or addition of multiple values. Supports both integers and floating-point values. `-` : Unary minus, or subtraction of multiple values. Supports both integers and floating-point values. `*` : Multiplication of multiple integer or floating-point values. `/` : Division of 2 integer or floating-point values. If division of 2 integers results in a non-integer value, the decimal part is preserved in the floating-point result. For example, $ \\frac{1}{2} = 0.5 $. In addition, the expression $ \\frac{x}{0} $ is evaluated as `0`, where $ x $ is any integer. `%` : Modular division of 2 integer or floating-point values. If both operands are integers, the result is the remainder from dividing the 2 values. For example, $ 19 \\bmod 7 = 5 $. If at least one operand is a floating-point number, the result is a floating-point equivalent of the remainder; for example: $ 19.0 \\bmod 7 = 5.0 $. `~` : Bitwise "not" operator. Several examples: - `~1` is $ -2 $ - `~0` is $ -1 $ `!` : Logical "not" operator, which supports double negatives. Several examples: - $ !2 $ is `false` - $ !!0 $ is `true` `|` : Bitwise "or" operator. Supports more than 2 input values. Several examples: - $ 1 \| 0 = 1 $ - $ 1 \| 2 \| 4 = 7 $ `||` : Logical "or" operator. `&` : Bitwise "and" operator. Supports exactly 2 input values. `&&` : Logical "and" operator. `(` : Open parenthesis. Used for changing the standard order of operations, where multiplication and division ordinarily take priority over addition and subtraction. `)` : Closed parenthesis. Used for changing the standard order of operations, where multiplication and division ordinarily take priority over addition and subtraction. `<` : The "less than" comparison operator. When comparing an integer value with its floating-point equivalent, the result is `false`. `<=` : The "less than or equal to" comparison operator. When comparing an integer value with its floating-point equivalent, the result is `true`. `>` : The "greater than" comparison operator. When comparing an integer value with its floating-point equivalent, the result is `false`. `>=` : The "greater than or equal to" comparison operator. When comparing an integer value with its floating-point equivalent, the result is `true`. `?` and `:` : Provides support for ternary operations. The general format is as follows: condition ? value_if_true : value_if_false Supports nested ternary operations using parentheses. `,` : Separates values in functions that take more than 1 argument. `"` : When placed at the beginning and end of a value, indicates that the Watch Face Format should interpret the value as a string. `==` : Compare for equality. When comparing an integer value with its floating-point equivalent, the result is `true`. `!=` : Compare for inequality. When comparing an integer value with its floating-point equivalent, the result is `false`. ## Recommended for you - Note: link text is displayed when JavaScript is off - [Layouts and binding expressions](https://developer.android.com/topic/libraries/data-binding/expressions) - [AGSL Quick Reference](https://developer.android.com/develop/ui/views/graphics/agsl/agsl-quick-reference) - [Kotlin Bootcamp for Programmers 2: Kotlin basics](https://developer.android.com/codelabs/kotlin-bootcamp-basics)