StackFrameLayout '+' Operator Syntax: Adding Views and Spacing in FrameLayoutKit

Use the + operator in StackFrameLayout to add single views, arrays of views, or numeric spacing literals, returning a FrameLayout instance for immediate constraint configuration.

The StackFrameLayout class in the kennic/framelayoutkit repository provides a DSL-like syntax for building iOS layouts through operator overloading. By leveraging the + operator syntax, developers can declaratively add views and spacing without verbose method calls, streamlining the creation of complex vertical and horizontal stacks.

Understanding the '+' Operator Overloads

The + operator in StackFrameLayout is overloaded to handle four distinct use cases, each defined as a static function in StackFrameLayout+DSL.swift. These overloads enable fluent, chainable layout construction.

Adding Single Views with '+'

When the right-hand side is a UIView, the operator adds that view to the stack and returns a FrameLayout wrapper for constraint configuration.

let stack = StackLayout { layout in
    layout + UIImageView(image: UIImage(named: "avatar"))
}

Implementation: The overload static func +(lhs: StackFrameLayout, rhs: UIView? = nil) -> FrameLayout handles this case by forwarding to the add(_:) method in StackFrameLayout.swift.

Adding Multiple Views with Array Syntax

Passing an array of UIView objects adds each view in sequence, returning an array of FrameLayout instances for batch configuration.

let stack = StackLayout { layout in
    layout + [titleLabel, subtitleLabel, descriptionLabel]
}

Implementation: The overload static func +(lhs: StackFrameLayout, rhs: [UIView]? = nil) -> [FrameLayout] iterates through the array and calls add(_:) for each view.

Inserting Spacers with Numeric Literals

Using a numeric literal (CGFloat, Double, or Int) on the right-hand side inserts a fixed-size spacer between views.

let stack = StackLayout { layout in
    layout + avatarImageView
    layout + 16          // 16‑pt vertical space
    layout + nameLabel
}

Implementation: The numeric overloads all forward to addSpace(_:) in StackFrameLayout.swift, which creates a spacer view with the specified dimension.

Using the '---' Operator for Explicit Spacing

The --- operator provides an alternative, more explicit syntax for adding space that visually resembles a "gap" in code.

let stack = StackLayout { layout in
    layout + avatarImageView
    layout --- 24        // explicit 24‑pt spacer
    layout + nameLabel
}

Implementation: Defined as static func ---(lhs: StackFrameLayout, _ size: CGFloat = 0) -> FrameLayout, this operator offers the same functionality as the numeric + overload with enhanced readability.

Implementation Details in FrameLayoutKit

The operator DSL is implemented through specific extensions and core methods that ensure type safety and chainability.

Source File Structure

File	Role
StackFrameLayout+DSL.swift	Defines the + and --- operator overloads for StackFrameLayout (view addition, array addition, and spacing).
StackFrameLayout.swift	Core implementation containing add(_:) and addSpace(_:) methods that the operators delegate to.
ScrollStackView+Chainable.swift	Mirrors the same operator DSL pattern for ScrollStackView, demonstrating the reusable architecture.
Example/ViewController.swift	Real-world usage examples showing the operators in production code.

Core Methods and Return Values

All operator overloads delegate to two fundamental methods in StackFrameLayout.swift:

• add(_:) – Creates a FrameLayout, assigns the targetView, and appends it to the internal view array.
• addSpace(_:) – Generates a spacer FrameLayout with a fixed size along the stack's axis.

Each operator is marked with @discardableResult, allowing you to ignore the returned FrameLayout when you only need the insertion side effect. When captured, the return value enables immediate constraint configuration through the FrameLayout chainable API.

Practical Usage Examples

The following examples demonstrate complete layout construction using the + operator syntax in real-world scenarios.

Basic Vertical Stack with Spacing

StackLayout { layout in
    layout + profileImageView
    layout +--- 12
    layout + [firstNameField, lastNameField]
    layout +--- 8
    layout + submitButton
}

Explanation:

• + profileImageView adds the profile picture to the stack.
• +--- 12 inserts a 12‑point vertical gap using the combined operator syntax.
• + [firstNameField, lastNameField] adds two text fields simultaneously, returning an array of FrameLayout objects for individual constraint tuning.
• +--- 8 adds a smaller gap before the button.
• + submitButton completes the layout with the action button.

Horizontal Button Group with Explicit Spacers

StackLayout(axis: .horizontal) { layout in
    layout + cancelButton
    layout --- 20
    layout + confirmButton
}

Explanation:

• The --- operator provides explicit visual separation between the cancel and confirm actions, inserting a 20‑point horizontal spacer.

Mixed Layout with Chainable Configuration

let stack = StackLayout { layout in
    let titleLayout = layout + titleLabel
    titleLayout.height = 44
    
    layout + 24  // spacer
    
    let imageLayout = layout + heroImageView
    imageLayout.contentMode = .scaleAspectFill
    imageLayout.clipsToBounds = true
}

Explanation:

• Capturing the return value of + titleLabel allows immediate height constraint assignment.
• The numeric + 24 inserts spacing without configuration.
• The final view addition demonstrates chainable property setting on the returned FrameLayout.

Summary

• Operator Overloads: StackFrameLayout provides + overloads for UIView, [UIView], and numeric literals, plus the --- operator for explicit spacing.
• Source Location: All operators are defined in StackFrameLayout+DSL.swift and delegate to add(_:) and addSpace(_:) in StackFrameLayout.swift.
• Return Values: Each operator returns a FrameLayout (or array thereof) marked with @discardableResult, enabling both fluent chaining and fire-and-forget usage.
• DSL Syntax: The operators enable declarative layout construction that reads naturally, combining view insertion and spacing in a single expressive syntax.

Frequently Asked Questions

What types does the '+' operator accept in StackFrameLayout?

The + operator in StackFrameLayout accepts three distinct right-hand side types: a single UIView (adding one view), an array of UIView objects [UIView] (adding multiple views), and numeric literals such as CGFloat, Double, or Int (inserting fixed-size spacers). Each overload returns a FrameLayout or array of FrameLayout objects for immediate constraint configuration.

How does the '---' operator differ from using '+' with a number?

Both the --- operator and the numeric + overload call the same underlying addSpace(_:) method in StackFrameLayout.swift, but the --- operator provides enhanced readability. While + 16 inserts a spacer, --- 16 visually resembles a gap or separation in code, making the layout's visual structure more apparent to developers reading the source.

Can I ignore the return value when using the '+' operator?

Yes. All + operator overloads in StackFrameLayout+DSL.swift are marked with @discardableResult, meaning the compiler will not warn if you ignore the returned FrameLayout. This is useful when you only need the side effect of adding a view or spacer. However, capturing the return value enables immediate configuration of constraints, alignment, and sizing through the FrameLayout chainable API.

Where are the '+' operators implemented in the FrameLayoutKit source code?

The operator overloads are defined in FrameLayoutKit/Classes/Extensions/StackFrameLayout+DSL.swift. These static functions delegate to the core add(_:) and addSpace(_:) methods located in FrameLayoutKit/Classes/StackFrameLayout.swift. The same DSL pattern is also mirrored in ScrollStackView+Chainable.swift for the ScrollStackView class, demonstrating the reusable architecture across the library.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}