Documentation Archive


App Programming Guide for watchOS

On This Page

UI Essentials

The starting point for implementing your app is to define your storyboard scenes. Each scene defines a portion of your app’s user interface. You can customize scenes for different Apple Watch sizes, and you can configure different aspects of your interface.

Assembling Your Storyboard Scenes

Watch apps do not use the same layout model used by iOS apps. When assembling the scenes for your Watch app interface, Xcode arranges items for you, stacking them vertically on different lines. At runtime, Apple Watch takes those elements and lays them out based on the available space.

Although Xcode handles the overall layout of your interface, watchOS provides ways to fine tune the position of items within a scene. The size and position of most items can be configured using the Attributes inspector. The alignment options let you set the horizontal and vertical alignment of an item at its current location in the element stack. The sizing options let you specify a fixed width for an item or give it the ability to resize itself within the available space.

Group objects provide additional control over your layout. Groups act as containers for other elements, giving you the ability to arrange contained items horizontally or vertically. You can nest groups within other groups and use each group’s spacing and inset values to alter the size and position of its contained items. Groups have no default visual representation but they can be configured with a background color or image as needed.

Figure 6-1 shows how you can arrange different elements in your storyboard file. The first three elements are labels, which have different alignments within the interface controller’s bounds. Below the labels is a group object containing two images arranged horizontally. The interface also contains a separator and a button stacked vertically underneath the group object.

Figure 6-1Interface objects in Xcode image: ../Art/storyboard_layout_2x.png

When creating your interfaces in Xcode, let objects resize themselves to fit the available space whenever possible. App interfaces should be able to run both display sizes of Apple Watch. Letting the system resize objects to fit the available space minimizes the amount of custom code you have to write for each device.

Accommodating Different Display Sizes

Xcode supports customizing your interface for the different sizes of Apple Watch. By default, the changes you make in the storyboard editor apply to all sizes of Apple Watch, but you can customize your storyboard scenes as needed for different devices. For example, you might make minor adjustments to the spacing and layout of items or specify different images for different device sizes.

To customize an item for a specific device size, use the plus buttons (+) in the Attributes inspector to override the value of an attribute for a given device. Clicking a plus button adds a new device-specific entry for the attribute. Changes you make to that version of the attribute affect only the selected device. Figure 6-2 shows how text scaling is handled differently for Apple Watch 42mm.

Figure 6-2Customizing attributes for different devices image: ../Art/scalable_text_2x.png

Users should not notice significant differences in your app’s interface on different sizes of Apple Watch, so minimize the customizations you make for different device sizes. Whenever possible, limit interface changes to layout-related behaviors such as spacing and margins. Although it is possible to remove interface objects altogether from your interface in different layouts, doing so is not recommended. Try to use the exact same set of interface objects on all sizes of Apple Watch.

To see customizations applied to different device sizes, use the control at the bottom of the storyboard editor to toggle between the device sizes. The storyboard editor displays the Any device size by default. Changes applied in the Any display mode apply to all sizes of Apple Watch. If you change the display mode to a specific device size, the changes you make while in that mode apply only to the current device.

Updating Your Interface at Runtime

At runtime, an interface controller can make the following modifications to the objects in its corresponding storyboard scene:

  • Set or update data values.

  • Change the visual appearance of objects that support such modifications.

  • Change the size of an object.

  • Change the transparency of an object.

  • Show or hide an object.

You cannot add new objects to your interface or change the order of the objects that are already there. Although you cannot remove objects, you can hide them, which removes them from the layout temporarily. When an item is hidden, other objects fill in the space previously occupied by the item. To hide an object without filling in the space, set the item’s alpha value to 0. For more information about hiding objects in a scene, see Hiding Interface Objects.

Setting Your App’s Key Color

Every Watch app has an associated key color, which is applied to the following UI elements:

  • The title string in the status bar

  • The app name in short-look notifications

An app’s key color is stored in the Global Tint property of an app’s storyboard. To access this property, select your storyboard and display the File inspector. Select one of several preexisting colors from the pop-up menu, or use the color picker to specify a custom color.

Internationalizing Your Interface

The storyboards that come with your Watch app have base internationalization enabled by default. This feature causes any strings in your storyboard to be added to your project’s Localizable.strings files automatically. Simply translate the strings in those files for each target language, and include them with your shipping app. When you create a storyboard scene at runtime, Xcode inserts the strings associated with the appropriate localization.

Arrange your interface so that labels and controls that contain text have room to expand. Instead of placing multiple buttons on the same line, arrange them vertically so that each one has plenty of room to display its title.

For text and images that you specify programmatically, use the same internationalization techniques you use for iOS and macOS apps:

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.

For more information about internationalizing your app, see Internationalization and Localization Guide.