Tag expression
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 note health data is not shown when the device is locked 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 note watch faces should always check the [wthr_is_avail] value before accessing other weather tags 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 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 table 8 weather forecast functions 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 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 note the asterisk represents both the multiplication arithmetic operator and the and logical operator 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 note the plus sign represents both the addition arithmetic operator and the or logical operator 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