Split View Controller Basic Use

The Split View Controller is an iPad specific container view controller for managing two view controllers, a master in the left and a detail on the right. A prime example of the Split View Controller can be seen with the iPad Mail app which list messages and mailboxes in the master panel and displays the content of the currently selected message in the detail panel-see Figure 1 below. If the user put the iPad device in portrait orientation, only the detail view control is shown on screen-see Figure 2 below. The remainder of this tutorial demonstrates the basic use of the split view controller.

Figure 1: iPad Mail app in landscape orientation	Figure 2: iPad Mail app in portrait orientation

Create a New Master Detail Application

To get started, launch Xcode and create a new project. Select the “Master Detail” application template and set options shown in Figure 3 below for the project. As you can see in Figure 4 below, the template created a storyboard file and three class files in the Project Navigator panel. Further more, the template added a split view controller, two navigation controller, and two view controllers (Master and Detail) on the storyboard canvas.

Figure 3: Options for the Master-Detail Application	Figure 4:

Run The Application

Run the application on the iPad Simulator and you will see output in portrait orientation by default. Switching to landscape orientation, you will see output shown in Figure 6. To switch to landscape orientation, select the iPad Simulator’s Hardware | Rotate Left or Rotate Right menu item.

Figure 5: SplitView app in portrait orientation	Figure 6: SplitView app in landscape orientation

You don’t have to rotate the iPad Simulator to see the Master view; just click the navigation bar’s Master button. To hide the Master view once again, just click anywhere outside the Master view.

Figure 7: Master view in portrait orientation

Configure The Master View Navigation Bar and Table View Control

The first order of business is to add code in the MasterViewController class files so its view look like this:

Figure 8: Master View and Navigation Bar

Here is the code to add in the MasterViewController class files.

MasterViewController.h

#import <UIKit/UIKit.h>

@class DetailViewController;

@interface MasterViewController : UITableViewController

@property (strong, nonatomic) DetailViewController *detailViewController;
@property (strong, nonatomic) NSArray *categories;
@property (strong, nonatomic) NSArray *imageNames;

@end

MasterViewController.m

- (void)viewDidLoad
{
  [super viewDidLoad];
  self.detailViewController = (DetailViewController *)[[self.splitViewController.viewControllers lastObject] topViewController];

  //Set the Master view navigation bar's title
  self.navigationItem.title= @"Photo Categories";

  // Setup the Master view tableView control's data source
  self.categories = @[@"Planets & Nature", @"Business", @"Food", @"Maps & Flags", @"Other", @"Help",@"Attributions",];
  self.imageNames = @[@"blue-book.png", @"blue-book.png", @"blue-book.png", @"blue-book.png", @"blue-book.png", @"books-help.png",@"book-reader.png"];
}

- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section {
  return self.categories.count
}

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
{
  UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"Cell" forIndexPath:indexPath];

  // Populate the Master view tableView control's cells
  cell.textLabel.text = self.categories[indexPath.row];
  NSString *currentImageName = self.imageNames[indexPath.row];
  cell.imageView.image = [UIImage imageNamed:currentImageName];
  return cell;
}

- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath
{
  // Set up a dictionary object with content of the selected category name and photo name
  NSString *category = self.categories[indexPath.row];
  NSString *photo = self.imageNames[indexPath.row];

  // Set the DetailViewController controls with data belonging to the menu item selected
  self.detailViewController.imageViewOne.image = [UIImage imageNamed:photo];
  self.detailViewController.captionOne.text = category;
}

Add The Table View Images in The project

As you can see in Figure 8 above, images are displayed on the Table View cells; so add these images in the project.

Change The Detail View Navigation Bar Button Title

What we want to do now is change the Detail View navigation bar button’s title property to display, “Photo Categories” instead of Master. All you have to do is change a single line in the DetailViewController.m file’s willHideViewController method.

DetailViewController.m

- (void)splitViewController:(UISplitViewController *)splitController willHideViewController:(UIViewController *)viewController withBarButtonItem:(UIBarButtonItem *)barButtonItem forPopoverController:(UIPopoverController *)popoverController
{
  barButtonItem.title = @"Photo Categories";
  [self.navigationItem setLeftBarButtonItem:barButtonItem animated:YES];
  self.masterPopoverController = popoverController;
}

After Performing task 1 and 2, the app should look like output shown in these images.

Figure 9a	Figure 9b

Display Content in The Detail View

Looking good, looking good! Now, when the user tap a cell of the Master View’s table control, we want the app to display an image in an Image View control and a caption in a Label control. In order to achieve our goal, we have to do the following:

Delete the label control from the Detail View, then add these.

Figure 10: UIImageView and UILabel controls

Define properties for the view’s controls in the DetailViewController.h file.

@property (strong, nonatomic) IBOutlet UIImageView *imageViewOne;
@property (strong, nonatomic) IBOutlet UILabel *captionOne;

Hook up the view’s controls to their properties in Interface Builder. Set the Label control’s Color property to Ocean, set its Alignment property to center, set its Font property to System Bold 20, and remove default text from the Text property.

Add this code in the MasterViewController.m file, which display content in the Detail View’s controls.

- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath
{
  // Put the selected category name and photo in variables
  NSString *category = self.categories[indexPath.row];
  NSString *photo = self.imageNames[indexPath.row];

  // Add content in the Detail View's controls
  self.detailViewController.imageViewOne.image = [UIImage imageNamed:photo];
  self.detailViewController.captionOne.text = category;
}

Once you’ve performed above tasks, run the application on the iPad Simulator to test the Detail View interface. Put the simulator in landscape orientation, then select a Photo Category. As you can see in the Figure 11, the app display the selected category image and name in the Detail View’s controls. Cool huh?

Figure 11: Landscape view of the Detail View

Dismiss The Master View

If you want to dismiss the Master View when the user tap a Table View cell, you’ll have to do the following.

Declare and implement this method in the MasterViewController header and implementation file.

-(void)dismissMasterPopoverView
{
  if (self.detailViewController.masterPopoverController != nil) {
    [self.detailViewController.masterPopoverController dismissPopoverAnimated:YES];
  }
}

Add this statement in the MasterViewController.m file’s didSelectRowAtIndexPath: method.

[self dismissMasterPopoverView];

In the DetailViewController.m file, cut the property declaration statement that’s on line 12. Past it in the DetailViewController.h file.

After  performing above task, run the application and click a cell. As you can see, the Master View is dismissed.

That’s All Folks!

That’s it. Now you know the basics of using the Split View Controller.