Guides and Sample Code

Developer

App Programming Guide for watchOS

On This Page

Interface Navigation

For a Watch app interface with more than one screen of content, you must choose a technique for navigating between different screens. The Watch app interface supports two navigation styles, which are mutually exclusive:

  • Page based. This style is suited for apps with simple data models where the data on each page is not closely related to the data on any other page. A page-based interface contains two or more independent interface controllers, only one of which is displayed at any given time. At runtime, the user navigates between interface controllers by swiping left or right on the screen. A dot indicator control at the bottom of the screen indicates the user’s current position among the pages.

  • Hierarchical. This style is suited for master-detail interfaces, for presenting a navigable set of screens, or for cases where you might need to extend your app and add new content later. A hierarchical interface always starts with a single root interface controller. In that interface controller, you provide controls that, when tapped, push new interface controllers onto the screen.

Although you cannot mix page-based and hierarchical navigation styles in your app, you can supplement these base navigation styles with modal presentations. Modal presentations let you interrupt the current user workflow to request input or display information. You can present interface controllers modally from both page-based and hierarchical apps. The modal presentation itself can consist of a single screen or multiple screens arranged in a page-based layout.

Implementing a Page-Based Interface

You configure a page-based interface in your app’s storyboard by creating a next-page segue from one interface controller to the next.

To create a next-page segue between interface controllers
  1. In your storyboard, add interface controllers for each of the pages in your interface.

  2. Control-click your app’s main interface controller, and drag the segue line to another interface controller scene.

    The second interface controller should highlight, indicating that a segue is possible.

  3. Release the mouse button.

  4. Select “next page” from the relationship segue panel.

  5. Using the same technique, create segues from each interface controller to the next.

    The order in which you create your segues defines the order of the pages in your interface.

The segues you create in your storyboard file define the page-based interface that is loaded when your app is launched. You can change the set of pages you want to display by calling the reloadRootControllersWithNames:contexts: method and passing an array of identifiers for interface controllers defined in your storyboard. For example, you might call that method in the init method of your main interface controller to force watchOS to load a different set of pages.

All interface controllers in a page-based interface are created and initialized before the interface is displayed, but only one interface controller at a time is displayed. Normally, watchOS displays the first interface controller in the sequence initially. To change the initially displayed interface controller, call the becomeCurrentPage method in its init or awakeWithContext: method.

As the user navigates from page to page, watchOS activates and deactivates interface controllers accordingly. Use the willActivate, didAppear, willDisappear, and didDeactivate methods to determine when a view controller is being displayed.

Implementing a Hierarchical Interface

In a hierarchical interface, you tell watchOS when to transition to a new screen using segues or by calling the pushControllerWithName:context: method of the current interface controller. In your storyboard, you create push segues from a button, group, or table row in your interface to another interface controller in your storyboard. If you prefer to initiate the push transition programmatically, call the pushControllerWithName:context: method from any of your interface controller’s action methods.

When pushing a new interface controller onto the screen, it is recommended that you pass a data object in the context parameter of the pushControllerWithName:context: method. This context object is how you pass state information to the new interface controller before it appears onscreen. Use this object to tell the new interface controller what data to display.

A pushed interface controller displays a chevron in the upper-left corner of the screen to indicate that the user can navigate backward. When the user taps the upper-left corner of the screen or performs a left-edge swipe, watchOS dismisses the topmost interface controller automatically. You can also dismiss the interface controller programmatically by calling its popController method. You cannot dismiss your app’s main interface controller.

Tables in a hierarchical interface can also support item pagination. When enabled, item pagination lets users easily scroll through a series of detail views. The user selects an item from the table, and the app displays a detailed view for that item. The user can then scroll up and down to navigate between other sibling items from the table. For more information, see Supporting Item Pagination in WKInterfaceTable Class Reference.

Presenting Interface Controllers Modally

A modal interface is a way to interrupt the current navigation flow temporarily to prompt the user or display information. You can present a modal interface from any interface controller, regardless of the navigation style used by your app. To display an interface controller modally, do one of the following:

When creating a modal segue, connect the segue to the interface controller you want to display. When using a segue to present multiple interface controllers, first use the next-page segue to connect the modal interface controllers together, in the same way that you connect them together for a page-based interface. Your modal segue should connect to the first interface controller in the group. If you connect to an interface controller in the middle of the group, the interface controllers that precede it in the group are not displayed.

The top-left corner of a modal interface displays the interface controller’s title string. When the user taps that string, watchOS dismisses the modal interface. Set the title string to reflect the meaning of dismissing the modal interface. For example, when displaying information, you might set the string to Done or Close. If you do not specify a title for your interface controller, watchOS displays the string Cancel by default.