Contents

UIArrangementViewController

A view controller that dynamically lays out primary and secondary view controllers based on size class, orientation, and reserved regions.

Declaration

@MainActor class UIArrangementViewController

Overview

Use an arrangement view controller to lay out two related content view controllers differently depending on the current size classes, orientation, and status of reserved regions such as the fold on iPhone Duo. The arrangement view helps you improve how your app handles a folded display in addition to a flat display.

Because an arrangement view controller is a container that lays out other view controllers, avoid adding an arrangement view controller inside another container such as a scroll view, split view controller, collection view, or other container view that lays out other views. Also, avoid placing some container views inside an arrangement view controller, such as a split view controller or tab view controller.

When iPhone Duo is fully open or closed, people interact with the flat display like other iPhone and iPad models. An arrangement view controller is useful when:

  • You want to place two views next to each other horizontally when someone is holding a device in landscape orientation or above and below each other when someone is holding a device in portrait orientation, without having to write conditional logic to switch between horizontal and vertical stacks.

  • You want to adjust how much space each view takes when someone folds the display.

  • You want to layer one view over another view on a flat display, and place the views next to each other when the device is folded. This arrangement works well when there’s a clear foreground and background relationship between your views, such as a view for video playback and a view with playback controls.

Arrangement view controllers offer two distinct types of arrangement: split and overlay. You specify the split arrangement to indicate the views lay out next to each other, either horizontally or vertically. You specify the overlay arrangement to indicate the views layer over each other on a flat display and next to each other on a folded display.

For more information on designing your app to use an arrangement view, see Designing for iPhone Duo.

Configure an overlay arrangement

An overlay arrangement view controller places a primary view controller and a secondary view controller in a stacked arrangement when the device has a flat display, or next to each other horizontally when someone is holding a device in landscape orientation or above and below each other when someone is holding a device in portrait orientation. Here’s how the overlay arrangement positions the primary and secondary views:

  • In a stacked overlay arrangement, the arrangement places the primary view above the secondary view in the z-axis.

  • When someone holds a folded iPhone Duo in landscape orientation, the arrangement places the secondary view in the leading position and the primary view in the trailing position.

  • When someone holds a folded iPhone Duo in portrait orientation, the arrangement places the secondary view in the top position and the primary view in the bottom position.

Create an overlay arrangement view controller by specifying a primary and secondary view controller, and call the updateArrangement(_:animated:) method with overlay in Swift, or the updateArrangement: method with overlayArrangement in Objective-C:

For more information on configuring layout for a folded iPhone Duo in an overlay arrangement, see Customize a folded layout.

Configure a split arrangement

Unlike an overlay arrangement, which typically layers its two views and only separates them when the device folds, a split arrangement view always keeps its primary and secondary views in separate spaces: next to each other horizontally when someone is holding the device in landscape orientation, or stacked vertically when someone is holding the device in portrait orientation. Here’s how the split arrangement positions the primary and secondary views:

  • In landscape orientation, the arrangement view places the primary view in the leading position and the secondary view in the trailing position.

  • In portrait orientation, the arrangement view places the primary view in the top position and the secondary view in the bottom position.

  • When someone is holding a closed iPhone Duo in landscape orientation, the split arrangement only shows the primary view.

Create a split arrangement by specifying a primary and secondary view controller, and call the updateArrangement(_:animated:) method with split in Swift, or the updateArrangement: method with splitArrangement in Objective-C:

For more information on adjusting view sizes in a split arrangement, see Adjust a split arrangement’s layout sizing.

Limit an arrangement by orientation

You can limit which axes your split or overlay arrangement view controller supports by specifying the axes for the arrangement. The following example shows an arrangement that only splits vertically:

Use axes(_:) in Swift or axes in Objective-C to set the axes for a split arrangement, or axes(_:) in Swift or axes in Objective-C to set the axes for an overlay arrangement.

Topics

Creating an arrangement view controller

Configuring the arrangement

Managing arrangement view controllers

Getting view state

See Also

Container view controllers