QuickLayout

QuickLayout provides several key advantages for UIKit development:

• Lightning-Fast Performance: Uses a custom layout engine that avoids the overhead of Auto Layout or Flexbox.
• Modern Layout Primitives: Uses lightweight, pure Swift structs like HStack, VStack, ZStack, Grid, and Flow that do not add extra views to the hierarchy.
• Easy Integration: The @QuickLayout macro automates subview management and setup.
• Thread-Safe: The API can be used concurrently and off the main thread (refer to concepts/thread-safety/ for specific caveats).

A LazyView is a design pattern in QuickLayout used to delay the initialization of a view until it is actually required by the layout. This pattern is intended to improve startup time, scroll performance, and other business metrics by avoiding the immediate creation of views that might not be visible or needed.

LazyView behaves similarly to lazy variables in Swift, but includes an ifLoaded getter. This getter allows you to safely access and modify the underlying view only if it has already been initialized, without triggering a new load.

private var replyButton = LazyView { [weak self] in
  /// This closure is called when the view is used in the layout for the first time.
  let button = UIButton(type: .system)
  ...
  return button
}

The core QuickLayout layout algorithm (including VStack, HStack, frame, and padding) is thread-safe. However, the thread safety of a complete layout operation is determined by its leaf elements.

Critical Constraint: If your layout hierarchy contains UIView instances, you must perform layout operations on the main thread. This is because UIView methods like sizeThatFits and applyFrame are not thread-safe and attempting to use them on background threads will result in a runtime error.

QuickLayout may perform up to two measurements to determine child sizes. To ensure high performance:

• Fixed-size elements (e.g., .frame() or UIImage) are measured only once.
• Fully flexible elements are not measured directly; they receive a proportion of available space.
• Avoid double measurements: This occurs if a stack contains two or more partially flexible views (like UILabel) and the proposed size is smaller than their intrinsic content size. Signs of double measurement include unexpected line breaks or text truncation.
• Solution: Use the .layoutPriority() modifier to specify the measurement order of child elements, which helps prevent multiple measurement passes.

A Frame element acts like a 'picture frame': it ignores the size proposed by its parent and instead dictates a specific size to its child.

When quick_layoutThatFits(_:) is called on a Frame:

1. The Frame ignores the incoming proposedSize.
2. It creates a new proposed size based on its own fixed width and height.
3. The child is then asked to layout using this new fixed size.
4. The Frame itself adopts the fixed width and height as its own size.

struct FrameElement: Element {

  private let child: Element
  private let width: CGFloat
  private let height: CGFloat

  public func quick_layoutThatFits(_ proposedSize: CGSize) -> LayoutNode {
    let frameSize = CGSize(width: width, height: height)
    let childNode = child.quick_layoutThatFits(frameSize)
    return LayoutNode(frameSize, [childNode])
  }
}

The alignment property in a stack controls how child elements are positioned inside the stack, rather than how the stack itself is positioned within its parent.

• In a VStack, alignment only affects the horizontal alignment of children.
• In an HStack, alignment only affects the vertical alignment of children.

Alignment guides allow you to override the default alignment behavior of containers like HStack, VStack, or ZStack. While these stacks use standard values (e.g., .center, .leading, .top) by default, you can define custom rules for how children are positioned within the container using the alignmentGuide methods on an Element.

// Example of applying an alignment guide to an element
element
  .alignmentGuide(.emojiTitle) { _ in 0 }