Guides and Sample Code

Developer

App Programming Guide for watchOS

On This Page

Context Menus

The Retina display with Force Touch found on Apple Watch provides a new way to interact with content. Instead of just tapping items on the screen, pressing the screen with a small amount of force activates the context menu (if any) associated with the current interface controller. Context menus are optional, but provide an easy way to display actions related to the current screen. As the name suggests, they play the same role as the context menus in a macOS app. For example in macOS, Control-clicking on a text view presents options to Cut, Copy, or Paste text.

watchOS displays the menu over your content, as shown in Figure 14-1.

Figure 14-1A context menu with three items image: ../Art/context_menu_2x.png

A context menu can display up to four actions. Each action is represented by a title string and an image. Tapping an action’s image dismisses the menu and executes the action method associated with that menu item. Tapping anywhere else dismisses the menu without any further action.

Designing Your Menu Items

Each menu item consists of a tappable area and a title. The tappable area contains a circular background, on top of which sits an image that you provide. The image must be a template image, where the alpha channel defines the shape to draw on top of the background. Opaque portions of the image appear as black, and fully or partially transparent portions let the background color show through.

The template images you provide should be smaller than the circular background on which they sit. For more information about the size of menu images and guidelines for how to create them, see Apple Watch Human Interface Guidelines.

Adding a Context Menu to an Interface Controller

You configure an interface controller’s context menu at design time, but you can also add and remove menu items at runtime. At design time, edit your storyboard to include the menu items that you always want to be present on the menu for a given interface controller. When you initialize your interface controller later, you can add menu items to supplement the ones you created in your storyboard. Menu items you add programmatically can also be removed. The total number of menu items in a menu cannot exceed four, regardless of whether you included them in your storyboard or added them programmatically.

To add a context menu to an interface controller
  1. Open your storyboard file.

  2. Drag a menu object from the library and add it to your interface controller scene.

    The initial menu contains a single menu item.

  3. Drag up to three more items from the library to your menu.

    You can also use the Attributes inspector of the menu to set the number of items. The items you add cannot be removed programmatically later.

  4. For each item, use the Attributes inspector to specify the menu’s title and image. Both are required.

  5. Connect each menu item to an action method in your interface controller class.

    Menu action methods have the following format:

    • - (IBAction)doMenuItemAction
  6. Save your storyboard file.

To add menu items at runtime, call the addMenuItemWithImage:title:action: or addMenuItemWithImageNamed:title:action: method of your interface controller object. The items you specify are added to the ones in your storyboard file. Items added programmatically remain attached to the menu until you explicitly remove them or until your interface controller is deallocated.

Handling Taps in a Menu Item

When the user taps a menu item, watchOS dismisses the menu and calls the associated action method. You define action methods in your interface controller using the following syntax:

Objective-C

  1. - (IBAction)doMenuItemAction {
  2. // Handle menu action.
  3. }

Swift

  1. @IBAction func doMenuAction() {
  2. // Handle menu action.
  3. }

If any state information is required to perform the action, it is your responsibility to store and maintain that information in your interface controller object. For example, if an action relies on the currently selected row of a table, your interface controller must include a variable to track the most recently selected row. And, if you want to request more information from the user after tapping a menu action, your action method must present a modal interface controller.