menuPujie BlackPujie Black logo

Automation

For some watch parts it is possible to automate your layers based on data properties. For instance, when designing a custom complication, you can change the visibility of a layer based on the availability of a complication data type. Live texts can also be automated

Automation is seperated into layer automation and property automation. Layer automation works directly on the layers like positioning, scale, translation (moving), rotation and visibility. Property automation applies to specific properties of a layer, like the fill opacity, stroke opacity, stroke width (and more..) and arc angles.

Content
Automation Interface

Throughout the whole interface, automation is indicated using the automation icon.

Automation
APP BAR

When your watch part supports automation, the app bar is slightly different from the regular app bar. The play icon is removed, and the watch face preview is not available. Those buttons are replaced by other options as discussed below,

Pause automation
Use this button to temporarily pause all automation. This will allow you the adjust parameters which are unavailable when automation is applied
Resume automation
Resume automation when it has been paused
Complication data provider
When you are designing a custom complication, this button will allow you to switch between one of the built in complication data providers.
AUTOMATION INDICATOR

If a layer has any form of automation, this is indicated with the automation icon in front of the layer name, as demonstrated in the image below.

1
Automation indicator
Whenever a layer has any form of automation, this indicator is shown. Note that if there is an error in the script, the icon will show in red, and it will show a warning triangle.
Layer transformation automation

To automate the position, size, rotation and visibility of a layer, select the layer in the layer list and tap the automation icon on the header bar. This will show the following popup menu.

If one of the layer automation types is assigned, the button will show a darker background. Furthermore, the layer in the layer-list will show the automation icon, indicating that this layer uses automation.

Tapping one of the automation buttons will open the automation expression editor dialog, used to write your automation code. It is explained in the automation expression editor section.

Layer style automation

To automate the layer style of a layer, tap the layer style button (see button 5 in the layer list). Then look for a property which has the automation icon next to it. Tapping this automation icon will bring you to the automation expression editor.

The image below shows that you can automate the Stroke Size and the Opacity of the Stroke by tapping on the automation icon.

Whenever a property is automated, it's value is replaced with the text Automated. In that case the value stepper can not be used.

The following properties of the layer style can be automated

Stroke Opacity
Stroke Size
Fill Opacity
Shadow Opacity
Shadow Size
Shadow X Offset
Shadow Y Offset
Arc style automation

To automate the arc style of an arc layer, tap the arc style button (see button 1 in the arc layers section). Then look for a property which has the automation icon next to it. Tapping this automation icon will bring you to the automation expression editor.

The following properties of the arc style can be automated

Start Angle
Sweep Angle
Part Angle
Gap Angle
Text style automation

To automate the text style of a text layer, tap the text style button (see button 1 in the text layers section). Then look for a property which has the automation icon next to it. Tapping this automation icon will bring you to the automation expression editor.

The following properties of the text style can be automated

Text
Automation expression editor

The automation expression editor is used to define the automation. This is done using a combination of JavaScript and predefined variables.

The syntax used in the automation expression editor is called JavaScript. JavaScript is a well known and extensively used programming language. It is mainly used in web enviroments, but is extremely suitable in this case, because it is relatively easy to learn, and there is a lot of documentation available online. Below you can find some good resources for learning Javascript

A very extensive javascript manual. Note that we are using this in the context of Watch Face automation, and therefore simple expressions will often be sufficient
The Math object, containing functions like sine, cosine, tangent, square root etc. And constants for PI. Which could all be of interest to watch face automation

The image below shows the automation expression editor. In this case it was started to Automate rotation, as indicated in the title of the dialog.

SIMPLE AUTOMATION

In the image above, the expression is set to the following

[cnormval] * 360.

This will be the rotation angle for the selected layer. The normalized complication value (cnormval) is multiplied with 360 (for 360 degrees of a full circle).

COMPLEX AUTOMATION

When your automation expression is relatively simple and can be expressed in a single line, your expression can be stated as described above. If your expression uses more than one line of text you have to add the keyword return to the final value you want your expression to return.

In a complex automation expression you can define functions, use variables, use if statements, use the built-in JavaScript functions and more.

For example, you could write the following:

function convertToDegrees(inputValue) {
return inputValue * 360;
}

var value = [cnormval];

return convertToDegrees(value);

Note that the above complex example is exactly the same as the simple example above. It just uses a more complex syntax, indicating what is possible with the automation expression editor.

Because the we are using JavaScript we have access to a lot of built-in functions, especially of interest is the Math Object. For instance, this will allows you to write

var value = [cnormval];

return Math.sin(value);
RETURN TYPE

Depending on the property you would like to automate, the expression editor expects a certain return type. For instance if you are automating the visibility, the expression editor expects a boolean value ( true or false ) as the return type of the expression. But if you are automating the scale of a layer, the expression editor expects a numerical value.

If your expression returns the wrong type, it will be indicated in red in the editor.

Advanced automation data

Some automation data fields are represented as objects, or arrays of objects. These are described below:

Full in progress event & upcoming full event
tags : [cur_evnt_full] & [com_evnt_full]

An object containing the full event data:

{ 
  "title":"Going to the city",
  "begin":{ 
	 "day":12,
	 "month":9,
	 "year":2019,
	 "hour24":14,
	 "hour12":2,
	 "minutes":0,
	 "ampm":"pm",
	 // offset in minutes from now, 
	 // can be negative when the begin
	 // is in the past
	 "offset": 62 
  },
  "end":{ 
	 "day":12,
	 "month":9,
	 "year":2019,
	 "hour24":15,
	 "hour12":3,
	 "minutes":0,
	 "ampm":"pm",
	 // offset in minutes from now,
	 // can be negative when the end
	 // is in the past
	 "offset": 122
  },
  "color":"#ff7537",
  "allday":false,
  // duration in milliseconds
  "duration":3600000,
  "location":"Kalverstraat, 1012 Amsterdam, Netherlands",
  // human readable begin and end time, 
  // takes users clock settings 
  // into account
  "time":"02:00 PM - 03:00 PM",
  "day":"today",
  // progress is a value 
  // between 0 and 1, where 1 means 
  // finished and 0 means not yet started
  "progress":0.2245
}


	
Usage Example:
	
var event = [cur_evnt_full];	

if(event) {
   return "Current event: " + event.title;
}	

return "No current event";
	
Calendar Events
tag : [cal_events]

An array of Calendar Event objects (see FULL IN PROGRESS EVENT & UPCOMING FULL EVENT)

[ event1, event2, ... , eventN ]
	
Usage Example:
	
var events = [cal_events];	

if(events.length > 0) {
   return events[0].title;
}	

return "No events";
	
Global variables & functions

Custom elements can have global variables and global functions. These are variables and functions which can be accessed from all the layers in a custom element. This makes it a lot less tedious to automate the same behavior within multiple layers. Plus if done correctly, you only have to make changes in the global variables to update all layers.

1
Global variables & functions
Use this button to open the global variables and functions editor.

In the global variables editor you can freely add variables and functions to the global object. This is demonstrated in the image below.

Now these global variables and functions can be used in your automation scripts. Below you can see it being used in the text automation of a text layer.

In the same manner, you can use global functions for automation too. See below an example where the calcRotation function is used to automate the rotation of a layer.

Global variables become especially useful with more complex Custom Elements. If you have multiple layers doing complex automations, re-use and centralization can make it a lot easier.

The video below gives a hands on demo of how to use global variables and functions.