How to get text input from the user
(Originally published at FiveMinuteWatchKit.com, before the release of watchOS 2)
One of the most interesting features of WatchKit — collecting text input through dictation — is also one of the least talked about. Let’s get started.
Talk to me
Dictation is handled using a standard modal, presented by calling presentTextInputControllerWithSuggestions:allowedInputMode:completion:on your currently-active WKInterfaceController.
The controller runs asynchronously, waiting for the user to tap “Done” and confirm their input. Once that happens, the provided completion block is executed on the main thread and you can use the supplied results however you like.
You should always call presentTextInputControllerWithSuggestions:allowedInputMode:completion: on your WatchKit extension’s main thread.
When presenting the dictation controller, you can optionally provide an array of NSString objects representing suggested input for the user. In a messaging app, for example, you might want to suggest generic responses a user could send to their friend.
You have to choose which of the three WKTextInputMode options you would like to present to the user.
- WKTextInputModePlain: Dictation/suggested text only. No emoji. The emoji button will be hidden.
- WKTextInputModeAllowEmoji: Dictation, suggested text, and non-animated emoji.
- WKTextInputModeAllowAnimatedEmoji: Dictation, suggested text, and both animated and non-animated emoji.
If you skip providing suggestions and set the input mode to WKTextInputModePlain, the user will be sent directly to the dictation interface.
The completion block is passed an NSArray containing the input from the user. If the modal is dismissed before any input is given, this array will be nil. You can usually expect the array to contain a single NSString object representing the text input.
However, it can also contain an NSData object representing an emoji image if you’ve allowed the user to provide one. You can use that NSData object to create a UIImage, or use it directly in a WKInterfaceImage.
Since the text input interface is presented modally, the presenting WKInterfaceController will be re-activated before the completion block is called.
It’s worth mentioning a few things when it comes to testing dictation in the simulator:
- While you can specify any input mode you like, the simulator only supports providing text input using a suggested string. You can’t speak into your computer’s mic and have it converted to text. Similarly, the simulator does not support selecting either type of emoji.
- The dictation screen will appear blank. It’s important to know that dictation will begin immediately when used on an actual Watch. The user will have to tap a “Done” button to confirm the dictated text before it is passed back to your app.