iOS Developer Library

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

Inheritance


Import Statement


import UIKit @import UIKit;

Availability


Available in iOS 3.2 and later.
  • The array of view controllers managed by the receiver.

    Declaration

    Swift

    var viewControllers: [AnyObject]

    Objective-C

    @property(nonatomic, copy) NSArray *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.

    Import Statement

    import UIKit

    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.

    Import Statement

    import UIKit

    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 UISplitViewControllerDisplayModeOverlay in portrait orientations and UISplitViewControllerDisplayModeSideBySide in landscape orientations. The default value of this property is UISplitViewControllerDisplayModeAutomatic.

    Import Statement

    import UIKit

    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.

    Import Statement

    import UIKit

    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 *)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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • collapsed collapsed Property

    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.

    Import Statement

    import UIKit

    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.

    Import Statement

    import UIKit

    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.

    Import Statement

    import UIKit

    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.

    Import Statement

    import UIKit

    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.

    Import Statement

    import UIKit

    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 *)vc sender:(id)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.

    Import Statement

    import UIKit

    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 *)vc sender:(id)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.

    Import Statement

    import UIKit

    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

    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.

    Import Statement