en ko

Tag expressions

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 that represent 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 an 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, select Tags. In the scripting dialog, you can create longer tag expressions and search for the tags you want.

The available tags, their descriptions, and their value ranges are shown in the following tables.

Date and time

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

Setting information

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

Device information

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

Sensor data

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

Health data

Tag	Definition	Type	Range	Example
HR	Heart rate	Number	0 -	60
HR_Z	Heart rate with leading zero	String		00 80 120
SC	Step count	Number	0 -	1000
SC_GOAL	Step count goal	Number	1 - 20000	20000
SC_PER	Step count as percentage of step count goal	Number	0 - 100

Moon phase

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

The [MOON_PO] tag has the following range definitions:

• 0-0.5: New moon
• 0.5-6.5: Evening crescentnt
• 7: First quarterer
• 7.5-13.5: Waxing gibbousus
• 14: Full moonon
• 14.5-20.5: Waning gibbousus
• 21: Last quarterer
• 21.5-27.5: Morning crescentnt
• 27.5-28: New moon

The [MOON_TY] and [MOON_TY_NAME] tags have the following range definitions:

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

Weather

Tag	Definition	Type	Range	Example
WTHR_IS_AVAIL	Returns if there is any data that can be rendered.	Number	0 (No), 1 (Yes)	1
WTHR_COND	Weather Condition	Number	0 - 15 (See below)	8
WTHR_COND_NAME	Weather Condition Name	String		SUNNY
WTHR_IS_DAY	Returns if the current condition applies during daylight.	Number	0 (Night time), 1 (Day time)	0
WTHR_TEM	Current temperature	Number		25
WTHR_TEM_UNIT	Temperature unit	Number	1 / 2 (See below)	1
WTHR_DAY_TEM_LOW	Lowest temperature for the day	Number		18
WTHR_DAY_TEM_HIGH	Highest temperature for the day	Number		30
WTHR_CHANCE_PPTN	Current chance of precipitation	Number	0 - 100	0
WTHR_UV_INDEX	Current UV index	Number		3
WTHR_LAST_UPDATED	Last time the weather was updated from the provider	Number

The [WTHR_COND] tag has the following range definitions:

• 0: UNKNOWN_VALUE
• 1: CLEAR
• 2: CLOUDY
• 3: FOG
• 4: HEAVY_RAIN
• 5: HEAVY_SNOW
• 6: RAIN
• 7: SNOW
• 8: SUNNY
• 9: THUNDERSTORM
• 10: SLEET
• 11: LIGHT_SNOW
• 12: LIGHT_RAIN
• 13: MIST
• 14: PARTLY_CLOUDY
• 15: WINDY

The [WTHR_TEM_UNIT] tag has the following range definitions:

• 1: CELSIUS
• 2: FAHRENHEIT

Weather forecast functions

Function	Definition	Return Type	Expression example	Example
forecastHours(index, String)	Forecast for the next few hours. Index starts from 1.	Number / String	forecastHours(1, "COND") forecastHours(1, "COND_NAME") Forecast conditions 1 hour from now.	8 SUNNY
forecastDays(index, String)	Forecast for the next few days. Index starts from 1.	Number / String	forecastDays(2, "COND_DAY") forecastDays(2, "COND_DAY_NAME") Forecast conditions 2 days from now.	8 SUNNY

Second parameter of forecastHours function has the following definitions:

• IS_AVAIL
• COND
• COND_NAME
• IS_DAY
• TEM

Second parameter of forecastDays function has the following definitions:

• IS_AVAIL
• COND_DAY
• COND_DAY_NAME
• COND_NIGHT
• COND_NIGHT_NAME
• TEM_HIGH
• TEM_LOW
• CHANCE_PPTN
• CHANCE_PPTN_NIGHT

Functions

Function	Definition	Return Type	Expression example	Output example
round(num)	Returns the closest integer to num.	Number	round(1.6)	2
floor(num)	Returns the greatest integer less than or equal to num.	Number	floor(1.6)	1
ceil(num)	Returns the smallest integer that is greater than or equal to num.	Number	ceil(1.2)	2
sin(num)	Returns the sine of num.	Number	sin(1)	0.84147096
cos(num)	Returns the cosine of num.	Number	cos(1)	0.5403023
tan(num)	Returns the tangent of num.	Number	tan(1)	1.5574077
abs(num)	Returns the distance from zero.	Number	abs(-10)	10
clamp(num, min, max)	Returns the value of clamping num between max and min.	Number	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.	Number	(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.	Number	asin(0.841)	1
acos(num)	Returns the arccosine function of num.	Number	acos(0.54)	1
atan(num)	Returns the arctangent function of num.	Number	atan(1.557)	1
deg(num)	Converts num from radians to degrees.	Number	deg(3.142)	180
rad(num)	Converts num from degrees to radians.	Number	rad(180)	3.141
pow(base, exponent)	Returns the result of a base raised to an exponent.	Number	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 2 values, which are also called 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 2 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 1. A comparison that is false returns a value of 0.

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 examples 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 2 or more relational operations and return a value of 1 (true) or 0 (false). Tag expressions support the 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 operands—the values on either side of the operator—are relational operations. An arithmetic operator is applied if either of the 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 consists of 2 relational operations on either side of the operator (0<=1 and 1<2), so 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 consists of a relational operation (0<=1) and a number value (120), so 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 consists of 2 number values (1 and 120), so the arithmetic operator is applied. The result is 1 multiplied by 120, which returns a final result of 120.

Ternary operators

Ternary operations have 3 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 2 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.