Tag expressions

Stay organized with collections Save and categorize content based on your preferences.

Use tag expressions to create unique and dynamic watch faces. Tag expressions are conditions that let you change the rotation, placement, and opacity of a component based on tag values—watch data such as the date and time, battery status, or steps. Your watch face changes dynamically as the tag value changes.

For example, you can create a watch face where the object on the screen moves vertically with every passing second, or you can create a watch face with objects that appear or disappear at certain times.

Enter tag expressions directly into the rotate, placement, and opacity properties input fields of a component.

Tags must be enclosed in square brackets. To open the tag scripting dialog in Watch Face Studio, click Tags. In the scripting dialog, you can enter lengthy tag expressions and search for the data you want.

tag-exp

Figure 1. The tag scripting dialog.

Tag descriptions and value ranges are shown in the following tables.

Date and time

Tag Definition Range Example
UTC_TS Timestamp as UTC milliseconds from the epoch 1256953732
MSEC Millisecond 0 - 999 123
SEC Second in minute 0 - 59 12
SEC_Z Second in minute with leading zero 00 - 59 03
SEC_MSEC Second in minute with millisecond 0.0 - 59.999 1.234
SEC_IN_DAY Second in day 0 - 86,400 12,345
MIN Minute in hour 0 - 59 3
MIN_Z Minute in hour with leading zero 00 - 59 03
MIN_SEC Minute in hour with second 0.0 - 59.999 1.234
HOUR_0_11 Hour in day (0-11) 0 - 11 3
HOUR_0_11_Z Hour in day (0-11) with leading zero 00 - 11 03
HOUR_0_11_MIN Hour in day (0-11) with minute 0.0 - 11.999 1.234
HOUR_1_12 Hour in day (0-12) 1 - 12 3
HOUR_1_12_Z Hour in day (0-12) with leading zero 01 - 12 03
HOUR_1_12_MIN Hour in day (0-12) with minute 1.0 - 12.999 1.234
HOUR_0_23 Hour in day (0-23) 0 - 23 3
HOUR_0_23_Z Hour in day (0-23) with leading zero 00 - 23 03
HOUR_0_23_MIN Hour in day (0-23) with minute 0.0 - 23.999 1.234
HOUR_1_24 Hour in day (1-24) 1 - 24 3
HOUR_1_24_Z Hour in day (1-24) with leading zero 01 - 24 03
HOUR_1_24_MIN Hour in day (1-24) with minute 1.0 - 24.999 1.234
DAY_1_31 Day in month (1-31) 1 - 31 3
DAY_1_31_Z Day in month (1-31) with leading zero 01 - 31 13
DAY_1_31_HOUR Day in month (1-31) with hour 1.0 - 31.999 1.234
DAY_WEEK Day of week 1 (Sunday) - 7 (Saturday) 3
DAY_WEEK_F Day of week, full text Sunday - Saturday Wednesday
DAY_WEEK_S Day of week, abbreviated text Sun - Sat Wed
DAY_IN_YEAR Day in year 1 - 365 123
DAYS_IN_MON Days in the current month 28 - 31 31
MON Month in year 1 - 12 3
MON_Z Month in year with leading zero 01 - 12 03
MON_F Month in year, full text January - December November
MON_S Month in year, abbreviated text Jan - Dec Nov
MON_DAY Month with day 1.0 - 12.999 11.111
YEAR Year 0000 - 9999 2021
YEAR_S Abbreviated year, represented by last two digits 00 - 99 21
YEAR_MON Year with month 2021.307
WEEK_IN_YEAR Week in year 1-52 24
WEEK_IN_MON Week in month 1-5 2
IS_24H Whether the system uses 24-hour format 0 (12-hour), 1 (24-hour) 0
IS_DST Whether the system uses Daylight Saving Time 0 (No), 1 (Yes) 0
TMZN_ABB Timezone abbreviation PST
TMZN_OFS Timezone offset -12 - +14 +9
TMZN_OFS_WITH_DST Timezone offset, modified for Daylight Saving Time -12 - +14 -7
TMZN_ID ID of timezone Asia/Seoul
IS_AFTNOON Whether the hour is before or after noon 0 (AM), 1 (PM) 0
AMPM_PO Position of AM or PM string -1 (Unknown), 0 (First), 1 (Last) 0
AMPM AM/PM string formatted with system locale AM/PM AM

Setting information

Tag Definition Range Example
LANG_LOC String representation of the system locale object, consisting of language, country, variant, script, and extensions. For example, en_US. ko_KR

Device information

Tag Definition Range Example
BATT_PER Current battery percentage 0 - 100 70
BATT_IS_CHARGE Whether the battery is charging 0 (No), 1 (Yes) 1
BATT_IS_LOW Whether the battery of the watch is low and not charging 0 (No), 1 (Yes) 0
BATT_TEM_C Current battery Temperature (°C) 28.8
BATT_TEM_F Current battery Temperature (°F) 83.84
UNREAD_NC Count of unread notifications on the device 3

Sensor data

Tag Definition Range Example
IS_ACC Whether the device has an accelerometer sensor 0 (No), 1 (Yes) 1
ACC_X Acceleration on the x-axis
ACC_Y Acceleration on the y-axis
ACC_Z Acceleration on the z-axis
ACC_A_X Acceleration angle on the x-axis -90.0 - 90.0
ACC_A_Y Acceleration angle on the y-axis -90.0 - 90.0
ACC_A_Z Acceleration angle on the z-axis -90.0 - 90.0
ACC_A_XY Angle X + Angle Y -180.0 - 180.0

Health data

Tag Definition Range Example
HR Heart rate 0 - 60
HR_Z Heart rate with leading zero 00

80

120

HR_LAST_MEASURED_TIME Timestamp when the heart rate was measured 1256953732
HR_MEASURE_RESULT Whether heart rate measurement was successful 0 (Failure), 1 (Success) 0
HR_IS_MEASURING Whether heart rate is measuring or not 0 (No), 1 (Yes) 0
SC Step count 0 - 1000
SC_GOAL Step count goal 1 - 20000 20000
SC_PER Step count as percentage of step count goal 0 - 100

Moon phase

Tag Definition Range Example
MOON_PO Position of moon phase 0 - 28 (See below) 14.5
MOON_TY Type of moon phase 0 - 7 (See below) 2
MOON_TY_NAME Name of type (See below)

Range definitions for the MOON_PO tag include the following:

  • 0-0.5: New moon
  • 0.5-6.5 : Evening crescent
  • 7 : First quarter
  • 7.5-13.5 : Waxing gibbous
  • 14 : Full moon
  • 14.5-20.5 : Waning gibbous
  • 21 : Last quarter
  • 21.5-27.5 : Morning crescent
  • 27.5-28 : New moon

Range definitions for the MOON_TY and MOON_TY_NAME tags include the following:

  • 0 : New moon
  • 1 : Evening crescent
  • 2 : First quarter
  • 3 : Waxing gibbous
  • 4 : Full moon
  • 5 : Waning gibbous
  • 6 : Last quarter
  • 7 : Morning crescent

Functions

Functions Definition Expression example Output example
round(num) Returns the closest integer to num. round(1.6) 2
floor(num) Returns the greatest integer less than or equal to num. floor(1.6) 1
ceil(num) Returns the smallest integer that is greater than or equal to num. ceil(1.2) 2
sin(num) Returns the sine of num. sin(1) 0.84147096
cos(num) Returns the cosine of num. cos(1) 0.5403023
tan(num) Returns the tangent of num. tan(1) 1.5574077
abs(num) Returns the distance from zero. abs(-10) 10
clamp(num, min, max) Returns the value of clamping num between max and min. clamp([ACC_A_X], -30, 60) -30~60
numberFormat(form, num) Transforms num into the format of form. form is made up of the following values:

0: Fills empty spaces with zero.

#: Does not display places with no values.

.: Indicates the position of the decimal point.

(numberFormat("#.#", [SEC_MSEC]))

(numberFormat("#.###", ([SEC_MSEC]*10)))

(numberFormat("000.000", ([SEC_MSEC]*10)))

(numberFormat("0000.000", ([SEC_MSEC]*10)))

32.4

324.37

324.370

0324.370

asin(num) Returns the arcsine function of num. asin(0.841) 1
acos(num)m Returns the arccosine function of num. acos(0.54) 1
atan(num) Returns the arctangent function of num. atan(1.557) 1
deg(num) Converts num from radians to degrees. deg(3.142) 180
rad(num) Converts num from degrees to radians. rad(180) 3.141
pow(base, exponent) Returns the result of a base raised to an exponent. pow(12, 2) 144

Operators

Tag expressions support various operators that can modify the value of the tag expressions.

Arithmetic operators

Arithmetic operators are basic math functions. They perform a function between two values, or operands.

Operator Definition
+ Addition
- Subtraction
* Multiplication
/ Quotient of division
% Remainder of division

Examples

The following examples show how to use tags and arithmetic operations in a tag expression:

  • 5 * [BATT_PER] :

    This returns the battery percentage multiplied by 5.

    If the battery percentage is 7%, then the value returned is 35.

  • [SEC] / 3 :

    This returns the quotient of seconds in a minute divided by 3.

    If the number of seconds that have passed in the minute is 7, then the value returned is 2.33.

  • [SEC] % 3 :

    This returns the remainder of seconds in a minute divided by 3.

    If the number of seconds that have passed in the minute is 7, then the value returned is 1.

  • 3 + 5 * [BATT_PER] :

    The battery percentage is multiplied by 5, then 3 is added.

    If the battery percentage is 7%, then the value returned is 38.

    Multiplication is performed first, because it takes precedence over addition, and then 3 is added to the result: 3 + 5 * 7 → 3 + 35 → 38.

  • (3 + 5) * [BATT_PER] :

    The addition operation in parentheses is performed first, then the result is multiplied by the battery percentage. If the battery percentage is 7%, then the value returned is 56.

Relational operators

Relational operators compare two values to determine their relationship, such as whether one is greater than, less than, or equal to the other. A comparison that is true returns a value of one. A comparison that is false returns a value of zero.

Operator Definition
< Less than
<= Less than or equal to
> Greater than
>= Greater than or equal to
== Equal to
!= Not equal to

Examples

Relational operations are sometimes combined with arithmetic operations. The following are examples that use only relational operations, or relational operations and arithmetic operations.

  • [BATT_PER] <= 15 :

    If the battery percentage is less than or equal to 15%, [BATT_PER] <= 15 is true and returns 1.

    If the battery percentage is greater than 15%, [BATT_PER] <= 15 is false and returns 0.

  • 1000 * ([HRATE] < 100) + 120

    If the heart rate is less than 100 bpm, [HRATE] < 100 is true and returns the value of 1. Next, multiply 1 by 1,000 and then add 120. The final value returned is 1,120.

    If the heart rate is greater than or equal to 100 bpm, [HRATE] < 100 is false and returns the value of 0. Next, multiply 0 by 1,000 and then add 120. The final value returned is 120.

Logical operators

Logical operators combine the results of two or more relational operations and return a value of 1 (true) or 0 (false). Tag expressions support two types of logical operations: AND and OR.

  • AND – represented by an asterisk (*)

    Both relational operations must be true for the AND logical operator to return a value of 1 (true). Otherwise, the return value is 0 (false).

  • OR – represented by the plus sign (+)

    One or more of the relational operations must be true for the OR logical operator to return a value of 1 (true). If both of the relational operations are false, then the return value is 0 (false).

The following table describes the results of logical operations:

Result of relational operation 1 Result of relational operation 2 Result of AND (*)

(relational operation 1) * (relational operation 2)

Result of OR (+)

(relational operation 1) + (relational operation 2)

0 (false) 0 (false) 0 * 0 = 0 0 + 0 = 0
0 (false) 1 (true) 0 * 1 = 0 0 + 1 = 1
1 (true) 0 (false) 1 * 0 = 0 1 + 0 = 1
1 (true) 1 (true) 1 * 1 = 1 1 + 1 = 1

A logical operator is applied only if both of the two operands—the values on either side of the operator—are relational operations. An arithmetic operator is applied if either of the two operands is a number value.

Logical operation Arithmetic operation Arithmetic operation
Both operands are relational operations:

(0 <= 1) * (1 < 2)

Result: 1

One operand is a relational operation and the other is a value:

(0 <= 1) * 120

Result: 120

Both operands are values:

1 * 120

Result: 120

This tag expression is made up of two relational operations on either side of the operator (0<=1 and 1<2). Because of this, the logical operator is applied. Because both of the relational operations are true, the final result of this tag expression is 1 (true). This tag expression is made up of a relational operation (0<=1) and a number value (120). Because of this, the arithmetic operator is applied. The result of the relational operation is 1 (true) which is then multiplied by 120. The final result of this operation is 120. This tag expression is made up of two number values (1 and 120). Because of this, the arithmetic operator is applied. The result is 1 multiplied by 120, which returns a final result of 120.

Ternary operators

Ternary operations have three operands: a conditional operation, then a result if the conditional operation is true, and then a result if the conditional operation is false. A conditional operation can be a relational or logical operation.

Ternary operations are presented in the following format:

conditional_operation? result_if_true: result_if_false

Examples

The following examples are used to set the opacity of an image on the watch face.

  • [BATT_PER] <= 20? 15: 100

    This operation sets the opacity of an image on the watch face to 15 if battery percentage is less than or equal to 20%. Otherwise, it sets the opacity to 100.

  • ([BATT_PER] >= 50) * ([BATT_PER] <= 75)? 100: 0

    This example uses a logical operation for its conditional operation.

    This sets the opacity of an image on the watch face to 100 if the battery percentage is greater than or equal to 50% and less than or equal to 75%. Otherwise, it sets the opacity to 0.

Nested ternary operations

Ternary operations can be nested within the result operand of another ternary operation.

For example, if you have two ternary operations (a? b: c) and (x? y: z), you can create the following nested ternary operations:

  • conditional_operation? (a? b: c): result_if_false

    If conditional_operation is true, then check conditional operation a.

    If a is true, the result is b. If a is false, the result is c.

    If conditional_operation is false, the result is result_if_false.

  • conditional_operation? result_if_true: (x? y: z)

    If conditional_operation is true, the result is result_if_true.

    If conditional_operation is false, then check conditional operation x.

    If x is true, the result is y. If x is false, the result is z.

  • conditional_operation? (a? b: c): (x? y: z)

    If conditional_operation is true, then check conditional operation a.

    If a is true, the result is b. If a is false, the result is c.

    If conditional_operation is false, then check conditional operation x.

    If x is true, the result is y. If x is false, the result is z.