UITextField : A Complete API Overview

The UITextField is probably one of the most commonly used UI controls on the iPhone. It is the primary method of user input via the keyboard and provides a great deal of additional functionality.

With the success of our las API tutorial on NSArray, I thought I would do another walkthrough, this time on UITextField. I will be explaining all of the properties for it as well as bringing up some functionality that you may not have known about.

Text Attributes

The attributes have to do with the actual text inside of the UITextField.

text	The text displayed in the UITextField
placeholder	The text that gets displayed prior to the user entering in anything. This text is usually a lighter color than the primary text to denote that it will be replaced.
font	The font of the text to be displayed. You can set it like this
textColor	The color of the text that is displayed
textAlignment	How the text is aligned in the UITextField. The possible values for this are UITextAlignmentLeft, UITextAlignmentRight, UITextAlignmentCenter

Here are some examples of using these properties.

// Setting the text
[myTextField setText:@"This is some text!"];
 
// Setting the placeholder
[myTextField setPlaceholder:@"Type text here"];
 
// Setting the font.
[myTextField setFont:[UIFont fontWithName:@"Times New Roman" size:14]];
 
// Setting the text color
[myTextField setTextColor:[UIColor blueColor]];
 
// Setting the text alignment
[myTextField setTextAlignment:UITextAlignmentCenter];

Here is what the UITextField would look like after we update these properties.

Adjusting the size of the text in the UITextField

The text displayed in our UITextField can be dynamically sized based on the width of the UITextField. The benefit of this is all of the text being typed will be visible on the screen. It will shrink the text down until it reaches the default font size of 17. So, for this to make sense, you must set the font size of the UITextField to something larger than 17.

adjustsFontSizeToFitWidth

Boolean value denoting whether to fit the font size to the width of the UITextField.

Here is an example of using these properties.

[myTextField setFont:[UIFont fontWithName:@"Times New Roman" size:30]];
[myTextField setAdjustsFontSizeToFitWidth:YES];

Here are some screenshots of the text shrinking when typing in the UITextField.

Managing the editor’s behavior

These two properties are pretty straight forward.

editing	Read-only boolean value letting you know if the user is currently editing the UITextField
clearsOnBeginEditing	Clears the text in the field every time the user begins to edit it.

Not very exciting and probably doesn’t even deserve an example…

Setting the view’s background appearance

This group of properties defines how the UITextField will look. If you have ever seen a fancy input box, this is how they are doing it.

borderStyle	Defines the type of border for the UITextField. Possible choices are UITextBorderStyleNone, UITextBorderStyleLine, UITextBorderStyleBezel, and UITextBorderStyleRoundedRect. The default is UITextBorderStyleNone.
background	A UIImage representing the background image of the UITextField when it’s enabled. If this field is altered the borderStyle property is ignored.
backgroundDisabled	A UIImage representing the background image of the UITextField when it’s disabled.

Here is are some example of using each of the border styles

// Border Style None
[myTextField setBorderStyle:UITextBorderStyleNone];

// Border Style Line
[myTextField setBorderStyle:UITextBorderStyleLine];

// Border Style Bezel
[myTextField setBorderStyle:UITextBorderStyleBezel];

// Border Style Rounded Rect
[myTextField setBorderStyle:UITextBorderStyleRoundedRect];

The border style is not terribly exciting. However, you can really spruce up your UITextFields using the background property. Here is an example of setting the background property to this image.

myTextField.textAlignment = UITextAlignmentCenter;
myTextField.textColor = [UIColor whiteColor];
myTextField.borderStyle = UITextBorderStyleNone;
myTextField.background = [UIImage imageNamed:@"bg.png"];

and the result… Looks pretty good ehh? One GOTCHA that I want to point out here is, to get the background property to work correctly, you must set the boderStyle to anything other than UITextBorderStyleRoundedRect. Otherwise, the default UITextField will be displayed.
Setting the view’s background appearance

Managing Overlay Views

Another interesting way of customizing your UITextFields is to use an overlay. UITextField offers a left and right overlay for your UITextFields. Here are the properties:

clearButtonMode	The circled X that gets displayed when typing. Used to clear out the text. Possible values: UITextFieldViewModeNever, UITextFieldViewModeWhileEditing, UITextFieldViewModeUnlessEditing, UITextFieldViewModeAlways
leftView	The view that appears to the left inside a UITextField. This could be something like a magnifying glass for search.
leftViewMode	Works like clearButtonMode, but toggles the leftView.
rightView	Same as leftView, except it aligns to the right.
rightViewMode	Same as leftViewMode but controls the rightView

Let’s take a look at how adjusting the leftView works:

UIImageView * myView = [[ UIImageView  alloc ]  initWithImage :
  [UIImage  imageNamed : @"wordpress.png" ]];
[myTextField  setLeftView :myView];
[ myTextField   setLeftViewMode: UITextFieldViewModeAlways];
[myView release ];

As you can see, the text aligns after the image. This is a very simple way to really spruce up your UITextFields.

The last thing we are going to discuss is showing and hiding the keyboard.

Showing and Hiding The Keyboard

To show the keyboard:

[myTextField becomeFirstResponder];

To hide the keyboard

[myTextField resignFirstResponder];

Well, I hope you have enjoyed this tutorial on the UITextField.  I would love to see links to some interesting custom UITextFields in the comments, so please post them.  Thanks for reading and happy iCoding!