iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UISplitViewControllerDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

UISplitViewControllerDelegate

The UISplitViewControllerDelegate protocol defines methods that allow you to manage changes to a split view interface. Use the methods of this protocol to respond to changes in the current display mode and to the current interface orientation. When the split view interface collapses and expands, or when a new view controller is added to the interface, you can also use these methods to configure the child view controllers appropriately.

For more information about the UISplitViewController class, see UISplitViewController Class Reference.

  • Tells the delegate that the display mode for the split view controller is about to change.

    Declaration

    Swift

    optional func splitViewController(_ svc: UISplitViewController, willChangeToDisplayMode displayMode: UISplitViewControllerDisplayMode)

    Objective-C

    - (void)splitViewController:(UISplitViewController * _Nonnull)svc willChangeToDisplayMode:(UISplitViewControllerDisplayMode)displayMode

    Parameters

    svc

    The split view controller whose display mode is changing.

    displayMode

    The new display mode that is about to be applied to the split view controller.

    Discussion

    The split view controller calls this method when its display mode is about to change. Because changing the display mode usually means hiding or showing one of the child view controllers, you can implement this method and use it to add or remove the controls for showing the primary view controller.

    Availability

    Available in iOS 8.0 and later.

  • Asks the delegate to provide the display mode to apply when a split view controller action occurs.

    Declaration

    Swift

    optional func targetDisplayModeForActionInSplitViewController(_ svc: UISplitViewController) -> UISplitViewControllerDisplayMode

    Objective-C

    - (UISplitViewControllerDisplayMode)targetDisplayModeForActionInSplitViewController:(UISplitViewController * _Nonnull)svc

    Parameters

    svc

    The split view controller whose action may be triggered. Use this object to obtain the current display mode and configuration of the split view interface.

    Return Value

    The display mode to apply to the split view controller when the user performs specific actions.

    Discussion

    At appropriate times, the split view controller calls this method to determine which display mode to apply to itself in response to user-initiated actions. The split view controller has a built-in gesture recognizer that changes the current display mode. The split view controller also vends a bar button item from its displayModeButtonItem property that changes the display mode. The gesture recognizer is enabled using the presentsWithGesture property of the split view controller. Apps must incorporate the bar button item into their interface.

    Implement this method if you want to specify which display mode to apply to the split view controller in response to the user actions. The split view controller calls this method at appropriate times to obtain an updated value for the gesture and bar button item. If you do not implement this method or if your method returns UISplitViewControllerDisplayModeAutomatic, the split view controller applies its own heuristics to determine which mode to apply when the next action is triggered. You cannot specify different display modes for the gesture and bar button item.

    Availability

    Available in iOS 8.0 and later.

  • Asks the delegate to provide the single view controller to display after the split view interface collapses.

    Declaration

    Swift

    optional func primaryViewControllerForCollapsingSplitViewController(_ splitViewController: UISplitViewController) -> UIViewController?

    Objective-C

    - (UIViewController * _Nullable)primaryViewControllerForCollapsingSplitViewController:(UISplitViewController * _Nonnull)splitViewController

    Parameters

    splitViewController

    The split view controller whose interface is collapsing.

    Return Value

    The new primary view controller to display onscreen.

    Discussion

    When the split view controller transitions from a horizontally regular to a horizontally compact size class, it calls this method and asks you for the view controller to display when that transition is complete. The view controller you return becomes the new primary view controller of the split view interface.

    Use this method to specify which view controller you want displayed in a compact environment. By default, a collapsing split view controller displays its current primary view controller but you can return a different view controller if you want. For example, you might return the secondary view controller if that view controller contains the content you want to display. You might also return a completely different view controller that is better suited for displaying content in a compact environment.

    If you implement this method, you should also implement the primaryViewControllerForExpandingSplitViewController: method to handle the expansion of your interface from a horizontally compact to a horizontally regular environment. If you do not implement this method, or if your implementation returns nil, the split view controller chooses its primary view controller as the one to display.

    Availability

    Available in iOS 8.0 and later.

  • Asks the delegate to adjust the primary view controller and to incorporate the secondary view controller into the collapsed interface.

    Declaration

    Swift

    optional func splitViewController(_ splitViewController: UISplitViewController, collapseSecondaryViewController secondaryViewController: UIViewController, ontoPrimaryViewController primaryViewController: UIViewController) -> Bool

    Objective-C

    - (BOOL)splitViewController:(UISplitViewController * _Nonnull)splitViewController collapseSecondaryViewController:(UIViewController * _Nonnull)secondaryViewController ontoPrimaryViewController:(UIViewController * _Nonnull)primaryViewController

    Parameters

    splitViewController

    The split view controller whose interface is collapsing.

    secondaryViewController

    The secondary view controller of the split view interface.

    primaryViewController

    The primary view controller of the split view interface. If you implement the primaryViewControllerForCollapsingSplitViewController: method in your delegate, this object is the one returned by that method.

    Return Value

    NOfalse to let the split view controller try and incorporate the secondary view controller’s content into the collapsed interface or YEStrue to indicate that you do not want the split view controller to do anything with the secondary view controller.

    Discussion

    This method is your opportunity to perform any necessary tasks related to the transition to a collapsed interface. After this method returns, the split view controller removes the secondary view controller from its viewControllers array, leaving the primary view controller as its only child. In your implementation of this method, you might prepare the primary view controller for display in a compact environment or you might attempt to incorporate the secondary view controller’s content into the newly collapsed interface.

    Returning NOfalse tells the split view controller to use its default behavior to try and incorporate the secondary view controller into the collapsed interface. When you return NOfalse, the split view controller calls the collapseSecondaryViewController:forSplitViewController: method of the primary view controller, giving it a chance to do something with the secondary view controller’s content. Most view controllers do nothing by default but the UINavigationController class responds by pushing the secondary view controller onto its navigation stack.

    Returning YEStrue from this method tells the split view controller not to apply any default behavior. You might return YEStrue in cases where you do not want the secondary view controller’s content incorporated into the resulting interface.

    Availability

    Available in iOS 8.0 and later.

  • Asks the delegate to provide the view controller to display in the primary position when the split view interface expands.

    Declaration

    Swift

    optional func primaryViewControllerForExpandingSplitViewController(_ splitViewController: UISplitViewController) -> UIViewController?

    Objective-C

    - (UIViewController * _Nullable)primaryViewControllerForExpandingSplitViewController:(UISplitViewController * _Nonnull)splitViewController

    Parameters

    splitViewController

    The split view controller whose interface is expanding.

    Return Value

    The view controller to use as the primary view controller or nil to specify the current primary view controller.

    Discussion

    When the split view controller transitions from a horizontally compact to a horizontally regular size class, it calls this method and asks you for the view controller to display in the primary position when that transition is complete. The view controller you return becomes the primary view controller of the split view interface. If you do not implement this method, or if your implementation returns nil, the split view controller chooses its current primary view controller as the one to use.

    If you specified a specific view controller in your primaryViewControllerForCollapsingSplitViewController: method, use this method to restore the original primary view controller for your split view interface. You can also implement the splitViewController:separateSecondaryViewControllerFromPrimaryViewController: method to disentangle your view controllers from one another as needed.

    Availability

    Available in iOS 8.0 and later.

  • Asks the delegate to provide the new secondary view controller for the split view interface.

    Declaration

    Swift

    optional func splitViewController(_ splitViewController: UISplitViewController, separateSecondaryViewControllerFromPrimaryViewController primaryViewController: UIViewController) -> UIViewController?

    Objective-C

    - (UIViewController * _Nullable)splitViewController:(UISplitViewController * _Nonnull)splitViewController separateSecondaryViewControllerFromPrimaryViewController:(UIViewController * _Nonnull)primaryViewController

    Parameters

    splitViewController

    The split view controller whose interface is expanding.

    primaryViewController

    The primary view controller in the expanded split view interface. If you implement the primaryViewControllerForExpandingSplitViewController: method in your delegate, this object is the one returned by that method.

    Return Value

    The view controller to use as the secondary view controller in the expanded split view interface or nil to let the split view controller choose an appropriate secondary view controller for you.

    Discussion

    Use this method to designate the secondary view controller for your split view interface and to perform any additional cleanup that might be needed. After this method returns, the split view controller installs the newly designated primary and secondary view controllers in its viewControllers array.

    When an interface collapses, some view controllers merge the contents of the primary and secondary view controllers. This method is your opportunity to undo those changes and return your split view interface to its original state.

    When you return nil from this method, the split view controller calls the primary view controller’s separateSecondaryViewControllerForSplitViewController: method, giving it a chance to designate an appropriate secondary view controller. Most view controllers do nothing by default but the UINavigationController class responds by popping and returning the view controller from the top of its navigation stack.

    Availability

    Available in iOS 8.0 and later.

  • Asks the delegate if it wants to do the work of displaying a view controller in the primary position of the split view interface.

    Declaration

    Swift

    optional func splitViewController(_ splitViewController: UISplitViewController, showViewController vc: UIViewController, sender sender: AnyObject?) -> Bool

    Objective-C

    - (BOOL)splitViewController:(UISplitViewController * _Nonnull)splitViewController showViewController:(UIViewController * _Nonnull)vc sender:(id _Nullable)sender

    Parameters

    splitViewController

    The split view controller whose primary view controller is being updated.

    vc

    The view controller being displayed in the primary position.

    sender

    The object that made the request.

    Return Value

    YEStrue if you handled the presentation of the view controller or NOfalse if you want the split view controller to do it.

    Discussion

    When its showViewController:sender: method is called, the split view controller calls this method to see if your delegate wants to handle the presentation of the specified view controller. If you implement this method and your implementation returns YEStrue, you are responsible for presenting the specified view controller in the primary position of the split view interface. The split view controller does not do anything more to try and show the view controller.

    If you do not implement this method or if your implementation returns NOfalse, the split view controller presents the view controller in an appropriate way.

    Availability

    Available in iOS 8.0 and later.

  • Asks the delegate if it wants to do the work of displaying a view controller in the secondary position of the split view interface.

    Declaration

    Swift

    optional func splitViewController(_ splitViewController: UISplitViewController, showDetailViewController vc: UIViewController, sender sender: AnyObject?) -> Bool

    Objective-C

    - (BOOL)splitViewController:(UISplitViewController * _Nonnull)splitViewController showDetailViewController:(UIViewController * _Nonnull)vc sender:(id _Nullable)sender

    Parameters

    splitViewController

    The split view controller whose secondary view controller is being updated.

    vc

    The view controller being displayed in the secondary position.

    sender

    The object that made the request.

    Return Value

    YEStrue if you handled the presentation of the view controller or NOfalse if you want the split view controller to do it.

    Discussion

    When its showDetailViewController:sender: method is called, the split view controller calls this method to see if your delegate wants to handle the presentation of the specified view controller. If you implement this method and ultimately return YEStrue, your implementation is responsible for presenting the specified view controller in the secondary position of the split view interface.

    If you do not implement this method or if your implementation returns NOfalse, the split view controller presents the view controller in an appropriate way.

    Availability

    Available in iOS 8.0 and later.

  • Asks the delegate whether the first view controller should be hidden for the specified orientation.

    Deprecation Statement

    Orientation-related delegate methods are no longer supported.

    Declaration

    Swift

    optional func splitViewController(_ svc: UISplitViewController, shouldHideViewController vc: UIViewController, inOrientation orientation: UIInterfaceOrientation) -> Bool

    Objective-C

    - (BOOL)splitViewController:(UISplitViewController * _Nonnull)svc shouldHideViewController:(UIViewController * _Nonnull)vc inOrientation:(UIInterfaceOrientation)orientation

    Parameters

    svc

    The split view controller that owns the first view controller.

    vc

    The first view controller in the array of view controllers.

    orientation

    The orientation being considered.

    Return Value

    YEStrue if the view controller should be hidden in the specified orientation or NOfalse if it should be visible. If you do not implement this method, a value of YEStrue is assumed for portrait orientations and NOfalse is assumed for landscape orientations.

    Discussion

    The split view controller calls this method only for the first child view controller in its array. The second view controller always remains visible regardless of the orientation.

    Prior to iOS 5.0, the first view controller was always hidden in portrait orientations and always shown in landscape orientations. If you do not implement this method in your delegate object, that default behavior remains in effect.

    Availability

    Available in iOS 5.0 and later.

    Deprecated in iOS 8.0.

  • Tells the delegate that the specified view controller is about to be hidden.

    Deprecation Statement

    Implement the splitViewController:willChangeToDisplayMode: method instead.

    Declaration

    Swift

    optional func splitViewController(_ svc: UISplitViewController, willHideViewController aViewController: UIViewController, withBarButtonItem barButtonItem: UIBarButtonItem, forPopoverController pc: UIPopoverController)

    Objective-C

    - (void)splitViewController:(UISplitViewController * _Nonnull)svc willHideViewController:(UIViewController * _Nonnull)aViewController withBarButtonItem:(UIBarButtonItem * _Nonnull)barButtonItem forPopoverController:(UIPopoverController * _Nonnull)pc

    Parameters

    svc

    The split view controller that owns the specified view controller.

    aViewController

    The view controller being hidden.

    barButtonItem

    A button you can add to your toolbar.

    pc

    The popover controller that uses taps in barButtonItem to display the specified view controller.

    Discussion

    When the split view controller rotates from a landscape to portrait orientation, it normally hides one of its view controllers. When that happens, it calls this method to coordinate the addition of a button to the toolbar (or navigation bar) of the remaining custom view controller. If you want the soon-to-be hidden view controller to be displayed in a popover, you must implement this method and use it to add the specified button to your interface.

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 8.0.

  • Tells the delegate that the specified view controller is about to be shown again.

    Deprecation Statement

    Implement the splitViewController:willChangeToDisplayMode: method instead.

    Declaration

    Swift

    optional func splitViewController(_ svc: UISplitViewController, willShowViewController aViewController: UIViewController, invalidatingBarButtonItem barButtonItem: UIBarButtonItem)

    Objective-C

    - (void)splitViewController:(UISplitViewController * _Nonnull)svc willShowViewController:(UIViewController * _Nonnull)aViewController invalidatingBarButtonItem:(UIBarButtonItem * _Nonnull)button

    Parameters

    svc

    The split view controller that owns the specified view controller.

    aViewController

    The view controller being hidden.

    button

    The button used to display the view controller while it was hidden.

    Discussion

    When the view controller rotates from a portrait to landscape orientation, it shows its hidden view controller once more. If you added the specified button to your toolbar to facilitate the display of the hidden view controller in a popover, you must implement this method and use it to remove that button.

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 8.0.

  • Tells the delegate that the hidden view controller is about to be displayed in a popover.

    Deprecation Statement

    Orientation-related delegate methods are no longer supported.

    Declaration

    Swift

    optional func splitViewController(_ svc: UISplitViewController, popoverController pc: UIPopoverController, willPresentViewController aViewController: UIViewController)

    Objective-C

    - (void)splitViewController:(UISplitViewController * _Nonnull)svc popoverController:(UIPopoverController * _Nonnull)pc willPresentViewController:(UIViewController * _Nonnull)aViewController

    Parameters

    svc

    The split view controller that owns the hidden view controller.

    pc

    The popover controller that is about to display the view controller.

    aViewController

    The view controller to be displayed in the popover.

    Discussion

    The toolbar button you add to your user interface facilitates the display of the hidden view controller in response to user taps. When the user taps that button, the split view controller calls this method. You can use this method to perform any additional steps prior to displaying the currently hidden view controller.

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 8.0.