While user interfaces on Apple iOS apps are often composed of fun things like buttons, sliders, and gestures, sooner or later you'll write an app that needs good old-fashion text input. In this post we're going to build a simple project to learn how to use UITextField to gather text-based input.
If you're familiar with creating a basic Single-View project, feel free to go ahead and do so now and then skip down to "Setting Up the User Interface." Otherwise, follow along below to create a new project.
Open Xcode and from the File menu, select New, and then New Project. A new workspace window will appear, and you will be presented with several application templates to choose from.On the left-hand side, select Application from the iOS section. Select Single View Application and click the Next button. (Figure A)
On the next pane, enter TextMe for the Product Name and com.myappcompany as the Company Identifier. (Feel free to substitute your own product name and company identifier).
Leave the Class Prefix as is. It should be blank - XYZ is just a placeholder hint.
Make sure Use Automatic Reference Counting is checked and uncheck the others.
A new pane will appear asking you where you would like to save the project. XCode will create a TextMe project folder inside the directory you select.
Once the project is created, Xcode will open a workspace window with your new project.
Setting up the user interface
In the Files and Groups pane, click on ViewController.xib. After it opens in Interface Builder, select the View object, click on the Attributes Inspector and then change the view's background color to something other than white.
(Graphic design tip: it's generally not optimal to pick solid black as a background color for a view. Pure black creates a very intense, demanding feel that can easily become tiresome to the eyes if overused. Save pure black for Really Important Things, and use shades of gray when you just want a dark background.)Next go to the Object Library located on the lower right-hand side of the workspace and drag a UITextField onto the view. Drag it's resize handles to make it approximately the width of the view. Figure C summaries the situation so far.
We are now ready to wire up the UITextField and begin to experiment with it. First, we'll connect an outlet to our ViewController class so that we can manipulate the text field's properties and retrieve its value. (See Getting started with iOS Views and View Controllers: Part 2 to learn more about outlets.)
Click the Assistant Editor button in the upper right corner of the workspace. This will open ViewController.h in the window adjacent to the Interface Builder View. Control-drag from the UITextField to a point just under the word @interface and release the mouse; Xcode will display a popup window to help you establish the outlet.Enter "myTextField" in the Name field and click on Connect. Xcode will create a property definition for our UITextField, declare it as an IBOutlet, and connect it to the UITextField in our xib. Click the Standard Editor button to return to standard editing mode. Figure D shows the outlet connection dialog and the locations of the Editor buttons.
At this point we have a connection that we can use to set and retrieve the value of the text field, but we will need more than that to enable our user to enter data with the onscreen keyboard.
UITextField supports the use of a delegate object to handle editing-related notifications. When certain actions occur, the UITextField will call delegate methods that allow its behavior to be customized and controlled. The various methods are described in detail in the UITextFieldDelegate Protocol Reference. We will want our ViewController class to serve as the delegate, and to do so it must conform to the protocol. Let's set that up now.
In the Files and Groups pane, select ViewController.h and make the change shown in bold below.
@interface ViewController : UIViewController <UITextFieldDelegate>
@property (strong, nonatomic) IBOutlet UITextField *myTextField;
With this in place, Xcode now expects our class to conform to the protocol and will also be able to give us autocomplete assistance when we're typing in method signatures.We also need to tell the UITextField who its delegate will be. Select ViewController.xib and control drag from the UITextField to Files Owner; when you release the mouse, select 'delegate' from the popup as shown in Figure E.
Build and run the application and tap in the text field. The onscreen keyboard should now appear and we can enter text. Unfortunately, that's all we can do. Tapping the Return key does not dismiss the keyboard, and our class has no idea that any text has been entered. We will need to implement just one delegate method to make everything work.
Select ViewController.m and enter the following new method below the ViewDidLoad.
- (BOOL)textFieldShouldReturn:(UITextField *)textField
NSLog(@"You entered %@",self.myTextField.text);
Per the protocol, when we tap Return the text field will now call the textFieldShouldReturn: delegate method in our class. This gives us a chance to do whatever we need to with the contents of the field and then dismiss the keyboard by calling resignFirstResponder. Build and run the app again. When you tap the Return key, the text you entered appears in the Xcode console log. UITextField is quite powerful, but this one simple method is all you need to begin gathering text input in your apps.
UITextField AttributesMuch of the power of UITextField comes from configuring its attributes. Take some time to explore the various attributes shown in Figure E that allow you to alter the appearance and behavior of both the text field and the keyboard. For example, in Figure F the drop down box shows other possible ways for the Return key to appear.
Another affordance you'll want to explore is the Clear Button. In Figure E it's set to 'Appears while editing', which will cause the text field to make a clear button available within the field while the keyboard is showing. Tapping the clear button erases all of the text in the field in one simple motion.
UITextField is a fundamental tool in every iOS programmer's tool box. With this basic understanding in hand, you're well on your way to using it effectively.
Scott Kantner started his IT career on a Radio Shack TRS-80 model I back in 1978. He is CTO of a hosting/colocation firm, a tech writer, and an avid iOS app developer. He has several music-related apps in the App Store that you can learn about at OnStageTechnologies.com. Scott can be reached at firstname.lastname@example.org.