TableFormEditor v1.4: text field settings

A while ago, I introduced a reusable class for producing editable forms. This article can be read here. There was also a followup article containing a detailed usage example and some bug fixes in the TableFormEditor code. I have been using this class since then, and it quickly became clear that I needed a way to configure the text fields that were used in the form. For instance, one of the fields in my app takes a URL as input, and I would have liked to use the special keyboard that is designed for that type of input. This forced me to do some research on how to configure text fields. This research culminated into these two articles: part 1 and part 2. Now it is time to put this research into the TableFormEditor class. I came up with a solution that may not be the best, but since I need to make some progress on my app, I forged ahead and implemented this solution. Comments are appreciated on other ways to do this. It currently serves its purpose and might even be deemed "clever". If you are familiar with the TableFormEditor class, you know that you provide the field labels in an array. These labels are also used as keys to a dictionary that contains the field data. The edited data is also returned in a dictionary, again keyed by the row labels. Even if you don't use the field rows as labels, you still need to provide those for keying purposes. I extended this idea by allowing you to provide text field properties for each field. These properties are set to configure the behavior of the text field, as well as the keyboard behavior. All the supported properties are described in the two-part article mentioned above. I first thought about using a dictionary to hold the properties, or creating a new class, but decided to use a real UITextField object to hold the properties. After all, this class already has all the properties I want. What you do is create a UITextField object, set all the properties you need, and put this object in a dictionary. The field labels provide the dictionary keys, just as they do for the field data dictionary. It's important to understand that these UITextField objects you create are not used in the GUI; they are only used to hold values for properties, then they are thrown away. In this sense, they serve as "prototype" UITextField objects. The reason I chose to do it this way was based purely on convenience. There was no sense creating another class with all the same properties. And when setting the properties, XCode knows what the properties and it does the code completion for you. I have modified the TableFormEditor class to have an additional property: textfieldProto This is a mutable dictionary. The keys are the label names of each field. The value for each key is a UITextField object that has all the desired properties set. I have modified the example to have 4 fields:

1. name field. For this field I would like auto correction turned off, but would like to auto capitalize the beginning of each word.
2. age. This field is all numbers, so I would like the numeric keypad to come up when this field has the focus.
3. homepage. For this, I want the URL keyboard, and turn off any auto capitalization and auto correction.
4. password. This field should use the secure key feature, which dots out each letter as you type it.

The following is the code snippet from the example that demonstrates how you create the UITextField prototype objects and set them in the TableFormEditor object:

 
   // create the dictionary to hold the text field properties
   NSMutableDictionary* textFieldProto = [[NSMutableDictionary alloc] initWithCapacity:4];
  
   // prototype for the Name field
   // shrink the font to fit, don't autocorrect, autocap first letter
   UITextField* tf = [[UITextField alloc] init];
   tf.adjustsFontSizeToFitWidth = YES;
   tf.minimumFontSize = 7.0;
   tf.autocorrectionType = UITextAutocorrectionTypeNo;
   tf.autocapitalizationType = UITextAutocapitalizationTypeWords;
 
   // add it to the dictionary
   [textFieldProto setObject:tf forKey:@"Name"];
   [tf release];
  
   // prototype for the Age field
   // use the numeric keyboard
   tf = [[UITextField alloc] init];
   tf.keyboardType = UIKeyboardTypeNumberPad;
  
   [textFieldProto setObject:tf forKey:@"Age"];
   [tf release];
  
   // prototype for the Homepage field
   // use the URL keyboard, turn off autocorrect, show clear button, autocap off
   tf = [[UITextField alloc] init];
   tf.keyboardType = UIKeyboardTypeURL;
   tf.autocorrectionType = UITextAutocorrectionTypeNo;
   tf.autocapitalizationType = UITextAutocapitalizationTypeNone;
   tf.clearButtonMode = UITextFieldViewModeAlways;

   [textFieldProto setObject:tf forKey:@"Homepage"];
   [tf release];
  
   // prototype for the Password field
   // use secure entry
   tf = [[UITextField alloc] init];
   tf.secureTextEntry = YES;
  
   [textFieldProto setObject:tf forKey:@"Password"];
   [tf release];

   // now register all the text field prototypes
   form.textFieldProto = textFieldProto;
  

The updated example XCode project is available for you to play around with, as well as the updated TableFormEditor class to support text field prototypes,  using this link.

Configuring Text Fields (Part 2)

In Part 1 of this article, I described the various properties used to modify the "look and feel" of text fields. Most of these properties deal with the visual aspects, such as font and background color. They also handle various techniques for clearing out the text in a text field. In this second part, I will focus on the virtual keyboard and the behaviors of changing your entered text (due to spelling or capitalization errors). It is likely that most people will be interested in changing some of the default behaviors. As revolutionary as the iPhone virtual keyboard is, some of the things it does can be quite annoying for some applications. At the same time, some of the customizations you can make really help the usability of your application, so it is best to understand all your options in order to make the best user experience possible. These are additional properties of the UITextField object you can change: autocapitalizationType

Setting this property determines when characters are auotmatically capitalized. The allowed enumerations are:

• UITextAutocapitalizationTypeNone
• UITextAutocapitalizationTypeWords
• UITextAutocapitalizationTypeSentences
• UITextAutocapitalizationTypeAllCharacters

None will not autocapitalize anything. Words will capitalize the first character of every word, whereas Sentences will capitalize the first character of every sentence. AllCharacters will capitalize every character. The default is None.

autocorrectionType

The autocorrection mechanism on the iPhone allows you to type "fast" and it will correct most of your mistakes. I find this works well, but in some cases I don't want this behavior. Luckily you can disable it. This property can be set to one of these values:

• UITextAutocorrectionTypeDefault
• UITextAutocorrectionTypeNo
• UITextAutocorrectionTypeYes

The Default defers to what the documentation refers to what the "script system" supports, with no explanation of what a script system is. I assume this indicates in what context the keyboard is used. The UITextField is not the only user of the keyboard. By setting autocorrectionType to Default, you will get the auto-correction behavior *if* your current script system supports it. For the purposes of UITextField, it does support auto-correction. Setting this property to No will disable auto-correction. The default is Default, which for UITextField views, means auto-correction is enabled.

enablesReturnKeyAutomatically

By default, the return key on the keyboard is enabled. However, you can change this to be disabled *until* some text has been entered in the text field. I'm not sure what use this is for text fields, but you might have a need. If you set this property to YES, then you will have this keyboard when you have no text entered:

The return key is disabled, but as soon as you entered some text, the keyboard changes to this:

keyboardAppearance

There are two types of keyboard appearances supported: one has the blue-gray background like the one above, and the other has a black background, like you see on alerts. The two enums this property supports are:

• UIKeyboardAppearanceDefault
• UIKeyboardAppearanceAlert

If you choose the alert appearance, the keyboard looks like this: As far as I can tell, there is no other difference in looks or behavior with this keyboard

keyboardType

Depending on what kind of input you are gathering in your text field, you can have different keyboards that are optimized for that type of input. The keyboardType property can be set to one of the following enums. I also show what each keyboard looks like:

UIKeyboardTypeDefault:

UIKeyboardTypeASCIICapable:

The default looks the same as this. My guess is the default can change depending on context, whereas the ASCIICapable one always look like this.

UIKeyboardTypeNumbersAndPunctuation:

This is your standard numbers and punctuation keyboard.

UIKeyboardTypeURL:

This keyboard is handy if you are typing in a URL. Also note that if you tap and hold on the .com button, you'll get a little pop-up window that will allow you to choose .edu, .net, .org, etc. Here is what that looks like:

UIKeyboardTypeNumberPad:

This is useful if all you need is to enter numbers.

UIKeyboardTypePhonePad:



This is similar to the NumberPad, but this one resembles a phone keypad, with the letters under the numbers and the "+*#" button.

UIKeyboardTypeNamePhonePad:



This looks like your standard ASCII keypad, but the difference is when you hit the digits button in the lower left, you get a phone-specific keypad:

UIKeyboardTypeEmailAddress:

 


These are slightly optimized for entering email addresses.

returnKeyType

Just the return key can be changed with different labels. Like the keyboardType property, this allows you to customize the keyboard to fit your scenario. However, many of these are very application specific and may not have much use for text fields: UIReturnKeyDefault UIReturnKeyGo UIReturnKeyGoogle UIReturnKeyJoin UIReturnKeyNext UIReturnKeyRoute UIReturnKeySearch UIReturnKeySend UIReturnKeyYahoo UIReturnKeyDone UIReturnKeyEmergencyCall I won't show what all these keyboards look like. The only difference is the label on the return key. The useful ones for most text fields would be Next and Done. When the return key is tapped, no matter what text is on it, the text field will call the textFieldShouldReturn: method on its delegate. You can use this callback as a means to do something when the return is hit. One common trick is have textFieldShouldReturn: resign the first responder, or in normal English: give up the focus, which in turn hides the keyboard.

secureTextEntry

If your text field is for entering passwords or other sensitive information, you can get the password-like entering behavior by setting this property to YES. When this is YES, only the last character entered will display in the text field; all others are replaced with a dot. Here is what is looks like:

There you have all the properties you can change to modify the keyboard and auto-correction behaviors of your text fields. Instead of accepting the defaults, you can customize your text fields and make them more user-friendly and efficient.

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.

backgroundColor

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:

borderStyle

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.

clearButtonMode

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.

clearsOnBeginEditing

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.

enabled

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.

font

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).

placeholder

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:

text

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.

textAlignment

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:

textColor

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.