Using WatchKit apps

Text and Labels

When you want to show text to to the user, you most often use a label. Labels in WatchKit are instances of the WKInterfaceLabel class.

Labels in WatchKit can display either plain text or attributed text. Attributed text is text that contains style information throughout the text, like making certain characters bold.

To update the text shown in a WKInterfaceLabel, you use the setText method:

  label.setText("Hi Hello Hi")

To show attributed text using an NSAttributedString, use the setAttributedText method. You can also set the color of a label using setTextColor.

Images

To display images on your watch, you use the WKInterfaceImage class. This object displays both static and animated images.

There are several methods you can use to display an image on a WKInterfaceImage:

• setImage takes a UIImage object and displays it.

• setImageData takes an NSData object that contains an image. It loads the image into a UIImage and displays it.

• setImageNamed makes the watch look for an image with the specified name, and displays it. If it can’t be found, the image view shows no image.

You can always clear the image from an image view by calling setImage and passing nil.

WKInterfaceImage supports the same image formats as iOS. However, it’s better if you use PNG and JPEG images, as these don’t need to be converted by iOS before being sent to the watch.

If you send an image that’s too big for the control, it’s scaled down so that it fits in the control (preserving the image’s aspect ratio).

Finally, images can be given a tint color using setTintColor. This allows you to save space by providing a single grayscale image, which is then filled with a color. Because this tinting is done on the watch, you can update the color of a WKInterfaceImage at any time, and without having to transfer an entirely new UIImage to the watch.

Animations

In addition to showing single images, you can also use a WKInterfaceImage to display animations. You can either configure a WKInterfaceImage to show an animated image using the Interface Builder, or you can do it with code.

To create an animated image, you first need to have all of the frames of your image ready, and add them to your application. You do this in the same way you add static images: by dragging and dropping them into an asset bundle. The key difference between static and animated images is that the frames attached to each animated image must all have the same name, suffixed with an increasing number.

For example, if you want an animation named “Animation,” you’d add an image called “Animation0,” a second called “Animation1,” and so on (see Figure 1-5). You can have up to 1024 frames in an animation.

To set up an animated image in the Interface Builder, you set the name of the image to “Animation” (or whatever the name of your animation is)—without the frame number suffix. Next, change Animate from “No” to “Yes,” and specify how long the animation should run in seconds (see Figure 1-6: in this case, each loop of the animation will take one second). The Interface Builder won’t recognize the image, so you won’t see a preview in the window, but when you run the app, it’ll work fine.

Alternatively, you can set up an animation in code. The way that you interact with the WKInterfaceImage actually remains the same: you simply provide it with a UIImage object by calling the setImage or setImageNamed methods.

The difference is in how the UIImage object is set up. To create an animated UIImage, you use the animatedImageNamed method, and provide the name and duration of your animation:

  let animatedImage =
      UIImage.animatedImageNamed("Animation",
                                 duration: 1.0)

  self.imageView.setImage(animatedImage)

Menus

A menu is a place where you can put additional actions that the user can perform. These actions aren’t visible until the user pushes on the screen with a little extra force (a force touch). When the user does this, and the interface controller that’s currently active has a menu, menu items appear. You can see an example of a menu in Figure 1-7.

Menus are used all over the Apple Watch to provide access to extra actions that aren’t critical to the main functionality of whatever you’re using. For example, when you force-touch the notifications list, a menu appears that contains a single menu item, which lets you dismiss all notifications at once.

Menus are attached to interface controllers. To add a menu, you drag and drop the Menu item from the Object Library onto an interface controller.

Unlike the other controls, you don’t work with code to configure menus. In fact, you don’t really configure menus at all—you can’t customize their appearance in code, and you can’t change any properties at runtime. The only thing you can do is add them to your interface, and connect the buttons to methods in your interface controller’s code.

Each menu contains between one and four menu items. Menu items themselves contain an image and a label. You can select from a list of different built-in images, or you can add a custom image to your app’s asset catalog.

You connect the button to the interface controller by following the same steps outlined for a WKInterfaceButton: control-drag from the item in the outline pane into your WKInterfaceController class and create an action; this action is called when the button is tapped.

To test menus in the iOS simulator, you need to indicate that you want to simulate a force touch. To do this, follow these steps:

1. Open the Hardware menu, and choose Force Touch Pressure→Deep Press.

2. Click on the screen, and the watch will react as if you’d pressed hard on it.

3. Choose Hardware→Force Touch Pressure→Shallow Press to go back to regular presses.

Tables

A table is a list of content that the user can scroll through. Tables are represented by the WKInterfaceTable class.

Tables in WatchKit work a little differently to their equivalents in iOS. In iOS, table views call back to a controller object to ask questions about how many rows there are in the list, and, for each cell, what content should be displayed. This kind of interaction would generate way too much back-and-forth traffic for the Apple Watch, which means that WKInterfaceTables are optimized to support preparing the entire content of the list all at once.

The way that it works is as follows: at design time, you define a number of row types. For each type of row, you lay out the controls that go in the row. You also give the row type an identifier, which is a string, plus the name of a row controller class that will store outlets to the controls that go in the cell.

At runtime, you tell the WKInterfaceTable about the number of cells that are in the table, and what the row type is. Doing this creates instances of all of the row controller classes. You can then ask the table for a specific row controller, and use that object’s outlets to access the controls in a specific label.

For example, let’s say you want to add a table that displays a list of words. This will mean that each cell will need a label, and you’ll need a way of sending the correct word to each cell’s label.

To do this, follow these steps:

1. Drag a table from the Objects inspector into your interface.

2. In one of your source code files, create a class called MyRow. Make it a subclass of NSObject. (You can create a new file for this class, or you can add the class to an existing .swift file.)

3. By default, tables come with a single row controller already set up. Select the row controller in the outline—it has a yellow circular icon—and set its Identifier to MyRow in the Attributes Inspector. Then go to the Identity Inspector, and set its Class to MyRow.

4. Set up the row by dragging a label into the row’s interface. Then, open the MyRow class in the Assistant, hold down the control key, and drag from the label into the MyRow class. Create a new outlet for the label called label.

5. In your interface controller’s awakeWithContext method, add the following code:

     // An array of strings to show in the table
     let dataToDisplay = ["Hello", "World", "This", "Is", "A", "Table"]
   
     myTable.setNumberOfRows(dataToDisplay.count, withRowType: "MyRow")
   
     for i in 0 ..< dataToDisplay.count {
         let rowController = myTable.rowControllerAtIndex(i) as? MyRow
   
         rowController?.label.setText(dataToDisplay[i])
     }

6. Finally, run the application; you’ll see a scrollable list of words.

Picker Views

A picker view displays a collection of options that the user can select from, by either swiping the screen or rotating the Digital Crown. Picker views can display text and images in a variety of ways; they can display a rotating list of captions, a stack of images, or a sequence of images.

Picker views are configured by creating a collection of WKPickerItem objects, which you provide to a WKInterfacePicker object.

To add a picker item, you drag a Picker from the Object Library into your interface controller. To provide the picker with content, you connect it to an outlet in your interface controller’s class, and call setItems to give it the list of WKPickerItems it should show.

For example, let’s say self.picker is a variable that refers to a WKPickerView. In this case, you could make it show the strings “Item 0,” “Item 1,” and “Item 2” in it by doing this:

  var listContent : [WKPickerItem] = []

  for i in 0...2 {
      let item = WKPickerItem()
      item.title = "Item \(i)"
      listContent.append(item);
  }

  self.picker.setItems(listContent)

Picker items can contain images, text, or a combination of both. The specifics of what’s shown depend on the list’s style.

As the user interacts with the picker, the picker calls whichever method is connected in the interface builder, much like a button does when the user taps on it. This method receives an Int, representing the index of the currently selected item. The first item is given the index 0, the second item is given the index 1, and so on.

  @IBAction func pickerSelectedItem(value: Int) {
      print ("Picker selected item \(value)")
  }

Hierarchical Navigation

To set up a hierarchical navigation in your app, you create a “push” segue that links a button to another interface controller. When you tap on this object, the second interface controller will appear, and the user can go back by tapping on the back arrow.

If you want to try this out for yourself, follow these steps:

1. Add a button to your interface controller, and add a new interface controller that you want to show when the button is tapped.

2. Hold down the Control key, then click and drag from the button to the interface controller.

3. A list of segue types will appear; click Push. This will create the segue that links the button to the interface controller.

4. Run the app. When you tap the button, the interface controller will appear.

If you don’t want to use segues to connect screens, you can also create a hierarchical navigation structure in code. To do this, follow these steps:

1. Select the interface controller that you want to navigate to, and go to the Identity inspector.

2. Set the interface controller’s Identifier to something useful—for example, detailScreen.

3. In order to present this interface controller, call the pushControllerWithName(_, context:) method:

  self.pushControllerWithName("secondScreen", context: nil)

You can also return the user to the previous screen by calling popController, and return the user to the very beginning by calling popToRootController.

Page-Based Navigation

The alternative to hierarchy-based navigation in a watchOS app is page-based navigation. In page-based navigation, the watch shows a horizontally scrolling list of interface controllers, and you swipe left and right to access them. This is very similar in terms of design to how the home screen on an iPhone works.

To create a page-based navigation flow for your application, you need to include a “next page” segue between your interface controllers. You can do this by following these steps:

1. Hold down the Control key, and drag from the interface controller that you’d like to appear first in the list to another.

2. A menu containing possible segues will appear. Select “next page” in the menu that appears.

3. Run the app. When you swipe from right to left, the second interface controller will appear.

When the app starts up, the Apple Watch uses this chain of segues to build a horizontally scrolling collection, with the first view controller at the far left, and each interface controller connected via a “next page” segue on the right. Each screen can be scrolled vertically, based on the content that’s stored inside it, and if the user scrolls horizontally, he’s taken to the additional screens.

You can connect a chain of interface controllers like this, by linking the first screen to the second, the second to the third, and so on.

When using page-based navigation, you typically won’t often need to change the pages. If you do want to do this, then use the Identity Inspector to give each interface controller a name, and then call WKInterfaceController.reloadRootControllersWithNames(_,contexts:). This method takes an array of interface controller names and replaces the collection of pages with new interface controllers:

  WKInterfaceController.reloadRootControllersWithNames(["mainScreen",
      "additionalScreen"], contexts: nil)

Modal Presentation

The last way to let your users get access to other screens is via a modal presentation. When you use a modal presentation to show an interface controller, the interface controller takes over the entire screen.

You use a modal presentation when you need to interrupt the user’s experience. For example, if the user is in the middle of some task, like requesting an Uber, you could present a modal interface controller to let her know that her driver was nearby.

You can use either segues or code to present an interface controller modally. To use a segue, connect a button, group, or table row to an interface controller, and then create a “modal” segue. To modally present an interface controller using code, give the interface controller an identifier in the interface builder’s Identity inspector, and then call presentControllerWithName(_, context:):

  self.presentControllerWithName("detailScreen", context: nil)

If you simply need to present an alert (such as some text), you can also use the method presentAlertControllerWithTitle(_, message:, preferredStyle:, actions:). This method modally presents an interface controller containing a title and message, along with a number of buttons.

To show an alert, you first prepare the buttons you want it to have. You do this by creating an array of WKAlertAction objects, which each contain two things—the text that the button should display and a closure that should be run if the user taps the button:

  let actions = [
      WKAlertAction(title: "OK", style: WKAlertActionStyle.Default, handler: {
          print("OK button tapped")
      })
  ]

Once you have the list of actions you want to attach to the alert, you simply need to call presentAlertControllerWithTitle, and provide the title and optional message, as well as the list of actions and the layout that the alert should have:

  let alertTitle = "Error!"
  let alertMessage = "There was a problem!"

  self.presentAlertControllerWithTitle(alertTitle,
                                       message: alertMessage,
                                       preferredStyle: .Alert,
                                       actions: actions)

Sending and Receiving Messages

The most straightforward way to send data from the watch to the phone, or from the phone to the watch, is by sending messages. A message is a dictionary that contains simple data: strings, numbers, dates, NSData objects, or arrays or dictionaries containing these types.

To send a message, you first construct the dictionary that represents the message you want to deliver. The message can be anything you like. For example:

  let message = [
      "message":"hi"
  ]

Once you have your message, you send it, using the sendMessage method on your WCSession:

  WCSession.defaultSession().sendMessage(message,
                                         replyHandler: nil,
                                         errorHandler: { (error) in

          print("Got an error sending to the phone: \(error)")
  })

The sendMessage method takes three parameters: the message itself, a reply handler closure (more on that in a moment!), and a closure that’s called if there was an error sending the message to the other device.

When this is called, the message is transmitted over the radio link to the counterpart app; when the message is received, the counterpart WCSession‘s delegate receives the session(_, didReceiveMessage:) method call:

  func session(session: WCSession,
       didReceiveMessage message: [String : AnyObject]) {
      print("Phone received message: \(message)")
  }

Sometimes, a message needs a reply. For example, your watchOS app may need to ask the iOS app for a list of strings to display; the iOS app will receive the request, and will then need to reply to that request.

To enable this, you provide a closure for the replyHandler parameter when calling sendMessage:

  WCSession.defaultSession().sendMessage(message,
                                         replyHandler: { (replyMessage) in
      print("Got a reply from the phone: \(replyMessage)")
  }, errorHandler: { (error) in
      print("Got an error sending to the phone: \(error)")
  })

The replyHandle takes a single parameter: a dictionary, containing the reply sent by the counterpart app. It’s up to you to interpret the contents of this dictionary.

When you send a message and provide a replyHandler, the counterpart app’s session delegate receives a slightly different method call: session(_, didReceiveMessage:, replyHandler:).

This method works identically, receiving the message sent from the other device; it also receives a replyHandler closure, which it is required to call before the method returns. When you call this closure, you provide the dictionary that you’d like to reply with:

  func session(session: WCSession,
       didReceiveMessage message: [String : AnyObject],
         replyHandler: ([String : AnyObject]) -> Void) {

      print("Phone received message that needs a reply: \(message)")

      let replyMessage = [
          "reply":"hello!"
      ]

      replyHandler(replyMessage)

  }

Moving Between Devices Using Handoff

Handoff is a technology that’s built into iOS, OS X, and watchOS, which allows the user to begin an activity on one of their devices and continue it on another.

For example, if you’re writing an email on your iPhone, your Mac is made aware of this fact, and displays an icon in the Dock. If you click on that icon in the Dock, the Mail application on OS X launches, and shows the draft email that you were just editing. You can then finish writing the email on your Mac, and send it from there.

Handoff works in both directions—you can start an activity on your Mac and finish it on your iPhone. It also supports handing off an activity between devices of the same type—for example, you can hand off from an iPhone to an iPad.

Handoff also works on the Apple Watch, and it’s a powerful technology that allows you to let users start doing something on the watch, and continue it on any of their other devices.

Before you start adding support for handoff to your applications, it’s worth taking a moment to think about what activities users might want to continue from one device to another. In the case of mail, it’s likely that users might want to continue reading or writing a specific message, but they probably won’t care about synchronizing where in the list of messages they are. Don’t forget that when you tell the system about an activity that the user is performing, an icon will appear on her iOS device’s lock screen and in her Mac’s dock. This can get a little annoying, so it pays to think about what’s important and what’s not.

Handoff works through the NSUserActivity class. A user activity contains two critical pieces of information: a string that identifies the type of the activity and a dictionary containing the context of the activity:

• The type of the activity is a period-separated string, like com.oreilly.CoolWatchApp.chatting. The activity type needs to have your iOS application’s bundle identifier as its prefix (which, in this example, would be com.oreilly.CoolWatchApp).

• The context of the activity is a dictionary containing additional information that describes details of what the user is doing. To continue our example, the context dictionary might contain information like the username of the person the user is chatting to.

To support receiving an activity that’s being handed off by another device, you need to add some information to your iOS app’s Info.plist file. This file provides information about an app (for example, its name and icon) to the rest of iOS.

To add support for a handoff activity, you first work out what you want to call the activity. Earlier, we used com.oreilly.CoolWatchApp.chatting; again, the type identifier can be anything you like, as long as it begins with your app’s bundle identifier. The activity’s type identifier is never shown to the user, and is only used in your code.

Once you’ve figured out the activity type string, you create an array inside the iOS app’s Info.plist file called NSUserActivityTypes, and add your activity type to that array (see Figure 1-9.)

Once this has been added to your iOS app’s Info.plist file, the iOS app has declared that it’s capable of receiving that type of activity from other devices. To share that activity, you use the NSUserActivity class to indicate what the user is doing.

To do this, you call updateUserActivity(_, userInfo:, webpageURL:) and pass in the activity type and context dictionary, as in the following code:

  // Define the activity that the user is doing
  let activityType = "au.com.secretlab.SwiftDevForAppleWatch.funActivity"

  // Add some additonal information that provides more context
  let activityInfo = [
      "additionalInfoForTheApp": "tennis"
  ]

  // Indicate to the system that the user
  // is now doing an activity
  self.updateUserActivity(activityType, userInfo: activityInfo, webpageURL: nil)

When you call updateUserActivity, all other nearby devices that belong to the user and have an app installed that’s capable of handling that type of activity are notified that the user is currently performing an activity; as a result, the application’s icon is shown on the iOS lock screen, and in the OS X Dock. When the user swipes up on the icon in the iOS lock screen, or clicks on the app in the Dock, the application is activated, and its application delegate object receives the application(_, continueUserActivity:, restorationHandler:) method:

  func application(application: UIApplication,
       continueUserActivity userActivity: NSUserActivity,
                      restorationHandler: ([AnyObject]?) -> Void) -> Bool {

      print("Handling activity \(userActivity.activityType) " +
          "(parameters: \(userActivity.userInfo)")
      return true
  }

This method receives three parameters: the UIApplication or NSApplication object that represents the current app, the NSUserActivity object that was prepared on the other device, and a closure that should be called if your application created any view controllers or windows as a result of resuming the activity (for example, if you opened a chat window to continue the user’s conversation, you pass in that window to the closure).

Using handoffs, you can let your user quickly and easily move between devices with a minimum of effort. Add this feature, and your users will thank you.