8
Introduction to Complications
Written by Scott Grosch
Heads up... You're reading this book for free, with parts of this chapter shown beyond this point as text.
You can unlock the rest of this book, and our entire catalogue of books and videos, with a raywenderlich.com Professional subscription.
When you design an iOS app, it’s normal to expect users will engage with your app for some time. On the other hand, when designing a watchOS app, you’ll likely find users engage with the app for mere seconds. Therefore, you should always strive to add complications to your app.
Wait, what? Not that kind of complication — a watch complication. According to Wikipedia:
A complication is any feature of a mechanical timepiece beyond the display of hours, minutes and seconds.
By that definition, the Apple Watch is full of complications! :]
On the Apple Watch, complications have been slightly redefined as elements on the watch face that display small, immediately relevant bits of information. They are by far one of the most compelling and useful features of the Apple Watch. They lie right on the watch face, making accessing information as fast as raising your wrist.
This chapter will speak to a high-level overview of what complications are and why you should use them. The following chapters will dive into the technical details of actually implementing them.
Unless there’s a compelling reason not to include one, every watchOS app should include at least one complication.
Why complications?
As previously mentioned, interacting with a watchOS app is generally on the order of a second or two, if even that long. For example, when using a mapping app, you probably just want to know how far away your next turn is and which direction you’ll be heading.
Even if you don’t feel that your app contains any data which would make sense to display on the watch face, providing a complication gives your user a way to launch your app with a simple touch of the screen. On top of that, watchOS provides several benefits when your user includes your complication on their watch face:
- watchOS keeps your app in memory and gives it extra update time, making app launches almost instantaneous.
- You complication can receive up to 50 pushes per day containing updated information.
- Your app can perform additional background refresh tasks.
- Your complication can be featured in the Apple Watch Face Gallery on the phone.
Imagine the types of questions you can instantly answer by having a complication available on the watch face:
- What’s the score?
- How hot is it outside?
- Is the air safe to breathe?
- What is your name?
- What is your quest?
- What is the average airspeed velocity of an unladen swallow?
Note: If you’re confused by the last three questions, they’re from a famous scene in the 1975 movie Monty Python and the Holy Grail. The internet seems to think a swallow would average around 20 miles per hour or about 9 meters per second.
Recent versions of iOS provide a similar concept via Widgets. However, unlike the Apple Watch, to see the data on a widget, you’ll need to pull the phone out of your pocket or purse, unlock the screen, possibly swipe to another screen and then see your data. Complications are quicker.
The following chapters will dive into the technical details of using the ClockKit framework to implement complications and show how to keep them up-to-date with current information.
In other words, by providing complications, you’ll uncomplicate your app. :]
Complication families
If you’ve spent any time looking at the Apple Watch’s available watch faces, you’ve seen that there are quite a few. Each new release of watchOS tends to include more faces than the previous version.
Complication identifiers
Most watch faces include the ability to specify multiple complications. While most apps only provide a single complication, ideally supporting all families, you can support more than one. If you’ve created a weather app, you might provide one complication which shows the temperature and a separate complication that displays the current air quality index.
Complication templates
Within each family, Apple provides multiple templates which describe the layout of the complication. Most of the templates consist of simple text and images, though some provide partial SwiftUI View support.
Circular small
The Circular Small template provides a small circle in the corners of the Color watch face that can display a few characters of text, an image or a circular progress ring. It includes the following templates:
Image templates
Text templates
Extra-large
The extra-large templates are similar to the Circular Small templates but larger and with a 2x2 grid template. They’re designed for the X-Large watch face.
Image templates
Text templates
Modular small
When using the Modular watch face, you can provide content to the smaller spaces via these templates.
Image templates
Text templates
Modular large
The modular large templates target the large canvas on the Modular watch face, providing up to three lines of content.
Body templates
Table templates
Utilitarian
The utilitarian templates provide multiple ways to display content on numerous watch faces, including Utility, Chronograph, Simple and the character watch faces.
Utilitarian small
Utilitarian large
-
CLKComplicationTemplateUtilitarianLargeFlat: Displays an image followed by a long text string on a single line.
Graphic
The graphic templates display visually rich content on several different watch faces, including the Infograph, Infograph Modular and Solari Dial faces.
Tinted complications
While you can include full-color images in many complication templates, you need to be careful not to make your complication depend on those colors being visible.
Key points
- Always provide a complication, even if just to provide a quick way to launch your app.
- Support every complication family, not just one or two.
- Consider the different pieces of data someone might want to regularly see on the watch face and create a complication for each one.
Where to go from here?
- Apple’s documentation on ClockKit shows images of exactly where each type of complication displays on the watch face, as well as examples of each template type.
Have a technical question? Want to report a bug? You can ask questions and report bugs to the book authors in our official book forum here.
© 2022 Razeware LLC
