iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UISplitViewController Class Reference

Options
Deployment Target:

On This Page
Language:

UISplitViewController

The UISplitViewController class is a container view controller that presents a master-detail interface. In a master-detail interface, changes in the primary view controller (the master) drive changes in a secondary view controller (the detail). The two view controllers can be arranged so that they are side-by-side, so that only one at a time is visible, or so that one only partially hides the other. In iOS 8 and later, you can use the UISplitViewController class on all iOS devices; in previous versions of iOS, the class is available only on iPad.

When building your app’s user interface, the split view controller is typically the root view controller of your app’s window. The split view controller has no significant appearance of its own. Most of its appearance is defined by the child view controllers you install. You can configure the child view controllers using Interface Builder or programmatically by assigning the view controllers to the viewControllers property. The child view controllers can be custom view controllers or other container view controller, such as navigation controllers.

The split view controller determines the arrangement of its child view controllers based on the available space. In a horizontally regular environment, the split view controller presents its view controllers side-by-side whenever possible. In a horizontally compact environment, the split view controller acts more like a navigation controller, displaying the primary view controller initially and pushing or popping the secondary view controller as needed. You can also ask the split view controller to prefer a specific arrangement by assigning a value to the preferredDisplayMode property.

When displayed onscreen, the split view controller works with its delegate object to manage the presentation of its child view controllers. The delegate is an object you provide that adopts the UISplitViewControllerDelegate protocol. Use the methods of that protocol to customize the behavior of your split view interface when changes occur. For more information about the protocol methods, see UISplitViewControllerDelegate Protocol Reference.

Configuring the Appearance of the Split View Interface

The visual configuration of a split view controller is controlled by its current display mode. You do not set the display mode directly; instead, you set it indirectly using the preferredDisplayMode property. The split view controller makes every effort to respect the display mode you specify but may not be able to accommodate that mode visually because of space constraints. For example, the split view controller cannot display its child view controllers side-by-side in a horizontally compact environment.

Table 1 lists the available display modes and describes how the view controllers are arranged onscreen. The table also lists the constants you use to request the specified display mode.

Table 1Display modes for a split view controller

Mode

Description

Side-by-side

Both view controllers are displayed onscreen at the same time. The primary view controller is displayed on the left side and is typically narrower than the secondary view controller. You can adjust the primary view controller’s width using the preferredPrimaryColumnWidthFraction property.

This display mode is not applied when the collapsed property is YEStrue. In a collapsed interface, only one view controller at a time is visible.

This mode is represented by the UISplitViewControllerDisplayModeAllVisible constant.

Hidden

The secondary view controller is displayed onscreen and the primary view controller is off screen.

To display the primary view controller, you must present it modally or change the display mode.

This mode is represented by the UISplitViewControllerDisplayModePrimaryHidden constant.

Overlay

The secondary view controller is onscreen and the primary view controller is layered on top of it. In this mode, the primary view controller partially obscures the secondary view controller.

This mode is represented by the UISplitViewControllerDisplayModePrimaryOverlay constant.

After setting the preferred display mode, the split view controller updates itself and reflects the actual display mode in the displayMode property. You can change the preferred display mode at any time, and doing so causes the split view controller to adjust itself accordingly. The split view controller also installs a built-in gesture recognizer that lets the user change the display mode using a swipe. You can suppress this gesture recognizer by setting the presentsWithGesture property to NOfalse.

The displayModeButtonItem method returns a special bar button item for changing the display mode that you can incorporate into your app’s user interface. The split view controller manages the behavior and appearance of this item. All you have to do is add it to an appropriate navigation bar or toolbar in your interface. When tapped, the button sends an action to the split view controller telling it to change its current display mode to the one specified by the targetDisplayModeForActionInSplitViewController: method of the split view controller’s delegate. Specifying a display mode of automatic (or not implementing the delegate method at all) causes the split view controller to implement behavior that is appropriate for the current size class. For example, on an iPad in portrait orientation, the split view controller toggles between the hidden and overlay modes. Gesture-based actions also use the delegate method to determine which display mode to employ.

Changing Child View Controllers in a Split View Interface

When designing your split view interface, it is best to install primary and secondary view controllers that do not change. A common technique is to install navigation controllers in both positions and then push and pop new content as needed. Having these types of anchor view controllers makes it easier to focus on your content and let the split view controller apply its default behavior to the overall interface.

In cases where you do need to change either the primary or secondary view controller, it is recommended that you do so using the showViewController:sender: and showDetailViewController:sender: methods. Using these methods (instead of modifying the viewControllers property directly) lets the split view controller present the specified view controller in a way that is most appropriate for the current display mode and size class. The split view controller knows how to adjust the interface in more intuitive ways. It even works with other container view controllers (like navigation controllers) to present view controllers. For example, in a compact environment where the primary view controller is a navigation controller, calling showDetailViewController:sender: does not replace the secondary view controller. Instead, the primary navigation controller pushes the view controller onto its navigation stack.

Collapsing and Expanding the Split View Interface

The split view controller performs collapse and expand transitions when its size class toggles between horizontally regular and horizontally compact. During these transitions, the split view controller changes how it displays its child view controllers. When changing from horizontally regular to horizontally compact, the split view controller collapses one view controller onto the other. When changing from horizontally compact back to horizontally regular, it expands the interface again and displays one or both of its child view controllers depending on the display mode.

When transitioning to a collapsed interface, the split view controller works with its delegate to manage the transition. At the end of a collapse transition, the split view controller normally shows only the content from its primary view controller. You can change this behavior by implementing the primaryViewControllerForCollapsingSplitViewController: method in your split view controller delegate. You might use that method to specify the secondary view controller or an entirely different view controller—perhaps one better suited for display in a horizontally compact environment. If you want to perform any additional adjustments of the view controllers and view hierarchy, you can also implement the splitViewController:collapseSecondaryViewController:ontoPrimaryViewController: method in your delegate.

The expansion process reverses the collapsing process by asking the delegate to designate which view controller becomes the primary view controller and to give the delegate a chance to perform the transition itself. If you implement the delegate methods for collapsing your split view interface, you should also implement the primaryViewControllerForExpandingSplitViewController: and splitViewController:separateSecondaryViewControllerFromPrimaryViewController: methods for expanding that interface. If you do not implement any of the methods, the split view controller provides default behavior to handle the collapsing and expanding transitions.

For more information about the methods you use to manage the collapse and expand transitions, see UISplitViewControllerDelegate Protocol Reference.

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

State Preservation

In iOS 6 and later, if you assign a value to this split view controller’s restorationIdentifier property, it preserves any child view controllers that have their 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 App Programming Guide for iOS.

  • The array of view controllers managed by the receiver.

    Declaration

    Swift

    var viewControllers: [UIViewController]

    Objective-C

    @property(nonatomic, copy) NSArray <__kindof UIViewController *> * _Nonnull viewControllers

    Discussion

    When the split view interface is expanded, this property contains two view controllers; when it is collapsed, this property contains only one view controller. The first view controller in the array is always the primary (or master) view controller. If a second view controller is present, that view controller is the secondary (or detail) view controller.

    When configuring the split view controller, you can use this property to assign the primary and secondary view controllers that you want displayed initially. After the split view controller is onscreen, you can use this property to get the view controllers in the split view interface. After the split view controller is onscreen, it is better to set the child view controllers using the showDetailViewController:sender: or showViewController:sender: methods. Although you can still change the view controllers in this property directly, you should do so only if you manually manage your app’s view controller transitions.

    Availability

    Available in iOS 3.2 and later.

  • Specifies whether a hidden view controller can be presented and dismissed using a swipe gesture.

    Declaration

    Swift

    var presentsWithGesture: Bool

    Objective-C

    @property(nonatomic) BOOL presentsWithGesture

    Discussion

    When this property is set to YEStrue, the split view controller installs a gesture recognizer for changing the current display mode. The gesture recognizer applies the display mode returned by the delegate’s targetDisplayModeForActionInSplitViewController: method. If that method returns the UISplitViewControllerDisplayModeAutomatic mode, the split view controller applies the most appropriate display mode given its current configuration and size class.

    The default value of this property is YEStrue.

    Availability

    Available in iOS 5.1 and later.

  • The preferred arrangement of the split view controller interface.

    Declaration

    Swift

    var preferredDisplayMode: UISplitViewControllerDisplayMode

    Objective-C

    @property(nonatomic) UISplitViewControllerDisplayMode preferredDisplayMode

    Discussion

    Use this property to specify the display mode that you prefer to use. The split view controller makes every effort to adopt the interface you specify but may use a different type of interface if there is not enough space to support your preferred choice. If changing the value of this property leads to an actual change in the current display mode, the split view controller animates the resulting change.

    Setting the value of this property to UISplitViewControllerDisplayModeAutomatic causes the split view controller to choose the most appropriate display mode for the currently available space. On iPad, this results in use of the mode UISplitViewControllerDisplayModePrimaryOverlay in portrait orientations and UISplitViewControllerDisplayModeAllVisible in landscape orientations. The default value of this property is UISplitViewControllerDisplayModeAutomatic.

    Availability

    Available in iOS 8.0 and later.

    See Also

    displayMode

  • The current arrangement of the split view controller’s contents. (read-only)

    Declaration

    Swift

    var displayMode: UISplitViewControllerDisplayMode { get }

    Objective-C

    @property(nonatomic, readonly) UISplitViewControllerDisplayMode displayMode

    Discussion

    This property reflects the arrangement of the two child view controllers in a split view interface. The value in this property is never set to UISplitViewControllerDisplayModeAutomatic. To change the current display mode, change the value of the preferredDisplayMode property.

    When the collapsed property is YEStrue, the value of this property is ignored. A collapsed split view interface contains only one view controller so the display mode is superfluous.

    Availability

    Available in iOS 8.0 and later.

  • A button that changes the display mode of the split view controller.

    Declaration

    Swift

    func displayModeButtonItem() -> UIBarButtonItem

    Objective-C

    - (UIBarButtonItem * _Nonnull)displayModeButtonItem

    Return Value

    A preconfigured bar button item that changes the display mode.

    Discussion

    Incorporate this button into your user interface when you want to give the user an explicit way to change the display mode of the split view controller. Tapping this button changes the display mode to the value last returned by the delegate’s targetDisplayModeForActionInSplitViewController: method. Use that method to determine what mode to apply next based on the current configuration of the split view controller.

    Do not change the configuration of the returned button. The split view controller updates the button’s configuration and appearance automatically based on the current display mode and the information provided by the delegate object.

    Availability

    Available in iOS 8.0 and later.

  • A Boolean value indicating whether only one of the child view controllers is displayed. (read-only)

    Declaration

    Swift

    var collapsed: Bool { get }

    Objective-C

    @property(nonatomic, readonly, getter=isCollapsed) BOOL collapsed

    Discussion

    This property is set to YEStrue when the split view controller content is semantically collapsed into a single container. Collapsing happens when the split view controller transitions from a horizontally regular to a horizontally compact environment. After it has been collapsed, the split view controller reports having only one child view controller in its viewControllers property. The other view controller is collapsed into the other view controller’s content with the help of the delegate object or discarded temporarily. When collapsed, the displayMode property has no impact on the appearance of the split view controller interface.

    The value of this property is NOfalse when the split view controller is capable of displaying both of its child view controllers at the same time, even if it is not showing them both at the moment. In this expanded mode, the split view controller’s configuration of its child view controllers is determined by the displayMode property. In addition, the viewControllers property contains both the primary and secondary view controllers.

    During a transition from an expanded to collapsed interface, the value of this property is NOfalse until after the collapse transition finishes and all of the relevant delegate methods have been called. Similarly, when transitioning back to an expanded interface, the value is YEStrue until the transition finishes.

    Availability

    Available in iOS 8.0 and later.

  • The relative width of the primary view controller’s content.

    Declaration

    Swift

    var preferredPrimaryColumnWidthFraction: CGFloat

    Objective-C

    @property(nonatomic, assign) CGFloat preferredPrimaryColumnWidthFraction

    Discussion

    Use this property to specify your preferred width for the primary view controller’s view. The value of this property is a floating-point number between 0.0 and 1.0 that represents the percentage of the overall width of the split view controller. For example, the value 0.4 represents 40% of the current width. The default value of this property is UISplitViewControllerAutomaticDimension, which results in an appropriate width for the primary view controller.

    The actual width of the primary view controller is constrained by the values in the minimumPrimaryColumnWidth and maximumPrimaryColumnWidth properties. The split view controller makes every other attempt to honor the width you specify but may change this value to accommodate the available space. You can get the actual width assigned to the primary view controller’s view from the primaryColumnWidth property.

    Availability

    Available in iOS 8.0 and later.

  • The width (in points) of the primary view controller’s content. (read-only)

    Declaration

    Swift

    var primaryColumnWidth: CGFloat { get }

    Objective-C

    @property(nonatomic, readonly) CGFloat primaryColumnWidth

    Discussion

    This property contains the actual width applied to the primary view controller’s view.

    Availability

    Available in iOS 8.0 and later.

  • The minimum width (in points) required for the primary view controller’s content.

    Declaration

    Swift

    var minimumPrimaryColumnWidth: CGFloat

    Objective-C

    @property(nonatomic, assign) CGFloat minimumPrimaryColumnWidth

    Discussion

    Use this property in conjunction with the maximumPrimaryColumnWidth property to ensure the width of the primary view controller’s content is set to an acceptable value. The preliminary width is specified by the preferredPrimaryColumnWidthFraction property, which is applied to the split view controller’s width and checked against these bounds. If the resulting width is less than the value in this property, it is set to the value in this property.

    The default value of this property is UISplitViewControllerAutomaticDimension, which corresponds to a minimum width of 0 points.

    Availability

    Available in iOS 8.0 and later.

  • The maximum width (in points) allowed for the primary view controller’s content.

    Declaration

    Swift

    var maximumPrimaryColumnWidth: CGFloat

    Objective-C

    @property(nonatomic, assign) CGFloat maximumPrimaryColumnWidth

    Discussion

    Use this property in conjunction with the minimumPrimaryColumnWidth property to ensure the width of the primary view controller’s content is set to an acceptable value. The preliminary width is specified by the preferredPrimaryColumnWidthFraction property, which is applied to the split view controller’s width and checked against these bounds. If the resulting width is greater than the value in this property, it is set to the value in this property.

    The default value of this property is UISplitViewControllerAutomaticDimension, which corresponds to a minimum width of 320 points.

    Availability

    Available in iOS 8.0 and later.

  • Presents the specified view controller as the secondary view controller of the split view interface.

    Declaration

    Swift

    func showDetailViewController(_ vc: UIViewController, sender sender: AnyObject?)

    Objective-C

    - (void)showDetailViewController:(UIViewController * _Nonnull)vc sender:(id _Nullable)sender

    Parameters

    vc

    The view controller to display in the secondary (or detail) location of the split view interface. If you specify nil for this parameter or if this view controller is the same as the one it would replace, this method does nothing.

    sender

    The view or view controller that made the request.

    Discussion

    Whenever possible, use this method (instead of modifying the contents of the viewControllersproperty directly) to replace the secondary view controller of your split view interface. This method displays the specified view controller in the best way possible given the current size class in effect. It also takes advantage of existing navigation controller behaviors whenever possible to minimize changes to the split view interface.

    This method calls the delegate’s splitViewController:showDetailViewController:sender: method to give the delegate an opportunity to show the view controller. If the delegate does not show the view controller, the split view controller forwards the message to the view controller being replaced to see if it wants to do anything. For example, a navigation controller responds by pushing vc onto its navigation stack. If no other object wants to show the view controller, the split view controller shows it using the following heuristics:

    • In a horizontally regular environment, the split view controller installs vc as the secondary view controller.

    • In a horizontally compact environment, the split view controller presents vc modally.

    All view controllers implement this method. If they do not show the view controller themselves, they forward the message to the parent split view controller (if any) and let it show the view controller. As a result, a child view controller can call this method on itself to achieve the same results as calling this method on the split view controller object.

    Availability

    Available in iOS 8.0 and later.

  • Presents the specified view controller as the primary view controller in the split view interface.

    Declaration

    Swift

    func showViewController(_ vc: UIViewController, sender sender: AnyObject?)

    Objective-C

    - (void)showViewController:(UIViewController * _Nonnull)vc sender:(id _Nullable)sender

    Parameters

    vc

    The view controller to display in the primary (or master) location of the split view interface.

    sender

    The object that made the request to show the view controller.

    Discussion

    Whenever possible, use this method (instead of modifying the contents of the viewControllersproperty directly) to replace the primary view controller of your split view interface. This method displays the specified view controller in the best way possible given the current size class in effect.

    Typically, you call this method from an action method when you want to replace the primary view controller with the one specified in vc. This method calls the split view controller delegate’s splitViewController:showViewController:sender: method to give the delegate an opportunity to show the view controller. If the delegate does not show the view controller, the split view controller shows it using the following heuristics:

    • In a horizontally regular environment, the split view controller installs vc as the primary view controller unless vc is already a child of the primary view controller, in which case it installs vc as the secondary view controller.

    • In a horizontally compact environment, the split view controller presents vc modally.

    Availability

    Available in iOS 8.0 and later.

  • Constants describing the possible display modes for a split view controller.

    Declaration

    Swift

    enum UISplitViewControllerDisplayMode : Int { case Automatic case PrimaryHidden case AllVisible case PrimaryOverlay }

    Objective-C

    typedef enum UISplitViewControllerDisplayMode : NSInteger { UISplitViewControllerDisplayModeAutomatic, UISplitViewControllerDisplayModePrimaryHidden, UISplitViewControllerDisplayModeAllVisible, UISplitViewControllerDisplayModePrimaryOverlay, } UISplitViewControllerDisplayMode;

    Constants

    • Automatic

      UISplitViewControllerDisplayModeAutomatic

      The split view controller automatically decides the most appropriate display mode based on the device and the current app size. You can assign this constant as the value of the preferredDisplayMode property but this value is never reported by the displayMode property.

      Available in iOS 8.0 and later.

    • PrimaryHidden

      UISplitViewControllerDisplayModePrimaryHidden

      The primary view controller is hidden.

      Available in iOS 8.0 and later.

    • AllVisible

      UISplitViewControllerDisplayModeAllVisible

      The primary and secondary view controllers are displayed side-by-side onscreen.

      Available in iOS 8.0 and later.

    • PrimaryOverlay

      UISplitViewControllerDisplayModePrimaryOverlay

      The primary view controller is layered on top of the secondary view controller, leaving the secondary view controller partially visible.

      Available in iOS 8.0 and later.

    Discussion

    Display modes apply to a split view controller in an expanded arrangement. When the split view interface is collapsed, the display mode is ignored.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Constant indicating the default width for the primary view controller.

    Declaration

    Swift

    let UISplitViewControllerAutomaticDimension: CGFloat

    Objective-C

    CGFloat const UISplitViewControllerAutomaticDimension;

    Constants

    • UISplitViewControllerAutomaticDimension

      UISplitViewControllerAutomaticDimension

      The default value to apply to a given dimension.

      Available in iOS 8.0 and later.