Developing Complications for Apple Watch Series 4

The ClockKit framework allows you to display your app’s data on the watch face. These areas are called complications. Complications are a great way to connect people to their favorite apps with every wrist raise and keep them informed throughout their day. Complications can also be tapped for quick access into the app. With Apple Watch Series 4, we’re adding new complication capabilities to ClockKit, which allow you to create engaging, full-color complications for the new Infograph and Infograph Modular watch faces. On the Infograph watch face, these new complications can extend into the corners of the incredible new display. On the Infograph Modular watch face, you can now present even more of your app’s information in full-color, right in the middle of the watch face. Complications are divided into families. These determine how information is presented onscreen. On Apple Watch Series 4, we’ve added four new families: Graphic Corner, Graphic Circular, Graphic Bezel, and Graphic Rectangular. Each complication family uses system-defined templates to determine how the information is laid out, like the Graphic Circular family seen here. There are many templates for you to choose from to display your data. The complication family templates each consist of different combinations of data provider classes from the ClockKit framework, from text to images to the all-new gauges. For the Infograph and Infograph Modular watch faces, we’ve added a new full-color image provider and a new gauge provider. Let’s learn about these. First is the all-new gauge provider. Gauge providers allow you to show progress completed or a value within a range to the user in different ways, depending on the complication template family you are using. You can also use a time interval gauge to automatically animate the values as they change, as you see here with the timer complication. With gauge providers, you can provide a single color or you can provide a gradient, specifying the gradient colors along the gauge. You can also specify whether the color or gradient will fill the gauge as the data progresses or if it’s a range and uses a ring to indicate the value. Next, we have image providers. Image providers allow you to display a tintable image or a one-color image for use on existing watch faces, and now on the Infograph and Infograph Modular watch faces, full color images. Finally, we have text providers, which allow you to use text throughout the various templates. They can be used to display text, dates, time, time ranges, and even automatic countdowns or count-ups between two dates or times. In a handful of complication family templates, you can also now use multiple text providers together, each with their own tint color, to make one multi-purpose string. This can be really useful if your app has specific branding for different pieces of data. Now that you’re familiar with the gauge, image, and text providers, let’s look at the new graphic complication family templates available on the Infograph and Infograph Modular watch faces and learn how to combine providers to display your data in different ways. The first new complication family template is the Graphic Corner. This is available for use on the Infograph watch face. This template curves along the corner of the display to allow for more content like never before. The Graphic Corner templates have a handful of different combinations of providers to use. You can use a gauge provider with text, a gauge provider with an image, a set of text providers, a text provider with an image. And finally, you can use a full-color image by itself. Now, for consistency with other corner complications, it’s recommended that you use providers that will curve around the display. OK, let’s look at a code example of how to create a graphic corner complication that uses a gauge provider with text. Let’s make something similar to the Weather app.

First, we’ll need to work with our designer to get some values for the text tint colors. In this example, we have text showing our high, low, and current temperatures. We will also need an array of values for which colors will make up the gradient. Here, we’re going to use three colors. One for the low, one for the middle of the range, and one for the high. watchOS will take care of the gradient between colors, so the only additional information we need to provide is an array of values to express where each color should be located along the gauge. Now that we have all of our values, we need to create our graphic corner complication template. We’re going to create a corner complication with a gauge provider and text provider, so we create an instance of the GraphicCornerGaugeText template. Once we’ve created our template instance, we need to create the providers for it, starting with the gauge provider. Here we’re using CLKSimpleGaugeProvider. The style can be a ring, which displays a ring around the value in the gauge, or a fill, if you’re wanting to fill the progress within the gauge. Here we’ll use the ring style. Next, we set our gauge colors to the gradient colors we created earlier, as well as the gauge color locations, which will define where the colors are along our gauge. Finally, we need to set the fill fraction. This sets the current value for the gauge and should be dynamic, depending on your data. Next, we set the gauge provider property of the corner template and set the various text providers for the template, which we created earlier in code with tint colors for each. All that’s left is to pass in the completed template to create a timeline entry. This looks great. You can see our gradient between colors is handled by the system, and our ring-style gauge provider centers in the ring on our current value. Next, let’s look at the graphic circular complication family templates available on both the Infograph and Infograph Modular watch faces. The Graphic Circular templates provide the ability to combine gauge providers with text providers to show an open gauge with values at the end of a range. You can also create a template with text below the center text value with an open gauge, as well as use a full-color image provider below the center text with an open gauge. Using a closed gauge, you can provide a full-color image inside of the gauge or text. And finally, you can use a full-color image to represent the entire area of the complication. In our previous example, we created a graphic corner complication representing weather data. Now, let’s take that same data and create a graphic circular complication using an open gauge with text. The text providers, gradient colors, and gradient color locations we're going to use are the same as we used in the graphic corner complication. The main difference is that we need to instantiate the graphic circular open gauge range text template. We will create the gauge provider as we did last time. One additional change is that we will set the center text provider property for the template, where on the graphic circular template, this was an outer text provider. And that’s all. Now we have our graphic circular complication. But there’s more that we can do with a graphic circular complication. On the Infograph watch face, there is another family called Graphic Bezel. This utilizes a graphic circular complication and adds a text provider to it to wrap the text within the time bezel. First, we start by creating a graphic circular template. In this example, we’ll use the one we just created in our last example. Once the graphic circular template is configured, we create an instance of the GraphicBezelCircularText template. This takes a configured graphic circular template and a text provider for the bezel text. Here, we’re just hardcoding some values for the example. Finally, you need to pass in the configured bezel template for the complication timeline entry. Here’s our completed Graphic Bezel complication. The text will automatically curve along the bezel and display as uppercase. The bezel text can fill nearly 180 degrees of the bezel before it is truncated. The final addition to our complication families is the Graphic Rectangular, which is available on the Infograph Modular watch face. This family has templates allowing you to create a full-color image that fills the middle of the watch face. This template also includes a text provider. This image should be highly visual and not rely on text to convey the information shown. The graphic rectangular templates also allow for a more traditional configuration, utilizing multiple text providers. Additionally, an image can be used beside the header text and you can also use a template that displays a gauge provider instead of a third line of text. This is great to communicate progress. Let’s create a graphic rectangular complication that provides a header text and a big full-color image below it. First, we need to instantiate our graphic rectangular large image template. The next step is to create a text provider with our header text. Again, this can be a text provider that is made up of multiple text providers. Finally, we create a full-color image provider with an image of our data. Some key points to keep in mind as you create complications for the new Infograph and Infograph Modular watch faces are that the update opportunities remain the same. You have 50 guaranteed complication push updates every 24 hours, as well as the possibility of an update each hour if your app is taking advantage of background app refresh or is in the most recently used apps on the person’s Apple Watch. As you take advantage of the graphic circular and graphic rectangular families, be aware that there are potential CPU and update time thresholds while you get your data, process it, and render images, so do this work quickly. For full-color image providers, use the accessibility label property to provide meaningful information to people using VoiceOver. This is especially important for graphic circular templates using only an image, as there will be no accompanying text, as well as for the graphic rectangular large image template, which allows for a lot of data to be represented. For more information on creating the new graphic complications using the ClockKit framework, please visit the Apple developer documentation at developer.apple.com. The watchOS Sketch and Photoshop resources in the Human Interface Guidelines have also been updated for Apple Watch Series 4 and watchOS 5. In addition, the size specifications for each of the templates in the Graphic complication families are shown here and can also be found in the Human Interface Guidelines at developer.apple.com.