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.

Figure 1. Tag scripting dialog

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

Table 1. Date and time tags

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

Table 2. Setting information tag

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

Table 3. Device information tags

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

Table 4. Sensor data tags

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

Table 5. Health data tags

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

Table 6. Moon phase tags

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

Table 7. Weather tags

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

forecastHour(index, String)

Forecast for the next few hours. Index starts from 1.

Number / String

forecastHour(1, "COND")

forecastHour(1, "COND_NAME")

Forecast conditions 1 hour from now.

8

SUNNY

forecastDay(index, String)

Forecast for the next few days. Index starts from 1.

Number / String

forecastDay(2, "COND_DAY")

forecastDay(2, "COND_DAY_NAME")

Forecast conditions 2 days from now.

8

SUNNY

Table 8. Weather forecast functions

Second parameter of forecastHour function has the following definitions:

  • IS_AVAIL
  • COND
  • COND_NAME
  • IS_DAY
  • TEM

Second parameter of forecastDay 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

Table 9. Mathematical functions

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

Table 10. Arithmetic operators

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

Table 11. Relational operators

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

Table 12. Logical operation results

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.

Table 13. Examples of whether an operation is logical or arithmetic

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.