Structures

AttributedText allows you to apply strongly-typed attributes to strings (much like the AttributedString type introduced in iOS 15). You can then access the attributedString property to get an attributed string with those attributes applied.

For example:

var text = AttributedText(string: "Hello, world")
// Apply a font to the entire range
text.font = .systemFont(ofSize: 20)

// Apply a color to part of the string
let range = text.string.range(of: "world")!
text[range].color = .blue

// Render the attributed text
let label = AttributedLabel(attributedText: text.attributedString)

The context passing to the backingViewDescription of an Element.

Context object passed into updateUIView.

A two-way binding between a focusable element’s backing view and a FocusState-wrapped property.

Generally you should not need to interact with this type directly. However, you can use focus bindings to add focus support to custom elements.

Adding Focus Bindings

On a FocusState, call the binding(for:) method to get a binding bound to an optional value, or binding() to get a binding bound to a boolean.

To set up the 2-way binding, there are 2 steps:

1. Assign actions to the nested FocusTrigger, so that your backing view is updated when the FocusState‘s value changes.

2. Call the onFocus and onBlur callbacks when your backing view gains or loses focus, so that the value of the bound FocusState is updated.

Example

final class FocusableView: UIView {
    var focusBinding: FocusBinding? {
        didSet {
            oldValue?.trigger.focusAction = nil
            oldValue?.trigger.blurAction = nil

            guard let focusBinding = focusBinding else { return }

            focusBinding.trigger.focusAction = { [weak self] in
                self?.becomeFirstResponder()
            }
            focusBinding.trigger.blurAction = { [weak self] in
                self?.resignFirstResponder()
            }

            if isFirstResponder {
                focusBinding.onFocus()
            } else {
                focusBinding.onBlur()
            }
        }
    }

    @discardableResult
    override func becomeFirstResponder() -> Bool {
        let focused = super.becomeFirstResponder()
        if focused {
            focusBinding?.onFocus()
        }
        return focused
    }

    @discardableResult
    override func resignFirstResponder() -> Bool {
        let blurred = super.resignFirstResponder()
        if blurred {
            focusBinding?.onBlur()
        }
        return blurred
    }
}

• Tag: FocusBinding

A property wrapper type that can read and write a value that represents the placement of focus.

Use this property wrapper in conjunction with modifiers on elements that support focus, such as TextField.focused(when:equals:) and TextField.focused(when:), to describe when those elements should have focus. When focus enters the modified element, the wrapped value of this property updates to match a given value. Similarly, when focus leaves, the wrapped value of this property resets to nil or false. Setting this property’s value programmatically has the reverse effect, causing focus to move to the element associated with the updated value.

In the following example of a simple login screen, when the user presses the Sign In button and one of the fields is still empty, focus moves to that field. Otherwise, the sign-in process proceeds.

struct LoginForm: ProxyElement {
    enum Field: Hashable {
        case username
        case password
    }

    var username: String
    var password: String
    var handleLogin: () -> Void

    @FocusState private var focusedField: Field?

    var elementRepresentation: Element {
        Column { column in
            column.add(
                child: TextField(text: "")
                    .focused(when: $focusedField, equals: .username)
            )

            column.add(
                child: TextField(text: "")
                    .focused(when: $focusedField, equals: .password)
            )

            column.add(
                child: Button(
                    onTap: {
                        if username.isEmpty {
                            focusedField = .username
                        } else if password.isEmpty {
                            focusedField = .password
                        } else {
                            handleLogin()
                        }
                    },
                    wrapping: Label(text: "Sign In")
                )
            )
        }
    }
}

To allow for cases where focus is completely absent from a view tree, the wrapped value must be either an optional or a Boolean. Set the focus binding to false or nil as appropriate to remove focus from all bound fields. You can also use this to remove focus from a TextField and thereby dismiss the keyboard.

Auto-Focus

To auto-focus a field when it appears, set the value in an onAppear hook.

struct Example: ProxyElement {
    @FocusState var isFocused: Bool

    var elementRepresentation: Element {
        TextField(text: "")
            .focused(when: $isFocused)
            .onAppear {
                isFocused = true
            }
    }
}

Avoid Ambiguous Focus Bindings

A TextField can have only one focus binding, stored in its focusBinding property. If you apply the focused modifier multiple times, the last one will overwrite the previous value.

On the other hand, binding the same value to two views is ambiguous. In the following example, two separate fields bind focus to the name value:

struct Content: ProxyElement {
    enum Field: Hashable {
        case name
        case fullName
    }

    @FocusState private var focusedField: Field?

    var elementRepresentation: Element {
        Column { column in
            column.add(
                child: TextField(text: "")
                    .focused(when: $focusedField, equals: .name)
            )

            column.add(
                child: TextField(text: "")
                    .focused(when: $focusedField, equals: .name) // incorrect re-use of .name
            )
        }
    }
}

If the user moves focus to either field, the focusedField binding updates to name. However, if the app programmatically sets the value to name, the last field bound will be chosen.

An alignment in both axes.

An alignment position along the horizontal axis.

An alignment position along the vertical axis.

Represents an a proportional relationship between width and height.

Generic result builder for converting blocks of Child... into [Child].

Places a decoration element behind or in front of the given wrapped element, and positions it according to the position parameter.

The size and position of the element is determined only by the wrapped element, the decoration element does not affect the layout at all.

Example

The arrows represent the measured size of the element for layout purposes.

┌───────────────────┐     ┌──────┐
│    Decoration     │     │      │
│ ┏━━━━━━━━━━━━━━━┓ │ ▲   │      ┣━━━━━━━━━━┓   ▲
│ ┃               ┃ │ │   └─┳────┘          ┃   │
│ ┃    Wrapped    ┃ │ │     ┃    Wrapped    ┃   │
│ ┃               ┃ │ │     ┃               ┃   │
│ ┗━━━━━━━━━━━━━━━┛ │ ▼     ┗━━━━━━━━━━━━━━━┛   ▼
└───────────────────┘
  ◀───────────────▶         ◀───────────────▶

An element’s size and its alignment guides in its own coordinate space.

You can access the size of the element through the width and height properties. You can access alignment guide values by subscripting with the specific alignment.

These dimensions are typically used when setting an alignment guide on a stack, with StackElement.add(...).

Example

// get the alignment guide value for `VerticalAlignment.center`, falling back to the default
// value if no alignment guide has been set
dimensions[VerticalAlignment.center]

// get the alignment guide value for `HorizontalAlignment.trailing`, or `nil` if none has been
// set.
dimensions[explicit: .trailing]

See Also

StackElement.add()

Contains information about the current layout being measured by GeometryReader

Like Row, GridRow displays a list of items in a linear horizontal layout. Unlike Row, GridRow provides convenience for describing columnar layout.

Horizontally, GridRow children are stretched to fill the available space. Vertically, children are aligned according to the verticalAlignment property.

Children may be sized proportionally or absolutely. Proportionally-sized children are granted a proportion of the total layout space after absolutely-sized children and margins have been subtracted.

Example:

GridRow { row in
  row.verticalAlignment = .fill
  row.spacing = 8.0
  row.add(width: .proportional(0.75), child: name)
  row.add(width: .proportional(0.25), child: number)
  row.add(width: .absolute(100), child: status)
}

Expected layout:

┌────────────────────────────┬─┬────────┬─┬──────────────────┐
│            name            │ │ number │ │      status      │
│            (75%)           │8│  (25%) │8│     (100 pts)    │
│                            │ │        │ │                  │
●──────────── 150 ───────────● ●── 50 ──● ●─────── 100 ──────●
└────────────────────────────┴─┴────────┴─┴──────────────────┘
●──────────────────────────── 316 ───────────────────────────●

Hidden conditionally hides its wrapped element.

Keyed allows providing a Hashable value which is used during view updates to uniquely identify content during the diff process between the old and new element structure.

This is useful if you have two elements of the same type at the same depth in the element hierarchy, and you’d like to differentiate between them, eg for appearance transition purposes.

Example

Keying the image returned, so that a transition occurs when changing between a placeholder image and an available photo.

func imageElement() -> Element {
    if let photo = self.photo {
        return Image(image: photo)
                .transition(.fade)
                .keyed("photo")
    } else {
        return Image(image: self.placeholder)
                .transition(.fade)
                .keyed("placeholder")
    }
}

Contains layout-related metrics for an element.

Configuration options for caffeinated.

Generally these are only useful for experimenting with the performance profile of different element compositions, and you should stick with default.

A proxy that represents one child element of a layout.

This type acts as a proxy for a child element in a Layout. Layout protocol methods receive a LayoutSubelements collection that contains exactly one proxy for each of the child elements managed by the layout.

Use this proxy to get information about the associated element, like its size and traits. You should also use the proxy to tell its corresponding element where to appear by calling the proxy’s place(at:anchor:size:) method. Do this once for each subview from your implementation of the layout’s placeSubelements(in:subelements:environment:cache:) method.

A parent element which allows arbitrary, custom layout and positioning of its children.

Instead of creating a custom Element with a custom Layout, you might use this element to create a customized layout in a more lightweight way.

LayoutWriter { context, layout in
    layout.add(with: myFrame, child: myElement)
    layout.add(with: myOtherFrame, child: myOtherElement)

    layout.sizing = .unionOfChildren
}

Allows element lifecycle callbacks to be inserted anywhere into the element tree.

Changes the opacity of the wrapped element.

A layout implementation that linearly lays out an array of children along either the horizontal or vertical axis.

TintAdjustmentMode conditionally modifies the tint adjustment mode of its wrapped element.

Changes the transform of the wrapped element.

A normalized point in an element’s coordinate space.

Use a unit point to represent a location in an element without having to know the element’s rendered size. The point stores a value in each dimension that indicates the fraction of the element’s size in that dimension — measured from the element’s origin — where the point appears. For example, you can create a unit point that represents the center of any element by using the value 0.5 for each dimension:

let unitPoint = UnitPoint(x: 0.5, y: 0.5)

To project the unit point into the rendered element’s coordinate space, multiply each component of the unit point with the corresponding component of the element’s size:

let projectedPoint = CGPoint(
    x: unitPoint.x * size.width,
    y: unitPoint.y * size.height
)

You can perform this calculation yourself if you happen to know an element’s size, but Blueprint typically does this for you to carry out operations that you request, like when you place a subelement in a custom layout.

You can create custom unit points with explicit values, like the example above, or you can use one of the built-in unit points, like zero, center, or topTrailing. The built-in values correspond to the alignment positions of the similarly named, built-in Alignment types.

UserInteractionEnabled conditionally enables user interaction of its wrapped element.

Defines the maximum size for a measurement.

Currently this constraint type can only handles layout where the primary (breaking) axis is horizontal (row in CSS-speak).

UIView animation configuration values.

Enables VoiceOver focus to jump to the wrapped element via a trigger that can be manually fired.

Allows showing the system’s UIMenuController editing menu.

You can show the menu upon tap or long press:

myElement.editingMenu(show: .onLongPress) {
    EditingMenuItem.copying("A String")

    EditingMenuItem(.select) {
        print("Selected!")
    }
}

You can also show the menu as a result of another element’s onTap closure, using the trigger-based API:

EditingMenu { menu in
    MyRow(text: "Hello, World") {
        menu.show()
    }
} items: {
    EditingMenuItem.copying("A String")
}

A single item in an editing menu.

Describes a shadow that can be applied to text elements, like Label.