Article summary
The default Apple Watch applications offer some truly beautiful and useful complications. In my previous two posts, I explained how to plan your Apple Watch complications and the basics of the ClockKit complication API. These posts should get you to a point where you can present data on the watch face in a basic way.
Today, I’ll help you take the next steps and use more interesting features and techniques to create beautiful and useful complications for your app.
Gauge Providers
One provider type that I think makes for a particularly nice and clean UI is the gauge. It doesn’t make sense for every data source, of course, but when used properly, it looks great and provides a lot of information at a glance.
Gauge providers come in two types: simple and time interval.
Simple
If your data represents discrete values that will only update with new timeline entries, then the simple gauge provider is probably what you want. Its constructor accepts a few parameters:
- The style parameter must be a CLKGaugeProviderStyle, which can be either
.fillor.ring. The fill style acts as you might expect by filling up the fraction of the gauge as specified by the fillFraction parameter. The ring style presents a full gauge and positions a ring-like indicator at the position of the fillFraction parameter. - gaugeColor specifies the color of the gauge as it fills up.
Time Interval
Time interval gauge providers are slightly harder to understand but offer a bit more customizability. These providers are best for representing time-dependent or continuous data sources.
- The style parameter acts the same as in a simple gauge. The difference is how the gauge fills.
- The start and end parameters specify a time interval that the gauge will represent the passage of.
- You can use the constructor that includes startFillFraction and endFillFraction to specify whether the gauge empties or fills with the passage of time and how much of the gauge will be affected.
- You have the ability to fill the gauge with a gradient of colors as specified by the gaugeColors and gaugeColorLocations parameters.
I found the time interval behavior to be a little unintuitive. If you start by playing with some simple examples (like counting down for an hour) and then adapt that to your desired behavior, you will have a better experience.
Text Provider Composition
Text providers are another great way to take your complications to the next level. This capability is largely overlooked by the ClockKit documentation, and it’s hidden in the abstractions of the CLKTextProvider constructor.
If you’ve experimented with CLKTextProvider previously, you may have noticed that you can construct one with a formatting string in the format parameter, and then subsequent arguments will be applied to the format specifiers. The obvious use-case is to pass variables in these trailing arguments, but I’ve discovered that you can also use other text providers. This allows you to build interesting UIs. For example, you can have different font colors within one text slot of your complication; accomplish this by setting the tintColor property of your text providers.
Watch out! Your embedded text providers need to be matched with a %@ format specifier rather than a %s. Using the wrong format specifier causes an opaque crash report; it took me far too long to debug this.
Final Thoughts
I hope the ClockKit API will be improved in subsequent versions. I found the initial learning curve for complications to be quite steep. Nevertheless, once you see an example that establishes some patterns to follow, they become more tenable.
Manually testing complications can be a slow, time-consuming process, but I found skipping steps to be counter-productive. Start simple and build from there; it will help you to establish good testing iterations and build an understanding of the lifecycle before diving into something more complicated.
I hope that this series has provided some good examples and thoughts to get you started building your own complications.