| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/UIKit.framework |
| Availability | Available in iPhone OS 2.0 and later. |
| Declared in | UITextField.h |
| Related sample code |
A UITextField object is a control that displays editable text and sends an action message to a target object when the user presses the return button. You typically use this class to gather small amounts of text from the user and perform some immediate action, such as a search operation, based on that text.
In addition to its basic text-editing behavior, the UITextField class supports the use of overlay views to display additional information (and provide additional command targets) inside the text field boundaries. You can use custom overlay views to display features such as a bookmarks button or search icon. The UITextField class also provides a built-in button for clearing the current text.
A text field object supports the use of a delegate object to handle editing-related notifications. You can use this delegate to customize the editing behavior of the control and provide guidance for when certain actions should occur. For more information on the methods supported by the delegate, see the UITextFieldDelegate protocol.
When the user taps in a text field, that text field becomes the first responder and automatically asks the system to display the associated keyboard. Because the appearance of the keyboard has the potential to obscure portions of your user interface, it is up to you to make sure that does not happen by repositioning any views that might be obscured. Some system views, like table views, help you by scrolling the first responder into view automatically. If the first responder is at the bottom of the scrolling region, however, you may still need to resize or reposition the scroll view itself to ensure the first responder is visible.
It is your application’s responsibility to dismiss the keyboard at the time of your choosing. You might dismiss the keyboard in response to a specific user action, such as the user tapping a particular button in your user interface. You might also configure your text field delegate to dismiss the keyboard when the user presses the “return” key on the keyboard itself. To dismiss the keyboard, send the resignFirstResponder message to the text field that is currently the first responder. Doing so causes the text field object to end the current editing session (with the delegate object’s consent) and hide the keyboard.
The appearance of the keyboard itself can be customized using the properties provided by the UITextInputTraits protocol. Text field objects implement this protocol and support the properties it defines. You can use these properties to specify the type of keyboard (ASCII, Numbers, URL, Email, and others) to display. You can also configure the basic text entry behavior of the keyboard, such as whether it supports automatic capitalization and correction of the text.
When the system shows or hides the keyboard, it posts several keyboard notifications. These notifications contain information about the keyboard, including its size, which you can use for calculations that involve moving views. Registering for these notifications is the only way to get some types of information about the keyboard. The system delivers the following notifications for keyboard-related events:
For more information about these notifications, see their descriptions in UIWindow Class Reference. For information about how to show and hide the keyboard, see Text and Web.
text property
placeholder property
font property
textColor property
textAlignment property
adjustsFontSizeToFitWidth property
minimumFontSize property
editing property
clearsOnBeginEditing property
borderStyle property
background property
disabledBackground property
clearButtonMode property
leftView property
leftViewMode property
rightView property
rightViewMode property
delegate property
For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.
A Boolean value indicating whether the font size should be reduced in order to fit the text string into the text field’s bounding rectangle.
@property(nonatomic) BOOL adjustsFontSizeToFitWidth
Normally, the text field’s content is drawn with the font you specify in the font property. If this property is set to YES, however, and the contents in the text property exceed the text field’s bounding rectangle, the receiver starts reducing the font size until the string fits or the minimum font size is reached. The text is shrunk along the baseline.
The default value for this property is NO. If you change it to YES, you should also set an appropriate minimum font size by modifying the minimumFontSize property.
UITextField.hThe image that represents the background appearance of the text field when it is enabled.
@property(nonatomic, retain) UIImage *background
When set, the image referred to by this property replaces the standard appearance controlled by the borderStyle property. Background images are drawn in the border rectangle portion of the image. Images you use for the text field’s background should be able to stretch to fit.
This property is set to nil by default.
UITextField.hThe border style used by the text field.
@property(nonatomic) UITextBorderStyle borderStyle
The default value for this property is UITextBorderStyleNone. If a custom background image is set, this property is ignored.
UITextField.hControls when the standard clear button appears in the text field.
@property(nonatomic) UITextFieldViewMode clearButtonMode
The standard clear button is displayed at the right side of the text field as a way for the user to remove text quickly. This button appears automatically based on the value set for this property.
The default value for this property is UITextFieldViewModeNever.
UITextField.hA Boolean value indicating whether the text field removes old text when editing begins.
@property(nonatomic) BOOL clearsOnBeginEditing
If this property is set to YES, the text field’s previous text is cleared when the user selects the text field to begin editing. If NO, the text field places an insertion point at the place where the user tapped the field.
YES, the text field delegate can override this behavior by returning NO from its textFieldShouldClear: method. UITextField.hThe receiver’s delegate.
@property(nonatomic, assign) id<UITextFieldDelegate> delegate
A text field delegate responds to editing-related messages from the text field. You can use the delegate to respond to the text entered by the user and to some special commands, such as when the return button is pressed.
UITextField.hThe image that represents the background appearance of the text field when it is disabled.
@property(nonatomic, retain) UIImage *disabledBackground
Background images are drawn in the border rectangle portion of the image. Images you use for the text field’s background should be able to stretch to fit. This property is ignored if the background property is not also set.
This property is set to nil by default.
UITextField.hA Boolean value indicating whether the text field is currently in edit mode. (read-only)
@property(nonatomic, readonly, getter=isEditing) BOOL editing
This property is set to YES when the user begins editing text in this text field, and it is set to NO again when editing ends. Notifications about when editing begins and ends are sent to the text field delegate.
UITextField.hThe font of the text.
@property(nonatomic, retain) UIFont *font
This property applies to the entire text of the text field. It also applies to the placeholder text. The default font is a 12-point Helvetica plain font.
UITextField.hThe overlay view displayed on the left side of the text field.
@property(nonatomic, retain) UIView *leftView
You can use the left overlay view to indicate the intended behavior of the text field. For example, you might display a magnifying glass in this location to indicate that the text field is a search field.
The left overlay view is placed in the rectangle returned by the leftViewRectForBounds: method of the receiver. The image associated with this property should fit the given rectangle. If it does not fit, it is scaled to fit.
If your overlay view does not overlap any other sibling views, it receives touch events like any other view. If you specify a control for your view, the control tracks and sends actions as usual. If an overlay view overlaps the clear button, however, the clear button always takes precedence in receiving events.
UITextField.hControls when the left overlay view appears in the text field.
@property(nonatomic) UITextFieldViewMode leftViewMode
The default value for this property is UITextFieldViewModeNever.
UITextField.hThe size of the smallest permissible font with which to draw the text field’s text.
@property(nonatomic) CGFloat minimumFontSize
When drawing text that might not fit within the bounding rectangle of the text field, you can use this property to prevent the receiver from reducing the font size to the point where it is no longer legible.
The default value for this property is 0.0. If you enable font adjustment for the text field, you should always increase this value.
UITextField.hThe string that is displayed when there is no other text in the text field.
@property(nonatomic, copy) NSString *placeholder
This value is nil by default. The placeholder string is drawn using a 70% grey color.
UITextField.hThe overlay view displayed on the right side of the text field.
@property(nonatomic, retain) UIView *rightView
You can use the right overlay view to provide indicate additional features available for the text field. For example, you might display a bookmarks button in this location to allow the user to select from a set of predefined items.
The right overlay view is placed in the rectangle returned by the rightViewRectForBounds: method of the receiver. The image associated with this property should fit the given rectangle. If it does not fit, it is scaled to fit.
If your overlay view does not overlap any other sibling views, it receives touch events like any other view. If you specify a control for your view, that control tracks and sends actions as usual. If an overlay view overlaps the clear button, however, the clear button always takes precedence in receiving events. By default, the right overlay view does overlap the clear button.
UITextField.hControls when the right overlay view appears in the text field.
@property(nonatomic) UITextFieldViewMode rightViewMode
The default value for this property is UITextFieldViewModeNever.
UITextField.hThe text displayed by the text field.
@property(nonatomic, copy) NSString *text
This string is nil by default.
UITextField.hThe technique to use for aligning the text.
@property(nonatomic) UITextAlignment textAlignment
This property applies to the both the main text string and the placeholder string. The default value of this property is UITextAlignmentLeft.
UITextField.hThe color of the text.
@property(nonatomic, retain) UIColor *textColor
This property applies to the entire text string. The default value for this property is nil, which results in opaque black text.
UITextField.hReturns the receiver’s border rectangle.
- (CGRect)borderRectForBounds:(CGRect)bounds
The bounding rectangle of the receiver.
The border rectangle for the receiver.
You should not call this method directly. If you want to provide a different border rectangle for drawing, you can override this method and return that rectangle.
The default implementation of this method returns the original bounds rectangle.
UITextField.hReturns the drawing rectangle for the built-in clear button.
- (CGRect)clearButtonRectForBounds:(CGRect)bounds
The bounding rectangle of the receiver.
The rectangle in which to draw the clear button.
You should not call this method directly. If you want to place the clear button in a different location, you can override this method and return the new rectangle. Your method should call the super implementation and modify the returned rectangle’s origin only. Changing the size of the clear button may cause unnecessary distortion of the button image.
UITextField.hDraws the receiver’s placeholder text in the specified rectangle.
- (void)drawPlaceholderInRect:(CGRect)rect
The rectangle in which to draw the placeholder text.
You should not call this method directly. If you want to customize the drawing behavior for the placeholder text, you can override this method to do your drawing.
By the time this method is called, the current graphics context is already configured with the default environment and text color for drawing. In your overridden method, you can configure the current context further and then invoke super to do the actual drawing or do the drawing yourself. If you do render the text yourself, you should not invoke super.
UITextField.hDraws the receiver’s text in the specified rectangle.
- (void)drawTextInRect:(CGRect)rect
The rectangle in which to draw the text.
You should not call this method directly. If you want to customize the drawing behavior for the text, you can override this method to do your drawing.
By the time this method is called, the current graphics context is already configured with the default environment and text color for drawing. In your overridden method, you can configure the current context further and then invoke super to do the actual drawing or you can do the drawing yourself. If you do render the text yourself, you should not invoke super.
UITextField.hReturns the rectangle in which editable text can be displayed.
- (CGRect)editingRectForBounds:(CGRect)bounds
The bounding rectangle of the receiver.
The computed editing rectangle for the text.
You should not call this method directly. If you want to provide a different editing rectangle for the text, you can override this method and return that rectangle. By default, this method returns a region in the text field that is not occupied by any overlay views.
UITextField.hReturns the drawing rectangle of the receiver’s left overlay view.
- (CGRect)leftViewRectForBounds:(CGRect)bounds
The bounding rectangle of the receiver.
The rectangle in which to draw the left overlay view.
You should not call this method directly. If you want to place the left overlay view in a different location, you can override this method and return the new rectangle.
UITextField.hReturns the drawing rectangle for the text field’s placeholder text
- (CGRect)placeholderRectForBounds:(CGRect)bounds
The bounding rectangle of the receiver.
The computed drawing rectangle for the placeholder text.
You should not call this method directly. If you want to customize the drawing rectangle for the placeholder text, you can override this method and return a different rectangle.
UITextField.hReturns the drawing location of the receiver’s right overlay view.
- (CGRect)rightViewRectForBounds:(CGRect)bounds
The bounding rectangle of the receiver.
The rectangle in which to draw the right overlay view.
You should not call this method directly. If you want to place the right overlay view in a different location, you can override this method and return the new rectangle.
UITextField.hReturns the drawing rectangle for the text field’s text.
- (CGRect)textRectForBounds:(CGRect)bounds
The bounding rectangle of the receiver.
The computed drawing rectangle for the label’s text.
You should not call this method directly. If you want to customize the drawing rectangle for the text, you can override this method and return a different rectangle.
The default implementation of this method returns a rectangle that is derived from the control’s original bounds, but which does not include the area occupied by the receiver’s border or overlay views.
UITextField.hThe type of border drawn around the text field.
typedef enum {
UITextBorderStyleNone,
UITextBorderStyleLine,
UITextBorderStyleBezel,
UITextBorderStyleRoundedRect
} UITextBorderStyle;
UITextBorderStyleNoneThe text field does not display a border.
Available in iPhone OS 2.0 and later.
Declared in UITextField.h.
UITextBorderStyleLineDisplays a thin rectangle around the text field.
Available in iPhone OS 2.0 and later.
Declared in UITextField.h.
UITextBorderStyleBezelDisplays a bezel-style border for the text field. This style is typically used for standard data-entry fields.
Available in iPhone OS 2.0 and later.
Declared in UITextField.h.
UITextBorderStyleRoundedRectDisplays a rounded-style border for the text field. This style is typically used for search buttons.
Available in iPhone OS 2.0 and later.
Declared in UITextField.h.
Defines the times at which overlay views appear in a text field.
typedef enum {
UITextFieldViewModeNever,
UITextFieldViewModeWhileEditing,
UITextFieldViewModeUnlessEditing,
UITextFieldViewModeAlways
} UITextFieldViewMode;
UITextFieldViewModeNeverThe overlay view never appears.
Available in iPhone OS 2.0 and later.
Declared in UITextField.h.
UITextFieldViewModeWhileEditingThe overlay view is displayed only while text is being edited in the text field.
Available in iPhone OS 2.0 and later.
Declared in UITextField.h.
UITextFieldViewModeUnlessEditingThe overlay view is displayed only when text is not being edited.
Available in iPhone OS 2.0 and later.
Declared in UITextField.h.
UITextFieldViewModeAlwaysThe overlay view is always displayed.
Available in iPhone OS 2.0 and later.
Declared in UITextField.h.
Notifies observers that an editing session began in a text field. The affected text field is stored in the object parameter of the notification. The userInfo dictionary is not used.
UITextField.hNotifies observers that the text in a text field changed. The affected text field is stored in the object parameter of the notification.
UITextField.hNotifies observers that the editing session ended for a text field. The affected text field is stored in the object parameter of the notification. The userInfo dictionary is not used.
UITextField.hLast updated: 2009-08-19
