WKInterfaceTextField
An interface element that displays an editable text area.
Declaration
class WKInterfaceTextFieldOverview
Text fields gather text-based input from the user. The text field defines an area of editable text within your user interface, letting you create forms with multiple input fields.
[Image]
When the user taps the text field, WatchKit displays the text input controller. Users can enter text by selecting one of the suggestions, or using dictation or Scribble. Users can also launch the Apple Continuity Keyboard, entering text from a nearby iOS device logged into the same iCloud account.
Use text fields to gather short, specific pieces of information such as the user’s name, address, password, or credit card number. Identify the type of data using the text field’s content type, which allows the system to optimize the behavior of the text input controller and the Apple Continuity Keyboard. For more information, see Authenticating Users on Apple Watch.
You can also describe the expected content to the user in the text field’s placeholder. Effective placeholders let you build a form that is both compact and easy to use.
For general text input, consider using presentTextInputController(withSuggestions:allowedInputMode:completion:) or presentTextInputControllerWithSuggestions(forLanguage:allowedInputMode:completion:) instead. Call these methods to display the text input controller with the suggestions that you provide. Keep in mind that the system doesn’t provide the text input controller with a content type, so the system cannot optimize its behavior.
Configure the Text Field
As with other WatchKit interface objects, you should not subclass or create instances of this class. Instead, add a text field to your WatchKit App’s storyboard. The system then creates the text field when it loads the storyboard.
Xcode also lets you configure the text field directly in the storyboard. The following table lists the attributes and their meaning.
Attribute | Description |
|---|---|
Text | The initial text displayed by the text field. Specify a plain string or an attributed string. You can set this value programmatically using the Settext(_:) or Setattributedtext(_:) methods. |
Placeholder | The placeholder text displayed by the text field. When the text field’s value is empty, the text field displays the placeholder, formatting it to make it clear that it’s not an actual text entry. Typing any text into the text field hides this string. You can set this value programmatically using the Setplaceholder(_:) or Setattributedplaceholder(_:) methods. |
Text Color | The color of the text. The system applies this color to the entire string. You can set this value programmatically using the Settextcolor(_:) method. |
Content Type | The text field’s expected content, such as a username, password, or address. You can set this value programmatically using the Settextcontenttype(_:) method. |
Secure Text Entry | A checkbox indicating whether the text field hides the text that the user entered, keeping passwords and other secure data private. You can set this value programmatically using the Setsecuretextentry(_:) method. |
Enabled | A checkbox indicating whether the text field is enabled and responds when tapped. You can configure this value programmatically using the Setenabled(_:) method. |
To dynamically modify a text field at runtime, define an outlet in your interface controller and connect it to the corresponding text field in your storyboard. For example, define a property with the following syntax in your interface controller class:
During your interface controller’s initialization, WatchKit creates a new instance of the WKInterfaceTextField class and assigns it to your outlet. At that point, you can use the object in your outlet to manage the text field.
Receive Text Input
To receive the text entered by the user, connect the text field in the storyboard to an action method defined in your interface controller.
WatchKit calls the action method after the user dismisses the text input controller. The value parameter contains the string entered by the user. If the user cancels the text input controller, the value is nil.
Topics
Specifying the Content Type
Setting the Text
Setting a Placeholder
Configuring the Control
See Also
Related Documentation
presentTextInputController(withSuggestions:allowedInputMode:completion:)presentTextInputControllerWithSuggestions(forLanguage:allowedInputMode:completion:)