Guides and Sample Code

Developer

App Programming Guide for watchOS

On This Page

Text and Labels

To display text in your Watch app, use label objects. Labels support formatted text that can be changed programmatically at runtime.

To add a label to your interface controller, drag it into the corresponding storyboard scene. From there, configure the label’s initial text string and format. watchOS supports both standard fonts and custom fonts that you specify yourself. Figure 9-1 shows the standard font styles available for you to use.

Figure 9-1Standard font styles for labels image: ../Art/text_styles_2x.png

For more information about configuring label objects in Xcode and in your code, see WKInterfaceLabel Class Reference.

Using Custom Fonts

By default, the Watch app interface and notification interfaces use the system font for displaying text. Your Watch app interface may also use custom fonts (notifications can only use the system font). To use custom fonts, you must install the fonts into both the Watch app bundle and the WatchKit extension bundle, as shown below:

  • Include the custom font file in both your Watch app and your WatchKit extension bundle.

  • Add the UIAppFonts key to your Watch app’s Info.plist file, and use it to specify the fonts you added to the bundle. For more information about this key, see Information Property List Key Reference.

To format text using a custom font, create an attributed string using the font information and then use that string to set the text of your label, as shown in Listing 9-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 neither the system font nor one of your custom installed fonts, watchOS uses the system font.

Listing 9-1Using a custom font in a label string
  1. // Configure an attributed string with custom font information
  2. let menloFont = UIFont(name: "Menlo", size: 12.0)!
  3. var fontAttrs = [NSFontAttributeName : menloFont]
  4. var attrString = NSAttributedString(string: "My Text", attributes: fontAttrs)
  5. // Set the text on the label object
  6. self.label.setAttributedText(attrString)

If a custom font does not include the glyphs needed to display your string, the system must fall back to another font to retrieve any missing glyphs. This fall back process may result in poor performance in your app. To avoid any delays, always make sure that your custom fonts contain the glyphs you need to display your content.

Managing Text Input

watchOS provides a standard modal interface for retrieving text input from the user. When presented, the interface allows the user to enter text via dictation or to select from a standard set of phrases or emoji, as shown in Figure 9-2.

Figure 9-2Gathering text input from the user image: ../Art/text_input_phrases_2x.png

To present this interface, call the presentTextInputControllerWithSuggestions:allowedInputMode:completion: method of the currently active interface controller. When presenting the interface, you specify the types of input you support and a block to execute with the results. You also specify an initial set of phrases to display in the interface. The user can select from the available phrases or use the controls to input a different phrase.

Listing 9-2 shows how to configure the text input controller and process the results. After you specify the initial phrases and input modes, the controller runs asynchronously. When the user selects an item or cancels input, your block is executed on the main thread. Use that block to retrieve the text or emoji image that was selected by the user and update your app.

Listing 9-2Presenting the text input controller
  1. NSArray* initialPhrases = @[@"Let's do lunch.", @"Can we meet tomorrow?", @"When are you free?"];
  2. [self presentTextInputControllerWithSuggestions:initialPhrases
  3. allowedInputMode:WKTextInputModeAllowAnimatedEmoji
  4. completion:^(NSArray *results) {
  5. if (results && results.count > 0) {
  6. id aResult = [results objectAtIndex:0];
  7. // Use the string or image.
  8. }
  9. else {
  10. // Nothing was selected.
  11. }
  12. }];

Internationalizing Your Text Code

Watch apps can use the same technologies for internationalization that iOS apps use.

  • Use Xcode’s base internationalization support for storyboards and xib files. Base internationalization lets you have only one set of storyboard files, which supports all localizations. The localized strings for the storyboard are stored separately in language-specific strings files.

  • Use the NSLocalizedString family of macros to retrieve localized strings programmatically.

  • Use NSFormatter subclasses to format values using the user’s region and locale settings. The system provides formatters for a number of value types. For example:

    • The NSNumberFormatter class formats numerical values using the user’s region and locale settings.

    • The NSDateFormatter class formats dates using the user’s region and locale settings.

    • The CNContactFormatter class formats a contact’s name using the user’s region and locale settings.

When internationalizing your app, your main concern should be arranging your interface so that labels (and other controls with text) have room to expand. For example, rather than using a group to arrange three buttons horizontally, arrange the buttons vertically to give each one room to grow horizontally when its text becomes longer.

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