UISplitViewController Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 3.2 and later.
Companion guide
Declared in
UISplitViewController.h
Related sample code

Overview

The UISplitViewController class is a container view controller that manages the presentation of two side-by-side view controllers. You use this class to implement a master-detail interface, in which the left-side view controller presents a list of items and the right-side presents details of the selected item. Split view controllers are for use exclusively on iPad devices. Attempting to create one on other devices results in an exception.

The split view controller has no significant interface of its own. Its job is to manage the presentation of its two child view controllers and transitions between different orientations. (A split view controller supports the same interface orientations as its currently visible child view controllers.) Some aspects of the presentation are coordinated in conjunction with a delegate object.

By default, the split view controller displays both of its view controllers when in a landscape orientation. However, in a portrait orientation, the split view controller displays only the detail view controller by default. You can change this default behavior using the delegate’s splitViewController:shouldHideViewController:inOrientation: method.

When in a portrait orientation, the split view controller places the master view controller in a popover that is linked to a bar button item. The split view controller then makes this bar button item available to your app so that you can display it. To facilitate the display of that button, the split view controller calls the methods of its delegate at appropriate times:

For more information on the methods of the delegate object, see UISplitViewControllerDelegate Protocol Reference.

In iOS 5.1 and later, the hidden master view controller can also be displayed using a swipe gesture. If necessary (for example, if the split view controller’s use of the swipe gesture interferes with your use of swipe gestures), you can suppress this behavior by setting presentsWithGesture to NO.

This class is generally used as-is but may be subclassed in iOS 6 and later.

Application Architecture Using Split View Controllers

You must assign two view controllers to a split view controller. Usually you configure these view controllers in a storyboard; if you create a split view controller programmatically, you assign them using the viewControllers property. A split view controller does not provide any inherent support for managing the communication between the view controllers you assign to it. It is your responsibility to determine the best way to do that. There are two main approaches you can take, depending on the type of application you create:

  • A simple master-detail interface in which the detail view remains constant.

    In this configuration, a single view controller manages the detail view for the lifetime of the application and updates the contents of subviews to reflect the selection in the master view. The master view controller has a reference to the detail view controller and informs the detail view controller whenever the selected item changes or some other relevant event occurs. The detail view controller might also serve as the split view controller’s delegate.

  • A complex application in which the master and detail views (and corresponding view controllers) may change.

    In complex configurations, you need a separate custom controller object to manage the master and detail view controllers and mediate between them. The custom controller is typically the split view controller’s delegate and is responsible for communicating with the current detail view controller to show and hide the popover bar button item.

Message Forwarding to Its Child View Controllers

A split view controller interposes itself between the application’s window and its child view controllers. As a result, all messages to the visible view controllers must flow through the split view controller. This works generally as you might expect and the flow of messages should be relatively intuitive. For example, view appearance and disappearance messages are sent only when the corresponding child view controller actually appears on screen. Thus, when a split view controller is first displayed in a portrait orientation, it calls the viewWillAppear: and viewDidAppear: methods of only the view controller that is shown initially. The view controller that is presented using a popover does not receive those messages until the popover is shown or until the split view controller rotates to a landscape orientation.

State Preservation

In iOS 6 and later, if you assign a value to this split view controller’s restorationIdentifier property, it preserves each child view controller that has its own valid restoration identifier. During the next launch cycle, the split view controller restores the preserved view controllers to their previous state.

The child view controllers of a split view controller may use the same restoration identifiers. The split view controller automatically stores additional information to ensure that each child’s restoration path is unique.

For more information about how state preservation and restoration works, see iOS App Programming Guide.

Tasks

Managing the Child View Controllers

Accessing the Delegate Object

Properties

delegate

The delegate you want to receive split view controller messages.

@property(nonatomic, assign) id <UISplitViewControllerDelegate> delegate
Discussion

The split view controller uses its delegate to manage the showing and hiding of related view controllers. For more information about the methods you can implement in your delegate, see UISplitViewControllerDelegate Protocol Reference.

Availability
  • Available in iOS 3.2 and later.
Declared In
UISplitViewController.h

presentsWithGesture

Specifies whether the hidden view can be presented and dismissed via a swipe gesture.

@property (nonatomic) BOOL presentsWithGesture
Discussion

If YES and your delegate implements splitViewController:willHideViewController:withBarButtonItem:forPopoverController:, the hidden view can be presented and dismissed via a swipe gesture.

The default value is YES.

Availability
  • Available in iOS 5.1 and later.
Declared In
UISplitViewController.h

viewControllers

The array of view controllers managed by the receiver.

@property(nonatomic, copy) NSArray *viewControllers
Discussion

The array in this property must contain exactly two view controllers. The view controllers are presented left-to-right in the split view interface when it is in a landscape orientation. Thus, the view controller at index 0 is displayed on the left side and the view controller at index 1 is displayed on the right side of the interface.

The first view controller in this array is typically hidden when the device is in a portrait orientation. Assign a delegate object to the receiver if you want to coordinate the display of this view controller using a popover.

Availability
  • Available in iOS 3.2 and later.
See Also
Related Sample Code
Declared In
UISplitViewController.h