With the extended amount of screen space available to you on the iPad, you have a better option. Instead of displaying the master data and detail data separately on two different screens, you can combine the two so that all of this information is visible at the same time. The release of the iPhone SDK 3.2 included new functionality specifically designed for the iPad. In this release, Apple introduced a new control called the UISplitViewController. You can use this new user interface element to display two distinct View Controllers side by side in landscape mode, as you can see in Figure 4-2. This enables you to take advantage of the extra screen space afforded by the iPad's large screen.

Figure 4.2. UISplitViewController in Landscape Mode

In portrait mode, the controller allows the user to view the detail data onscreen while popping up the master data on demand by tapping a button in the interface. Figure 4-3 shows the same View Controller as Figure 4-2, but in this case, I have rotated the iPad into portrait mode. The UISplitViewController automatically changes the display of its child View Controllers based on the orientation of the device.

The UISplitViewController does not do anything to support communication between its child View Controllers. That code is your responsibility. In the template code when you start a new Split View–based Application project, the RootViewController maintains a reference to the DetailViewController, which is set in the MainWindow.xib file. However, you are free to delete this implementation and build the communication between the two views in any way that you choose.

Figure 4.3. UISplitViewController in portrait mode

When the orientation of the device changes, the UISplitViewController calls its delegate methods. The UISplitViewControllerDelegate protocol defines these methods.

The Split View Controller calls the splitViewController:popoverController:willPresentViewController: method when the popover containing the Root View Controller should appear. This happens when the user taps the button in the toolbar while the device is in the portrait orientation. If you are using any other popover controls in your application, you should make sure that you dismiss them in this delegate method. It is a violation of the Apple Human Interface Guidelines to display more than one Popover Controller at a time. If you do, Apple will reject your application during the review process.

The Split View Controller calls the splitViewController:willHideViewController:withBarButtonItem:forPopoverController: method when the View Controller passed into the method is hidden. This occurs when the user rotates the device from landscape to portrait orientation. In this method, you need to add the button that will call the Popover Controller to the toolbar. The application template code implements this method for you.

The Split View Controller calls the splitViewController:willShowViewController:invalidatingBarButtonItem: method when the user rotates the device from portrait orientation back to landscape orientation. This indicates that the left View Controller will be displayed again. The code in this method should remove the toolbar button from the toolbar that the interface uses in portrait mode to display the popover. Again, this is implemented already if you start your project by using the Split View–based Application template.

In this chapter, you build a sample application that implements some very basic survey features. Survey takers that are out in the field collecting data could use an application like this. The application will use a UISplitViewController to display the names of the people that the user has surveyed on the left side as the master data. The right side will display the actual survey data that the user entered as the child data. Figure 4-4 shows the completed application in landscape mode.

Figure 4.4. Completed survey application

The application will allow the user to add new survey responses to the data set and view existing responses. To keep the application focused on demonstrating the user interface features that are unique to the iPad, you will not be implementing every feature that would be required for a complete application. For instance, I won't cover adding the code to modify existing surveys, or to delete surveys.

To begin the Survey application, open Xcode and create a new project. Choose to use the Split View–based Application template for the new project. Make sure that you leave the "Use Core Data for storage" checkbox unchecked. You will learn about Core Data in the next section of the book. Call your new application Survey.

Just to see the basic functionality that you get from the template code, build and run the application. When the iPad simulator starts, you will see the simulated iPad in portrait mode. Notice how the detail view takes up the whole screen. Click on the Root List button and you will see a View Controller with some data in a popover control as you saw in Figure 4-3.

Press Command+Left Arrow to rotate the iPad in the simulator. You will see the split view change to show the detail in the right pane and the root list in the left pane, as shown in Figure 4-2.

Now, you will take a brief look at the code and XIB that the template provides. First, double-click the MainWindow.xib file located in the project's Resources folder. This will open the file in Interface Builder so that you can look at the structure of the interface.

In the Interface Builder window, click the disclosure triangle next to the Split View Controller item. Next, open the Navigation Controller by clicking the disclosure icon next to it. You should now see the Root View Controller. The thing to notice here is that the Split View Controller does not actually do anything on its own. It is simply a container for the Root View Controller, which implements the left-hand pane, and the Detail View Controller, which implements the right-hand pane.

Next, select the Detail View Controller and press Command+2 to bring up the connections pane for the Detail View Controller. Click the disclosure triangle next to Multiple to see the referencing outlets for the detailViewController. You will see that the App Delegate and Root View Controller reference the detailViewController. This reference is the communication mechanism that allows the Root View Controller to set the data that the Detail View Controller will display.

Next, select the Survey App Delegate. If you look at the outlets for the Survey App Delegate, you will see that the App Delegate has references to both the Root View Controller and the Detail View Controller. You will take advantage of this in your application when you need to communicate back from the Detail View Controller to the Root View Controller.

Now let's take a brief look at the template code for the RootViewController. The RootViewController defaults to a UITableViewController, which the template places in the left pane in landscape mode and the popover in portrait mode. The template code is a straightforward implementation of a table just like you learned in the last chapter. You will find the typical TableView delegate methods numberOfSectionsInTableView:, tableView:numberOfRowsInSection:, and tableView:cellForRowAtIndexPath: implemented in this class.

The DetailViewController is a UIViewController subclass. The template creates an associated XIB file called DetailView.xib. This XIB contains the user interface elements that you will display in the detail view. By default, the XIB contains a label only. In the sample, you will add other controls to allow the user to enter and view survey data.

When the user selects an item in the RootViewController, the Table View calls the tableView:didSelectRowAtIndexPath: method. The default implementation of this method sets the detailItem property of the detailViewController, which, by default, is of type id.

Instead of synthesizing the detailItem property of the DetailViewController, there is code that implements the setter. This is a departure from most of the properties that we have seen so far. The setter is coded because you need to do some additional processing aside from simply setting the associated instance variable. The method sets the detailItem instance variable and then calls the configureView method. The configureView method updates the display to show the new detailItem data. Then, the setter dismisses the popover, if it is visible.

Now you are ready to start working on the detail view interface. First, however, there are a couple of changes that you need to make to the DetailViewController header file in preparation for the changes that you will make to the view in Interface Builder.

In the DetailViewController header, change the type of the detailItem instance variable to NSDictionary*:

NSDictionary* detailItem;

Also, change the type in the property declaration for the detailItem property:

@property (nonatomic, retain) NSDictionary*  detailItem;

Next, you will add instance variables and outlet properties for the UITextFields that you will use in Interface Builder to collect the survey data. In the @interface section, add the following instance variables:

UITextField* firstNameTextField;
UITextField* lastNameTextField;
UITextField* addressTextField;
UITextField* phoneTextField;
UITextField* ageTextField;
                                                         

Then, add the associated properties:

@property (nonatomic, retain) IBOutlet UITextField* firstNameTextField;
@property (nonatomic, retain) IBOutlet UITextField* lastNameTextField;
@property (nonatomic, retain) IBOutlet UITextField* addressTextField;

@property (nonatomic, retain) IBOutlet UITextField* phoneTextField;
@property (nonatomic, retain) IBOutlet UITextField* ageTextField;
                                                         

Next, add the clearSurvey and addSurvey IBAction methods that will execute when the user taps on the Clear or Add buttons in the interface:

-(IBAction)clearSurvey:(id)sender;
-(IBAction)addSurvey:(id)sender;

Because you will not use the detailDescriptionLabel, delete the detailDescriptionLabel instance variable and outlet property.

Now, switch over to the DetailViewController implementation file. Implement the viewDidUnload method to set the properties that hold the user interface controls to nil:

- (void)viewDidUnload {
    // Release any retained subviews of the main view.
    // e.g. self.myOutlet = nil;
    self.popoverController = nil;

    self.firstNameTextField = nil;
    self.lastNameTextField = nil;
    self.addressTextField = nil;
    self.phoneTextField = nil;
    self.ageTextField = nil;
}
                                                         

Finally, implement the dealloc method to free the memory that your interface controls use:

- (void)dealloc {
    [popoverController release];
    [toolbar release];

    [detailItem release];
    [firstNameTextField release];
    [lastNameTextField release];
    [addressTextField release];
    [phoneTextField release];
    [ageTextField release];

    [super dealloc];
}
                                                         

Now you are ready to move on to building the user interface in Interface Builder. Double-click on the DetailView.xib file to open the file in Interface Builder. Delete the UILabel that is in the view by default.

You will be building an interface like the one in Figure 4-5. Add a UILabel for each field in the interface. Change the text to match the text in Figure 4-5. Next, add a UITextField next to each of the labels that you just created. Finally, add two UIButtons at the bottom of the form and change their text to read Clear and Add.

Figure 4.5. DetailViewController interface

Now you need to connect each UITextField in Interface Builder to the appropriate outlet in File's Owner. This will enable you to retrieve the data from these controls or populate the controls with data. Finally, connect the Touch Up Inside event of the Clear button to the clearSurvey: method in File's Owner. Likewise, connect the Touch Up Inside event of the Add button to the addSurvey: method in File's Owner.

In this section, you implement the basic functionality of the application that demonstrates using the split view to show master/detail view relationships.

-(IBAction)clearSurvey:(id)sender
{
    NSLog (@"clearSurvey");
    // Update the user interface for the detail item.
    self.firstNameTextField.text = @"";
    self.lastNameTextField.text = @"";
    self.addressTextField.text = @"";
    self.phoneTextField.text = @"";
    self.ageTextField.text = @"";
}
                                                         

-(IBAction)addSurvey:(id)sender
{
    NSLog (@"addSurvey");
}

- (void)configureView {
    // Update the user interface for the detail item.
    self.firstNameTextField.text = [detailItem objectForKey:@"firstName"];
    self.lastNameTextField.text = [detailItem objectForKey:@"lastName"];
    self.addressTextField.text = [detailItem objectForKey:@"address"];
    self.phoneTextField.text = [detailItem objectForKey:@"phone"];
    self.ageTextField.text = [[detailItem objectForKey:@"age"] stringValue];
}
                                                         

NSMutableArray* surveyDataArray;

@property (nonatomic, retain) NSMutableArray* surveyDataArray;

@synthesize detailViewController,surveyDataArray;

- (void)viewDidUnload {
    // Relinquish ownership of anything that can be recreated in viewDidLoad or
    // on demand.
    // For example: self.myOutlet = nil;
    self.surveyDataArray = nil;
}


- (void)dealloc {
    [detailViewController release];
    [surveyDataArray release];
    [super dealloc];
}
                                                         

- (void)viewDidLoad {
    [super viewDidLoad];
    self.clearsSelectionOnViewWillAppear = NO;
    self.contentSizeForViewInPopover = CGSizeMake(320.0, 600.0);

    NSMutableArray* array = [[NSMutableArray alloc] init];
    self.surveyDataArray = array;
    [array release];
}
                                                         

- (NSInteger)tableView:(UITableView *)aTableView
    numberOfRowsInSection:(NSInteger)section {
    // Return the number of rows in the section.
    return [self.surveyDataArray count];
}
                                                         

- (UITableViewCell *)tableView:(UITableView *)tableView
         cellForRowAtIndexPath:(NSIndexPath *)indexPath {

    static NSString *CellIdentifier = @"CellIdentifier";

    // Dequeue or create a cell of the appropriate type.
    UITableViewCell *cell =
        [tableView dequeueReusableCellWithIdentifier:CellIdentifier];
    if (cell == nil) {
        cell = [[[UITableViewCell alloc]
                 initWithStyle:UITableViewCellStyleDefault
                 reuseIdentifier:CellIdentifier] autorelease];
        cell.accessoryType = UITableViewCellAccessoryNone;
    }

    // Configure the cell.
    NSDictionary* sd = [self.surveyDataArray objectAtIndex:indexPath.row];

    cell.textLabel.text = [NSString stringWithFormat:@"%@, %@",
                           [sd objectForKey:@"lastName"],
                           [sd objectForKey:@"firstName"]];
    return cell;
}
                                                         

- (void)tableView:(UITableView *)aTableView
    didSelectRowAtIndexPath:(NSIndexPath *)indexPath {

    /*
     When a row is selected, set the detail View Controller's detail item to the
     item associated with the selected row.
     */
    [aTableView deselectRowAtIndexPath:indexPath animated:NO];

    NSDictionary* sd = [self.surveyDataArray objectAtIndex:indexPath.row];
    detailViewController.detailItem = sd;
}
                                                         

-(void) addSurveyToDataArray: (NSDictionary*) sd;

-(void) addSurveyToDataArray: (NSDictionary*) sd
{
    NSLog (@"addSurveyToDataArray");

    // Add the survey to the results array
    [self.surveyDataArray addObject:sd];

    // Refresh the tableview
    [self.tableView reloadData];
}
                                                         

#import "RootViewController.h"
#import "SurveyAppDelegate.h"
                                                         

-(IBAction)addSurvey:(id)sender
{
    NSLog (@"addSurvey");

    // Create a new NSDictionary object to add to the results array of the root
    // View Controller

    // Set the values for the fields in the new object from the text fields of
    // the form

    NSArray *keys = [NSArray arrayWithObjects:@"firstName", @"lastName",
                     @"address", @"phone", @"age", nil];
    NSArray *objects = [NSArray arrayWithObjects:self.firstNameTextField.text,
                        self.lastNameTextField.text,
                        self.addressTextField.text,
                        self.phoneTextField.text,
                        [NSNumber
                          numberWithInteger:[ self.ageTextField.text intValue]],
                        nil];

    NSDictionary* sData = [[NSDictionary alloc]
                           initWithObjects:objects forKeys:keys];


    // Get a reference to the app delegate so we can get a reference to the
    // Root View Controller
    SurveyAppDelegate* appDelegate =
        [[UIApplication sharedApplication] delegate];
    RootViewController* rvc = appDelegate.rootViewController;

    // Call the addSurveyToDataArray method on the rootViewController to
    // add the survey data to the list
    [rvc addSurveyToDataArray:sData];

    // Clean up
    [sData release];

}
                                                         

The UIPopoverController is a container that you can use to display another View Controller anywhere on the screen on top of another view. Therefore, the first thing that you need to do when you want to display content in the popover is build the View Controller that you would like to display. For the Survey application, you will create a new class called InfoViewController. Then, you will display this class in a UIPopoverController when the user taps an informational button.

The first step is to create your new class. Add a new UIViewController subclass called InfoViewController to your project. As you add the class, make sure that the "Targeted for iPad" and "With XIB for user interface" checkboxes in the New File dialog box are selected.

Open your new InfoViewController header file. Add a UILabel* instance variable called infoLabel. Then, add an IBOutlet property that you can use to set and get your new instance variable. Finally, add a method signature for a new method called setText. You will use the setText method to set the text that you want to display in the popover. The header file for the InfoViewController should look like this:

#import <UIKit/UIKit.h>


@interface InfoViewController : UIViewController {
  UILabel* infoLabel;
}

@property (nonatomic, retain) IBOutlet UILabel* infoLabel;
-(void) setText: (NSString*) text;

@end
                                                         

Next, you will open the InfoViewController XIB file with Interface Builder to build the user interface for the new View Controller. Double-click on the InfoViewController XIB file to open it in Interface Builder. For this application, the user interface will be extremely simple, just a lone UILabel. However, you can build views that are as complex as you want with Interface Builder and use the methodology outlined here to display those interfaces using popovers.

Once you have the XIB file opened in Interface Builder, open the Attributes inspector for the View by pressing Command+1 or selecting Tools

Now that you have the view configured correctly, add a UILabel control and resize it to fill most of the view. The exact size and position are not particularly important for this example.

Finally, connect the new UILabel to the infoLabel property of File's Owner. This connects your code to the interface that you built in Interface Builder. You can now save your InfoViewController XIB file and close Interface Builder.

Now, you will need to add some logic to the InfoViewController implementation file. First, you should add code to the viewDidUnload and dealloc methods to clean up the instance variable and property of the class:

- (void)viewDidUnload {
    [super viewDidUnload];

    self.infoLabel = nil;

    // Release any retained subviews of the main view.
    // e.g. self.myOutlet = nil;
}


- (void)dealloc {
    [infoLabel release];

    [super dealloc];
}
                                                         

Next, add a line to synthesize the infoLabel property:

@synthesize infoLabel;

The next step is to implement the viewDidLoad method. In this method, you will set the size of the View Controller to display in the popover. Here is the code:

- (void)viewDidLoad {
    [super viewDidLoad];

    CGSize size;
    size.width=320;
    size.height = 175;
    self.contentSizeForViewInPopover = size;
}
                                                         

The original size of the popover comes from the View Controller's contentSizeForViewInPopover property. The default size for a UIPopoverController is 320 pixels by 1100 pixels. There are two ways that you can change the size of the popover. First, you can set the size in the View Controller that the popover will hold by setting the View Controller's size using the contentSizeForViewInPopover property. Alternatively, you can set the size of the popoverContentSize property of the Popover Controller. Keep in mind that if you use this method and change the View Controller that you are displaying in the popover, the popover will automatically resize to the size of the new View Controller. The custom size that you set in the popoverContentSize property is lost.

In this example, you created a CGSize struct to define the size of the popover in the View Controller. You set the size to 320 pixels wide by 175 pixels high. Then, you set the contentSizeForViewInPopover property on the View Controller.

Finally, you need to implement the setText method that clients who want to display the InfoViewController will use to set the text to display. This method does nothing more than set the text in the UILabel:

-(void) setText: (NSString*) text
{
    self.infoLabel.text = text;
}
                                                         

Now that you have a View Controller, you need to display it in a popover. You will display the popover when the user taps a button in the DetailViewController. Therefore, you will need to make some changes to the DetailViewController header file. First, add a #import statement for the new InfoViewController.h header file:

#import "InfoViewController.h"

Next, you will add a new action method called showInfo. The user will invoke this method when he taps on the information button in the user interface. Here is the declaration:

-(IBAction)showInfo:(id)sender;

The next step is to add a new outlet and instance variable for the UIButton* called infoButton. Inside of the interface declaration, add the instance variable for the UIButton*:

UIButton* infoButton;

Outside of the interface declaration, declare the infoButton property:

@property (nonatomic, retain) IBOutlet UIButton* infoButton;

Now add an instance variable for the UIPopoverController. Call it infoPopover:

UIPopoverController *infoPopover;

Add a property for the infoPopover:

@property (nonatomic, retain) UIPopoverController *infoPopover;

Now you need to move over to the DetailViewController implementation file.

In the implementation, synthesize the new infoButton and infoPopover properties:

@synthesize infoButton,infoPopover;

Next, you will implement the showInfo method to show the InfoViewController in the infoPopover:

-(IBAction)showInfo:(id)sender
{
    NSLog (@"showInfo");

    // Instatiate Info View Controller
    InfoViewController *ivc = [[InfoViewController alloc] init];

    UIPopoverController *popover =
        [[UIPopoverController alloc] initWithContentViewController:ivc];

    [ivc setText:@"If the survey taker refuses, that is okay"];

    [ivc release];

    // Set the infoPopover property
    self.infoPopover = popover;

    // Clean up the local popover
    [popover release];

    [self.infoPopover presentPopoverFromRect:self.infoButton.frame
                                      inView:self.view
                    permittedArrowDirections:UIPopoverArrowDirectionAny
                                    animated:YES];

}
                                                         

The first thing that you do in this method, after logging the method name, is create an instance of the InfoViewController.

Next, you allocate a UIPopoverController and initialize it by calling the initWithContentViewController method. You pass the View Controller that you want to display in the popover as a parameter to this method. Next, you set the text that you want to display in the popover and release the InfoViewController. You must send the InfoViewController the release message or you will leak memory. When you pass the View Controller in to the popover in the initWithContentViewController method, the popover will retain the View Controller.

The next step is to set the infoPopover property to the new popover that you created in this method. Then, you can release the local popover.

Finally, you call the presentPopoverFromRect:inView:permittedArrowDirections:animated: method to present the popover. The first parameter to this method specifies the CGRect structure from which the popover should emanate. In this example, you use the frame of the info button that you will add to the user interface. Then, you specify the view that will hold the popover. The permittedArrowDirections parameter allows you to specify from which direction the popover will appear with respect to the frame that you specified in the first parameter. Generally, you should specify any direction as permitted and leave the layout and positioning of the popover to the UIKit framework. The permitted directions are specified using members from the UIPopoverArrowDirection enumeration. Valid direction values are:

Finally, the last parameter specifies whether the framework should animate the display of the popover.

The last step is to clean up the infoButton and infoPopover properties in the dealloc and viewDidUnload methods:

- (void)viewDidUnload {
    // Release any retained subviews of the main view.
    // e.g. self.myOutlet = nil;
    self.popoverController = nil;

    self.firstNameTextField = nil;
    self.lastNameTextField = nil;
    self.addressTextField = nil;
    self.phoneTextField = nil;
    self.ageTextField = nil;

    self.infoButton = nil;
    self.infoPopover = nil;
}

- (void)dealloc {
    [popoverController release];
    [toolbar release];

    [detailItem release];
    [firstNameTextField release];
    [lastNameTextField release];
    [addressTextField release];
    [phoneTextField release];
    [ageTextField release];
    [infoButton release];
    [infoPopover release];
    [super dealloc];
}
                                                         

Now, you need to add the info button to the user interface in Interface Builder. Open the DetailView.xib file in Interface Builder. Add a new UIButton next to the age UITextField. In the attributes inspector for the button, change the type of the button to Info Dark. This will change the button from a rounded rectangle to a gray circle with a white letter i inside.

Next, wire the File's Owner infoButton property to the new button. Then, wire the infoButton's touchUpInside event to the File's Owner showInfo method.

You are finished with the interface so you can save the XIB file and close Interface Builder.

Build and run the application. When the interface appears, tap the new info button. You should see the message appear in a popover next to the info button.

The UIGestureRecognizer class is an abstract base class that defines what gesture recognizer classes must do and how they should operate. Apple has provided the concrete subclasses UIPinchGestureRecognizer, UIPanGestureRecognizer, and UISwipeGestureRecogsnizer that you can use in your applications to recognize pinch, pan, and swipe gestures respectively. This saves you from having to write the significant amount of code required to interpret a series of touches as one of these common gestures. However, if your application requires gestures that the framework does not support, you can implement your own custom gesture recognizer as a UIGestureRecognizer subclass to define any gesture that your application may need.

To use a gesture recognizer, you must attach the gesture recognizer to a view. When you attach a gesture recognizer to a view, the framework routes touches in the application to the gesture recognizer before sending them to the view. This gives the gesture recognizer the chance to evaluate the touches to see if they qualify as a gesture. If the touches meet the requirements of a gesture, the framework cancels the touch messages and instead of sending the touches to the view, the framework sends a gesture message instead. If the touches do not qualify as a gesture, the framework sends the touches to the view.

There are two different types of gestures, discrete and continuous. A discrete gesture, such as a tap, causes the gesture recognizer to simply send one action message when the action is complete. A continuous gesture, like a pinch, results in the gesture recognizer calling the action message multiple times until the continuous action is completed.

You implement a gesture recognizer in your code by instantiating a gesture recognizer concrete class. This can be one of the Apple provided classes mentioned above, or your own custom subclass of UIGestureRecognizer. Then, you assign a target and an action to the recognizer. The target is the class that will receive the action and the action is the method that the gesture recognizer will call when a gesture is recognized. Finally, you attach the gesture recognizer to the view in which you want gestures recognized.

In this section, you will add gesture recognizers to your Survey application. You will use a UISwipeGestureRecognizer to determine if the user has swiped across the DetailViewController screen. If he has, you will navigate either forward or backward in the survey list, depending on the direction of the swipe, and display the appropriate record.

The first step in using a gesture recognizer is to create an instance of the recognizer that you want to use and attach it to a view. You will do this in the viewDidLoad method of the DetailViewController like this:

- (void)viewDidLoad {
    [super viewDidLoad];

    // Create the right swipe gesture recognizer
    UISwipeGestureRecognizer *swipeRight = [[UISwipeGestureRecognizer alloc]
        initWithTarget:self action:@selector(handleSwipeRight:)];

    swipeRight.direction=UISwipeGestureRecognizerDirectionRight;

    // Attach it to the view
    [self.view addGestureRecognizer:swipeRight];


    // Create the left swipe gesture recognizer
    UISwipeGestureRecognizer *swipeLeft = [[UISwipeGestureRecognizer alloc]
        initWithTarget:self action:@selector(handleSwipeLeft:)];

    swipeLeft.direction=UISwipeGestureRecognizerDirectionLeft;

    // Attach it to the view
    [self.view addGestureRecognizer:swipeLeft];


    // Clean up
    [swipeRight release];
    [swipeLeft release];
}
                                                         

First, you call the superclass viewDidLoad method to ensure that the class is set up correctly.

Next, you create an instance of the UISwipeGestureRecognizer. In creating this instance, you need to specify the target class that will receive the action method call when the gesture recognizer detects a swipe. The action parameter specifies the method that the gesture recognizer should call when it detects the gesture. In this case, the target is self and the method the gesture recognizer will call is handleSwipeRight, which you will implement in a moment.

After you create an instance of the UISwipeGestureRecognizer, you need to specify which swipe direction you want to detect. Here, you have specified that you would like to detect swipes to the right.

Finally, you add the gesture recognizer to the view by calling the view's addGestureRecognizer method, passing in the gesture recognizer.

The code then goes on to perform the same procedure to attach another swipe gesture recognizer to the view. This time, you configure the recognizer to detect swipes to the left. You have also set this gesture recognizer to call the handleSwipeLeft method as its action.

Lastly, you release both of the gesture recognizers that you created in this method.

In the DetailViewController header, add action methods for the gesture recognizers handleSwipeRight and handleSwipeLeft:

-(void)handleSwipeRight:(UIGestureRecognizer*) sender;
-(void)handleSwipeLeft:(UIGestureRecognizer*) sender;
                                                         

In order to be able to implement the functionality to navigate forward and backward in the survey array using gestures, you have to add a variable and a couple of methods to the RootViewController. In the RootViewController header file, add an instance variable of type int called currentIndex. You will use this variable to maintain the index of the record that you are displaying in the DetailViewController. Here is the declaration:

int currentIndex;

You also need to add declarations for two new methods, moveNext and movePrevious. The gesture recognizer action methods will call these methods on the RootViewController to tell the RootViewController to navigate to the next or previous record. Here are the declarations for the moveNext and movePrevious methods:

-(void) moveNext;
-(void) movePrevious;
                                                         

In the RootViewController implementation, you will need to add code to the viewDidLoad method to initialize the currentIndex instance variable:

- (void)viewDidLoad {
    [super viewDidLoad];
    self.clearsSelectionOnViewWillAppear = NO;
    self.contentSizeForViewInPopover = CGSizeMake(320.0, 600.0);

// Set up surveyDataArray
    NSMutableArray* array = [[NSMutableArray alloc] init];
    self.surveyDataArray = array;

    // Initialize the current index
    currentIndex = 0;
}
                                                         

Next, you need to modify the tableView:didSelectRowAtIndexPath: method to set the currentIndex instance variable to the row that the user has selected in the table:

- (void)tableView:(UITableView *)aTableView
    didSelectRowAtIndexPath:(NSIndexPath *)indexPath {

    /*
     When a row is selected, set the detail View Controller's detail item to the
     item associated with the selected row.
     */
    [aTableView deselectRowAtIndexPath:indexPath animated:NO];

    NSDictionary* sd = [self.surveyDataArray objectAtIndex:indexPath.row];
    detailViewController.detailItem = sd;

    // Set the currentIndex
    currentIndex = indexPath.row;

}
                                                         

Finally, you will implement the moveNext and movePrevious methods:

-(void) moveNext
{
    NSLog (@"moveNext");
    // Check to make sure that there is a next item to move to
    if (currentIndex < (int)[self.surveyDataArray count] −1)
    {

NSDictionary* sd = [self.surveyDataArray objectAtIndex:++currentIndex];
        detailViewController.detailItem = sd;
    }
}

-(void) movePrevious
{
    NSLog (@"movePrevious");
    // Check to make sure that there is a previous item to move to
    if (currentIndex > 0)
    {

        NSDictionary* sd = [self.surveyDataArray objectAtIndex:--currentIndex];
        detailViewController.detailItem = sd;
    }

}
                                                         

In the moveNext method, you first check to make sure that the next record exists. If it does, you increment the currentIndex, get the object at the new index from the surveyDataArray, and set the detailItem of the DetailViewController to the corresponding NSDictionary.

The movePrevious method is the same with one minor exception. You need to test to make sure that the user is not trying to navigate backward if the current index is already 0.

Back in the DetailViewController implementation, you are ready to implement the handleSwipeRight and handleSwipeLeft methods:

-(void)handleSwipeRight:(UIGestureRecognizer*) sender
{
    NSLog (@"handleSwipeRight");
    // Get a reference to the app delegate so we can get a reference to the
    // Root View Controller
    SurveyAppDelegate* appDelegate =
        [[UIApplication sharedApplication] delegate];
    RootViewController* rvc = appDelegate.rootViewController;

    // Call the movePrevious method on the rootViewController to move to the
    // previous survey in the list
    [rvc movePrevious];
}

-(void)handleSwipeLeft:(UIGestureRecognizer*) sender
{
    NSLog (@"handleSwipeLeft");
    // Get a reference to the app delegate so we can get a reference to the
    // Root View Controller
    SurveyAppDelegate* appDelegate =
        [[UIApplication sharedApplication] delegate];
    RootViewController* rvc = appDelegate.rootViewController;

    // Call the moveNext method on the rootViewController to move to the
    // next survey in the list
    [rvc moveNext];
}
                                                         

In the handleSwipeRight and handleSwipeLeft methods, you do almost the same thing. First, you get a reference to the app delegate so that you can get a reference to the RootViewController. Then, you call the appropriate method, either moveNext or movePrevious, on the RootViewController.

Build and run the application. You should be able to add new surveys to the application. Then, select a row, or just start with the first row. Swipe right in the DetailViewController and the application should display the data in the DetailViewController for the next entry in the completed survey list. Swiping to the left should display the detail information for the previous entry in the list.

First, you need to add a new key, UIFileSharingEnabled, to the Survey-Info.plist file. This file is located in the Resources folder of your Xcode project. You can add this key inside of Xcode by first selecting the Survey-Info.plist file in the browser pane. You should see the plist file displayed in the right hand pane. Click in the right hand margin next to any of the plist entries and you will see a plus sign appear. Click the plus sign to add a new entry to the plist. In the dropdown list that appears, select "Application supports iTunes file sharing." To the right of the key, you will then see a box with a checkmark in it. Leave the box checked to enable file sharing.

That is all that you need to do to enable file sharing.

Next, you will add code to serialize the surveyDataArray and store the serialized file in the /Documents folder for the application.

When the user installs an application on an iPhone or iPad, the installation process creates a home directory for that application. Each application has its own home directory. You should write your application data files to the /Documents directory. Additionally, iTunes backs up this directory when the user syncs the device with a computer.

Now that you understand where to save the application data, you will add code to the applicationWillTerminate method in the SureveyAppDelegate to serialize the array and save it to a file. Serialization simply takes a data structure that is stored in memory, in this case an array, and converts it to a format that can be saved to a file or sent over a network. Here is the implementation:

- (void)applicationWillTerminate:(UIApplication *)application {
    // Serialize the rootViewController's surveyDataArray
    NSData *serializedData;
    NSString *error;

    serializedData = [NSPropertyListSerialization
                      dataFromPropertyList:rootViewController.surveyDataArray
                      format:NSPropertyListXMLFormat_v1_0
                      errorDescription:&error];

    if (serializedData)
    {
        // Serialization was successful, write the data to the file system
        // Get an array of paths.
        // (This function is carried over from the desktop)
        NSArray *documentDirectoryPath =
            NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,
                                                NSUserDomainMask, YES);
        NSString *docDir = [NSString stringWithFormat:@"%@/serialized.xml",
                            [documentDirectoryPath objectAtIndex:0]];

        [serializedData writeToFile:docDir atomically:YES];
    }
    else
    {
        // An error has occurred, log it
        NSLog(@"Error: %@",error);
    }
}
                                                         

First, you serialize the data in the surveyData array by using the NSPropertyListSerialization class. This class provides methods that covert the types of objects that you can use in a property list (NSData, NSString, NSArray, NSDictionary, NSDate, and NSNumber) into different serialized forms. In this case, you will convert an NSArray into XML format. I chose XML for this example so that you could open the file on your computer after syncing with iTunes and verify that the data in the file is the same as the data that is contained in the application. For production applications, it is generally more efficient to use the binary format.

After serializing the array to XML, the code obtains the path to the /Documents directory for the application. Here, you use the NSSearchPathForDirectoriesInDomains function to obtain the path to the /Documents directory by passing in the NSDocumentDirectory constant as the directory parameter. The NSSearchPathDirectory enumeration provides several predefined constants that you can use to help you to navigate to specific directories.

Next, you use the path to the /Documents directory to build a string that represents the file that you want to save. Finally, you call the writeToFile method of the serializedData object to write the XML to a file.

Now that you have written code to save the survey data array to disk, you need to add code to load the array from disk when the application starts. The process of taking the data from its on-disk format and turning it back into an object is called deserialization. You will do that in the RootViewController's viewDidLoad method. Modify the viewDidLoad method to use the data from the plist, if it exists, like this:

- (void)viewDidLoad {
    [super viewDidLoad];
    self.clearsSelectionOnViewWillAppear = NO;
    self.contentSizeForViewInPopover = CGSizeMake(320.0, 600.0);

    // Set up surveyDataArray
    // Get an array of paths. (This function is carried over from the desktop)
    NSArray *documentDirectoryPath =
    NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,
                                        NSUserDomainMask, YES);
    NSString *docDir = [NSString stringWithFormat:@"%@/serialized.xml",
                        [documentDirectoryPath objectAtIndex:0]];
    NSData* serializedData = [NSData dataWithContentsOfFile:docDir];

    // If serializedData is nil, the file doesn't exist yet
    if (serializedData == nil)
    {
        NSMutableArray* array = [[NSMutableArray alloc] init];
        self.surveyDataArray = array;
        [array release];
    }
    else
    {
        // Read data from the file
        NSString *error;

        self.surveyDataArray =
        (NSMutableArray *)[NSPropertyListSerialization
                           propertyListFromData:serializedData
                           mutabilityOption:kCFPropertyListMutableContainers
                           format:NULL errorDescription:&error];
    }

    // Initialize the current index
    currentIndex = 0;
}
                                                         

This code is the opposite of the code that you wrote in the previous section. First, you create the file name the same way that you did before using the NSSearchPathForDirectoriesInDomains function. Then, you create an NSData object from the serialized file by calling the dataWithContentsOfFile method.

Next, you need to check if the serialized data exists. If there is no data, you need to create a new NSMutableArray* to hold the completed surveys. If there was data, you populate the surveyDataArray from the NSData object by calling the propertyListFromData:mutabilityOption:format:errorDescription: method of the NSPropertyListSerialization class.

Now you are ready to build and run the application on an iPad device. Add some survey data and then quit the application.

To retrieve the data from the iPad, hook your iPad up to your computer and sync it with iTunes. Click on the iPad under Devices in iTunes and select the Apps tab. If you scroll to the bottom, you should see Survey listed as one of the applications in the Apps box, as in Figure 4-7. Click on Survey and you should see serialized.xml in the Survey Documents window. Click on serialized.xml and click the Save to button. Save the file to your desktop or some other convenient location.

Figure 4.7. Survey application and data in iTunes

You should be able to navigate to that XML file using the Finder. If you open the XML file, you should see an XML representation of your data. The XML for the sample data looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/
    PropertyList-1.0.dtd">
<plist version="1.0">
<array>
    <dict>
        <key>address</key>
        <string>123 Any St.</string>
        <key>age</key>
        <integer>20</integer>
        <key>firstName</key>
        <string>John</string>
        <key>lastName</key>
        <string>Smith</string>
        <key>phone</key>
        <string>555-1234</string>
    </dict>
    <dict>
        <key>address</key>
        <string>789 Town St.</string>
        <key>age</key>
        <integer>40</integer>
        <key>firstName</key>
        <string>Doris</string>
        <key>lastName</key>
        <string>Jones</string>
        <key>phone</key>
        <string>555-1234</string>
    </dict>
</array>
</plist>