April 2, 2009

Configuring Text Fields (Part 1)

For something as seemingly simple as the UITextField view, it is a fairly rich control. Because of the limitations of the iPhone interface, the text field can be customized in many different ways to make it easier to use. This two-part article will attempt to shed some light on all the options used to configure the text field, as they are lightly documented in the SDK documentation. Even the iPhone "Bible" (Beginning iPhone Development) only gives it a cursory mention. Most of the configurations on a UITextField object is done through properties. In Part 1, I describe the properties used for modifying the behavior and look of text fields. In the follow-up Part 2, I describe the properties used to configure the virtual keyboard that is associated with each text field. So on to the properties:
adjustsFontSizeToFitWidth minimumFontSize
As you enter text in a text field and you reach the end of the field, it will scroll left so that what you are typing will stay visible. The following image shows what this looks like when entering a long input:
The text at the beginning of the text field has scrolled to the left so that it is no longer visible. If you want to support long input but not scroll, you can set the adjustsFontSizeToFitWidth property to YES so that the font will reduce in size in order for the entire input to remain visible. Here is what a long line looks like with this option set to YES:
See how the font got smaller? Of course, the font won't get infinitely smaller, else you wouldn't be able to read it. Once the font size reaches its minimum size, it begins to scroll. The text in the image above was the smallest it would get. The next character I typed started the field scrolling. While this technique helps a little, it really doesn't offer much more vertical space. According to the documentation, there is another property called minimumFontSize that allows you to specify what the minimum is before the shrinking stops and the scrolling starts. By default, this value is 0.0. But no matter how I changed this property, the font shrinking behavior never changed. This may be a limitation in the iPhone Simulator, as I did not try this on a real iPhone.
background disabledBackground
The background property allows you to provide a background image for the text field. The image will be scaled to fit the field. Here is an example of a text field with a custom background:
Although it appears the image does not fill up the entire text field, be aware that my text field example lives inside a table cell, which has its own border around it. The disabledBackground property is similar, but is used when the text field is disabled. This property is ignored unless the background property is also set.
You can change the background color from the default white to any color. If you have a background image specified, it will override your backgroundColor settings. Here is a text field with a red background:
If you have no background image, you can change the border style of the text field. This property can be set to one of four possible enums. The following image shows what the border style looks like with the enum name entered in the text field:
The default is UITextBorderStyleNone.
This property allows you to put a little "x" button on the right to quickly clear out the contents of the text field. It looks like this:
This property can be set to one of several enumerations, which determine when this clear button is shown:
  • UITextFieldViewModeNever
  • UITextFieldViewModeWhileEditing
  • UITextFieldViewModeUnlessEditing
  • UITextFieldViewModeAlways
The WhileEditing enum will only show the button while you are editing that particular text field. The UnlessEditing enum will do the opposite: it will show the button when you are not editing the field, and hide it when you are editing. In this context, editing means that the field has the focus. Never and Always should be obvious. The default value is UITextFieldViewModeNever.
Here is another property for controlling clearing the contents of a text field. When this is set to YES, the field will remove whatever is there when it gets the focus. By default, this is set to NO.
By default, your text fields are enabled, meaning they can accept input. If for some reason you wanted to disable a text field (making it read-only), then set the enabled property to NO. Disabling a text field doesn't change its appearance. However, if you are setting a custom background via the background property, and have also set a disabledBackground property, then this latter property will go in effect if the text field is disabled.
This changes the font of the text inside a text field. It takes a UIFont object. Here is an example of setting the font to [UIFont italicSystemFontOfSize:16.0]:
The default font is 12-point Helvetica plain.
leftView leftViewMode
These two properties allow you to put a view, like an image, on the left side of the text field. Any image will be scaled to fit the space. Here is an example of putting a little magnifying glass icon there:
Just setting leftView to an image is not enough, though. You also have to set the mode. The modes are the same as for clearButtonMode. The default is UITextFieldViewModeNever. This property accepts any view, as the name implies, so you could even put a button here (this is how the clearButton does it).
When this is set to a string, it displays that text when there is no text in the text field. As soon as you start entering text, the placeholder disappears. It simply gives you a hint as to what is supposed to be entered in the text field. Here is what it looks like:
Notice how the font color is not so dark. By default, the placeholder is empty.
rightView rightViewMode
These two properties work the same as leftView and leftViewMode, except it deals with the space on the right hand side of the text field. Here is what that looks like:
This property contains the text that is displayed on the text field. It is a read/write property, so you can pre-populate the text in a text field before showing it. And, of course, you can read the text so you know what the user entered.
The allows you to align the text in the text field horizontally. This setting also applies to any placeholder text. The allowed values are:
  • UITextAlignmentLeft
  • UITextAlignmentCenter
  • UITextAlignmentRight
The default is UITextAlignmentLeft. Here are three text fields, each with a different textAlignment setting:
You can change the text color from the default black. Here is an example of setting the text color to [UIColor redColor]:
There you have most of the properties that affect the behavior and look of a text field. In the next part, I will cover the properties that have to do with the virtual keyboard.

No comments:

Post a Comment