iOS 9 Swift Programming Cookbook (2015)

Chapter 2. Apple Watch

2.7 Setting up Apple Watch for Custom Complications

Problem

You want to create a barebone watch project with support for complications and you want to see a complication on the screen.

Solution

Follow these steps:

1. Add a watch target to your project using what you learned in. Make sure that it includes complications, upon setting it up.

2. In Xcode, in your targets, select your watch extension. Under the General tab, ensure that the Modular Small complication is the only complication that is enabled. Disable all the others (see Figure 2-29).

3. Write your complication code in your ComplicationController class. We’ll discuss this code soon.

4. Run your app on the watch simulator.

5. Once your app is opened in the simulator, press Cmd+Shift+H to go to the clock face (see Figure 2-3).

6. Press Cmd+Shift+2 to simulate Deep Press on the watch simulator and then tap and hold on the watch face (see Figure 2-30).

Figure 2-29. We are going to support only Small Modular complications

Figure 2-30. We can now customize our watch face

7. Press Cmd+Shift+1 to simulate Shallow Press and then scroll to the modular watchface (see Figure 2-31).

Figure 2-31. Select the modular watch face

8. Press the Customize button (see Figure 2-32).

Figure 2-32. Now you can customize your modular watch face

9. Scroll to the next page to the right, and then tap on the small modular complication at the bottom left of the screen until it becomes selected (see Figure 2-33). You will replace this with your own complication.

Figure 2-33. Select the small modular complication at the bottom left

10.Now use the up and down arrows on your keyboard (or if on the device, use the digital crown) to select your complication (see Figure 2-34). What you see on the screen is the preview template that you have provided to the system. We will implement this template soon, but in the figure I have already done that, hence the number 22

Figure 2-34. Your own small modular complication is shown

11.Press Cmd+Shift+2 to simulate Deep Press and then tap on the screen (see Figure 2-35).

Figure 2-35. We have now configured our complication on the selected watch face

12.Press Cmd+Shift+H to go to the clock app on the screen. Notice that your complication is gone and shows no data. That is because what we displayed on the screen while configuring our watch face was just a preview template. What the clock app displays is real data and we are not providing any of it.

Figure 2-36. Our complication is on the bottom left but is empty

Discussion

Complications are pieces of information that apps can display on a watch face. They are divided into a few main categories:

Modular small

A very small amount of space with minimal text and/or a very small image (see Figure 2-37; the date on the top left is a modular small complication).

Modular large

An image, title, and up to two lines of text (see Figure 2-37; the calendar event in the center of the screen is a modular large complication).

Utilitarian small

Mainly a small image with optional text (see Figure 2-37, the activity icon in bottom center is of this type).

Utilitarian large

A date/text mixed with an image, rendered on one line. This is similar to modular large but on just one line.

Circular small

A circular image with optional text (see Figure 2-37, the sunrise/sunset complication on the bottom right is an example of a circular-small complication).

Figure 2-37. Everything except the time is a complication

Assuming that you have already created a watch target with a complication attached to it, go into your ComplicationController class and find the getPlaceholderTemplateForComplication(_:withHandler:) method. This method gets called by iOS when your complication is being added to a watch face. This gives you the chance to provide a placeholder for what the user has to see while adjusting her watch face. It won’t usually be real data.

After this method is called, you need to create a complication template of type CLKComplicationTemplate (or one of its many subclasses) and return that into the replyHandler block that you are given. For now, implement the template like this:

func getPlaceholderTemplateForComplication(complication: CLKComplication,

withHandler handler: (CLKComplicationTemplate?) -> Void) {

let temp = CLKComplicationTemplateModularSmallSimpleText()

temp.textProvider = CLKSimpleTextProvider(text: "22")

handler(temp)

}

NOTE

I am not going to discuss the details of this code right now. You’ll learn them in other recipes in this chapter.

One more thing that you have to know is that once you have provided watchOS with your placeholder template, you won’t be asked to do it again unless the user uninstalls your watchOS app and installs it again from her iPhone (see Figure 2-38).

Figure 2-38. If the user uninstalls and reinstalls your app, it can provide a new placeholder template

If you are working on the getPlaceholderTemplateForComplication(_:withHandler:) method and want to test out different templates, you can simply reset the watch simulator and then run your app again. This will retrigger thegetPlaceholderTemplateForComplication(_:withHandler:) method on your complication controller.

See Also