Class

NSStackView

A view that arranges an array of views horizontally or vertically and that automatically updates their placement and sizing when the window size changes.

Overview

A stack view employs Auto Layout (the system’s constraint-based layout feature) to arrange and align an array of views according to your specification. To use a stack view effectively, you need to understand the basics of Auto Layout constraints as described in Auto Layout Guide.

Basic Features of Stack Views

A stack view supports vertical and horizontal layouts and interacts dynamically with window resizing and Cocoa animations. You can easily reconfigure the contents of a stack view at runtime. That is, after you create and configure a stack view in Interface Builder, you can add or remove views dynamically without explicitly working with layout constraints. For example, if you configure a stack view with three checkboxes and dynamically add a fourth, the stack view automatically adds constraints as needed, according to the stack view’s configuration. The new checkbox gains dynamic layout configuration from the stack view.

Stack views are nestable: a stack view is a valid element in the views array of another stack view.

Layout Direction and Gravity Areas

A stack view has three so-called gravity areas that each identify a section of the stack view’s layout. A horizontal stack view, which is the default type, has a leading, a center, and a trailing gravity area. The ordering of these areas depends on the value of the stack view’s userInterfaceLayoutDirection property (inherited from the NSView class). In a left to right language, the leading gravity area in a horizontal stack view is on the left. To enforce a left to right layout independently of language, explicitly set the layout direction by calling the inherited userInterfaceLayoutDirection method on your stack view instance.

To specify vertical layout, use the orientation property and the vertical constant from the NSUserInterfaceLayoutOrientation enumeration. In a vertical stack view, the gravity areas always are top, center, and bottom.

View Detachment and Hiding

A stack view can automatically detach and reattach its views in response to layout changes, such as window resizing performed by the user, or resizing/repositioning of another view in the same view hierarchy. A view in a detached state is not present in the stack view’s view hierarchy, but it still consumes memory.

To allow views to detach, set the so-called clipping resistance for a stack view to a value lower than its default of NSLayoutPriorityRequired. See the setClippingResistancePriority(_:for:) method.

You can influence which views detach first (and reattach last). Do this by setting the so-called visibility priority for each view whose detachment order you want to specify. A view with a lower visibility priority detaches before one with a higher priority, and reattaches after it. See the NSStackView.VisibilityPriority enumeration and the setVisibilityPriority(_:for:) method.

To explicitly detach a view from a stack view, call the setVisibilityPriority(_:for:) method with a value of NSStackViewVisibilityPriorityNotVisible. To explicitly reattach a view to a stack view, call the same method with a value of NSStackViewVisibilityPriorityMustHold. If you hide a view that belongs to a stack view (by calling the view’s isHidden method with a value of true), the view does not detach from the stack view. It is no longer visible and it no longer receives input events, but it remains part of the view hierarchy and continues to participate in Auto Layout.

The system calls a stack view delegate method when a view is about to be detached and when a view has been reattached, giving you the opportunity to run code at those times. See NSStackViewDelegate.

Topics

Initializing a Stack View

init(views: [NSView])

Creates and returns a stack view with a specified array of views.

Responding to Stack-Related Changes

var delegate: NSStackViewDelegate?

The delegate object for the stack view.

protocol NSStackViewDelegate

To configure a custom class to respond to a view detaching from, or reattaching to, a stack view (an instance of the NSStackView class), configure the custom class to adopt the NSStackViewDelegate protocol. Then, in a stack view instance, set the delegate property to refer to an instance of your custom class.

Creating and Configuring a Stack View

func setViews([NSView], in: NSStackView.Gravity)

Specifies an array of views for a specified gravity area in the stack view, replacing any views previously assigned to the gravity area.

var alignment: NSLayoutConstraint.Attribute

The view alignment within the stack view.

var orientation: NSUserInterfaceLayoutOrientation

The horizontal or vertical layout direction of the stack view.

var spacing: CGFloat

The minimum spacing, in points, between adjacent views in the stack view.

var edgeInsets: NSEdgeInsets

The geometric padding inside the stack view, surrounding its views, in points.

var hasEqualSpacing: Bool

A Boolean value that indicates whether the spacing between adjacent views should equal each other.

Deprecated

Configuring Dynamic Behavior for a Stack View

func setClippingResistancePriority(NSLayoutConstraint.Priority, for: NSLayoutConstraint.Orientation)

Sets the Auto Layout priority for resisting clipping of views in the stack view when Auto Layout attempts to reduce the stack view’s size.

func setHuggingPriority(NSLayoutConstraint.Priority, for: NSLayoutConstraint.Orientation)

Sets the Auto Layout priority for the stack view to minimize its size, for a specified user interface axis.

Adding and Removing Views

func addView(NSView, in: NSStackView.Gravity)

Adds a view to a stack view gravity area, at the end of the gravity area.

func insertView(NSView, at: Int, in: NSStackView.Gravity)

Adds a view to a stack view gravity area at a specified index position.

func removeView(NSView)

Removes a specified view from the stack view.

Configuring Views in a Stack View

func customSpacing(after: NSView)

Returns the custom spacing, in points, between a specified view in the stack view and the view that follows it.

func setCustomSpacing(CGFloat, after: NSView)

Specifies custom spacing, in points, to employ between a specified view and the view that follows it in the stack view.

func visibilityPriority(for: NSView)

Returns the visibility priority for a specified view in the stack view.

func setVisibilityPriority(NSStackView.VisibilityPriority, for: NSView)

Sets the Auto Layout priority for a view to remain attached to the stack view when Auto Layout reduces the stack view’s size.

Inspecting a Stack View

var views: [NSView]

The array of views owned by the stack view.

func views(in: NSStackView.Gravity)

Returns the array of views in the specified gravity area in the stack view.

var detachedViews: [NSView]

An array containing the detached views from all of the stack view’s gravity areas.

func clippingResistancePriority(for: NSLayoutConstraint.Orientation)

Returns the Auto Layout priority for resisting clipping of views in the stack view when Auto Layout attempts to reduce the stack view’s size.

func huggingPriority(for: NSLayoutConstraint.Orientation)

Returns the Auto Layout priority for the stack view to minimize its size to fit its contained views as closely as possible, for a specified user interface axis.

Constants

enum NSUserInterfaceLayoutOrientation

The two stack view layout directions and, for clipping resistance and hugging priority, the two user interface axes.

enum NSStackView.Gravity

The various gravity areas available in a stack view.

struct NSStackView.VisibilityPriority

The various Auto Layout priorities for a view in the stack view to remain attached.

Relationships

Inherits From