A proxy that represents one subview of a layout.
This type acts as a proxy for a view that your custom layout container
places in the user interface. ``Layout`` protocol methods
receive a ``LayoutSubviews`` collection that contains exactly one
proxy for each of the subviews arranged by your container.
Use a proxy to get information about the associated subview, like its
dimensions, layout priority, or custom layout values. You also use the
proxy to tell its corresponding subview where to appear by calling the
proxy's ``LayoutSubview/place(at:anchor:proposal:)`` method.
Do this once for each subview from your implementation of the layout's
``Layout/placeSubviews(in:proposal:subviews:cache:)`` method.
You can read custom layout values associated with a subview
by using the property's key as an index on the subview. For more
information about defining, setting, and reading custom values,
see ``LayoutValueKey``.
Asks the subview for its dimensions and alignment guides.
Call this method to ask a subview of a custom ``Layout`` type
about its size and alignment properties. You can call it from
your implementation of any of that protocol's methods, like
``Layout/placeSubviews(in:proposal:subviews:cache:)`` or
``Layout/sizeThatFits(proposal:subviews:cache:)``, to get
information for your layout calculations.
When you call this method, you propose a size using the `proposal`
parameter. The subview can choose its own size, but might take the
proposal into account. You can call this method more than
once with different proposals to find out if the view is flexible.
For example, you can propose:
* ``ProposedViewSize/zero`` to get the subview's minimum size.
* ``ProposedViewSize/infinity`` to get the subview's maximum size.
* ``ProposedViewSize/unspecified`` to get the subview's ideal size.
If you need only the view's height and width, you can use the
``sizeThatFits(_:)`` method instead.
- Parameter proposal: A proposed size for the subview. In SwiftUI,
views choose their own size, but can take a size proposal from
their parent view into account when doing so.
- Returns: A ``ViewDimensions`` instance that includes a height
and width, as well as a set of alignment guides.
method · iOS 16.0+
sizeThatFits
TypeScript
sizeThatFits(proposal: ProposedViewSize): { width: number; height: number }
Asks the subview for its size.
Use this method as a convenience to get the ``ViewDimensions/width``
and ``ViewDimensions/height`` properties of the ``ViewDimensions``
instance returned by the ``dimensions(in:)`` method, reported as a
<doc://com.apple.documentation/documentation/CoreFoundation/CGSize>
instance.
- Parameter proposal: A proposed size for the subview. In SwiftUI,
views choose their own size, but can take a size proposal from
their parent view into account when doing so.
- Returns: The size that the subview chooses for itself, given the
proposal from its container view.
Assigns a position and proposed size to the subview.
Call this method from your implementation of the ``Layout``
protocol's ``Layout/placeSubviews(in:proposal:subviews:cache:)``
method for each subview arranged by the layout.
Provide a position within the container's bounds where the subview
should appear, and an anchor that indicates which part of the subview
appears at that point.
Include a proposed size that the subview can take into account when
sizing itself. To learn the subview's size for a given proposal before
calling this method, you can call the ``dimensions(in:)`` or
``sizeThatFits(_:)`` method on the subview with the same proposal.
That enables you to know subview sizes before committing to subview
positions.
> Important: Call this method only from within your
``Layout`` type's implementation of the
``Layout/placeSubviews(in:proposal:subviews:cache:)`` method.
If you call this method more than once for a subview, the last call
takes precedence. If you don't call this method for a subview, the
subview appears at the center of its layout container and uses the
layout container's size proposal.
- Parameters:
- position: The place where the anchor of the subview should
appear in its container view, relative to container's bounds.
- anchor: The unit point on the subview that appears at `position`.
You can use a built-in point, like ``UnitPoint/center``, or
you can create a custom ``UnitPoint``.
- proposal: A proposed size for the subview. In SwiftUI,
views choose their own size, but can take a size proposal from
their parent view into account when doing so.
get · iOS 16.0+
spacing
TypeScript
get spacing(): ViewSpacing
Swift declaration
var spacing: ViewSpacing { get }
The subviews's preferred spacing values.
This ``ViewSpacing`` instance indicates how much space a subview
in a custom layout prefers to have between it and the next view.
It contains preferences for all edges, and might take into account
the type of both this and the adjacent view. If your ``Layout`` type
places subviews based on spacing preferences, use this instance
to compute a distance between this subview and the next. See
``Layout/placeSubviews(in:proposal:subviews:cache:)`` for an
example.
You can also merge this instance with instances from other subviews
to construct a new instance that's suitable for the subviews' container.
See ``Layout/spacing(subviews:cache:)``.
get · iOS 16.0+
priority
TypeScript
get priority(): number
Swift declaration
var priority: Double { get }
The layout priority of the subview.
If you define a custom layout type using the ``Layout``
protocol, you can read this value from subviews and use the value
when deciding how to assign space to subviews. For example, you
can read all of the subview priorities into an array before
placing the subviews in a custom layout type called `BasicVStack`:
extension BasicVStack {
func placeSubviews(
in bounds: CGRect,
proposal: ProposedViewSize,
subviews: Subviews,
cache: inout ()
) {
let priorities = subviews.map { subview in
subview.priority
}
// Place views, based on priorities.
}
}
Set the layout priority for a view that appears in your layout by
applying the ``View/layoutPriority(_:)`` view modifier. For example,
you can assign two different priorities to views that you arrange
with `BasicVStack`:
BasicVStack {
Text("High priority")
.layoutPriority(10)
Text("Low priority")
.layoutPriority(1)
}
Skipped declarations
1 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.
