reservedRegions(kind:options:layoutDirectionBehavior:)
Returns an array of reserved regions that match the selection options you specify.
Declaration
func reservedRegions(kind: ReservedRegion.Kind, options: ReservedRegion.QueryOptions = [], layoutDirectionBehavior: LayoutDirectionBehavior = .mirrors) -> [ReservedRegion]Parameters
- kind:
The kind of reserved region to return, such as Occlusion or Division.
- options:
Options that change which regions the method returns. By default, the method returns only active regions. Pass Includeinactive to also return regions that aren’t currently active.
- layoutDirectionBehavior:
A value that determines how the method handles right-to-left layout directions. By default, the system mirrors the frames of the regions. Pass Fixed to get unmirrored frames.
Return Value
The reserved regions that overlap the view, with frames in the view’s coordinate space.
Discussion
A reserved region is an area of your view that an entity reserves, such as the device hardware. Arrange your view’s content around it. Each region describes a frame, margins, active state, and an identifier.
There are two categories of reserved regions:
- occlusion
An area where an element, such as the Dynamic Island, a camera, or window controls, cover your content. Place content outside this area.
- division
An area where content splits into separate regions, such as at the fold of a hinge. Arrange your content on both sides of this area.
Call this method on the proxy of a GeometryReader to get the reserved regions that overlap your view. By default, the method returns only the active regions. To also get the inactive regions, pass includeInactive for the options parameter.
In the following example, RegionAvoidingLayout is a layout that you write yourself. It takes the reserved regions from the geometry proxy, and places each view it contains in a spot that doesn’t overlap a region:
GeometryReader { proxy in
RegionAvoidingLayout(
regions: proxy.reservedRegions(kind: .occlusion)
) {
ForEach(items) { item in
ItemView(item)
}
}
}Make sure a region’s frame and your layout’s positions use the same coordinates. The frame is measured from the top-leading corner of the view you read it from, but the bounds that a layout receives in placeSubviews(in:proposal:subviews:cache:) don’t always start at (0, 0). Do your calculations from (0, 0), and add bounds.origin only when you place each view.
With some right-to-left languages, SwiftUI flips the left and right sides of a layout. To keep reserved regions consistent with the flipped layout, the system mirrors the frames of reserved regions by default before it gives them to you. A layout that flips automatically, such as a custom Layout, lines up with the mirrored frames without extra work.
If you position content in a way that doesn’t flip with the layout direction, pass LayoutDirectionBehavior.fixed for the layoutDirectionBehavior parameter to get the unmirrored frames.
For more information, see ReservedRegion.