AILW: Beta 4 Documentation Changes

watchOS series

Today Apple rolled out Beta 4 of WatchKit. While you can easily get the diffs between beta 3 and 4 at the code level, you can’t easily see what has changed in the developer documentation. This was frustrating me for past betas so I went ahead and worked out a way to do it.

I’ve setup a script to go out to download and normalize the WatchKit Programming Guide and Apple Watch Human Interface Guidelines. Nothing fancy but it means that when a new Beta has been released I can easily diff between the old and new to look for relevant, interesting changes.

As you’d expect there are a bunch of little changes—Typos, rewordings, etc. I’m not interested in those for the purpose of this. Just material changes that will affect how I build apps.

They are shown below. Text in green (with an alternate background) is new. Struck through text was removed.

WatchKit Programming Guide

When used in your WatchKit extension, an NSLocale object returns the locale information configured on the user’s Apple Watch. Use that class to get the user’s preferred languages and other language and locale-related information.

To format text using a custom font, create an attributed string using the font information and use that string to set the text of your label, as shown in Listing 8-1. The font name and size are encoded with the attributed string, which is then used to update the label on the user’s Apple Watch. If the font name you specify is not the system font or one of your custom installed fonts, WatchKit uses the system font.

Specifying images by name is preferred because the only the name string is transferred to Apple Watch, which takes less time and uses less power than sending the entire image. WatchKit searches your WatchKit app bundle for an image file with the name you specified. If it does not find an image file in the bundle, it then searches the device-side image caches for an image with the given name.

The Apple Watch image caches are limited in size, with each app receiving approximately 20 MB of cache space. Caches are persistent and can be used between launches of the WatchKit app. When you reach the maximum cache size, WatchKit throws away older images to make room for newer ones. When your app’s caches fill up, you must remove existing images from the cache before attempting to add new ones. Use the removeCachedImageWithName: method to remove a single image or use the removeAllCachedImages method to clear the caches completely.

When configuring tables, you can improve performance by limiting the number of rows you create initially. Because table rows must all be created up front, creating large numbers of rows can adversely affect the performance of your app. The precise number of rows depends on the complexity of your data and how long it takes you to create each one, but consider keeping the total number of rows to 20 or fewer. For tables that require more rows, consider loading only a subset of rows initially and providing the user with controls to load more rows. An even better solution is to display only the most important subset of rows. For example, you might use location data to limit the number of rows to those that are most relevant to the user’s current location.

Apple Watch displays local and remote notifications only if the containing iOS supports them. For information about how to support local and remote notifications in your iOS app, see Local and Remote Notification Programming Guide.

Apple Watch Human Interface Changes

Home screen icons are circular and Table 20-1 lists the appropriate diameter (in pixels) and the usage for each icon. Create your icons as full-bleed square images using the given dimensions. The system applies the circular mask automatically. (Note that Xcode lists icon sizes in points.)

David Smith