iOS Developer Library

Developer

UIKit Framework Reference UITextFieldDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

UITextFieldDelegate

The UITextFieldDelegate protocol defines methods that you use to manage the editing and validation of text in a UITextField object. All of the methods of this protocol are optional.

A text field calls the methods of its delegate in response to important changes. You use these methods to validate text that was typed by the user, to respond to specific interactions with the keyboard, and to control the overall editing process. Editing begins shortly before the text field becomes the first responder and displays the keyboard (or its assigned input view). The flow of the editing process is as follows:

  1. Before becoming the first responder, the text field calls its delegate’s textFieldShouldBeginEditing: method. Use that method to allow or prevent the editing of the text field’s contents.

  2. The text field becomes the first responder.

    In response, the system displays the keyboard (or the text field’s input view) and posts the UIKeyboardWillShowNotification and UIKeyboardDidShowNotification notifications as needed. If the keyboard or another input view was already visible, the system posts the UIKeyboardWillChangeFrameNotification and UIKeyboardDidChangeFrameNotification notifications instead.

  3. The text field calls its delegate’s textFieldDidBeginEditing: method and posts a UITextFieldTextDidBeginEditingNotification notification.

  4. The text field calls various delegate methods during editing:

  5. Before resigning as first responder, the text field calls its delegate’s textFieldShouldEndEditing: method. Use that method to validate the current text.

  6. The text field resigns as first responder.

    In response, the system hides or adjusts the keyboard as needed. When hiding the keyboard, the system posts the UIKeyboardWillHideNotification and UIKeyboardDidHideNotification notifications.

  7. The text field calls its delegate’s textFieldDidEndEditing: method and posts a UITextFieldTextDidEndEditingNotification notification.

For more information about the features of a text field, see UITextField Class Reference.

  • Asks the delegate if editing should begin in the specified text field.

    Declaration

    Swift

    optional func textFieldShouldBeginEditing(_ textField: UITextField) -> Bool

    Objective-C

    - (BOOL)textFieldShouldBeginEditing:(UITextField *)textField

    Parameters

    textField

    The text field in which editing is about to begin.

    Return Value

    YEStrue if editing should begin or NOfalse if it should not.

    Discussion

    The text field calls this method when the user performs an action that would normally initiate the editing of the text field’s text. Implement this method if you want to prevent editing from happening in some situations. For example, you could use this method to prevent the user from editing the text field’s contents more than once. Most of the time, you should return YEStrue to allow editing to proceed.

    If you do not implement this method, the text field acts as if this method had returned YEStrue.

    Availability

    Available in iOS 2.0 and later.

  • Tells the delegate that editing began in the specified text field.

    Declaration

    Swift

    optional func textFieldDidBeginEditing(_ textField: UITextField)

    Objective-C

    - (void)textFieldDidBeginEditing:(UITextField *)textField

    Parameters

    textField

    The text field in which an editing session began.

    Discussion

    This method notifies the delegate that the specified text field just became the first responder. Use this method to update state information or perform other tasks. For example, you might use this method to show overlay views that are visible only while editing.

    Implementation of this method by the delegate is optional.

    Availability

    Available in iOS 2.0 and later.

  • Asks the delegate if editing should stop in the specified text field.

    Declaration

    Swift

    optional func textFieldShouldEndEditing(_ textField: UITextField) -> Bool

    Objective-C

    - (BOOL)textFieldShouldEndEditing:(UITextField *)textField

    Parameters

    textField

    The text field in which editing is about to end.

    Return Value

    YEStrue if editing should stop or NOfalse if it should continue.

    Discussion

    The text field calls this method when it is asked to resign the first responder status. This can happen when the user selects another control or when you call the text field’s resignFirstResponder method. Before the focus change occurs, however, the text field calls this method and gives you a chance to prevent the change from happening.

    Normally, you would return YEStrue from this method to allow the text field to resign the first responder status. You might return NOfalse, however, in cases where your delegate detects invalid contents in the text field. Returning NOfalse prevents the user from switching to another control until the text field contains a valid value.

    Be aware that this method provides only a recommendation about whether editing should end. Even if you return NOfalse, UIKit might still force an end to editing. For example, text fields always resign the first responder status when they are removed from their parent view or window.

    Implementation of this method by the delegate is optional. If you do not implement this method, the text field resigns the first responder status as if this method had returned YEStrue.

    Availability

    Available in iOS 2.0 and later.

  • Tells the delegate that editing stopped for the specified text field.

    Declaration

    Swift

    optional func textFieldDidEndEditing(_ textField: UITextField)

    Objective-C

    - (void)textFieldDidEndEditing:(UITextField *)textField

    Parameters

    textField

    The text field for which editing ended.

    Discussion

    This method is called after the text field resigns its first responder status. You can use this method to update your delegate’s state information. For example, you might use this method to hide overlay views that should be visible only while editing.

    Implementation of this method by the delegate is optional.

    Availability

    Available in iOS 2.0 and later.

  • Asks the delegate if the specified text should be changed.

    Declaration

    Swift

    optional func textField(_ textField: UITextField, shouldChangeCharactersInRange range: NSRange, replacementString string: String) -> Bool

    Objective-C

    - (BOOL)textField:(UITextField *)textField shouldChangeCharactersInRange:(NSRange)range replacementString:(NSString *)string

    Parameters

    textField

    The text field containing the text.

    range

    The range of characters to be replaced.

    string

    The replacement string for the specified range. During typing, this parameter normally contains only the single new character that was typed, but it may contain more characters if the user is pasting text. When the user deletes one or more characters, the replacement string is empty.

    Return Value

    YEStrue if the specified text range should be replaced; otherwise, NOfalse to keep the old text.

    Discussion

    The text field calls this method whenever user actions cause its text to change. Use this method to validate text as it is typed by the user. For example, you could use this method to prevent the user from entering anything but numerical values.

    Availability

    Available in iOS 2.0 and later.

  • Asks the delegate if the text field’s current contents should be removed.

    Declaration

    Swift

    optional func textFieldShouldClear(_ textField: UITextField) -> Bool

    Objective-C

    - (BOOL)textFieldShouldClear:(UITextField *)textField

    Parameters

    textField

    The text field containing the text.

    Return Value

    YEStrue if the text field’s contents should be cleared; otherwise, NOfalse.

    Discussion

    The text field calls this method in response to the user pressing the built-in clear button. (This button is not shown by default but can be enabled by changing the value in the clearButtonMode property of the text field.) This method is also called when editing begins and the clearsOnBeginEditing property of the text field is set to YEStrue.

    If you do not implement this method, the text field clears the text as if the method had returned YEStrue.

    Availability

    Available in iOS 2.0 and later.

  • Asks the delegate if the text field should process the pressing of the return button.

    Declaration

    Swift

    optional func textFieldShouldReturn(_ textField: UITextField) -> Bool

    Objective-C

    - (BOOL)textFieldShouldReturn:(UITextField *)textField

    Parameters

    textField

    The text field whose return button was pressed.

    Return Value

    YEStrue if the text field should implement its default behavior for the return button; otherwise, NOfalse.

    Discussion

    The text field calls this method whenever the user taps the return button. You can use this method to implement any custom behavior when the button is tapped. For example, if you want to dismiss the keyboard when the user taps the return button, your implementation can call the resignFirstResponder method.

    Availability

    Available in iOS 2.0 and later.