I recently had the opportunity to give a talk at iOS Conf SG 2022:
in this talk, called SwiftUI Lessons, I don't share the usual content you can find on this website. Instead, I talk about my experience in transitioning to SwiftUI, coming from a UIKit developer's perspective.

The talk is addressed to both new and seasoned Apple platforms developers:

• video
• slides (pdf)
• slides source

If you know somebody making the jump into SwiftUI, feel free to send them this talk their way!

This build comes with a preview of Swift 5.6 (see main changes here), meaning that Swift Package Manager gains build tool/command plugins! See the associated Swift Evolution discussions here: SE-0303, SE-0325, SE-0332.

There is also plenty of developer's quality of life improvements, particularly in the Source Editor front. I recommend giving the official release notes a read.

Enough about Xcode; let's see what's new in SwiftUI!

Everything new in this Xcode version comes in the form of new and improved documentation; here, you can find small summaries of the changes. Each section links to the official (and updated) documentation.

Monospaced examples

Font/monospacedDigit(), Text/monospacedDigit(), and Font/monospaced() now come with examples and a longer explanation on how they work.

From Font/monospacedDigit() documentation:
/// This modifier only affects numeric characters, and leaves all other
/// characters unchanged. If the base font doesn't support fixed-width,
/// or _monospace_ digits, the font remains unchanged.

In particular, Font's monospaced() documentation suggests using AttributedString for advanced uses when mixing monospaced and normal text. The documentation also reminds us of AttributedString's markdown support, where we automatically get the monospaced style when we wrap text within `backticks`.

Padding cross-reference and modifier order

All padding modifiers (padding(_:_:), padding(_:), padding(_:)) have received new documentation with examples showcasing what's the difference between each modifier.

Just before each example image, the documentation warns about the modifier order, which is helpful for people just learning about SwiftUI.

At the end of each Discussion chapter, the documentation refers to all other padding modifiers alternatives, a nice touch for discoverability.

From View/padding(_:_:) documentation:
/// To control the amount of padding independently for each edge, use
/// ``View/padding(_:)``. To pad all outside edges of a view by a
/// specified amount, use ``View/padding(_:)``.

Scene padding

If you have ever wondered what the new scenePadding(_:) modifier is about, and what's the difference with the "old" padding modifiers, you're not alone (FB9487801). The first official word came out with a new WatchKit article after the reveal of the Apple Watch Series 7.

Thanks to Xcode 13.3b1, developers no longer have to find said article to discover the new modifier functionality: the new scenePadding(_:) documentation comes with a clear discussion explaining what this modifier is for.

Interestingly, as of today, this modifier behaves like other padding modifiers in all other platforms. The SwiftUI team could have made this modifier available only for WatchOS, but they chose not to.

Picker and tag enhancements

The complete Picker and View/tag(_:) documentation has improved with more straightforward descriptions and easier-to-understand examples. I find the new documentation/examples much clearer, especially the one with a Picker with an associated optional state (found in the tag documentation).

Picker's documentation also gains a new section explaining when explicit .tag(_:)s are necessary when using ForEach.

/// Other examples of when the views in a picker's ``ForEach`` need an explicit
/// tag modifier include when you:
/// * Select over the cases of an enumeration that conforms to the 
///   `Identifiable` protocol by using anything besides `Self` as the `id` 
///   parameter type. For example, a string enumeration might use the case's 
///   `rawValue` string as the `id`. That identifier type doesn't match the 
///   selection type, which is the type of the enumeration itself.
/// * Use an optional value for the `selection` input parameter. For that to
///   work, you need to explicitly cast the tag modifier's input as `Optional` 
///   to match.

Clearer luminanceToAlpha()

Lastly, we have another win for clarity with the new luminanceToAlpha() documentation, which now provides an improved example and references to the homonymous effect in SVG 2's specification.

Conclusions

Did you find anything else interesting in Xcode 13.3 beta 1? Please let me know!

defaults write com.apple.dt.XCBuild EnableSwiftBuildSystemIntegration 1

It's a very light update for SwiftUI. Let's see what's new.

TextField and SecureField

Both TextField and SecureField come with many initializers: instead of having parameters with default values, those views now have different overloads, either requiring or omitting such parameters.

For example we went from:

extension TextField where Label == Text {
  public init<S>(_ title: S, text: Binding<String>, prompt: Text? = nil) where S : StringProtocol
}

to:

extension TextField where Label == Text {
  public init<S>(_ title: S, text: Binding<String>, prompt: Text?) where S : StringProtocol
  public init<S>(_ title: S, text: Binding<String>) where S : StringProtocol
}

This change spans all TextField/SecureField overloads, is completely seamless for third-party developers, and is back-ported all the way to iOS 13.0, macOS 10.15, tvOS 13.0, watchOS 6.0.

This back-port is possible thanks to @_alwaysEmitIntoClient, which we covered here.

For example, if we take a look at SwiftUI's Swift Interface, we will see the implementation of the second initializer (from above):

extension TextField where Label == Text {
  @_alwaysEmitIntoClient @_disfavoredOverload 
  public init<S>(_ title: S, text: Binding<String>) where S : StringProtocol {
    self.init(title, text: text, onCommit: {})
  }
}

...while the first initializer just dropped the default value:

// From:
public init<S>(_ title: S, text: Binding<String>, prompt: Text? = nil) where S : StringProtocol

// To:
public init<S>(_ title: S, text: Binding<String>, prompt: Text?) where S : StringProtocol

All these new initializers, which are compatible with earlier OSes, come with the same documentation as the original initializers with the "extra" parameter, complete with mentions of:

• prompt parameter
• Focus API
• View.onSubmit view modifier

It's most likely an oversight, but it'd be great if this were a hint that a back-port of those features is on the way.

Conclusions

Did you find anything else interesting in Xcode 13.2 beta 2? Please let me know!

This is the sixth and last entry of the Five Stars SwiftUI Environment series. It's recommended to read the first few entries before proceeding: 1, 2, 3, 4, 5.

Struct, Enums, and primitives

SwiftUI environment values have been built specifically for these types, we've seen multiple examples of declaring a primitive environment value:

struct FSNumberKey: EnvironmentKey {
  static let defaultValue: Int = 5
}

extension EnvironmentValues {
  public var fsNumber: Int {
    get { self[FSNumberKey.self] } 
    set { self[FSNumberKey.self] = newValue }
  }
}

Replace Int with any other primitive, struct, or enum definition, and it will work the same way.

// Read:

struct ContentView: View {
  @Environment(\.fsNumber) var number: Int // 👈🏻

  var body: some View {
    Text("\(number)") // 👈🏻 
  }
}

// Set:

someView()
  .environment(\.fsNumber, 10)

about 90% of the built-in environment values fall under this category.

Bindings

The @Environment property wrapper gives us a read-only value, thus it makes sense to think about environment values as something set by a parent and read by a child.

However, we can use bindings to allow children to modify environment values, with the new changes bubbling up to their ancestors.

Take the following definition:

struct FSBoolBindingKey: EnvironmentKey {
  static var defaultValue: Binding<Bool> = .constant(false)
}

extension EnvironmentValues {
  var fsBoolBinding: Binding<Bool> {
    get { self[FSBoolBindingKey.self] }
    set { self[FSBoolBindingKey.self] = newValue }
  }
}

This is very similar to any other environment value type, but it lets child views both read and modify the value:

struct ContentView: View {
  @State var myBool = false

  var body: some View {
    VStack {
      Text(myBool ? "true" : "false")
      NestedView()
        .environment(\.myBoolBinding, $myBool) // 👈🏻 we inject myBool binding into the environment
    }
  }
}

struct NestedView: View {
  @Environment(\.myBoolBinding) @Binding var myBool: Bool // 👈🏻 we read the binding from the environment

  var body: some View {
    Toggle(isOn: _myBool.wrappedValue, label: EmptyView.init) // 👈🏻 we read/write the environment value!
  }
}

Here's another we way we could have defined the NestedView:

struct NestedView: View {
  @Environment(\.myBoolBinding) var myBool: Binding<Bool> // 👈🏻 different type

  var body: some View {
    Toggle(isOn: myBool, label: EmptyView.init) // 👈🏻 different isOn parameter
  }
}

This is equivalent to passing a binding as a parameter of a view, but via environment.

SwiftUI built-in binding environment values: presentationMode.

Optional bindings

In the previous FSBoolBindingKey definition, we've set a default value of .constant(false), which works great as long as we remember to set the binding in the environment before it's used:

struct ContentView: View {
  @State var myBool = false

  var body: some View {
    ...
    NestedView()
      .environment(\.myBoolBinding, $myBool) // 👈🏻 
    ...
  }
}

If we forget to set this value into the environment, NestedView (or any other view) won't be able to modify the myBoolBinding environment value.

Depending on our use case, this might be what we want. Alternatively, similarly to what we've seen in How to add optional @Bindings to SwiftUI views, we could define FSBoolBindingKey and fsBoolBinding with an associated optional binding:

struct FSBoolBindingKey: EnvironmentKey {
  static var defaultValue: Binding<Bool>?
}

extension EnvironmentValues {
  var fsBoolBinding: Binding<Bool>? {
    get { self[FSBoolBindingKey.self] }
    set { self[FSBoolBindingKey.self] = newValue }
  }
}

At this point, views using this value will have to deal with a binding that might or might not be there. In the following example, NestedView will use the environment value when present and, alternatively, will use a private state (that doesn't affect the environment):

struct NestedView: View {
  @Environment(\.fsBoolBinding) var myBool
  @State private var privateBool = false // 👈🏻 

  var body: some View {
    Toggle(isOn: myBool ?? $privateBool, label: EmptyView.init) // 👈🏻 
  }
}

SwiftUI built-in optional binding environment values: editMode.

Actions

This year we've seen the introduction of a new environment-actions pattern in SwiftUI:
instead of views directly accepting closures to trigger in specific scenarios, it's now common to set closures into the environment, which are then picked up and triggered by relevant/associated views.

An example is the new onSubmit modifier:

Form {
  TextField(...)
  TextField(...)
}
.onSubmit {
  print("Form submitted")
}
// 👆🏻 this closure is set into the environment and picked up by TextField, SecureField, and TextEditor.

To define a new action, we first define a struct accepting a closure (depending on our case, this closure may accept/return values):

struct FSAction {
  var action: () -> Void

  init(action: @escaping () -> Void = { }) {
    self.action = action
  }
}

We might have extra logic in this struct that we probably don't want to expose to other developers. Hence we set our action as private and, instead, we make the struct type callable via Swift's special callAsFunction method:

struct FSAction {
  private var action: () -> Void // 👈🏻 private

  func callAsFunction() { // 👈🏻 
    action()
  }

  init(action: @escaping () -> Void = { }) {
    self.action = action
  }
}

Next, we create the usual key and extend environment values:

struct FSActionKey: EnvironmentKey {
  static var defaultValue: FSAction = FSAction()
}

extension EnvironmentValues {
  var fsAction: FSAction {
    get { self[FSActionKey.self] }
    set { self[FSActionKey.self] = newValue }
  }
}

...and now we're ready to use this new action:

// Read:

struct ContentView: View {
  @Environment(\.fsAction) var action: FSAction // 👈🏻

  var body: some View {
    Button("Tap me") { action() } // 👈🏻 
  }
}

// Set:

someView()
  .environment(\.fsAction, FSAction { // 👈🏻 
    ...
  })

Thanks to FSAction's callAsFunction we don't need to reach for the FSAction.action property (and we can't, as it's private). Instead, we call the function directly on the FSAction instance. This helps hide any implementation detail of our FSAction struct.

SwiftUI built-in actions: dismissSearch (DismissSearchAction), openURL (OpenURLAction), refresh (RefreshAction). resetFocus (ResetFocusAction), dismiss (DismissAction).

Closures

The action pattern that we just introduced has an associated struct type that really is a wrapper for a closure. This was true for our simple case, but, in reality, our FSAction struct may contain implementation details that are just not exposed.

If we want our environment value to be just a closure and nothing else, we can skip the action struct definition, and use a closure directly:

struct ClosureKey: EnvironmentKey {
  static let defaultValue: () -> Void = { }
}

extension EnvironmentValues {
  public var fsAction: () -> Void {
    get { self[ClosureKey.self] }
    set { self[ClosureKey.self] = newValue }
  }
}

Which we can then use this way:

// Read:

struct ContentView: View {
  @Environment(\.fsAction) var action: () -> Void // 👈🏻

  var body: some View {
    Button("Tap me") { action() } // 👈🏻 
  }
}

// Set:

someView()
  .environment(\.fsAction) { // 👈🏻 
    ...
  }

Unlike SwiftUI views, which must be value types, environment values can also be reference types.

A kind reminder that Swift closures are reference types.

Classes

Speaking of reference types, we can also define environment values with an associated class type.

There are important implications when using a class rather than a struct:

• we can alter a class instance, and the exact change will be reflected anywhere else that same instance is referenced in the view hierarchy.
• views do not observe changes within classes defined in EnvironmentValues, regardless of whether the class is marked ObservableObject. If we're trying to do something similar to this, we should use environment objects instead.

Example:

public class FSClass {
  var x: Int

  init(x: Int = 5) {
    self.x = x
  }
}

private struct FSClassKey: EnvironmentKey {
  static let defaultValue = FSClass()
}

extension EnvironmentValues {
  public var fsClass: FSClass {
    get { self[FSClassKey.self] }
    set { self[FSClassKey.self] = newValue }
  }
}

Which we can then use like any other environment value:

// Read:

struct ContentView: View {
  @Environment(\.fsClass) private var fsClass // 👈🏻

  var body: some View {
    VStack {
      Text("\(fsClass.x)") // 👈🏻

      Button("change") {
        fsClass.x = Int.random(in: 1...99) 
        // 👆🏻 fsClass is a class, we can modify its properties
      }
    }
  }
}

// Set:

someView()
  .environment(\.fsClass, FSClass(x: 1))

There are very few reasons why we'd ever define a class-type environment value, but it's good to know that it's supported.

SwiftUI built-in class environment values: managedObjectContext (NSManagedObjectContext) and undoManager (UndoManager).

Conclusions

We've now completed the Five Stars SwiftUI environment series, thank you for reading, and I hope you've found these articles helpful!

What else would you like me to cover next? Let me know via email or Twitter!

Large Content Viewer

VStack {
  Button("Tap me") { print("Button Tapped") }
    .accessibilityShowsLargeContentViewer()
  
  Button("Tap me 2") { print("Button Tapped") }
    .accessibilityShowsLargeContentViewer {
      Text("A different text")
    }
}

Large Content Viewer is an accessibility feature that has been around since iOS 13.
In short, when an accessibility dynamic type size is enabled, it allows us to enlarge/highlight the UI element the user is hovering on via a system HUD.

With Xcode 13.2, we can now use it with SwiftUI as well.

Besides the two view modifiers shown in the example, SwiftUI now comes with a new accessibilityLargeContentViewerEnabled environment value, to be used in case we'd need to change some gesture behaviors to accommodate this accessibility feature.

Both view modifiers and environment value are available from iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0.

Documentation

While Xcode 13.2b1 doesn't bring many new SwiftUI features, we have a significant and welcome upgrade in SwiftUI's documentation.

We have new documentation for:

• SectionedFetchRequest
• SectionedFetchResults
• Text
• TextField
• ToggleStyle
• toggleStyle(_:)
• ToggleStyleConfiguration
• ToggleStyle.automatic
• All recent background and overlay view modifiers

Let's highlight a few important changes.

TextField's prompt vs. title

The updated TextField documentation has an entire section explaining why we have both a title/label and a prompt parameter, and the use of both:

/// Each text field style determines where and when the text field uses a prompt and label.
/// For example, a form on macOS always places the label at the leading edge of the field 
/// and uses a prompt, when available, as placeholder text within the field itself. In the 
/// same context on iOS, the text field uses either the prompt or label as placeholder 
/// text, depending on whether the initializer provided a prompt.

(Toggle) Styles defaults and contextual defaults

SwiftUI's styling is highly adaptive and can change widely based on the context. Until now, it was anyone's guess which style was adopted in which scenarios (and answered only via experimentation).

After this update, we no longer have to guess, as the documentation clearly states how our toggles will appear in different scenarios.

Looking forward to seeing all other styles get the same treatment.

Wording: from "primitive" to "built-in"

When referring to baked-in SwiftUI definitions for views, styles, commands, etc., the official wording has been "primitive".

However, the term "primitive" is not always correct, as, sometimes, even baked-in definitions are composed of other SwiftUI components. To address this, the documentation has changed the wording from "primitive" to "built-in".

Bolder soft deprecation

Despite SwiftUI having a clear direction on which syntax to use, most old definitions are still available and were soft deprecated with gentle messages like "You can also use X". New in Xcode 13.2, these messages are bolder and use imperative words instructing developers on what to use.

Bug fixes

From Xcode 13.2, Lists and Forms respect the safe areas insets declared via safeAreaInset(edge:content:) view modifier.

Conclusions

Did you find anything else interesting in Xcode 13.2 beta 1? Please let me know!

SwiftUI's official definition is "A collection of environment values propagated through a view hierarchy", but it oversimplifies and hides a bit too much for Five Stars' standards.

SwiftUI defines over 50 public environment values, and, as we've seen in a previous entry, there are many more private.

EnvironmentValues doesn't stop there: we can also create our own environment values. Let's explore how.

This is the fifth entry of the Five Stars SwiftUI's Environment series. It's recommended to read the first few entries before proceeding: 1, 2, 3, 4.

Creating a new environment value takes two steps:

1. define a new EnvironmentKey
2. extend EnvironmentValues with our new value

1. Define a new EnvironmentKey

Here's SwiftUI's EnvironmentKey definition:

public protocol EnvironmentKey {
  associatedtype Value
  static var defaultValue: Self.Value { get }
}

This key has three main roles:

1. it defines the type of the associated environment value (via associatedtype)
2. it helps SwiftUI identify the storage of the environment value
3. it defines the environment default value, used when the environment value has not been explicitly set

This first step comes down to define a new struct conforming to EnvironmentKey, for example:

struct FSNumberKey: EnvironmentKey {
  static let defaultValue: Int = 5
}

Thanks to this definition, we have created a new environment value:

1. …of type Int (as per defaultValue type)
2. …whose storage is identified by FSNumberKey
3. …with default value 5

EnvironmentValues is now able to get and set any environment value that uses this FSNumberKey as its storage.

2. Extend EnvironmentValues with our new value

If the environment was just a place to store values, we would only need the first step. However, if we take a look at the @Environment property wrapper definition, we'd see the following:

@propertyWrapper public struct Environment<Value>: DynamicProperty {
  public init(_ keyPath: KeyPath<EnvironmentValues, Value>)
  public var wrappedValue: Value { get }
}

Similarly, if we take a look at the environment(_:,_:) view modifier definition, we'd see:

extension View {
  public func environment<V>(_ keyPath: WritableKeyPath<EnvironmentValues, V>, _ value: V) -> some View
}

In both cases, we don't use the associated EnvironmentKey to access or write an environment value. Instead, both @Environment and the environment(_:,_:) view modifier ask for a KeyPath to a EnvironmentValues property.

This seems like an unnecessary step at first, but it unlocks all sorts of extra functionality.

Continuing with our FSNumberKey example, the most basic EnvironmentValues extension that we could make is:

extension EnvironmentValues {
  public var fsNumber: Int {
    get {
      self[FSNumberKey.self]
    } set {
      self[FSNumberKey.self] = newValue
    }
  }
}

Thanks to this extension, we can now set and read the FSNumberKey's value via EnvironmentValues's new fsNumber definition.

Setting FSNumberKey:

VStack {
  ViewA()
    .environment(\.fsNumber, 1) // 👈🏻
  ViewB()
}

Reading FSNumberKey:

struct ViewA: View {
  @Environment(\.fsNumber) private var fsNumber: Int  // 👈🏻

  var body: some View {
    Text("\(fsNumber)")
  }
}

Unlocking EnvironmentValues potential

Every time we set/access FSNumberKey via fsNumber, we are not directly accessing the underlying EnvironmentValues value, but we are executing fsNumber's getter and setter closures. We can add more functionality based on our environment value needs. Let's see some examples.

Non-negative value

Let's say for example that we'd like to prevent FSNumberKey to ever have a negative value. Instead of adding extra logic in each view that sets this value, we can update our EnvironmentValues extension with the following:

extension EnvironmentValues {
  public var fsNumber: Int {
    get { self[FSNumberKey.self] }
    set {
      self[FSNumberKey.self] = max(0, newValue)
    }
  }
}

Regardless of the value we set via environment(_:,_:) view modifier, we will now always have a value equal or greater than zero.

VStack {
  ViewA() // 👈🏻 ViewA will see fsNumber with value 0
    .environment(\.fsNumber, -5) // 👈🏻 negative value, not allowed! Set to zero instead.
  ViewB()
}

Depending on our needs, we can even prevent to write to EnvironmentValues entirely and use the last valid assigned value instead:

extension EnvironmentValues {
  public var fsNumber: Int {
    get { self[FSNumberKey.self] }
    set {
      if newValue >= 0 {
        self[FSNumberKey.self] = newValue // 👈🏻 write only if newValue > 0.
      }
    }
  }
}

VStack {
  ViewA() // 👈🏻 ViewA will see fsNumber with default value
    .environment(\.fsNumber, -5) // 👈🏻 negative value, not allowed! This assignment is ignored.
  ViewB()
}

Sharing the storage

Most of the time, we will create a specific EnvironmentKey for each EnvironmentValues extension. However this is not enforced in any way. Consider the following example:

struct FSSharedKey: EnvironmentKey {
  static let defaultValue: Int = 5
}

extension EnvironmentValues {
  public var fsSharedStorage: Int {
    get { self[FSSharedKey.self] }
    set { self[FSSharedKey.self] = newValue }
  }

  public var fsSharedStorage2: Int {
    get { self[FSSharedKey.self] }
    set { self[FSSharedKey.self] = newValue }
  }
}

We can now use fsSharedStorage and fsSharedStorage2 interchangeably:

ViewA() // 👈🏻 both fsSharedStorage and fsSharedStorage will be 6
  .environment(\.fsSharedStorage2, 6)

Read-only environment values

Since @Environment requires only a KeyPath<EnvironmentValues, Value> and not a WritableKeyPath<EnvironmentValues, Value>, we could also create read-only environment values.

We have two main ways to implement such read-only behavior:

1. the "traditional" way
2. the think outside the box way

1. The "traditional" way

The traditional way would be to define a key that then we only read:

struct FSReadOnlyNumberKey: EnvironmentKey {
  static let defaultValue: Int = 5
}

extension EnvironmentValues {
  public var fsReadOnlyNumber: Int {
    get {
      return self[FSNumberKey.self]
    }
  }
}

Since there's no setter in fsReadOnlyNumber, we can only read this value and the associated \.fsReadOnlyNumber keypath is not a WritableKeyPath. Attempting to write into this value would cause a compiler error:

ViewA()
  .environment(\.fsReadOnlyValue, 6) // 🛑 Key path value type 'WritableKeyPath<EnvironmentValues, Int>' cannot be converted to contextual type 'KeyPath<EnvironmentValues, Int>'

While this works great, as we've seen above, any EnvironmentKey definition can be shared among various EnvironmentValues extensions. Besides setting our read-only key as private, there's not much to prevent it from being written by malicious extensions.

2. The think outside the box way

To prevent our environment value from being written elsewhere, we can get rid of its storage altogether. We skip the key definition and write an EnvironmentValues extension that returns a value directly:

extension EnvironmentValues {
  public var fsReadOnlyNumber: Int {
    get {
      return 5 // 👈🏻 truly read-only environment value
    }
  }
}

This value will still be accessed via @Environment but it no longer relies on the EnvironmentValues storage.

Usage example: an app has a standard horizontal padding that never changes. Instead of using the same magic number throughout the codebase, we could define so via the environment. If we'd like the value to be dynamic in the future, we'd only need to change the EnvironmentValues extension implementation.

Conclusions

When it comes to passing down data through the view hierarchy, SwiftUI's environment offers a powerful and "simple" way that has no equivalent in previous imperative UI frameworks such as UIKit and AppKit.

What uses do you have for SwiftUI's Environment? Have you seen anything that stands out?
Please let me know via email or Twitter!

Stay tuned for the final entry on SwiftUI's environment next week!

EnvironmentValues is a struct defined within the SwiftUI SDK containing all the current modified environment values. Let's take a deeper look.

This is the fourth entry of the Five Stars SwiftUI's Environment series. It's recommended to read the first three entries before proceeding: 1, 2, 3.

EnvironmentValues

This is EnvironmentValues's entire definition:

public struct EnvironmentValues {
  public init()
  public subscript<K: EnvironmentKey>(key: K.Type) -> K.Value
}

Debugging properties have been omitted for readability's sake.

While not immediately apparent, it's important to note that the subscript is read-write, thus allowing both reading and modifying environment values.
The implementation would look like:

public struct EnvironmentValues {
  public init() { 
    ...
  }

  public subscript<K: EnvironmentKey>(key: K.Type) -> K.Value {
    get {
      ...
    }
    set(newValue) { // 👈🏻
      ...
    }
  }
}

EnvironmentKey

EnvironmentValues relies on a second definition, EnvironmentKey, which is a generic protocol defined as:

public protocol EnvironmentKey {
  associatedtype Value
  static var defaultValue: Self.Value { get }
}

This EnvironmentKey:

• lets us define the type of each environment value (via associatedtype)
• helps SwiftUI identify the storage for any environment value
• allows us to assign a default value for each key (more on this later)

A dictionary

We can think of EnvironmentValues as a Swift dictionary wrapper, where:

• the dictionary type is along the lines of [EnvironmentKey: Any]
• each EnvironmentKey key will have an associated value of type EnvironmentKey.Value
• the dictionary will only contain all the values that have been explicitly set for that specific view (and its ancestors)

Every view has its own, separate, EnvironmentValues instance. When we say that environment values are propagated through the view hierarchy, what really happens behind the scenes is that (a copy of) this dictionary is passed down from parent to child.

This EnvironmentValues "dictionary" is not really a Swift dictionary but a private PropertyList type. Regardless, it helps thinking about it as a dictionary.

Example

Let's make an example where we focus only on the environment values that we explicitly set.
Consider the following view:

VStack {
  ViewA()
    .foregroundColor(.red) // 🔴
  ViewB()
}

If we generate a high-level view hierarchy, we will have:

VStack
├── ViewA
└── ViewB

Since we don't set any environment value on VStack, its EnvironmentValues dictionary will be empty, [:].

We also don't set any environment value on ViewB; ViewB will inherit the same dictionary as VStack, [:].

On the other hand, we set the foregroundColor on ViewA:
ViewA will inherit VStack's dictionary, [:], and add its foregroundColor on top, ending up with a dictionary similar to [ForegroundColorKey: Color.red].

VStack      // Environment dictionary → [:]
├── ViewA   // Environment dictionary → [ForegroundColorKey: 🔴], VStack + foregroundColor modifier
└── ViewB   // Environment dictionary → [:], inherited from VStack

Since every environment value comes with a default value, if a view tries to get a value that has not been explicitly set, EnvironmentValues will return the EnvironmentKey.defaultValue for the associated key.

All the above is true for simple environment keys/values: we will see more advanced use cases in the following article of the series.

Dumping EnvironmentValues's dictionary

In the previous chapter, we ignored values that we hadn't explicitly set ourselves. However, a real EnvironmentValues dictionary has plenty of values coming from system settings, device characteristics, and all other values set on ancestor views.

Even when we don't set environment values ourselves, any view has an associated EnvironmentValues dictionary with 40+ environment values.
These values are not necessarily part of the public API, but are values that SwiftUI uses to determine each view's context, thus deciding how/what to draw.

For a sneak peek into the associated dictionary of any view, Chris Eidhof has a handy DumpingEnvironment code snippet:

struct DumpingEnvironment<V: View>: View {
  @Environment(\.self) var env
  let content: V

  var body: some View {
    dump(env)
    return content
  }
}

DumpingEnvironment wraps any view we're interested in, and prints in the debugger the associated EnvironmentValues instance (via Swift's dump(_:name:indent:maxDepth:maxItems:)).

Usage example:

DumpingEnvironment(content: ContentView())

Note that DumpingEnvironment is a View with its entire environment as a dependency. Make sure to use this only for debugging purposes.

Conclusions

As app developers, we don't directly interact with EnvironmentValues often. Instead, most interactions are done via proxies such as the @Environment property wrapper and the environment(_:,_:) view modifier.

In the next article, we will tie all of them together to get the bigger picture:
make sure to subscribe via feed RSS or follow @FiveStarsBlog on Twitter.

Thank you for reading!

Questions? Feedback? Feel free to reach out via email or Twitter!

As long as a view is a child of another, regardless of the connection between the two (via presentation or containment), the view will inherit the environment from their parent (plus any modification applied in-between).

This propagation happens even while many SwiftUI views are wrappers of their UIKit/AppKit counterparts (e.g., TabView and ScrollView).
This behavior is not limited to just SwiftUI wrappers: we can build our AppKit/UIKit SwiftUI wrappers, and the environment will be auto-magically propagated for us. In this short article, let's see an example of this.

In any app, it's reasonable to want to mix SwiftUI with previous UI frameworks. An example could be using SwiftUI as the content of UITableViewCells.

In order to do this we'll use Noah Gilmore's HostingCell<Content: View>: UITableViewCell definition:

final class HostingCell<Content: View>: UITableViewCell {
  private let hostingController = UIHostingController<Content?>(rootView: nil)

  override init(style: UITableViewCell.CellStyle, reuseIdentifier: String?) {
    super.init(style: style, reuseIdentifier: reuseIdentifier)
    hostingController.view.backgroundColor = .clear
  }

  required init?(coder aDecoder: NSCoder) {
    fatalError("init(coder:) has not been implemented")
  }

  func set(rootView: Content, parentController: UIViewController) {
    self.hostingController.rootView = rootView
    self.hostingController.view.invalidateIntrinsicContentSize()

    let requiresControllerMove = hostingController.parent != parentController
    if requiresControllerMove {
      parentController.addChild(hostingController)
    }

    if !self.contentView.subviews.contains(hostingController.view) {
      self.contentView.addSubview(hostingController.view)
      hostingController.view.translatesAutoresizingMaskIntoConstraints = false
      contentView.addConstraints([
        hostingController.view.leadingAnchor.constraint(equalTo: contentView.leadingAnchor),
        hostingController.view.trailingAnchor.constraint(equalTo: contentView.trailingAnchor),
        hostingController.view.topAnchor.constraint(equalTo: contentView.topAnchor),
        hostingController.view.bottomAnchor.constraint(equalTo: contentView.bottomAnchor)
      ])
    }

    if requiresControllerMove {
      hostingController.didMove(toParent: parentController)
    }
  }
}

Check out Noah's Self-Sizing UITableView Cells with SwiftUI article for more details on this.

With HostingCell we can now embed SwiftUI views as cells in a UITableViewController's tableView.

Let's define a simple cell:

struct CellView: View {
  var body: some View {
    HStack {
      Text("SwiftUI Text")
      Spacer()
    }
    .padding()
  }
}

Next, let's define a UITableViewController using this new cell:

final class TableViewController: UITableViewController {
  override init(style: UITableView.Style) {
    super.init(style: style)
    tableView.register(HostingCell<CellView>.self, forCellReuseIdentifier: "HostingCell<CellView>")
    tableView.separatorStyle = .none
  }

  required init?(coder: NSCoder) {
    fatalError("init(coder:) has not been implemented")
  }

  override func numberOfSections(in tableView: UITableView) -> Int {
    1
  }

  override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
    300
  }

  override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
    let cell = tableView.dequeueReusableCell(withIdentifier: "HostingCell<CellView>", for: indexPath) as! HostingCell<CellView>
    cell.set(rootView: CellView(), parentController: self)
    return cell
  }
}

We now have a working UIKit view hosting SwiftUI views. Let's wrap this new TableViewController into a SwiftUI view, we don't need to do anything beside wrapping:

struct TableViewWrapper: UIViewControllerRepresentable {
  func makeUIViewController(context: Context) -> some UIViewController {
    TableViewController(style: .plain)
  }

  func updateUIViewController(_ uiViewController: UIViewControllerType, context: Context) {
  }
}

Let's recap what we have:

• CellView, a simple SwiftUI view
• HostingCell, a generic UITableViewCell accepting SwiftUI views
• TableViewController, a UIViewController displaying multiple HostingCell as part of its tableView content
• TableViewWrapper, a SwiftUI view wrapping TableViewController

Despite having UIKit views/controllers in between, CellView will inherit TableViewWrapper's environment.

To prove this, let's define a view that will set TableViewWrapper's foreground color:

struct ContentView: View {
  @State var color: Color = .black

  var body: some View {
    VStack {
      ColorPicker("Choose foreground color", selection: $color)
        .pickerStyle(.inline)
        .font(.title)
        .padding(.horizontal)

      TableViewWrapper()
        .foregroundColor(color) // 👈🏻
    }
    .ignoresSafeArea(edges: .bottom)
  }
}

Note that we didn't have to do any extra work to make this possible. We never had to reach for the environment ourselves, nor use @Environment:
CellView's Text will automatically inherit and use the foreground color set on TableViewWrapper.

This propagation works both for environment values and objects.

Conclusions

While SwiftUI might be the recommended framework for any future project, the SwiftUI team has worked hard to ensure excellent integration with previous UI frameworks. Despite having to go through multiple UIKit layers, this seamless environment propagation is yet another example of this.

Thank you for reading!

View presentation and environment propagation

Everything we've seen so far could be summarized as: children views inherit the environment from their parent (plus additional changes). Things get tricky when we add view presentation into the mix.

That is, navigating to other views or presenting sheets. Before diving into these, we need to step back and introduce one more topic: UIKit's view controller hierarchy.

The View Controller Hierarchy

Like the view hierarchy we covered we covered last time, we can also create a hierarchy among UIViewControllers.

We can split the view controllers parent-child relationships into two categories, contained and presenting.

Contained parent-child relationship

A given view controller might contain several child view controllers dedicated to different sections of the screen. When they do so, these controllers are called Container View Controllers, and are considered the parents of the child view controllers.

We can build our own container view controllers, and UIKit comes with a few pre-built ones, for example, UINavigationController and UISplitViewController.

It's essential to know and understand the relationship among its children.

Let's imagine that we have a navigation controller and have pushed two screens into the navigation stack. At this point, the navigation controller's viewControllers stack has three view controllers in total. this is the current hierarchy:

UINavigationController
├── RootViewController
├── FirstPushedViewController
└── SecondPushedViewController

Despite a view controller pushing the next into the navigation, all view controllers in the navigation stack are siblings, and all share the same parent view controller, the UINavigationController.

Next, if we take a look at an UITabBarController, we will see the same pattern again:

UITabBarController
├── FirstTabViewController
├── SecondTabViewController
└── ...

Note also that any container view controller can have one or more container view controllers as its children.

We use:

• UIViewController's parentViewController: UIViewController? property to get the parent of a UIViewController
• each container viewControllers: [UIViewController] property to get its children

We can print the view controller hierarchy at any time in lldb viapo UIWindow.value(forKeyPath: "keyWindow.rootViewController._printHierarchy")!

Presenting parent-child relationship

Instead of containing children, this relationship represents the connection between one view controller and the one presenting modally.

This relationship is established when we call present(_:animated:completion:) from a view controller to present another one.

In this case, the 1-1 relationship has the presenting view controller as the parent of the presented view controller:

PresentingViewController
└── PresentedViewController

In other words, unlike navigation, a controller presented modally will always have its presenting view controller as its parent. Here's an example of hierarchy where a modal view controller present another view controller modally, which then present another view controller modally:

NonModalViewController
└── FirstModalViewController
    └── SecondModalViewController
        └── ThirdModalViewController

We use:

• UIViewController's presentingViewController: UIViewController? property to get the view controller that is presenting our view controller
• UIViewController's presentedViewController: UIViewController? property to get the view controller presented by our view controller

SwiftUI's View Controller Hierarchy

Moving back to SwiftUI, UIViewControllers are just gone (for argument's sake, let's forget about UIHostingController). This is because:

• container view controllers are now just Views. For example UINavigationController is NavigationView, and UITabBarController is TabView:

struct FSView: View {
  var body: some View {
    TabView {
      FirstTabView()
        .tabItem { Label("One", systemImage: "1.circle.fill") }
      SecondTabView()
        .tabItem { Label("Two", systemImage: "2.circle.fill") }
      ...
    }
  }
}

• view presentations are controlled via bindings and view modifiers like sheet(isPresented:onDismiss:content:):

struct FSView: View {
  @State var showingSheet = false
  
  var body: some View {
    Button("Show sheet") {
      showingSheet.toggle()
    }
    .sheet(isPresented: $showingSheet) {
      FSSheetView()
    }
  }
}

Despite this, the view controller hierarchy has migrated 1-1 to SwiftUI. For example, these are the two view hierarchies for the last two examples:

• TabBar example:

FSView
└── TabView
    ├── FirstTabView
    ├── SecondTabView
    └── ...

• Sheet example (when the sheet is presented):

FSView
└── FSSheetView

SwiftUI Environment Propagation and View Controller Hierarchy

Since SwiftUI doesn't have UIViews or UIViewControllers, UIKit's view and view controller hierarchies are merged into a single hierarchy in SwiftUI.

SwiftUI's environment is propagated across views and view controllers without any behavior change. All the logic we've covered in the first article in the series still counts when dealing with view presentations.

In conclusion, understanding UIKit's view controller hierarchy enables us to understand advanced SwiftUI's environment propagation.

Let's now take a few examples to consolidate/confirm what we have uncovered. We will continue to use foregroundColor as our environment value.

TabView

struct FSView: View {
  var body: some View {
    TabView {
      FirstTabView()
        .tabItem { Label("One", systemImage: "1.circle.fill") }
      SecondTabView()
        .tabItem { Label("Two", systemImage: "2.circle.fill") }
      ...
    }
  }
}

FSView
└── TabView
    ├── FirstTabView
    ├── SecondTabView
    └── ...

If we set the foreground color to a specific tab, only that tab view and its descendants will inherit the color:

struct FSView: View {
  var body: some View {
    TabView {
      FirstTabView()
        .tabItem { ... }
      SecondTabView()
        .foregroundColor(.red) // 🔴
        .tabItem { ... }
      ...
    }
  }
}

FSView
└── TabView
    ├── FirstTabView
    ├── SecondTabView 🔴
    └── ...

All SecondTabView siblings won't be affected by any change made into SecondTabView's environment, as only the tab parent, TabView, can affect SecondTabView's siblings environment.

If we'd like to set the same foreground color to all tab views, we have two ways:

1. set it to each tab

struct FSView: View {
  var body: some View {
    TabView {
      FirstTabView()
        .foregroundColor(.red) // 🔴
        .tabItem { ... }
      SecondTabView()
        .foregroundColor(.red) // 🔴
        .tabItem { ... }
      ...
        .foregroundColor(.red) // 🔴
    }
  }
}

FSView
└── TabView
    ├── FirstTabView 🔴
    ├── SecondTabView 🔴
    └── ... 🔴

2. set it on the TabView (or a TabView's ancestor)

struct FSView: View {
  var body: some View {
    TabView {
      FirstTabView()
        .tabItem { ... }
      SecondTabView()
        .tabItem { ... }
      ...
    }
    .foregroundColor(.red) // 🔴
  }
}

FSView
└── TabView 🔴
    ├── FirstTabView 🔴
    ├── SecondTabView 🔴
    └── ... 🔴

Sheets

struct FSView: View {
  @State var showingSheet = false
  
  var body: some View {
    Button("Show sheet") {
      showingSheet.toggle()
    }
    .sheet(isPresented: $showingSheet) {
      FSSheetView()
    }
  }
}

FSView
└── FSSheetView

When we present sheets, the environment inherited by those sheets is the same as the environment seen by the associated sheet(...) modifier.

We can consider the sheet modifier as the anchor point of our sheet view, expanding the view controller hierarchy above:

FSView
└── sheet view modifier
    ├── Button
    └── FSSheetView

Note how the presented sheet, FSSheetView, and the view where the sheet is applied to, Button, are siblings.

With this in mind, we can study different scenarios:

• the foreground color is set onto the sheet view modifier

struct FSView: View {
  @State var showingSheet = false
  
  var body: some View {
    Button("Show sheet") {
      showingSheet.toggle()
    }
    .sheet(isPresented: $showingSheet) {
      FSSheetView()
    }
    .foregroundColor(.red) // 🔴
  }
}

FSView
└── sheet view modifier 🔴
    ├── Button 🔴
    └── FSSheetView 🔴

• the foreground color is set after the sheet view modifier

struct FSView: View {
  @State var showingSheet = false
  
  var body: some View {
    Button("Show sheet") {
      showingSheet.toggle()
    }
    .foregroundColor(.red) // 🔴
    .sheet(isPresented: $showingSheet) {
      FSSheetView()
    }
  }
}

FSView
└── sheet view modifier
    ├── Button 🔴
    └── FSSheetView

• the foreground color is set on the sheet view

struct FSView: View {
  @State var showingSheet = false
  
  var body: some View {
    Button("Show sheet") {
      showingSheet.toggle()
    }
    .sheet(isPresented: $showingSheet) {
      FSSheetView()
        .foregroundColor(.red) // 🔴
    }
  }
}

FSView
└── sheet view modifier
    ├── Button
    └── FSSheetView 🔴

Which scenario we need/want to use is up to our needs. They're all acceptable and very justified to exist.

The same concepts are repeated when we have multiple sheet view modifiers and/or a chain of presented sheets.

iOS 13 vs iOS 14+

Before iOS 14 the environment was not propagated to the presented sheet. As we have seen in UIKit's view controller hierarchy, this was unexpected and is considered a bug in SwiftUI's environment behavior.

If our app targets iOS 13 and later, we need to keep this in mind and manually inject the environment values/objects that we need in our sheets.

Navigation

Imagine the following view definition:

struct FSView: View {
  var body: some View {
    NavigationView {
      FSRootView()
    }
  }
}

struct FSRootView: View {
  var body: some View {
    NavigationLink("tap", destination: FSFirstPushedView())
  }
}

struct FSFirstPushedView: View {
  var body: some View {
    NavigationLink("tap", destination: FSSecondPushedView())
  }
}

struct FSSecondPushedView: View {
  var body: some View {
    ...
  }
}

As we've seen in UIKit's view controller hierarchy, If we navigate from root to FSSecondPushedView, the resulting hierarchy will be:

FSView
└── NavigationView
    ├── FSRootView
    ├── FSFirstPushedView
    └── FSSecondPushedView

All pushed views (and root) are siblings, despite being declared in the NavigationLink of another view. In other words, NavigationLink's destination doesn't share the same environment seen by NavigationLink:

NavigationLink("tap", destination: DestinationView())
  .foregroundColor(.red) // 👈🏻 doesn't affect DestinationView

If we'd like to share environment values between pushing and pushed views, we have two options:

1. manually set the values in each NavigationLink's destination:

struct FSView: View {
  var body: some View {
    NavigationView {
      FSRootView()
        .foregroundColor(.red) // 🔴
    }
  }
}

struct FSRootView: View {
  var body: some View {
    NavigationLink(
      "tap", 
      destination: FSFirstPushedView().foregroundColor(.red) // 🔴
    )
  }
}

struct FSFirstPushedView: View {
  var body: some View {
    NavigationLink(
      "tap", 
      destination: FSSecondPushedView().foregroundColor(.red) // 🔴
    )
  }
}

struct FSSecondPushedView: View {
  var body: some View {
    ...
  }
}

FSView
└── NavigationView
    ├── FSRootView 🔴
    ├── FSFirstPushedView 🔴
    └── FSSecondPushedView 🔴

2. set the values in NavigationView or another common ancestor:

struct FSView: View {
  var body: some View {
    NavigationView {
      FSRootView()
    }
    .foregroundColor(.red) // 🔴
  }
}

...

FSView
└── NavigationView 🔴
    ├── FSRootView 🔴
    ├── FSFirstPushedView 🔴
    └── FSSecondPushedView 🔴

The latter option is recommended, especially when working with an app-wide state pattern.

Neither .navigationViewStyle(.stack) nor .isDetailLink(false) affect the environment propagation.

Conclusions

Despite SwiftUI being a massive departure from AppKit/UIKit, there's no way around it: to master SwiftUI, we need to master understand the UI frameworks SwiftUI relies on.

You've just completed the second entry of Five Stars' SwiftUI Environment series; make sure to subscribe via feed RSS or follow @FiveStarsBlog on Twitter to not miss out on upcoming entries and more deep dives.

Thank you for reading!

Questions? Feedback? Feel free to reach out via email or Twitter!

References

• About Windows and Views - Apple Documentation Archive
• Introducing Multiple Windows on iPad - WWDC Notes
• The View Controller Hierarchy - Apple Documentation Archive

Alongside SwiftUI's Environment, we will introduce a few concepts here and there; let's wait no further!

View Hierarchy

A View Hierarchy establishes the relationship among all views in any given window.

This hierarchy is connected by many parent-child relationships. Given any view:

• the view containing that view is known as its parent view (a.k.a. the superview)
• the views within that view are known as its children views (a.k.a. subviews)

Every view in the hierarchy has:

• (up to) one parent/superview
• zero or more children/subviews

In UIKit, we can access both superview and subviews of any UIView via its superview: UIView? and subviews: [UIView] properties.

Views that share the same parent/superview are called siblings, every view can have zero or more siblings.

A tree structure

If we zoom out, a view hierarchy can be seen as an inverted tree structure, where:

• each node is a UIView/View
• every link is a parent-child relationship

The top-most node, also known as the root of our tree, is UIWindow's rootViewController's view.

Everything we display on screen will have this root view as its ancestor.

We can print the view hierarchy at any time in lldb viapo UIWindow.value(forKeyPath: "keyWindow.rootViewController.view.recursiveDescription")!

A SwiftUI Example

So far, we've been talking primarily in UIKit terms: the same definitions apply to SwiftUI.

Let's define a small SwiftUI view:

struct FSView: View {
  var body: some View {
    VStack {
      HStack {
        ViewA()
        ViewB()
      }
      ViewC()
    }
  }
}

Everything we define in our view body is a descendant of FSView. This is the complete FSView view hierarchy:

FSView
└── VStack
    ├── HStack
    │   ├── ViewA
    │   └── ViewB
    └── ViewC

Where:

• FSView is the root of our view hierarchy
• VStack is the only child of FSView
• HStack and ViewC are siblings and VStack's children
• ViewA and ViewB are siblings and HStack's children

If we define our app WindowGroup with FSView, the view hierarchy above is our complete view hierarchy.

@main
struct FSApp: App {
  var body: some Scene {
    WindowGroup {
      FSView() // 👈🏻 SwiftUI view hierarchy starts here.
    }
  }
}

We can think of SwiftUI's WindowGroup definition as equivalent to UIKit's UIWindow.rootViewController.view

SwiftUI Environment

SwiftUI environment is a collection of values and objects propagated through the view hierarchy.

A lot of what we do in SwiftUI affects the environment. A few examples of environment values/objects:

• every view style
• accent, tint, foreground colors
• onSubmit(of:_:)'s TriggerSubmitAction, openURL's action
• the app AppDelegate and SceneDelegate
• ...and much more

Values vs Objects

When we talk about environment values, we refer to all definitions under EnvironmentValues:
these are mainly primitives such as an enum (e.g., the colorScheme value for dark and light mode) and other value-type instances, such as booleans (e.g., isEnabled) and numbers (e.g., Text's lineLimit).

On the contrary, environment objects are classes conforming to ObservableObject. These are the same ObservableObjects we define and use via @StateObject or @ObservedObject, with the difference that, instead of passing them down via view initializers, we can fetch them via environment.

Setting an environment value/object

There are mainly two ways to set values/objects into the environment:

1. Directly, via the environment(_:_:) and environmentObject(_:) view modifiers:

FSView()
  .environment(\.colorScheme, .dark) // Setting an environment value
  .environmentObject(appState) // Setting an environment object

Learn about SwiftUI's App-wide state here.

2. Indirectly, via convenience view modifiers:

FSView()
  .foregroundColor(.yellow)
  .buttonStyle(.borderedProminent)

These are also examples of environment values that are not part of EnvironmentValues's public API (FB8161189), but we can still set them via these modifiers.

The effect is the same, and it's up to the API designer to decide which way to take.

Reading an environment value/object

Regardless of how we set them, the only way to read both environment values and objects is via SwiftUI's associated property wrappers:

struct FSView: View {
  @EnvironmentObject var state: AppWideState // Reading an environment object
  @Environment(\.isEnabled) private var isEnabled: Bool // Reading an environment value

  var body: some View {
    ...
  }
}

Learn about SwiftUI's App-wide state here.

Note that accessing to an environment object that is not present in the environment will terminate the app.

Environment propagation

Environment values/objects are propagated through the view hierarchy. When we set something into the environment, we set it for:

• the view where the change is applied to
• the view's hierarchy descendants

Let's set the foregroundColor to red (🔴) in our FSView example:

struct FSView: View {
  var body: some View {
    VStack {
      HStack {
        ViewA()
        ViewB()
      }
      ViewC()
    }
    .foregroundColor(.red) // 🔴
  }
}

As we're setting it for VStack, both VStack and its descendants will inherit this foreground color value:

FSView
└── VStack 🔴
    ├── HStack 🔴
    │   ├── ViewA 🔴
    │   └── ViewB 🔴
    └── ViewC 🔴

An environment value/object is propagated until that same value/object is set again, let's set the foregroundColor to green (🟢) on the HStack:

struct FSView: View {
  var body: some View {
    VStack {
      HStack {
        ViewA()
        ViewB()
      }
      .foregroundColor(.green) // 🟢
      ViewC()
    }
    .foregroundColor(.red) // 🔴
  }
}

Now only VStack and ViewC will see red for their foregroundColor, while others will see green:

FSView
└── VStack 🔴
    ├── HStack 🟢
    │   ├── ViewA 🟢
    │   └── ViewB 🟢
    └── ViewC 🔴

Note how siblings can have different environment values:
HStack and ViewC are siblings but, for the same environment value, the former sees green, while the latter sees red.

What about FSView?

So far we have changed the environment to FSView's body. If we want to change the environment seen by FSView, we will then need to do so before its declaration, for example:

@main
struct FSApp: App {
  var body: some Scene {
    WindowGroup {
      FSView()
        .foregroundColor(.purple) // 🟣
    }
  }
}

At this point, FSView inherits purple as its foregroundColor. However, its children will see what has been set for them:

FSView 🟣
└── VStack 🔴
    ├── HStack 🟢
    │   ├── ViewA 🟢
    │   └── ViewB 🟢
    └── ViewC 🔴

If we didn't set the foregroundColor in FSView's body, its descendants would also see purple.

Environment default values

All environment values (EnvironmentValues) come with a default value (nil or something more appropriate): if no value is explicitly set, SwiftUI will use that default value.

Continuing with foregroundColor as an example, if we don't set it ourselves, SwiftUI will use black in light mode, and white in dark mode. These are the two default values defined by the SwiftUI team for that particular environment value.

This is how/why, by default, Text and all shapes will be rendered with black and white in, respectively, light and dark mode.

On the contrary, there's no default value for environment objects. These are ObservableObject classes that we define and set: SwiftUI doesn't initialize nor hold those objects for us. Except for a few cases like app and scene delegates, we are responsible to initialize and inject them into the environment when/where appropriate.

Conclusions

Whether we realize it or not, the environment is undoubtedly one of the most used aspects of any SwiftUI app.

SwiftUI views and controls are expected to adapt to their context and presentation, and the environment plays a significant role in making this possible.

In the following article in the series, we will continue our exploration with more advanced uses and some edge cases to be aware of. Make sure to subscribe via feed RSS or follow @FiveStarsBlog on Twitter.

Thank you for reading!

The default behavior in SwiftUI, and most software, is for the top-most views to obscure/hide the bottom ones.

This makes sense and is reflected in real life: if we look at a stack of papers/documents from above, we can only see the top-most document, or, perhaps, the top-most few if the paper is very, very thin.

Going back to the virtual world, we can think about each view as a layer of pixels/points.
Each pixel has a set of properties such as color, saturation, opacity, etc. Instead of stacking these pixels on top of each other, we can blend them with rules based on their properties, obtaining different effects/outcomes.

SwiftUI offers twenty-one blending modes. Let's explore all of them!

How to apply blend modes

The blendMode(_:) view modifier is dedicated to blending views, there are mainly two ways we can use it:

• via a ZStack:

ZStack {
  BottomView()
  TopView()
    .blendMode(...)
}

• via an .overlay:

BottomView()
  .overlay {
    TopView()
      .blendMode(...)
  }

In both cases, we apply the modifier on the top view.

Blending destination and source

When it comes to blending, we have two main objects:

• the source, which is the view that comes with the blending effect (e.g., TopView().blendMode(...))
• the destination, which is everything underneath that view

When blending, based on the mode, we consider the properties of both source and destination.

Let's overview the effects.

Blending modes

📚 Sample code available here.

Different blending techniques use different pixel properties for their effect. We can group them into seven categories:

1. Lighten
2. Darken
3. Contrast
4. Component
5. Compositing
6. Invert
7. Normal

The article's images might present some minor artifacts due to compression.

Lighten

The destination will get brighter by blending the hue of both source and destination. Pure black is the neutral color, while white is considered the brightest color.

• colorDodge - (opposite of colorBurn) decreases the contrast between the source and the destination. The brighter the source, the more its color affects the destination layer. Results in saturated midtones and bright highlights.

• lighten - (opposite of darken) compares and draws the brighter colors of either source or destination (if every point of the source view is darker than the destination, the outcome is just the destination)

• screen - (can be thought to be the opposite of multiply) inverts the destination colors and blends them with the source, then inverts the result. The resulting colors are lighter than the original colors, with less contrast. Screening with black leaves the color unchanged. Screening with white produces white.

• plusLighter - (a.k.a. Linear Dodge, opposite of plusDarker) brightens each destination color channel to reflect the source color. Blending with black produces no change.

Darken

The destination will get darker by blending the hue of both source and destination. Pure white is the neutral color.

• colorBurn - (opposite of colorDodge) Intensifies the dark areas in all layers. The effect increases the contrast between the source and destination.

• darken - (opposite of lighten) compares and draws the darker colors of either source and destination (if every point of the source view is lighter than the destination, the outcome is just the destination)

• multiply - (can be thought as opposite of screen) multiplies each channel colors of both source and destination. Multiplying any color with black produces black. Multiplying any color with white leaves the color unchanged.

• plusDarker - (a.k.a. Linear Burn, opposite of plusLighter) darkens each source color channel to reflect the destination color. Blending with white produces no change.

Contrast

The following blend modes create contrast by both lightening the lighter areas and darkening the darker areas in the destination. The outcome is more vibrant colors.

• overlay - (opposite of hardLight, can be thought as combination of multiply and screen) darker colors in the source intensify the destination colors, while lighter colors in the destination wash out the source. Where the source is light, the destination becomes lighter. Where the source is dark, the destination becomes darker.

• softLight - softer version of overlay, Applies a half-strength screen to lighter areas, and half-strength multiply to darker areas of the source.

• hardLight - based on the source color brightness, if it's dark, apply screen, apply multiply otherwise.

Component

These blend modes output a result based on one property/component of the source, and all others from the destination:

• hue - Uses hue from the source, luminosity and saturation from the destination.

• saturation - Uses saturation from the source, luminosity and hue from the destination.

• color - (opposite of luminosity) Uses luminosity from the destination, saturation and hue from the source.

• luminosity - (opposite of color) Uses luminosity from the source, saturation and hue from the destination.

Compositing

These blend modes apply different masks to both source and destination. For more options in SwiftUI, check out the three-part SwiftUI masking series.

• sourceAtop - the source is placed only where it's over the destination.

• destinationOver - the destination is placed over the source.

• destinationOut - the destination is shown only where it's not underneath the source (we used this to create a inverse mask view modifier).

Invert

Invert blend modes either invert or cancel out source colors depending on destination colors.

• difference - subtracts the darker of the two colors (from destination and source) from the lighter color. If either source or destination is all white, this blend inverts the other view colors.

• exclusion - similar to difference, but the outcome has lower contrast

Normal

• normal - the default behavior, this is needed as blending modes propagate via SwiftUI's environment.

Applying multiple blend modes

When we apply multiple blending modes, it's helpful to think that:

• the source is what we are currently drawing
• the destination is what has been drawn so far

If we apply multiple blend modes to the same view, only the closest one will take effect:

ZStack {
  Destination()
  Source()
    .blendMode(.color) // applied
    .blendMode(.destinationOut) // discarded
    .blendMode(.multiply) // discarded
}

This is consistent with other (photo editing) software. The source view is only one part of the equation. Applying blend modes without a destination is a no-op.

Things get more interesting when we apply different blend modes to different layers. Let's make an example:

ZStack {
  BottomView()
  MidView()
    .blendMode(...)
  TopView()
    .blendMode(...)
}

Here we will:

1. blend BottomView (destination) with MidView (source) using MidView's blend mode
2. blend the BootomView + MidView output (destination) with TopView (source) using TopView's blend mode

This is just an example, but the blending possibilities will just grow from here.

Wait, it's all CIFilters?

If we dig into SwiftUI's Environment, we see that our SwiftUI.BlendMode is translated into a CALayer.compositingFilter:

[...]
- SwiftUI.DisplayList.ViewUpdater.ViewCache
▿ value: SwiftUI.DisplayList.ViewUpdater.ViewInfo
  [...]
  - layer: <
    CALayer: ...; 
    [...]
    compositingFilter = colorBurnBlendMode // 👈🏻
  > 
[...]

This shouldn't come as a surprise, but it's a good reminder that SwiftUI stands on the shoulders of giants.

CIFilter goes well beyond just blending and compositing, Apple has excellent documentation, with images, here.

All SwiftUI.BlendMode cases have "No overview available." as documentation (FB9620110).

Conclusions

Blending might not be something we reach out to daily when building our apps, but it's a great tool to have at our disposal, and SwiftUI makes it very simple to use.

We've seen a few examples in this article, but I invite you to download the sample code, experiment with different views, and see the wide variety of results that you can get.

Do you use blending in SwiftUI? Please feel free to show me your work on Twitter! Thank you for reading.

References

• Blending mode descriptions - Adobe
• Compositing and Blending Level 1 - W3C
• Use blend modes - ArcGIS Online
• Blend Modes - Wikipedia
• Core Image Filter Reference - Apple

📚 This article comes with a companion app! Download it here.

In the last two articles, we've covered SwiftUI clipping and masking. In this final article of the series, let's explore what we can do beyond what SwiftUI offers out of the box.

In a hurry? Jump to the last chapter before the conclusions to grab the code you're looking for.

Reverse Mask (a.k.a. Inverse Mask)

Let's start with a simple yellow rectangle, we highlight the view bounds in red for reference:

Color.yellow
  .frame(width: 200, height: 200)
  .border(.red)

A reverse mask applies the opposite effect of regular masks:
it uses the same rule based on the mask opacity, but in reverse. Here's a first comparison:

In both cases, we use the same Star() shape as the mask:

• on the left, where we apply a regular mask, the original yellow rectangle is drawn only where the shape is
• on the right, where we apply a reverse mask, the original yellow rectangle is drawn everywhere but where the shape is

Here are a couple of more examples to render the idea:

Here we use a Text as the mask.

Here we use a LinearGradient as the mask.

A reverse mask modifier

Unfortunately, SwiftUI doesn't offer a reverse mask modifier. There are certainly reasons why this is the case, a few might be around answering the following questions:

• does a reverse mask allow content bleeding?
• does a reverse mask alignment refer to the view bound or the content bound?

There's no wrong answer to both questions, and probably legit use cases for all of them.

While there's no official API, we have various ways to create our own reverse mask API for our needs. Let's explore how.

Blending

When we stack views on top of each other, the views at the bottom are hidden by those above. We can leverage this through opacity or playing with views of different sizes, but the idea stays: views at the bottom will always have some parts hidden (or semi-hidden) by views above.

A powerful technique breaking out of this standard behavior is blending, which lets us use different view properties (hue, opacity, luminosity, and more) to compose the final stack appearance.

We will go through all the various blend modes in a future article: for the moment, let's focus on the destination out blending more, BlendMode.destinationOut.

With blend modes, the source is the top view, while the destination is the bottom view.

With destination out, the final view is the bits of the bottom view (the destination) where it doesn't overlap with the top view (the source).

Here's an example where the destination is a Rectangle, and the source is a Circle, both of the same size:

ZStack {
  Rectangle() // destination
  Circle()    // source
    .blendMode(.destinationOut)
}
.compositingGroup()
.border(.red)

If we now invert the two views, the ZStack draws nothing, because the Rectangle (source) overlaps the Circle (destination) entirely:

ZStack {
  Circle()    // destination
  Rectangle() // source
    .blendMode(.destinationOut)
}
.compositingGroup()
.border(.red)

Similar to the mask(alignment:_:) view modifier, blendMode(.destinationOut) uses each view opacity to determine the final output. Here are the same examples as before, where we replace the Rectangle with a fading gradient:

ZStack {
  LinearGradient(
    colors: [.clear, .black], 
    startPoint: .leading, endPoint: .trailing
  )           // destination
  Circle()    // source
    .blendMode(.destinationOut)
}
.compositingGroup()
.border(.red)

ZStack {
  Circle()    // destination
  LinearGradient(
    colors: [.clear, .black], 
    startPoint: .leading, endPoint: .trailing
  )           // source
  .blendMode(.destinationOut)
}
.compositingGroup()
.border(.red)

By now, readers of the previous two articles of this SwiftUI masking series might have already guessed where this is going: we can use this destination out blending technique to create our reverse mask.

Building a reverse mask modifier

First, we want to keep the same API as the mask(alignment:_:) modifier, this is how it will look like:

extension View {
  @inlinable
  public func reverseMask<Mask: View>(
    alignment: Alignment = .center, 
    @ViewBuilder _ mask: () -> Mask
  ) -> some View
}

Next, we know that mask(alignment:_:) works by showing the original view only where the mask has opacity, we want to do the opposite now. Let's start by applying a normal mask:

extension View {
  @inlinable
  public func reverseMask<Mask: View>(
    alignment: Alignment = .center,
    @ViewBuilder _ mask: () -> Mask
  ) -> some View {
    self.mask {
      Rectangle()
    }
  }
}

By passing a Rectangle() in the mask modifier, we have obtained the same effect as .clipped():
we no longer allow content bleeding, but the original content is still visible within the view bounds.

Next, we want to apply the .destinationOut blend mode with our mask as the source, and the clipping rectangle as the destination:

// ⚠️ this is not the final code.
extension View {
  @inlinable
  public func reverseMask<Mask: View>(
    alignment: Alignment = .center,
    @ViewBuilder _ mask: () -> Mask
  ) -> some View {
    self.mask {
      ZStack {
        Rectangle() // destination
        mask()      // source
          .blendMode(.destinationOut)
      }
    }
  }
}

Thanks to ZStack, we're applying the same effects covered in the Blending chapter above and then using the outcome as the input for a regular mask, obtaining a reverse mask.

Lastly, we want to respect the alignment parameter, the best way to do this, while also dealing with masks that could have a bigger size than the view they're applied to, is to apply an overlay to our Rectangle:

extension View {
  @inlinable
  public func reverseMask<Mask: View>(
    alignment: Alignment = .center,
    @ViewBuilder _ mask: () -> Mask
  ) -> some View {
    self.mask {
      Rectangle()
        .overlay(alignment: alignment) {
          mask()
            .blendMode(.destinationOut)
        }
    }
  }
}

This is exactly how we obtained the examples at the beginning of the article, here are them again, with their code.

HStack {
  Color.yellow
    .frame(width: 200, height: 200)
    .mask {
      Star()
    }
    .border(.red)

  Color.yellow
    .frame(width: 200, height: 200)
    .reverseMask {
      Star()
    }
    .border(.red)
}

HStack {
  Color.yellow
    .frame(width: 200, height: 200)
    .mask {
      Text("MASK")
        .font(.system(size: 60).weight(.black))
    }
    .border(.red)

  Color.yellow
    .frame(width: 200, height: 200)
    .reverseMask {
      Text("MASK")
        .font(.system(size: 60).weight(.black))
    }
    .border(.red)
}

HStack {
  Color.yellow
    .frame(width: 200, height: 200)
    .mask {
      LinearGradient(
        colors: [.clear, .black],
        startPoint: .leading, endPoint: .trailing
      )
    }
    .border(.red)
  
  Color.yellow
    .frame(width: 200, height: 200)
    .reverseMask {
      LinearGradient(
        colors: [.clear, .black],
        startPoint: .leading, endPoint: .trailing
      )
    }
    .border(.red)
}

The complete source code can be found here.

Conclusions

SwiftUI might not always offer the API that we need out of the box. However, most of the time, the tooling at our disposal can fill in the gap, and allow us to build the perfect API for any occasion.

This article is the final part of the SwiftUI masking series. Thank you for reading, and stay tuned for more SwiftUI content!

Have you ever used reverse masking before? Please let me know!

New accessibility ForEach initializer

@available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)
extension ForEach where ID == Data.Element.ID, Content : AccessibilityRotorContent, Data.Element : Identifiable {
  /// Creates an instance that generates Rotor content by combining, in order,
  /// individual Rotor content for each element in the data given to this
  /// `ForEach`.
  ///
  /// It's important that the `id` of a data element doesn't change unless you
  /// replace the data element with a new data element that has a new
  /// identity.
  ///
  /// - Parameters:
  ///   - data: The identified data that the ``ForEach`` instance uses to
  ///     create views dynamically.
  ///   - content: The result builder that generates Rotor content for each
  ///     data element.
  public init(_ data: Data, @AccessibilityRotorContentBuilder content: @escaping (Data.Element) -> Content)
}

The only difference in the SwiftUI SDK is the exposure of a ForEach accessibility initializer, if you haven't worked with accessibility rotors before, Majid Jabrayilov has a great overview.

This method was present from Xcode 13 beta 2, it was then moved to internal in beta 5, and it has been reverted back to public in this release candidate.

A look back to all Xcode 13 betas

This is a good time to overview all the changes in previous betas:

• What's new in Xcode 13 beta 2, where we gained a .mini control size, text selection, and more consistent Searchable APIs
• What's new in Xcode 13 beta 3, where we've seen a lot of view builders API backport(s), and great styles improvements
• What's new in Xcode 13 beta 4, where we've gained strikethrough and underline AttributedString styles, a new buttonBorderShape(_:) view modifier, and more
• What's new in Xcode 13 beta 5, where we've gained custom links handling, interactive shapes, and more

Conclusions

Xcode 13rc comes with the "old" macOS SDK (as macOS 12 will be released later this year): it's likely that we will get an Xcode 13.1 beta quite soon, that brings back the new macOS 12 SDKs and, perhaps, a sneak peek to upcoming changes for other SDKs, too.

Thank you for reading!

This article is part of a series exploring new SwiftUI features. We will cover many more during the rest of the summer: subscribe to Five Stars's feed RSS or follow @FiveStarsBlog on Twitter to never miss new content!

📚 This article comes with a companion app! Download it here.

In View clipping in SwiftUI, we've explored all the ways we can apply clipping masks to views (if you haven't already, read that article first). While powerful, clipping has two significant limitations:

• it requires shapes as masks
• the content is either masked or not; there's no gray area

Let's explore SwiftUI masking beyond clipping.

Mask

The last masking view modifier that SwiftUI offers is mask(alignment:_:):

extension View {
  @inlinable public func mask<Mask: View>(
    alignment: Alignment = .center, 
    @ViewBuilder _ mask: () -> Mask
  ) -> some View
}

This is a new view modifier using the new view builder pattern. For older OSes, the mask declaration is slightly different, but the same concepts are still applied.

Besides the naming, this modifier declaration is identical to a couple of other view modifiers we're probably very familiar with, overlay(alignment:_:) and background(alignment:_:):

extension View {
  @inlinable public func overlay<V: View>(
    alignment: Alignment = .center, 
    @ViewBuilder content: () -> V
  ) -> some View

  @inlinable public func background<V: View>(
    alignment: Alignment = .center, 
    @ViewBuilder content: () -> V
  ) -> some View
}

This is not a coincidence. mask(alignment:_:) positions its mask exactly like an overlay or a background modifier would:

• the modifier proposes to its mask the natural size of the view it's applied to
• once the mask size is known, it is placed over the view, according to the specified alignment

Mask alignment

The alignment parameter is particularly useful when the mask and the original view have different sizes. In the following example, the mask is 30% the size of the view it's applied to:

struct FSView: View {
  private let alignments: [Alignment] = [
    .center, .leading, .trailing, .top, .bottom, .topLeading, .topTrailing, .bottomLeading, .bottomTrailing
  ]
  @State var alignment: Alignment = .center

  var body: some View {
    VStack {
      Color.yellow
        .frame(width: 200, height: 200)
        .mask(alignment: alignment) {
          Rectangle()
            .frame(width: 60, height: 60) // 👈🏻 60 x 60 is smaller than 200x200
        }
        .border(.red)

      Button("Random alignment") {
        withAnimation {
          alignment = alignments.filter { $0 != alignment } .randomElement()!
        }
      }
    }
  }
}

Alignment should be CaseIterable (FB9581717)

The red border shows the bound of the original view for a visual aid: otherwise, we'd see just a small rectangle floating around.

Views as masks

The real power over clipping modifiers stands with the opportunity to use any Views as masks. What about Text, for example?

Color.yellow
  .frame(width: 200, height: 200)
  .mask {
    Text("MASK")
      .fontWeight(.black)
      .font(.system(size: 60))
  }
  .border(Color.red)

Unlike shapes, there's no expectation for views to stay within the natural size of the view they're applied to. Therefore masks can allow content bleeding.

In the following example:

• the view content extends to a 300x300 points rectangle
• the view bound is 200x200 points
• the applied mask exceeds the view bounds, allowing content bleeding

Color.yellow
  .frame(width: 300, height: 300)
  .frame(width: 200, height: 200)
  .mask {
    Text("MASK")
      .fontWeight(.black)
      .font(.system(size: 80))
      .fixedSize() // 👈🏻 Ignores the proposed 200x200 points size
  }
  .border(Color.red)

Opacity

mask(alignment:_:) uses the mask opacity to determine what is shown from the original view, for example:

Color.yellow
  .frame(width: 200, height: 200)
  .mask {
    LinearGradient(colors: [.clear, .black, .clear], startPoint: .leading, endPoint: .trailing)
  }
  .border(Color.red)

Here we use a linear gradient with three stops. The gradient color in the middle doesn't matter. It's the color opacity that does:
we could replace it with .white, .red etc. The result would be the same.

While we don't have to use gradients with masks, this fading technique is very popular in iOS.
In the following example we take the sample code from How to control safe area insets in SwiftUI and add a subtle fading effect below the button:

struct ContentView: View {
  var body: some View {
    ScrollView {
      ...
    }
    .safeAreaInset(edge: .bottom) {
      Button { } label: { ... }
        .background {
          Color(uiColor: .systemBackground)
            .mask(alignment: .top) {
              VStack(spacing: 0) {
                LinearGradient(
                  stops: [
                    Gradient.Stop(color: .clear, location: .zero),
                    Gradient.Stop(color: .black, location: 1.0)
                  ],
                  startPoint: .top,
                  endPoint: .bottom
                )
                .frame(height: 32)
                Color.black
              }
            }
            .padding(.top, -32)
            .ignoresSafeArea(.all, edges: .bottom)
        }
    }
  }
}

Blur

Another visually pleasing technique is mixing the fade effect with a blur. To obtain this mix, we need to change just two lines from the example above:

struct ContentView: View {
  var body: some View {
    ...
      .background {
        Color.clear // 👈🏻
          .background(.ultraThinMaterial) // 👈🏻
          .mask(alignment: .top) {
            ...
          }
          ...
      }
    }
  }
}

The complete source code can be found here.

Conclusions

Masking is one of those subtle effects that can help bring our app design to the next level.

So far, we've covered what SwiftUI offers: in the next and final article of the series, we will explore what we can do beyond the official APIs.

If you haven't already, this is a very good time to subscribe to Five Star's RSS feed. Thank you for reading!

📚 This article comes with a companion app! Download it here.

Masking is a powerful technique that we can use to push our app's design to the next level.

SwiftUI offers various ways to do just that: let's take a tour where it all begins by exploring clipping in SwiftUI.

Clipping Masks

Every view comes with a bound frame. This frame is used for composing the overall view hierarchy layout. When it comes to the drawing phase, the view content can exceed its bound frame (also known as bleeding).

For example, consider the following view:

Text("Five stars")
  .background(Color.yellow)
  .font(.system(size: 90))
  .border(Color.red)

The red border shows the content frame, which, in this case, also coincides with the bound frame.
Let's take a look at another example:

Text("Five stars")
  .background(Color.yellow)
  .font(.system(size: 90))
  .fixedSize()
  .border(Color.blue)
  .frame(width: 200, height: 100)
  .border(Color.red)

Here Text takes as much space as it needs, thanks to the fixedSize() view modifier. However, we also apply another .frame(width: 200, height: 50) view modifier on top of that.

For the rest of the view hierarchy, this view bound is represented by the red border, while the blue border represents the space the view content takes.

On the layout phase:

• only the bound frame/red border will be considered
• the content frame/blue border is completely disregarded

As SwiftUI allows content bleeding by default, the content is drawn even when it extends beyond the view frame edges. To avoid this, we can use clipping:

Text("Five stars")
  .background(Color.yellow)
  .font(.system(size: 90))
  .fixedSize()
  .border(Color.blue)
  .frame(width: 200, height: 100)
  .border(Color.red)
  .clipped() // 👈🏻

The clipped() view modifier limits the drawing of a view to its bound frame, everything else will be hidden.

In other words, clipped() applies a mask equivalent to the bound frame "rectangle", thus hiding anything that goes beyond that rectangle.

SwiftUI comes with two clipped() alternatives: cornerRadius(_:) and clipShape(_:style).

Corner Radius

cornerRadius(_:) behaves exactly like clipped(), but instead of matching 1:1 the bound frame, it also lets us specify a corner radius to be applied in the final mask:

Text("Five stars")
  .background(Color.yellow)
  .font(.system(size: 90))
  .fixedSize()
  .frame(width: 200, height: 100)
  .cornerRadius(50) // 👈🏻

Using the same thought process from before, cornerRadius(_:) applies a mask equivalent to the view bound frame rectangle, this time with rounded corners.

.clipped() can be seen as a more performant convenience over .cornerRadius(0).

Clip Shape

So far we've been playing with just rectangles, clipShape(_:style:) removes this limitation and lets us use any shape as the clipping mask:

Text("Five stars")
  ...
  .clipShape(Circle())

Shapes fit as best as they can within the natural size of the view that contains them, a.k.a. the view bound frame.

We're not limited to the shapes SwiftUI offers. We can also declare our own:

Text("Five stars")
  ...
  .clipShape(Star())

Similarly to how .clipped() can be seen as a convenience over .cornerRadius(0), .cornerRadius(x) can be seen as a convenience over .clipShape(RoundedRectangle(cornerRadius: x)).

Even-odd rule

When defining a Shape, it's acceptable for some of its parts to be drawn over multiple times. We can consider those sections to be "overlapping areas". For example, take this DoubleEllipse Shape definition, which consists of two ellipses overlapping by an arbitrary amount:

struct FSView: View {
  @State var overlapping: Double = 0.1

  var body: some View {
    VStack {
      DoubleEllipse(overlapping: overlapping)
        .frame(width: 300, height: 100)
      HStack {
        Text("Overlapping")
        Slider(value: $overlapping, in: 0.0...1.0)
      }
    }
  }
}

struct DoubleEllipse: Shape {
  /// 1 = complete overlap
  /// 0 = no overlap
  @Clamping(0.0...1.0) var overlapping: Double = 0

  func path(in rect: CGRect) -> Path {
    let rectSize = CGSize(width: (rect.width / 2) * (1 + overlapping), height: rect.height)

    var path = Path()
    path.addEllipse(in: CGRect(origin: .zero, size: rectSize))
    let secondEllipseOrigin = CGPoint(x: (rect.width / 2) * (1 - overlapping), y: rect.origin.y)
    path.addEllipse(in: CGRect(origin: secondEllipseOrigin, size: rectSize))

    return path
  }
}

By default, SwiftUI draws everything as defined. However, we can also apply a fill(style:) Shape modifier that threats those overlapping areas differently:

struct FSView: View {
  @State var overlapping: Double = 0.1

  var body: some View {
    VStack {
      DoubleEllipse(overlapping: overlapping)
        .fill(style: FillStyle(eoFill: true, antialiased: true)) // 👈🏻
        .frame(width: 300, height: 100)
      HStack {
        Text("Overlapping")
        Slider(value: $overlapping, in: 0.0...1.0)
      }
    }
  }
}

The magic is all in the oeFill parameter, where eo stands for Even-odd (rule), described as:
«A point "insideness" in a shape is determined by drawing a ray from that point to infinity in any direction and counting the number of path segments from the given shape that the ray crosses. If this number is odd, the point is inside; if even, the point is outside.»

The definition goes beyond just overlapping, but this is most likely how it will be used when masking in SwiftUI.

The fill(style:) Shape modifier returns some View, meaning that we cannot use it with clipShape(_:style:), as the latter requires a Shape instance. With that being said, .clipShape(_:style:) second parameter addresses this, letting us pass a FillStyle:

VStack {
  Text("Five stars")
    .background(Color.yellow)
    .font(.system(size: 90))
    .clipShape(
      OverlappingEllipses(ellipsesNumber: ellipsesNumber, overlapping: overlapping),
      style: FillStyle(eoFill: true, antialiased: false) // 👈🏻
    )
  Stepper("Ellipses number:", value: $ellipsesNumber, in: 2...16)
  HStack {
    Text("Overlapping")
    Slider(value: $overlapping, in: 0.0...1.0)
  }
}

Animating clipping masks

Shapes conform to both View and Animatable, we can declare a var animatableData: CGFloat in our shapes in order to take advantage of this:

struct OverlappingEllipses: Shape {
  @Clamping(1...Int.max) var ellipsesNumber: Int = 2
  @Clamping(0.0...1.0) var overlapping: Double = 0

  var animatableData: CGFloat { // 👈🏻
    get { overlapping }
    set { overlapping = newValue }
  }

  func path(in rect: CGRect) -> Path {
    ...
  }
}

With this, we can put everything we've covered so far and easily obtain some trippy effects:

struct FSView: View {
  @State var overlapping: Double = 0

  var body: some View {
    VStack(spacing: 16) {
        Text("Five stars")
          ...
          .clipShape(
            OverlappingEllipses(ellipsesNumber: 8, overlapping: overlapping),
            style: FillStyle(eoFill: true, antialiased: false)
          )

      Text("Five stars")
        ...
        .clipShape(
          OverlappingRectangles(rectanglesNumber: 8, overlapping: overlapping),
          style: FillStyle(eoFill: true, antialiased: false)
        )

      Button("Show/Hide") {
        withAnimation(.easeInOut(duration: 2)) {
          overlapping = overlapping == 1 ? 0 : 1
        }
      }
    }
  }
}

The complete source code can be found here.

Conclusions

View masking starts simple and gets powerful quickly: in this article, we've seen an overview of view clipping, but this is just the simplest masking method SwiftUI offers. Stay tuned for the second part!

Do you use masking in your apps? What effects have you built? Please let me know!

Generic component values

• controlSize (iOS, macOS)
• controlActiveState (macOS)
• isEnabled
• isFocused
• redactionReasons

First we have a few generic values that are applicable to most views. Ideally, we observe them in our view styles, and act accordingly.

struct FSButtonStyle: ButtonStyle {
  @Environment(\.isFocused) private var isFocused: Bool
  @Environment(\.isEnabled) private var isEnabled: Bool
  @Environment(\.controlSize) private var controlSize: ControlSize

  func makeBody(configuration: Configuration) -> some View {
    configuration
      .label
      .scaleEffect(isFocused ? 1.2 : 1)
      .foregroundColor(isEnabled ? .accentColor : .gray)
      .padding(controlSize == .large ? 16 : 0)
  }
}

Check out How to create custom redacted effects for a dive into redactionReasons.

Display values

• calendar
• dynamicTypeSize
• displayScale
• horizontalSizeClass (iOS)
• layoutDirection
• locale
• pixelLength
• timeZone
• verticalSizeClass (iOS)

The environment exposes important details of, well, the "view environment": such values give us a broader insight into where we're about to display our view, or how we're supposed to do so.

For example, we can use such values to make make our app layout adapt in different situations:

struct FSContentView: View {
  @Environment(\.horizontalSizeClass) private var horizontalSizeClass: UserInterfaceSizeClass?
  
  var body: some View {
    if horizontalSizeClass == .compact {
      TabNavigation()
    } else {
      SidebarNavigation()
    }
  }
}

struct FSContentView: View {
  @Environment(\.dynamicTypeSize) private var dynamicTypeSize: DynamicTypeSize

  var body: some View {
    if dynamicTypeSize.isAccessibilitySize {
      VStack {
        ...
      }
    } else {
      HStack {
        ...
      }
    }
  }
}

Most of these values can also be overridden by us. This is particularly useful when used with SwiftUI previews:

struct FSContentView_Previews: PreviewProvider {
  static var previews: some View {
    ForEach(DynamicTypeSize.allCases, id: \.self) { dynamicTypeSize in
      FSContentView()
        .environment(\.dynamicTypeSize, dynamicTypeSize)
        .previewDisplayName("\(dynamicTypeSize)")
    }
    .previewLayout(.sizeThatFits)
  }
}

View-specific values

The majority of environment values are meant to take effect on specific views. An example we're probably familiar with is view styles (Button styles, Label styles, TextField styles, etc.).

Here we will see interesting decisions/trade-offs that the SwiftUI team took in different situations.
The main three options the team had are:

1. expose an environment value that can be both read and, optionally, written by third-party developers
2. expose an associated view modifier and hide the environment value (e.g., all styles)
3. expose both the environment value and the associated view modifier

List

• defaultMinListRowHeight
• defaultMinListHeaderHeight
• editMode (iOS, tvOS)
• headerProminence

List {
  Section {
    Text("Very tall row")
  } header: {
    Text("Increased prominence header")
  }
  .headerProminence(.increased)

  Section {
    Text("Another very tall row")
  } header: {
    Text("Standard prominence header")
  }
}
// 👇🏻 sets the minimum row height to 200pt
.environment(\.defaultMinListRowHeight, 200)

Here we already see two of the three decisions above:

• defaultMinListRowHeight and defaultMinListHeaderHeight are exposed as environment values that can be both read and set
• headerProminence is also exposed as an environment value, but we can only set it via its associated .headerProminence(_:) modifier (attempting to setting it directly via .environment(\.headerProminence, .increased) won't have any effect, FB9543744)

Symbols

• imageScale
• symbolVariants
• symbolRenderingMode

SF Symbols have received wonderful updates this year thanks to their new variants and modes, these parameters are also available for our views to observe:

struct FSView: View {
  @Environment(\.symbolVariants) private var symbolVariant: SymbolVariants
  @Environment(\.symbolRenderingMode) private var symbolRenderingMode: SymbolRenderingMode?

  var body: some View {
    ...
  }
}

However, most likely, we will use them to apply such options on Label or other places where we use SF Symbols:

VStack(alignment: .leading) {
  Label("Ace of Hearts", systemImage: "suit.heart")
  Label("Ace of Spades", systemImage: "suit.spade")
  Label("Ace of Diamonds", systemImage: "suit.diamond")
  Label("Ace of Clubs", systemImage: "suit.club")
}
.symbolRenderingMode(.multicolor)
.symbolVariant(.fill)

Pickers

• defaultWheelPickerItemHeight (WatchOS)

WatchOS only, this value lets us read and set the height of a wheel picker.

Picker("My Favorite Fruit", selection: $fruit) {
  ForEach(Fruit.allCases, id: \.self) {
    Text("\($0)" as String)
  }
}.environment(\.defaultWheelPickerItemHeight, 125)

Search

• isSearching
• dismissSearch

SwiftUI's new search functionality comes with a couple of environment values, which can be used, respectively, for:

• detecting when the user is doing a search
• provide an alternative way to dismiss/stop the current search

struct StarredReposList: View {
  @StateObject var viewModel = SearchViewModel()
  @Environment(\.dismissSearch) var dismissSearch
  @Environment(\.isSearching) var isSearching

  let query: String

  var body: some View {
    List(viewModel.repos) { repo in
      RepoView(repo: repo)
    }
    .overlay {
      if isSearching && !query.isEmpty {
        VStack {
          Button("Dismiss search") {
            dismissSearch()
          }
          SearchResultView(query: query)
            .environmentObject(viewModel)
        }
      }
    }
  }
}

Example from Mastering search in SwiftUI by Majid Jabrayilov.

Keyboard shortcuts

• keyboardShortcut (iOS, macOS)

struct ContentView: View {
  var body: some View {
    VStack {
      Button("Tap me or press ⌘F") {
        print("tapped or pressed")
      }
      .keyboardShortcut("F", modifiers: [.command])

      Button("Tap me or press ⌘S") {
        print("tapped or pressed")
      }
      .keyboardShortcut("S", modifiers: [.command])
    }
    .buttonStyle(FiveStarsButtonStyle())
  }
}

private struct FiveStarsButtonStyle: ButtonStyle {
  @Environment(\.keyboardShortcut) private var shortcut: KeyboardShortcut? // 👈🏻

  func makeBody(configuration: Configuration) -> some View {
    configuration.label
      .font(.body.weight(shortcut == .init("F") ? .heavy : .regular))
  }
}

Example from What's new in Xcode 13 beta 3.

keyboardShortcut environment value lets us read the assigned keyboard shortcut to any view. We can use this value for example to customize the view appearance.

Text

• font
• legibilityWeight
• multilineTextAlignment
• truncationMode
• lineSpacing
• allowsTightening
• lineLimit
• minimumScaleFactor
• textCase
• disableAutocorrection

Rendering and editing text is complicated. There are many parameters to consider at any given time. Apple platforms come with TextKit and Core Text for most advanced needs, which help us fine control various aspects such as text storage, layout management, and text geometry containment.

SwiftUI exposes none of that. However, text rendering/editing still manages to be SwiftUI's corner with the most number of dedicated view modifiers and environment values.

struct ContentView: View {
  var body: some View {
    Text(
      """
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
      Ut vitae erat sit amet risus hendrerit cursus. 
      Aenean pulvinar ligula mauris, eu molestie magna sodales non. 
      In malesuada mattis nibh, in gravida elit.
      """
    )
    .modifier(BenevolentLineLimit())
    .lineLimit(2)
  }
}

/// Doubles the `lineLimit` number.
struct BenevolentLineLimit: ViewModifier {
  @Environment(\.lineLimit) private var lineLimit: Int?

  func body(content: Content) -> some View {
    let newLineLimit: Int?

    if let lineLimit = lineLimit {
      newLineLimit = lineLimit * 2
    } else {
      newLineLimit = nil
    }
    return content.lineLimit(newLineLimit)
  }
}

This is just a sneak peek into text management on Apple platforms. See Cocoa Text Architecture Guide for much more.

Accessibility

• accessibilityEnabled
• accessibilityDifferentiateWithoutColor
• accessibilityReduceTransparency
• accessibilityReduceMotion
• accessibilityInvertColors
• accessibilityShowButtonShapes
• accessibilityVoiceOverEnabled
• accessibilitySwitchControlEnabled

struct ContentView: View {
  @Environment(\.accessibilityReduceTransparency) var reduceTransparency

  var body: some View {
    VStack {
      ...
    }
    .background(Color.red.opacity(reduceTransparency ? 1 : 0.5))
  }
}

Accessibility has always been a main focus in SwiftUI: the number of view modifiers, environment values, documentation, etc., really shows that.

Unlike most other values, accessibility environment values are (nearly) all read-only.

Presentation

• dismiss
• isPresented
• scenePhase

The environment also gives us important values regarding the current presentation state, and even let us take control of the view presentation itself:

struct FSSheet: View {
  @Environment(\.dismiss) var dismiss

  var body: some View {
    Button("Dismiss Me") {
      dismiss()
    }
  }
}

Actions

• openURL
• refresh
• resetFocus (macOS, tvOS, watchOS)

This year we've seen new actions as environment values, which let us both grab and set closures that are then invoked by other views down the hierarchy:

struct FSView {
  @Environment(\.openURL) var openURL

  var body {
    ...
  }

  func onOpenURLTap(_ url: URL, completion: @escaping (_ accepted: Bool) -> Void) {
    openURL(url, completion: completion)
  }
}

Example from Handling links with SwiftUI's openURL.

Colors/Themes

• colorScheme
• colorSchemeContrast
• backgroundMaterial

The environment makes it easy to propagate preferences such as colors and themes. SwiftUI comes with a few values of its own:

struct FSView: View {
  @Environment(\.colorScheme) var scheme

  var body: some View {
    Label(title, systemImage: systemImage)
  }

  var title: LocalizedStringKey {
    switch scheme {
      case .dark: return "Dark"
      case .light: fallthrough
      @unknown default: return "Light"
    }
  }

  var systemImage: String {
    switch scheme {
      case .dark: return "moon"
      case .light: fallthrough
      @unknown default: return "sun.max"
    }
  }
}

One-off

• managedObjectContext
• undoManager

Lastly, we have a couple of environment values that are not strictly associated with any view, but still need to be propagated into and managed within the environment.

struct AddItemView: View {
  @Environment(\.managedObjectContext) var managedObjectContext
  @State var itemTitle: String = ""

  var body: some View {
    ...
  }

  var addButton: some View {
    Button("Add item") {
      let item = FSItem(context: managedObjectContext)
      item.title = itemTitle
      try? selfmanagedObjectContext.save()
      // to do: navigate back and handle errors
    }
  }
}

For a great introduction on UndoManager, check out Handling Undo & Redo in SwiftUI by Matthaus Woolard.

Conclusions

SwiftUI exposes over 50 environment values (without considering deprecated ones). I'd argue that the SwiftUI team has been conservative on what to make public:
more values could be exposed as read-only, foregroundColor and tintColor immediately come to mind (FB8161189, FB9552347).

Do you use or define environment values in your apps? Let me know via email or Twitter!

In this article, let's explore everything around openUrl and handling links in SwiftUI views.

Introduction

Two views handle URLs in SwiftUI: Link and, from this year, Text.

Link

From iOS 14 (and equivalent in other platforms) SwiftUI apps can declare Links in views.

Link("Go to the main blog", destination: URL(string: "https://fivestars.blog/")!)

Links are buttons in disguise (we can apply button styles), specializing in opening URLs. Their primary purpose is to deep-link into apps from widgets, as no logic can run on widgets (as of iOS 15/macOS 12).

Their use is not limited to widgets. We can use Links within apps for various situations/needs:

// Opens URL in Safari
Link("Go to the main blog", destination: URL(string: "https://fivestars.blog/")!)
  .buttonStyle(.borderedProminent)

// Opens Settings.app
Link("Go to settings", destination: URL(string: UIApplication.openSettingsURLString)!)
  .buttonStyle(.bordered)

// Open third party app
Link("Go to app", destination: URL(string: "bangkok-metro://Sukhumvit%20Line%2FAsok")!)

Text

Text is one of the SwiftUI views that has received most new functionalities this year, mainly thanks to the new markdown and AttributedString support.

By using either of these new functionalities, we can now add links to Text:

var body: some View {
  VStack {
    Text(attributedString)
    Text("Check out [Five Stars](https://fivestars.blog)")
  }
}

var attributedString: AttributedString {
  var attributedText = AttributedString("Visit website")
  attributedText.link = URL(string: "https://fivestars.blog")
  return attributedText
}

Similar to Link, Text also supports non-http urls.

openURL

When the user interacts with a link (in either a Text or Link view), SwiftUI will reach for the view openURL environment value:

extension EnvironmentValues {
  public var openURL: OpenURLAction { get }
}

Where the OpenURLAction is defined as following:

public struct OpenURLAction {
  public func callAsFunction(_ url: URL)
  public func callAsFunction(_ url: URL, completion: @escaping (_ accepted: Bool) -> Void)
}

The view will call openURL with the relevant URL. The system will then receive and handle the URL, which will either open the default device browser and load a web page, or deep-link into another app.

As openURL is a public environment value, we can also use it ourselves, replacing legacy's UIApplication calls:

struct FSView {
  @Environment(\.openURL) var openURL // 👈🏻 New way

  var body {
    ...
  }

  func onOpenURLTap(_ url: URL, completion: @escaping (_ accepted: Bool) -> Void) {
    // Old way 👇🏻
    if UIApplication.shared.canOpenURL(url) {
      UIApplication.shared.open(url)
      completion(true)
    } else {
      completion(false)
    }

    // New way 👇🏻
    openURL(url, completion: completion)
  }
}

What's new

New in Xcode 13 beta 5, openURL can not only be read, but also set:

extension EnvironmentValues {
  // public var openURL: OpenURLAction { get } 👈🏻 Previous declaration
  public var openURL: OpenURLAction // 👈🏻 New declaration
}

OpenURLAction has also gained a public initializer:

public struct OpenURLAction {
  @available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)
  public init(handler: @escaping (URL) -> OpenURLAction.Result)
}

Which requires a closure returning a new OpenURLAction.Result type, defined as following:

public struct Result {
  public static let handled: OpenURLAction.Result
  public static let discarded: OpenURLAction.Result
  public static let systemAction: OpenURLAction.Result
  public static func systemAction(_ url: URL) -> OpenURLAction.Result
}

The default behavior stays the same, but this small change enables third-party developers to control the URL handling entirely. Let's have a look at that next.

Handling URLs

The default behavior is equivalent to setting the following openURL value:

Link("FIVE STARS", destination: URL(string: "https://fivestars.blog/")!)
  .environment(\.openURL, OpenURLAction { url in
    return .systemAction
  })

OpenURLAction.Result has three more options. Let's have a look at those next.

.handled

.handled tells SwiftUI that our app logic successfully took care of the url:

Link("FIVE STARS", destination: URL(string: "https://fivestars.blog/")!)
  .environment(\.openURL, OpenURLAction { url in
    // ...
    return .handled
  })

Regardless of the URL value, by returning .handled, the system won't open Safari or trigger any deep link.

.discarded

.discarded works exactly like .handled, but tells SwiftUI that the url couldn't be handled.

Link("FIVE STARS", destination: URL(string: "https://fivestars.blog/")!)
  .environment(\.openURL, OpenURLAction { url in
    // ...
    return .discarded
  })

Going back to OpenURLAction's definition, the difference between .discarded and .handled lays on the value passed within the openURL completion block:

public struct OpenURLAction {
  public func callAsFunction(_ url: URL, completion: @escaping (_ accepted: Bool) -> Void)
}

• .handled will call completion with true
• .discarded will call completion with false

.systemAction(_ url: URL)

The last option is similar to the default .systemAction behavior, with the difference that we can now forward to a different URL:

Link("Go to Google", destination: URL(string: "https://google.com/")!)
  .environment(\.openURL, OpenURLAction { url in
    // Go to Bing instead 😈
    return .systemAction(URL(string: "https://www.bing.com")!)
  })

Custom actions

The hidden power of openURL is within the .handled case:
the most common use case has been forwarding users out of the app, but we can now handle different intents.

For example, imagine a welcome screen within an app, prompting the user to either sign in or sign up:

VStack {
  Text("Welcome to Five Stars!")
    .font(.largeTitle)

  Text("Please [sign in](https://fivestars.blog/sign-in) or [sign up](https://fivestars.blog/create-account) to continue.")
    .font(.headline)
    .environment(\.openURL, OpenURLAction { url in
      switch url.lastPathComponent {
        case "sign-in":
          // show sign in screen
          return .handled
        case "crate-account":
          // show sign up screen
          return .handled
        default:
          // Intent not recognized.
          return .discarded
      }
    })
}

First, Text has two distinct and interactive parts: this was not possible before the latest SwiftUI iteration.

Despite the new features, I still look forward the day we have a .onTapGesture(_:) Text modifier, FB8917806.

Second, because the URL is now handled within the app, we don't need the whole http declaration.
We can simplify the code above with the following:

Text("Please [sign in](sign-in) or [sign up](create-account) to continue.")
  .font(.headline)
  .environment(\.openURL, OpenURLAction { url in
    switch url.absoluteString {
      case "sign-in":
        // show sign in page
        return .handled
      case "crate-account":
        // show sign up page
        return .handled
      default:
        // Intent not recognized.
        return .discarded
    }
  })

Environment value

Unlike onSubmit's onSubmitAction environment value, which we covered previously, setting the openURL environment value always replaces the previous one, which means that only the closest closure to our view will be called.

In the following example, only the closure returning .systemAction will be triggered:

Link(...)
  .environment(\.openURL, OpenURLAction { url in
    return .systemAction
  })
  .environment(\.openURL, OpenURLAction { url in
    return .systemAction(URL(string: "https://www.anotherURL.com")!)
  })
  .environment(\.openURL, OpenURLAction { url in
    return .handled
  })
  .environment(\.openURL, OpenURLAction { url in
    return .discarded
  })

As of today, there's no way to tell SwiftUI to trigger the "next" closure instead of stopping after the first one.

View Modifier

In SwiftUI we already have a onOpenURL(perform:) view modifier, used to handle deep-links in the app. This naming is unfortunate, as it would make sense to have a companion onOpenURL(handler:) modifier for openURL.

Despite this modifier not being part of the official API, we can still create it ourselves:

extension View {
  func onOpenURL(handler: @escaping (URL) -> OpenURLAction.Result) -> some View {
    environment(\.openURL, OpenURLAction(handler: handler))
  }
}

This extension would, for example, reduce this:

Link("FIVE STARS", destination: URL(string: "https://fivestars.blog/")!)
  .environment(\.openURL, OpenURLAction { url in
    return .systemAction
  })

Into this:

Link("FIVE STARS", destination: URL(string: "https://fivestars.blog/")!)
  .onOpenURL(handler: { url in
    return .systemAction
  })

...which is less verbose and easier on the eye.

Conclusions

We're now at the third SwiftUI iteration, and the SwiftUI team is steadily patching all the essential missing features. Are you going to use openURL in your apps? Please let me know via email or Twitter!

This article is part of a series exploring new SwiftUI features. We will cover many more during the rest of the summer: subscribe to Five Stars's feed RSS or follow @FiveStarsBlog on Twitter to never miss new content!

Interactive shapes with ContentShapeKinds

Button("Hover me") {}
  .hoverEffect(.lift)
  .contentShape(.hoverEffect, Circle())

Text("Open Menu")
  .contextMenu {
    Button(...) { ... }
    Button(...) { ... }
  }
  .contentShape(.contextMenuPreview, Circle())

A new contentShape(_:_:eofill:) modifier has been introduced, letting us further define the shape of our interactive elements in special situations:

extension View
  @inlinable public func contentShape<S: Shape>(
    _ kind: ContentShapeKinds,
    _ shape: S,
    eoFill: Bool = false
  ) -> some View
}

ContentShapeKinds is a new option set with the following values:

@available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)
public struct ContentShapeKinds : OptionSet {
  public static let interaction: ContentShapeKinds
  public static let dragPreview: ContentShapeKinds
  public static let contextMenuPreview: ContentShapeKinds
  public static let hoverEffect: ContentShapeKinds
}

iOS 15b5 simulator crashes when showing a context menu, FB9486120.

Custom links handling

VStack {
  Link("Visit Five Stars", destination: URL(string: "https://fivestars.blog")!)
  Text("Visit [Five Stars](https://fivestars.blog) for more SwiftUI.")
}
.environment(\.openURL, OpenURLAction { url in
  // do something here...
  return .handled
})

Links and links within Text can now trigger custom actions. The default (and previous) behavior is for these links to open the associated URL on the device's browser. Now it's up to apps to decide what to do.

The custom behavior is possible by setting the openURL environment value.

Here are the possible outcomes we can return when a link is tapped:

public struct OpenURLAction.Result {
  /// The URL was handled (by the app).
  public static let handled: OpenURLAction.Result

  /// Action was ignored.
  public static let discarded: OpenURLAction.Result

  /// The original URL should be handled by the system (default behavior, opens browser with original URL).
  public static let systemAction: OpenURLAction.Result

  /// The given URL should be handled by the system (opens browser with the given URL).
  public static func systemAction(_ url: URL) -> OpenURLAction.Result
}

Opening a URL via Link view on iOS 15b5 simulator crashes very often, FB9486139.

More binding options

Following SE-0293 and List new binding capabilities, now also hierarchy Lists and OutlineGroups accept binding parameters:

struct FileItem: Identifiable {
  var name: String
  var children: [FileItem]?

  var id: String { name }

  static let spmData: [FileItem] = [
    FileItem(name: ".gitignore"),
    FileItem(name: "Package.swift"),
    FileItem(name: "README.md"),
    FileItem(name: "Sources", children: [
      FileItem(name: "fivestars", children: [
        FileItem(name: "main.swift")
      ])
    ])
  ]
}

struct ContentView: View {
  @State var data: [FileItem] = FileItem.spmData

  var body: some View {
    List($data, children: \.children) { $item in // 👈🏻
      TextField("Name", text: $item.name)
    }
  }
}

Making a few changes to the children values in the example above crashes the app, FB9486151.

Task priorities

We have a new task(priority:_:) view modifier letting us specify the priority to use when creating the given task. The previous modifier (without priority parameter) has been removed.

From:

.task {
  ...
}

To:

.task(priority: .high) {
  ...
}

AnimatableModifier deprecation

The AnimatableModifier protocol has been deprecated, instead we can make our modifiers conform to both Animatable and ViewModifier.

From:

struct FSAnimationEffect: AnimatableModifier { // 👈🏻
  var animatableData: CGFloat { ... }

  func body(content: Content) -> some View {
    ...
  }
}

To:

struct FSAnimationEffect: ViewModifier, Animatable { // 👈🏻
  var animatableData: CGFloat { ... }

  func body(content: Content) -> some View {
    ...
  }
}

Documentation

We have a new documentation for:

• @FetchRequest
• FetchedResults
• Text

Conclusions

Did you find anything else interesting in Xcode 13 beta 5? Please let me know!

We should have at least one more Xcode beta seed before the release candidate: don't forget to report any issue you find to Apple!

This article is part of a series exploring new SwiftUI features. We will cover many more during the rest of the summer: subscribe to Five Stars's feed RSS or follow @FiveStarsBlog on Twitter to never miss new content!

However, ZStack falls short as soon as we present a sheet or a fullScreenCover:
ZStack's presentation is bound to the views it contains.

In this article, let's see how we can overcome this challenge and much more.

Code examples are provided at the end of the article.

The challenge

Picking up from where we left in Custom HUDs in SwiftUI, the current limitation manifests as soon as we present something on top of the view associated with our HUD:

Instead, we want always to show our HUD on top of the screen, regardless of what's happening in our app:

App UI hierarchy

Everything we see on apps is placed on top of UIWindows. A window delivers touch events to the correct views and responds to other events such as (device) orientation changes.

With the introduction of multiple windows support for iPad (and Catalyst), UIWindows are associated with and managed by UIScenes, which representing a UI instance of our app.

We don't need to interact with either of them most of the time, especially with SwiftUI's new life cycle. However, even on SwiftUI apps, those components are still set up and used behind the curtain.

Lastly, we use a UISceneDelegate/UIWindowSceneDelegate to respond to various events related to our UIScene (and associated UISceneSession).

While a UIScene is normally set up with one window, scenes support multiple windows.

How to add extra windows to an app

Two requirements:

• keep a strong reference to the window
• provide the associated scene (a UIWindowScene instance)

Scenes do manage UIWindows, but we own the window life-cycle:
if only the scene holds a reference to the window, the window will be de-allocated (and its UI won't show in the app).

Since we get our app's UIWindowScene instances via our UISceneDelegate/UIWindowSceneDelegate, adding windows there is probably the easiest way to do so.

The scene delegate

If we refer to the scene delegate of an app using the UIKit life-cycle, we will see something similar to:

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
  var window: UIWindow?

  func scene(
    _ scene: UIScene, 
    willConnectTo session: UISceneSession, 
    options connectionOptions: UIScene.ConnectionOptions
  ) {
    let contentView = ContentView()

    if let windowScene = scene as? UIWindowScene {
      let window = UIWindow(windowScene: windowScene)
      window.rootViewController = UIHostingController(rootView: contentView)
      self.window = window
      window.makeKeyAndVisible()
    }
  }

  ...
}

The scene delegate is responsible for setting up the app's main window in scene(_:willConnectTo:options:).

SceneDelegate meets the windows requirements mentioned earlier:

• it keeps a strong reference to the window via its var window: UIWindow property
• it provides the associated scene during the window initialization via let window = UIWindow(windowScene: windowScene)

Because a scene supports multiple windows, we can add as many windows as we like, for example:

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
  var keyWindow: UIWindow?
  var hudWindow: UIWindow?

  func scene(
    _ scene: UIScene, 
    willConnectTo session: UISceneSession, 
    options connectionOptions: UIScene.ConnectionOptions
  ) {
    if let windowScene = scene as? UIWindowScene {
      setupKeyWindow(in: windowScene)
      setupHUDWindow(in: windowScene)
    }
  }

  func setupKeyWindow(in scene: UIWindowScene) {
    let window = UIWindow(windowScene: scene)
    window.rootViewController = UIHostingController(rootView: MainSceneView())
    self.keyWindow = window
    window.makeKeyAndVisible()
  }

  func setupHUDWindow(in scene: UIWindowScene) {
    let hudWindow = UIWindow(windowScene: scene)
    let hudViewController = UIHostingController(rootView: HUDSceneView())
    hudViewController.view.backgroundColor = .clear
    hudWindow.rootViewController = hudViewController
    hudWindow.isHidden = false
    self.hudWindow = hudWindow
  }
}

For simplicity's sake, we will add windows right from the app launch. We can add them whenever we like in our apps, as long as we meet the two requirements above.

Where:

• we set up the main window as before, named keyWindow
• we set up a secondary window, named hudWindow

The setup for this secondary (and any other) window doesn't match 1-1 the set up for the main window:

• we don't call makeKeyAndVisible() on the secondary window. There can be only one key window per scene, receiving keyboard and other non-touch-related events. Instead, we make sure that secondary windows are visible via isHidden = false
• we make the UIHostingController's view background color transparent. Otherwise, the main window would be hidden by the secondary window.

For apps using the SwiftUI life-cycle, everything we've seen so far still holds true, with a couple of differences:

1. we must associate the app with a scene delegate, check out How to add an AppDelegate and a SceneDelegate to a SwiftUI app on how to do so
2. we don't have to set up/manage the key window in our scene delegate: SwiftUI does that for us (on a private SwiftUI.AppSceneDelegate).

Windows hierarchy and behaviors

With the current setup, we're able to layer as many windows as we like, with one caveat:
only the topmost window receives touches.

The scene delegate places its windows in a stack.
When the user interacts with the screen, touches are received by the topmost window in that stack.

There could also be multiple stacks of windows if we have windows at different window levels.

This is because all windows are part of the app responder chain. Unless this behavior is what we need, we can change so by either sub-classing UIWindow, or setting the proper UIWindow properties in the scene delegate.

Non-interactive window

For example, we could make a window ignore touches by setting isUserInteractionEnabled = false:

/// in our scene delegate:

func setupNonInteractiveWindow(in scene: UIWindowScene) {
  let nonInteractiveWindow = UIWindow(windowScene: scene)

  let controller = UIHostingController(rootView: NonInteractiveView())
  controller.view.backgroundColor = .clear
  nonInteractiveWindow.rootViewController = controller
  nonInteractiveWindow.isHidden = false
  nonInteractiveWindow.isUserInteractionEnabled = false // 👈🏻
  self.nonInteractiveWindow = secondWindow
}

This window would be used exclusively for visualization purposes, and all touches would be ignored and received by the next window in the stack.

Pass through window

Most of the time, we probably want our window to:

• handle user interactions when the interaction touches something shown in that window
• pass the interaction to other windows otherwise

At first, this seems particularly tricky when presenting SwiftUI views, as this UIWindow interactions management is only possible via UIKit's responder chain.

However, there is a way.

In both UIKit and SwiftUI, a view does not receive touches when any of the following conditions is true:

• the view opacity is less than 0.01 (alpha = ... in UIKit):

Button("This button can be tapped") {
  // ...
}

Button("This button also can be tapped") {
  // ...
}
.opacity(0.01)

Button("This button *cannot* be tapped") {
  // ...
}
.opacity(0.001) // 👈🏻

• the view doesn't allow hit testing (isUserInteractionEnabled = false in UIKit):

Button("This button cannot be tapped") {
  // ...
}
.allowsHitTesting(false)

• the view is hidden (isHidden = true in UIKit):

Button("This button cannot be tapped") {
  // ...
}
.hidden()

If no SwiftUI view responds to the user touch, then the containing UIHostingController's (UI)view will.

With these two pieces of information, we can create a UIWindow subclass that handles touches only when anything but the UIHostingController (UI)view is hit:

class PassThroughWindow: UIWindow {
  override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
    // Get view from superclass.
    guard let hitView = super.hitTest(point, with: event) else { return nil }
    // If the returned view is the `UIHostingController`'s view, ignore.
    return rootViewController?.view == hitView ? nil : hitView
  }
}

And this is how we achieve the toast behavior seen at the beginning of the article.

Sharing state between windows

Recommended read: App-wide state in SwiftUI.

From SwiftUI point of view, different windows could be as well as different apps:
they do not share the environment or any other state.

However, at least with UIKit's life-cycle, they have a common starting point: the scene delegate.

We could define a shared state in this delegate, that is then injected to the relevant windows, for example:

class SharedState: ObservableObject {
  ...
}

final class SceneDelegate: UIResponder, UIWindowSceneDelegate {
  lazy var sharedState = SharedState()
  
  var keyWindow: UIWindow?
  var secondaryWindow: UIWindow?

  func scene(
    _ scene: UIScene, 
    willConnectTo session: UISceneSession, 
    options connectionOptions: UIScene.ConnectionOptions
  ) {
    if let windowScene = scene as? UIWindowScene {
      setupKeyWindow(in: windowScene)
      setupSecondaryWindow(in: windowScene)
    }
  }

  func setupKeyWindow(in scene: UIWindowScene) {
    let window = UIWindow(windowScene: scene)
    window.rootViewController = UIHostingController(
      rootView: MainSceneView().environmentObject(sharedState) // 👈🏻 shared state
    )
    self.window = window
    window.makeKeyAndVisible()
  }

  func setupSecondaryWindow(in scene: UIWindowScene) {
    let secondaryViewController = UIHostingController(
      rootView: SecondarySceneView().environmentObject(sharedState) // 👈🏻 shared state
    )
    secondaryViewController.view.backgroundColor = .clear

    let secondaryWindow = PassThroughWindow(windowScene: scene)
    secondaryWindow.rootViewController = secondaryViewController
    secondaryWindow.isHidden = false
    self.secondaryWindow = secondaryWindow
  }
}

Regardless of where changes come from, any change in this shared state will be observed by all windows.

In an app using the SwiftUI life-cycle, things are slightly trickier, as we don't have this common starting point, instead:

1. the App will hold the shared state, which is then injected into the main view
2. the main view will inject the shared state to our scene delegate
3. once injected in the scene delegate, the secondary windows are created, and the state is injected in their views

Both examples with UIKit and SwiftUI life-cycle are provided here.

Conclusions

Layering multiple windows is not something we do very often nowadays. However, it's a need quickly justified even on simple apps (see HUD example above).

As this nearly 1500-words article has shown us, SwiftUI window support is far from ready (FB9018136), but, fortunately, it is achievable by going back to UIKit and work with some knowledge on both UI frameworks.

Do you use multiple windows in your apps? What are your use cases? Please let me know via email or Twitter.

As part of this great and heavily requested enhancement, views such as TextField had to adapt their APIs. Let's dive in.

The shift

Prior to this year's WWDC, TextField initializers followed this pattern:

init(
  _ titleKey: LocalizedStringKey, 
  text: Binding<String>, 
  onEditingChanged: @escaping (Bool) -> Void = { _ in }, 
  onCommit: @escaping () -> Void = {}
)

Where:

• the title was used both as a description and as a placeholder for the view
• text is the main TextField value
• onEditingChanged was called when the TextField gained or lost the focus (the Bool parameter was true when the field gained the focus, false when it lost the focus)
• onCommit triggered when the user submitted (e.g., hit the Return key) while on focus on this specific field

New this year, all former initializers have been deprecated and replaced by new ones:

init(
  _ titleKey: LocalizedStringKey, 
  text: Binding<String>, 
  prompt: Text? = nil
)

Where:

• the title describes the view
• the text is unchanged
• the prompt is used as the field placeholder

To summarize, we have...

• ...gained one parameter, prompt, to disambiguate between the view description and placeholder
• ...lost two parameters, onEditingChanged has been replaced with the new focus API, onCommit has been replaced by the new onSubmit modifier

Let's explore onSubmit next.

As of Xcode 13b4, the new focus APIs are not yet ready (FB9432618), and the TextField documentation still uses the deprecated initializers (FB9438780).

onSubmit definition

For an overview on the new onSubmit modifier and more, check out Submitting values to SwiftUI view by Majid Jabrayilov.

There's only one definition for this modifier:

public func onSubmit(
  of triggers: SubmitTriggers = .text, 
  _ action: @escaping (() -> Void)
) -> some View

The optional triggers parameter lets us define what triggers the given closure:
the current options are either .text (for TextFields and SecureFields) or .search for search submissions via the new searchable(text:placement:) modifier.

// Triggers when text fields submit:

Form {
  TextField(...)
  TextField(...)
}
.onSubmit {
  print("Form submitted")
}

// Triggers when search submits:

NavigationView {
  List {
    ...
  }
  .searchable(text: $text)
  .onSubmit(of: .search) {
    print("Search submitted")
  }
}

SubmitTriggers is an option set: meaning that, theoretically, we could have a single, "catch-all" onSubmit modifier:

.onSubmit(of: [.text, .search]) {
  print("Something has been submitted")
}

Unless we have an unique situation where this is needed, it's preferred to separate the two cases with two different submission closures:

NavigationView {
  Form {
    TextField(...)
    TextField(...)
  }
  .onSubmit {
    print("Form submitted")
  }
  .searchable(text: $text)
  .onSubmit(of: .search) {
    print("Search submitted")
  }
}

onSubmit environment

Behind the scenes, onSubmit adds a TriggerSubmitAction value into the environment. Understanding this is very important: the position and location of the view modifier are fundamental.

For example, this search will trigger the onSubmit closure:

FSView()
 .searchable(text: $text)
 .onSubmit(of: .search) {
   print("Search submitted")
 }

While this one won't:

FSView()
 .onSubmit(of: .search) {
   print("Search submitted")
 }
 .searchable(text: $text)

The explanation lays on the environment:

• in the first example, searchable(...) receives the environment given by onSubmit, which includes the onSubmit closure
• in the latter example, the onSubmit modifier is applied after/underneath the searchable(...) modifier. In this case, the onSubmit closure is not part of searchable(...)'s environment, thus never triggering it

Keeping this in mind, it should be clear what the next example does:

Form {
  TextField("Username", text: $username)
    .onSubmit {
      ...
    }

  SecureField("Password", text: $password)
}

Here onSubmit triggers only when the user submits on the TextField, but not on the SecureField.

To avoid confusion, it's recommended to apply onSubmit on the container (the Form in this example) instead.

This showcases a SwiftUI characteristic that we've explored over and over: SwiftUI never tries to be clever, it always behaves as intended, by doing as little work as possible, for performance reasons.

Unfortunately, this environment value is not exposed to third party developers: the submit action cannot be triggered programmatically (FB9429770).

Cumulative

Similarly to the new safeAreaInset(edge:alignment:spacing:content:) modifier, onSubmit is also cumulative:
if we apply multiple onSubmit modifiers, their closures will all trigger, according to their SubmitTriggers, from outermost to innermost.

For example:

Form {
  TextField(...)
  TextField(...)
  ...
}
.onSubmit {
  print("This will trigger last")
}
.onSubmit {
  print("This will trigger second")
}
.onSubmit {
  print("This will trigger first")
}

EnvironmentValues and closures

SwiftUI already had view modifiers accepting closures before (onAppear for example), however, onSubmit might be the first case where the closure is injected into the environment.

Let's recreate (a simplified version of) the onSubmit modifier ourselves, which can also help us back port the new behavior to older OSes.

First, we need an EnvironmentKey:

struct TriggerSubmitKey: EnvironmentKey {
  static let defaultValue: () -> Void = {}
}

This definition contains the default value of our closure, which is empty.
Alternatively, we could make the definition optional, static let defaultValue: (() -> Void)? = nil, we will use the non-optional variant for simplicity's sake.

Next, we will define the onSubmitAction environment value. As we want to mock SwiftUI's behavior, we will make our closures cumulative and triggering from outermost to innermost:

extension EnvironmentValues {
  public var onSubmitAction: () -> Void {
    get {
      self[TriggerSubmitKey.self]
    } set {
      let oldValue = self[TriggerSubmitKey.self]
      self[TriggerSubmitKey.self] = {
        oldValue()
        newValue()
      }
    }
  }
}

The "magic" happens on the onSubmitAction setter, where we make sure to always trigger both the "old" closure first, and then the new one.

Lastly, we need a new modifier definition, injecting the closure into the environment:

extension View {
  func onSubmit(_ action: @escaping (() -> Void)) -> some View {
    environment(\.onSubmitAction, action)
  }
}

With this, we're now all set to start reading and using our new environment value, for example we could define a new text field or a button that trigger the environment action:

struct SubmitButton<Label: View>: View {
  @Environment(\.onSubmitAction) private var onSubmitAction
  @ViewBuilder var label: Label

  var body: some View {
    Button(action: onSubmitAction) {
      label
    }
  }
}

struct SubmitTextField: View {
  @Environment(\.onSubmitAction) private var onSubmitAction
  let title: LocalizedStringKey
  @Binding var text: String

  init(_ title: LocalizedStringKey, text: Binding<String>) {
    self.title = title
    self._text = text
  }

  var body: some View {
    TextField(title, text: $text, onCommit: onSubmitAction) // 👈🏻 Uses the iOS 13/14 API
  }
}

Here's an example on how we could use them:

struct ContentView: View {
  @State var text = ""

  var body: some View {
    Form {
      SubmitTextField("Name", text: $text)
      SubmitButton {
        Text("Submit form")
      }
    }
    .onSubmit {
      print("Form Submitted")
    }
  }
}

In this example we can submit either when:

• we commit on the text field
• we tap on the button

This is possible because both views, SubmitTextField and SubmitButton, have access to the onSubmitAction environment value. We cannot do this directly with SwiftUI's definition, because SwiftUI's TriggerSubmitAction environment value is not exposed to third party developers, FB9429770.

Conclusions

This year's changes on both view focus and submission are two very welcome quality of life improvements that will allow SwiftUI apps to create new flows that were not possible before (without bridging back to legacy frameworks).

What's your favorite change from this year? Let me know let me know via email or Twitter!

This article is part of a series exploring new SwiftUI features. We will cover many more during the rest of the summer: subscribe to Five Stars's feed RSS or follow @FiveStarsBlog on Twitter to never miss new content!

Bordered Button style updates

A new buttonBorderShape(_:) view modifier has been introduced, replacing the previous BorderedButtonStyle shape parameter:

From:

Button("Tap me") {}
  .buttonStyle(BorderedButtonStyle(shape: .roundedRectangle))

Button("Tap me") {}
  .buttonStyle(BorderedButtonStyle(shape: .capsule))

To:

Button("Tap me") {}
  .buttonStyle(.bordered)
  .buttonBorderShape(.roundedRectangle)

Button("Tap me") {}
  .buttonStyle(.bordered)
  .buttonBorderShape(.capsule)

The new buttonBorderShape(_:) parameter type, ButtonBorderShape, comes with a new roundedRectangle(radius: CGFloat) option, meaning that we can now customize the button radius:

ForEach(1..<6) { index in
  Button("Tap me") {}
    .buttonStyle(.bordered)
    .buttonBorderShape(.roundedRectangle(radius: 4 * Double(index)))
}

As of Xcode 13b4, there's no public API to read the environment BorderedButtonStyle value, FB9413086.

Control prominence updates

The controlProminence(_:) modifier has been deprecated in favor of a new .borderedProminent button style.

From:

Button("Tap me") {}
  .buttonStyle(.bordered)
  .controlProminence(.increased)

To:

Button("Tap me") {}
  .buttonStyle(.borderedProminent)

Prominence is still used used with for (List's) headerProminence(_:) modifier.

controlProminence environment value has not yet been deprecated, FB9413125.

New strikethrough and underline AttributedString styles

AttributeStrings can now further customize the strikethrough and underline lines with a new Text.LineStyle.Pattern type, here are all the new styles:

struct ContentView: View {
  var body: some View {
    HStack {
      VStack {
        Text(strikethroughAttributedString(pattern: .solid))
        Text(strikethroughAttributedString(pattern: .dot))
        Text(strikethroughAttributedString(pattern: .dash))
        Text(strikethroughAttributedString(pattern: .dashDot))
        Text(strikethroughAttributedString(pattern: .dashDotDot))
      }

      VStack {
        Text(underlineAttributedString(pattern: .solid))
        Text(underlineAttributedString(pattern: .dot))
        Text(underlineAttributedString(pattern: .dash))
        Text(underlineAttributedString(pattern: .dashDot))
        Text(underlineAttributedString(pattern: .dashDotDot))
      }
    }
  }

  private func strikethroughAttributedString(
    pattern: Text.LineStyle.Pattern
  ) -> AttributedString {
    var attributedString = AttributedString("Strikethrough")
    attributedString.strikethroughStyle = .init(pattern: pattern, color: .red)
    return attributedString
  }

  func underlineAttributedString(
    pattern: Text.LineStyle.Pattern
  ) -> AttributedString {
    var attributedString = AttributedString("Underline")
    attributedString.underlineStyle = .init(pattern: pattern, color: .red)
    return attributedString
  }
}

With this update, AttributedString's strikethroughColor and underlineColor have been deprecated.

Text field auto capitalization gains a full-SwiftUI modifier

SwiftUI's autocapitalization(_:) is now deprecated in favor of a new textInputAutocapitalization(_:) modifier.

From:

TextField("All characters auto capitalization", text: $text)
  .autocapitalization(.allCharacters)

To:

TextField("All characters auto capitalization", text: $text)
  .textInputAutocapitalization(.characters)

The new modifier uses a new TextInputAutocapitalization SwiftUI struct:

struct TextInputAutocapitalization {
  /// Defines an autocapitalizing behavior that will not capitalize anything.
  public static var never: TextInputAutocapitalization { get }

  /// Defines an autocapitalizing behavior that will capitalize the first
  /// letter of every word.
  public static var words: TextInputAutocapitalization { get }

  /// Defines an autocapitalizing behavior that will capitalize the first
  /// letter in every sentence.
  public static var sentences: TextInputAutocapitalization { get }

  /// Defines an autocapitalizing behavior that will capitalize every letter.
  public static var characters: TextInputAutocapitalization { get }
}

While the deprecated modifier used UIKit's UITextAutocapitalizationType:

public enum UITextAutocapitalizationType : Int {
  case none = 0
  case words = 1
  case sentences = 2
  case allCharacters = 3
}

Documentation

We have a lot more documentation for:

• Task view modifiers
• AccessibilityChildBehavior properties (combine, ignore, contain)

Conclusions

Did you find anything else interesting in Xcode 13 beta 4? Please let me know!

As always, please report any issue to Apple: we're still months away from the official release, things can and will be fixed, as long as we report them.

This article is part of a series exploring new SwiftUI features. We will cover many more during the rest of the summer: subscribe to Five Stars's feed RSS or follow @FiveStarsBlog on Twitter to never miss new content!

New in Xcode 13 beta 3, most of those extensions are no longer needed: the SwiftUI team back-ported this pattern for us. How is it possible? Let's find out.

The change

Prior to Xcode 13 beta 3, the new pattern was limited to the newly announced OSes, for example:

@available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *) // 👈🏻
extension Section where Parent: View, Content: View, Footer: View {
  public init(
    @ViewBuilder content: () -> Content, 
    @ViewBuilder header: () -> Parent, 
    @ViewBuilder footer: () -> Footer
  )
}

New in Xcode 13 beta 3, those definitions are now available to all OSes supporting SwiftUI:

@available(iOS 13.0, macOS 10.15, tvOS 13.0, watchOS 6.0, *) // 👈🏻
extension Section where Parent: View, Content: View, Footer: View {
  public init(
    @ViewBuilder content: () -> Content, 
    @ViewBuilder header: () -> Parent, 
    @ViewBuilder footer: () -> Footer
  )
}

Older OSes did not magically learn the new pattern: once the OS is shipped, the system framework capabilities for that OS are sealed and cannot be changed (strictly speaking, this is mostly true).

This is all we get from SwiftUI's headers. Let's dig deeper.

Swift Interfaces and ABI stability

A core part of Swift's ABI stability is Module Stability, which lets apps use libraries/frameworks even when compiled with different Swift versions.

On top of Module Stability, we have Library Evolution, which lets libraries change while remaining binary-compatible with previous versions.

For app developers, all of this comes down to library Swift interfaces, also known as .swiftinterface file(s), and what's declared on them.

System frameworks Swift interfaces

Xcode always comes with Apple's OSes framework binaries, including SwiftUI's, which also contains the .swiftinterface files mentioned above.

The location might vary, currently it's Xcode.app/Contents/Developer/Platforms/YOUR_PLATFORM_HERE.platform/Developer/SDKs/YOUR_PLATFORM_HERE.sdk/System/Library/Frameworks/

Continuing with SwiftUI's Section example, prior to Xcode 13 beta 3, the Swift interface declared:

@available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)
extension Section where Parent: View, Content: View, Footer: View {
  public init(
    @ViewBuilder content: () -> Content, 
    @ViewBuilder header: () -> Parent, 
    @ViewBuilder footer: () -> Footer
  )
}

Which translates 1-1 to what we see in SwiftUI's headers.

From Xcode 13 beta 3, the previous definition becomes:

@available(iOS 13.0, macOS 10.15, tvOS 13.0, watchOS 6.0, *)
extension Section where Parent: View, Content: View, Footer: View {
  @_alwaysEmitIntoClient
  public init(
    @ViewBuilder content: () -> Content, 
    @ViewBuilder header: () -> Parent, 
    @ViewBuilder footer: () -> Footer
  ) {
    self.init(header: header(), footer: footer(), content: content)
  }
}

We have two significant changes, the initializer...

• ... comes with its complete implementation
• ... is associated with the @_alwaysEmitIntoClient attribute

Going back to Swift's Module Stability and Library Evolution, this definition is possible because it's entirely additive:

• the new initializer is a convenience initializer, using another public initializer, which has been available since iOS 13 (and equivalent in other platforms)
• since the interface exposes the complete implementation, we can now use this new API even in older OSes

All of this is possible thanks to the @_alwaysEmitIntoClient attribute.

@_alwaysEmitIntoClient

The underscore prefix means that this attribute hasn't gone through Swift Evolution just yet.

From what we know so far, it looks like @_alwaysEmitIntoClient is similar to @inlinable, which also exposes the associated implementation as part of the module’s public interface (regardless of whether the declaration is public or internal).

There are two major differences between @_alwaysEmitIntoClient and @inlinable:

• an @inlinable declaration is part of the library binary. Removing an @inlinable symbol is both a binary-breaking and a source-breaking change
• the compiler is allowed to replace calls to an @inlinable symbol with a copy of the symbol’s implementation at call site

On the contrary:

• an @_alwaysEmitIntoClient declaration is never part of a library binary. Removing a @_alwaysEmitIntoClient symbol is a binary-compatible and source-breaking change
• an @_alwaysEmitIntoClient implementation will always get copied into the client (e.g., an app) binary

This last point explains why using @_alwaysEmitIntoClient allows back-porting new definitions to older OSes:
it's not the framework that has the new capabilities. It's the app that brings them within its binary.

There are a few drawbacks with this approach:

• @_alwaysEmitIntoClient code that’s compiled into apps cannot be improved/fixed via OS updates. The only way to update those is for the app to be rebuilt with a newer @_alwaysEmitIntoClient implementation
• @_alwaysEmitIntoClient brings unnecessary code size bloat, as these implementations, again, are never part of the library binary and must come within the app binaries using them, even on future OSes
• @_alwaysEmitIntoClient does not work with new types

It's up to the library maintainers to decide whether the trade-off is worth it.

Beside for view builders, among others, SwiftUI also uses @_alwaysEmitIntoClient in all the new styles declaration, allowing us to use .toggleStyle(.switch) instead of the legacy .toggleStyle(SwitchToggleStyle()) even when targeting iOS 13 (and equivalent in other platforms).

Conclusions

We've seen how binary frameworks can make additive changes to their API while remaining binary-compatible with previous versions:
SwiftUI uses this pattern quite a bit (there are 282 @_alwaysEmitIntoClient matches in Xcode 13b3 SwiftUI interface), have you spotted @_alwaysEmitIntoClient elsewhere? Please let me know via email or Twitter!

More specifically, the crash happened when we used @EnvironmentObject inside our styles definition: when is it safe to use them together? Let's find out.

For the impatients, the results are at the end of the article.

An example

Meet FSStyle, a button style expecting an environment object (FSEnvironmentObject):

class FSEnvironmentObject: ObservableObject {
  @Published var title = "tap me"
}

struct FSStyle: ButtonStyle {
  @EnvironmentObject var object: FSEnvironmentObject

  func makeBody(configuration: Configuration) -> some View {
    Button(object.title) { }
  }
}

For an introduction to Buttons styles, see Exploring SwiftUI's Button styles and Meet the new Button styling.

From this definition, we'd expect things to work as long as we inject the environment object at some point before applying the style. For example:

struct ContentView: View {
  @StateObject var object = FSEnvironmentObject()

  var body: some View {
    Button("tap me") {
    }
    .buttonStyle(FSStyle())
    .environmentObject(object)
  }
}

..and yet, if we ran this code in any iOS version before 14.5, it reliably crashed 100% of the times, with Fatal error: No ObservableObject of type FSEnvironmentObject found..

The crash occurs as soon as the environment object is used within the makeBody(configuration:) method, both the object definition and makeBody(configuration:) implementation don't matter.

The main two workarounds are either to make the style conform to DynamicProperty (many thanks to Lin Qing Mo for letting me know!), or to return a view in the makeBody(configuration:) method, and have that view read the environment object.

Now that we've seen what the issue is, let's explore in which iOS versions and styles this crash occurs.

The test setup

We want to figure out in which iOS versions is safe to use all the possible styles (not just button styles). We can create a small test app and run it throughout all iOS versions supporting SwiftUI and report back.

Continuing with the ButtonStyle example, here's the complete app:

import UIKit
import SwiftUI

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate { }

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
  var window: UIWindow?
  var object: FSEnvironmentObject = FSEnvironmentObject()

  func scene(
    _ scene: UIScene, 
    willConnectTo session: UISceneSession, 
    options connectionOptions: UIScene.ConnectionOptions
  ) {
    if let windowScene = scene as? UIWindowScene {
      let window = UIWindow(windowScene: windowScene)
      let contentView = ContentView().environmentObject(object)
      window.rootViewController = UIHostingController(rootView: contentView)
      self.window = window
      window.makeKeyAndVisible()
    }
  }
}

struct ContentView: View {
  var body: some View {
    Button("tap me") {
    }
    .buttonStyle(FSStyle())
  }
}

struct FSStyle: ButtonStyle {
  @EnvironmentObject var object: FSEnvironmentObject

  func makeBody(configuration: Configuration) -> some View {
    Button(object.title) { }
  }
}

class FSEnvironmentObject: ObservableObject {
  @Published var title = "tap me"
}

The app consists of one screen, which contains our test component/style.

A few points:

• we're using UIKit's lifecycle because we want to run the tests with iOS 13 as well
• we're don't use @StateObject for the environment object because that property wrapper is iOS 14+ only
• the only difference between testing ButtonStyle and other styles is in the FSStyle and ContentView body definition, everything else stays the same

CI/CD Setup

We will be testing twelve iOS versions, from iOS 13.0 to iOS 14.5, and all eight styles that support customization.

Testing each combination manually would be quite a lot of work, instead, we can let a CI/CD provider do all the heavy lifting for us. Any CI/CD setup will do, here's how the various Xcode/iOS versions where distributed for this study:

• macOS 10.14
  • iOS 13.0, Xcode 11.0
  • iOS 13.1, Xcode 11.1
  • iOS 13.2, Xcode 11.2

• macOS 10.15
  • iOS 13.3, Xcode 11.3.1
  • iOS 13.4, Xcode 11.4.1
  • iOS 13.5, Xcode 11.5
  • iOS 13.6, Xcode 11.6
  • iOS 13.7, Xcode 11.7
  • iOS 14.0, Xcode 12.0.1
  • iOS 14.1, Xcode 12.1
  • iOS 14.2, Xcode 12.2
  • iOS 14.3, Xcode 12.3

• macOS 11.4:
  • iOS 14.4, Xcode 12.4
  • iOS 14.5, Xcode 12.5

Results

As the test app only has one screen that shows immediately the tested component, all it's needed to pass the test is launching the app and not crash right away. Here is the outcome:

💥 = crash, ✅ = pass. *Style available from iOS 14.

To recap:

• all styles but ButtonStyle support @EnvironmentObject from iOS 14.0
• from iOS 14.5, all styles including ButtonStyle support @EnvironmentObject

Conclusions

The reason why the styles + @EnvironmentObject combo was not supported from the beginning will probably remain within the SwiftUI team, however it could have been intentional:
looking at the way SwiftUI stock styles are applied, besides a few parameters passed via the Configuration, most moving parts come from EnvironmentValues, e.g. @Environment(\.isEnabled), @Environment(\.font), and @Environment(\.controlProminence).

Unlike @EnvironmentObject, EnvironmentValues are supported (without 💥!) from iOS 13.0, and it's the way I also recommend going when adding dynamic to our custom styles.

Regardless of whether this was a bug or by design, as an SDK vendor, it's up to us to disambiguate and clarify such scenarios to developers.
As far as I know, this was not documented anywhere, nor was addressed on any release note: if developers misused it, it's on the framework.

Another place where this could have been an issue are view modifiers, however both EnvironmentValues and @EnvironmentObject are supported (without 💥) from iOS 13.0.

Are there any other SwiftUI feature where you've experience similar unexpected behaviors? I have the test setup from this article ready to go: feel free to reach out via email or Twitter, I will be happy to run tests for your case!

Shape style erasing with AnyShapeStyle

/// A type-erased ShapeStyle value.
@available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)
@frozen public struct AnyShapeStyle : ShapeStyle {
  /// Create an instance from `style`.
  public init<S>(_ style: S) where S : ShapeStyle
}

While we have @ViewBuilder to build advanced views, the same cannot be said for shapes. Until today, offering different shape styles meant defining multiple times the same view with different shape styles.

New from this beta seed, we have AnyShapeStyle, which makes our life easier:

struct ContentView: View {
  @State private var isAngular = false

  var body: some View {
    ZStack {
      Rectangle()
        .fill(shapeStyle)
        .ignoresSafeArea()
      Button(isAngular ? "Angular" : "Linear") { isAngular.toggle() }
        .buttonStyle(.bordered)
        .controlProminence(.increased)
    }
  }

  var shapeStyle: some ShapeStyle {
    let gradient: Gradient = Gradient(colors: [.red, .pink, .purple])
    if isAngular {
      return AnyShapeStyle(.conicGradient(gradient, center: .center)) // 👈🏻
    } else {
      return AnyShapeStyle( // 👈🏻
        LinearGradient(gradient: gradient, startPoint: .leading, endPoint: .trailing)
      )
    }
  }
}

Maybe we can get a @ShapeStyleBuilder next? 🙏🏻 FB9331755

Styles re-organization with HierarchicalShapeStyle

We have a new HierarchicalShapeStyle, used for all the .primary, .secondary, etc styles. Previously each one of these styles had their own style, e.g. QuaternaryContentStyle for .quaternary.

All the old styles have been deprecated and will likely be removed in an upcoming beta seed.

From:

extension ShapeStyle where Self == PrimaryContentStyle {
  public static var primary: PrimaryContentStyle { get }
}

extension ShapeStyle where Self == SecondaryContentStyle {
  public static var secondary: SecondaryContentStyle { get }
}

...

To:

extension ShapeStyle where Self == HierarchicalShapeStyle {
  public static var primary: HierarchicalShapeStyle { get }
  public static var secondary: HierarchicalShapeStyle { get }
  public static var tertiary: HierarchicalShapeStyle { get }
  public static var quaternary: HierarchicalShapeStyle { get }
}

Angular Gradient convenience initializers

Angular gradients have gained new static convenience initializers (available from iOS 13 and later):

extension ShapeStyle where Self == AngularGradient {
  public static func conicGradient(
    _ gradient: Gradient, center: UnitPoint, angle: Angle = .zero
  ) -> AngularGradient

  public static func conicGradient(
    colors: [Color], center: UnitPoint, angle: Angle = .zero
  ) -> AngularGradient

  public static func conicGradient(
    stops: [Gradient.Stop], center: UnitPoint, angle: Angle = .zero
  ) -> AngularGradient
}

For an example on this, go back to the AnyShapeStyle example, I've sneaked one of those in there 😜

keyboardShortcut environment value

struct ContentView: View {
  var body: some View {
    VStack {
      Button("Tap me or press ⌘F") {
        print("tapped or pressed")
      }
      .keyboardShortcut("F", modifiers: [.command])

      Button("Tap me or press ⌘S") {
        print("tapped or pressed")
      }
      .keyboardShortcut("S", modifiers: [.command])
    }
    .buttonStyle(FiveStarsButtonStyle())
  }
}

private struct FiveStarsButtonStyle: ButtonStyle {
  @Environment(\.keyboardShortcut) private var shortcut: KeyboardShortcut? // 👈🏻

  func makeBody(configuration: Configuration) -> some View {
    configuration.label
      .font(.body.weight(shortcut == .init("F") ? .heavy : .regular))
  }
}

Xcode 13 Beta 3 introduces new \.keyboardShortcut environment value, letting us read the assigned keyboard shortcut to any view. We can use this value as we please, for example to customize the appearance of a button.

More compact TimelineView definitions

Similar to styles, the SwiftUI team is pushing us to use the more compact syntax for the new TimelineView.

From Xcode 13b3, this generates a deprecation warning:

TimelineView(EveryMinuteTimelineSchedule()) { context in
  Text(context.date.description)
}

Where the recommended way is:

TimelineView(.everyMinute) { context in
  Text(context.date.description)
}

View builders backport

In SwiftUI patterns evolution: view builders we've covered a new emerging SwiftUI pattern from this year, at the end of the article we've seen how it was relatively easy to create extensions back-porting said pattern to previous versions OSes.

Thanks to this new beta seed, most of these extensions are no longer needed, as SwiftUI backports these new initializers view modifiers all the way to iOS 13 (and equivalent on other platforms).

For example, we went from:

@available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *) // 👈🏻
extension Section where Parent : View, Content : View, Footer : View {
  public init(
    @ViewBuilder content: () -> Content, 
    @ViewBuilder header: () -> Parent, 
    @ViewBuilder footer: () -> Footer
  )
}

To:

@available(iOS 13.0, macOS 10.15, tvOS 13.0, watchOS 6.0, *) // 👈🏻
extension Section where Parent : View, Content : View, Footer : View {
  public init(
    @ViewBuilder content: () -> Content, 
    @ViewBuilder header: () -> Parent, 
    @ViewBuilder footer: () -> Footer
  )
}

Documentation

We have a lot more documentation for:

• AsyncImage
• AngularGradient

Conclusions

Did you find anything else interesting in Xcode 13 beta 3? Please let me know!

As always, please report any issue to Apple: we're still months away from the official release, things can and will be fixed, as long as we report them.

This article is part of a series exploring new SwiftUI features. We will cover many more during the rest of the summer: subscribe to Five Stars's feed RSS or follow @FiveStarsBlog on Twitter to never miss new content!

Fast forward one year later, and SwiftUI has a brand new life-cycle, dropping both UIKit's app and scene delegates entirely. Here's what's left:

@main
struct FSApp: App {
  var body: some Scene {
    WindowGroup {
      ContentView()
    }
  }
}

While the SwiftUI team keeps moving forward at a neck-breaking speed, not all third party libraries and, admittedly, not even all Apple's API, are ready for the big shift:
to this day, many APIs still require either an AppDelegate or an UIScene to operate.

Does it mean that we can't use the new SwiftUI life-cycle? No! The SwiftUI team has thought about these scenarios and provided us with the right tools. Let's dig in.

Add an app delegate to a SwiftUI app

Along with the new SwiftUI life-cycle, the @UIApplicationDelegateAdaptor property wrapper has been introduced, letting us associate an app delegate to a SwiftUI app.

First, let's define our UIApplicationDelegate:

class FSAppDelegate: NSObject, UIApplicationDelegate {
  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
  ) -> Bool {
    // ...
    return true
  }
}

Then we can add it to our App:

@main
struct FSApp: App {
  @UIApplicationDelegateAdaptor var delegate: FSAppDelegate 

  var body: some Scene {
    WindowGroup {
      ContentView()
    }
  }
}

SwiftUI will both initialize and manage our delegate lifetime. No further work is necessary.

App delegate access via the environment

Environment is one of the most powerful SwiftUI features, if we conform our app delegate to ObservableObject, it will be accessible anywhere in our app:

class FSAppDelegate: NSObject, UIApplicationDelegate, ObservableObject { // 👈🏻
  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
  ) -> Bool {
    // ...
    return true
  }

  // ...
}

With just this change, we can access our app delegate like any other environment object:

struct ContentView: View {
  @EnvironmentObject var appDelegate: FSAppDelegate
  
  var body: some View {
    Button("Tap me") {
      // appDelegate. ...
    }
  }
}

We didn't have to inject the app delegate ourselves.

Besides receiving the app life-cycle events, we can add to our app delegate any @Published properties, and views depending on it will produce a new body whenever changes are published, for example:

class FSAppDelegate: NSObject, UIApplicationDelegate, ObservableObject {
  @Published var date: Date = .now // 👈🏻

  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
  ) -> Bool {
    // 👇🏻 Publishes every second
    Timer
      .publish(every: 1, on: .main, in: .default)
      .autoconnect()
      .assign(to: &$date)
    return true
  }
}

struct ContentView: View {
  @EnvironmentObject var appDelegate: FSAppDelegate // 👈🏻
  
  var body: some View {
    Text(appDelegate.date.formatted(date: .omitted, time: .standard))
  }
}

Add a scene delegate to a SwiftUI app

Similar to app delegate, some legacy APIs require access to the UIWindowSceneDelegate or to the UIScene in general.

We have mainly two ways to add a scene delegate to our app. Let's create the delegate:

class FSSceneDelegate: NSObject, UIWindowSceneDelegate {
  func sceneWillEnterForeground(_ scene: UIScene) {
    // ...
  }

  func sceneDidBecomeActive(_ scene: UIScene) {
    // ...
  }

  func sceneWillResignActive(_ scene: UIScene) {
    // ...
  }

  // ...
}

The first way is via our app delegate, thanks to the application(_:configurationForConnecting:options:) method, which lets us return a new UISceneConfiguration, where we can also declare the scene delegate class:

class FSAppDelegate: NSObject, UIApplicationDelegate {

  func application(
    _ application: UIApplication,
    configurationForConnecting connectingSceneSession: UISceneSession,
    options: UIScene.ConnectionOptions
  ) -> UISceneConfiguration {
    let sceneConfig = UISceneConfiguration(name: nil, sessionRole: connectingSceneSession.role)
    sceneConfig.delegateClass = FSSceneDelegate.self // 👈🏻
    return sceneConfig
  }
}

With this change, our scene delegate will start receiving all the scene events.

The second way, which doesn't require an app delegate, is via the main app info.plist, where we can update the Application Scene Manifest:

<dict>
  <key>UISceneConfigurations</key>
  <dict>
    <key>UIWindowSceneSessionRoleApplication</key>
    <array>
      <dict>
        <key>UISceneDelegateClassName</key>
        <string>$(PRODUCT_MODULE_NAME).FSSceneDelegate</string>
      </dict>
    </array>
  </dict>
  <key>UIApplicationSupportsMultipleScenes</key>
  <true/>
</dict>

The most crucial bit is the Delegate Class Name definition, a.k.a. the value of key UISceneDelegateClassName, where we specify the scene delegate to be used.

Once this is set, our scene delegate will start receiving all the scene events.

If we implement both ways, the app delegate approach takes priority.

Scene delegate access via the environment

Regardless of which we way we use, like for app delegate, if we make our scene delegate conform to ObservableObject, it will automatically be injected in SwiftUI's environment:

class FSSceneDelegate: NSObject, UIWindowSceneDelegate, ObservableObject { // 👈🏻
  func sceneWillEnterForeground(_ scene: UIScene) {
    // ...
  }

  // ...
}

Exactly like for the app delegate, we can add dynamic properties and publish things, and all views depending on it will update accordingly:

class FSSceneDelegate: NSObject, UIWindowSceneDelegate, ObservableObject {
  @Published var date: Date = .now // 👈🏻

  func scene(
    _ scene: UIScene,
    willConnectTo session: UISceneSession,
    options connectionOptions: UIScene.ConnectionOptions
  ) {
    // 👇🏻 Publishes every second
    Timer
      .publish(every: 1, on: .main, in: .default)
      .autoconnect()
      .assign(to: &$date)
  }
}

struct ContentView: View {
  @EnvironmentObject var sceneDelegate: FSSceneDelegate // 👈🏻
  
  var body: some View {
    Text(sceneDelegate.date.formatted(date: .omitted, time: .standard))
  }
}

This delegate will have its separate UISceneSession, meaning that we won't get access to SwiftUI's @SceneStorage storage.

To be clear, it's completely fine having a view depending on both delegates:

struct FSView: View {
  @EnvironmentObject var appDelegate: FSAppDelegate
  @EnvironmentObject var sceneDelegate: FSSceneDelegate

  var body: some View {
    ...
  }
}

Conclusions

Since SwiftUI's introduction, one of its flagship features has been compatibility with previous UI frameworks:

• Is something not available in SwiftUI yet? A collection of Representable protocols will help you fill in the gap (UIViewRepresentable, NSViewRepresentable, WKInterfaceObjectRepresentable, ...).

• Does something still require an app delegate or an UIScene (looking at you, SKStoreReviewController, FB9301675)? @UIApplicationDelegateAdaptor and the Scene Manifest have you covered.

As time passes, we will reach for these fallbacks less and less. Until then, we're glad they're here.

Where do you find yourself going back to UIKit/AppKit/WatchKit? Let me know via email or Twitter!

This year Buttons has gained new powerful customization tools; Let's see how we can take advantage of them in our styles.

Groundwork

This article assumes some knowledge on SwiftUI buttons and styles in general:

• for an overview of what's new this year, see The many faces of button in SwiftUI by Majid Jabrayilov
• for a deep dive into Button styling, see Exploring SwiftUI's Button styles
• for a guide on how to create styles for custom views, see Custom SwiftUI view styles

Meet FiveStarsButtonStyle

We're going to create our own button style that takes advantage of all the new Xcode 13 features, meet FiveStarsButtonStyle:

struct FiveStarsButtonStyle: ButtonStyle {
  func makeBody(configuration: Configuration) -> some View {
    configuration
      .label
      .opacity(configuration.isPressed ? 0.5 : 1)
  }
}

What's new in SwiftUI told us that there's a new way to apply styles:

• the old approach, e.g. Button(...).buttonStyle(PlainButtonStyle()), has been deprecated
• the new approach, e.g. Button(...).buttonStyle(.plain), is more succinct and to the point

Let's make it possible to use our style with the new API:

extension ButtonStyle where Self == FiveStarsButtonStyle {
  static var fiveStars: FiveStarsButtonStyle {
    FiveStarsButtonStyle()
  }
}

Great! We can now apply our style like any other, with the new modern API:

Button("Tap me") { 
  ...
}
.buttonStyle(.fiveStars)

Roles

From this year, buttons can be associated with a ButtonRole. Like Button's title and action, role is assigned via parameter instead of being passed down via the environment. Here are all the possible values (as of Xcode 13b2):

Button("No role", role: nil) { ... } // default, equivalent to Button("No role") { ... }
Button("Cancel role", role: .cancel) { ... }
Button("Destructive role", role: .destructive) { ... }

We can take advantage of this role in our style via the new ButtonStyleConfiguration role property:

public struct ButtonStyleConfiguration {
  public let role: ButtonRole? // 👈🏻
  public let label: ButtonStyleConfiguration.Label
  public let isPressed: Bool
}

role is the first property that has been added to both ButtonStyleConfiguration and PrimitiveButtonStyleConfiguration since their launch.

For example:

struct FiveStarsButtonStyle: ButtonStyle {
  func makeBody(configuration: Configuration) -> some View {
    configuration
      .label
      .padding(.horizontal)
      .padding(.vertical)
      .foregroundColor(foregroundColor(for: configuration.role))
      .background {
        RoundedRectangle(cornerRadius: 8)
          .strokeBorder(color(for: configuration.role), lineWidth: 2)
      }
      .opacity(configuration.isPressed ? 0.5 : 1)
  }

  func foregroundColor(for role: ButtonRole?) -> Color? {
    role == .destructive ? .red : nil
  }

  func color(for role: ButtonRole?) -> Color {
    switch role {
      case .cancel?, .destructive?:
        return Color.red
      default:
        return Color.accentColor
    }
  }
}

Control size

From Xcode 13 we also have the possibility to declare the size of our controls, this is done via a new controlSize(_:) modifier:

Button("Mini") { ... }
  .controlSize(.mini)
Button("Small") { ... }
  .controlSize(.small)
Button("Regular") { ... }
  .controlSize(.regular) // default
Button("Large") { ... }
  .controlSize(.large)

The ControlSize value is then passed down through the environment, which we can read and use in our style:

struct FiveStarsButtonStyle: ButtonStyle {
  @Environment(\.controlSize) var controlSize: ControlSize // 👈🏻

  func makeBody(configuration: Configuration) -> some View {
    configuration
      .label
      .frame(maxWidth: controlSize == .large ? .infinity : nil)
      .padding(.horizontal, horizontalPadding)
      .padding(.vertical, verticalPadding)
      .foregroundColor(foregroundColor(for: configuration.role))
      .background {
        RoundedRectangle(cornerRadius: 8)
          .strokeBorder(color(for: configuration.role), lineWidth: 2)
      }
      .opacity(configuration.isPressed ? 0.5 : 1)
  }

  var horizontalPadding: Double {
    switch controlSize {
      case .mini:
        return 8
      case .small:
        return 16
      case .regular:
        return 32
      case .large:
        return 0 // no need.
      @unknown default:
        return 0
    }
  }

  var verticalPadding: Double {
    switch controlSize {
      case .mini:
        return 2
      case .small:
        return 4
      case .regular:
        return 8
      case .large:
        return 16
      @unknown default:
        return 0
    }
  }

  func foregroundColor(for role: ButtonRole?) -> Color? {
    ...
  }

  func color(for role: ButtonRole?) -> Color {
    ...
  }
}

Control prominence

Similar to control size, we also have control prominence, which lets us further emphasize/highlight our buttons:

Button("Standard") { ... }
  .controlProminence(.standard) // default
Button("Increased") { ... }
  .controlProminence(.increased)

We use the environment to retrieve the Prominence value:

struct FiveStarsButtonStyle: ButtonStyle {
  @Environment(\.controlSize) var controlSize: ControlSize
  @Environment(\.controlProminence) var controlProminence: Prominence // 👈🏻

  func makeBody(configuration: Configuration) -> some View {
    configuration
      .label
      .frame(maxWidth: controlSize == .large ? .infinity : nil)
      .padding(.horizontal, horizontalPadding)
      .padding(.vertical, verticalPadding)
      .foregroundColor(foregroundColor(for: configuration.role))
      .background {
        backgroundColor(for: configuration.role).cornerRadius(8)
        if let borderColor = borderColor(for: configuration.role) {
          RoundedRectangle(cornerRadius: 8)
            .strokeBorder(borderColor, lineWidth: 2)
        }
      }
      .opacity(configuration.isPressed ? 0.5 : 1)
  }

  var horizontalPadding: Double {
    ...
  }

  var verticalPadding: Double {
    ...
  }

  func foregroundColor(for role: ButtonRole?) -> Color? {
    switch (controlProminence, role) {
      case (.standard, .destructive?):
        return .red
      case (.increased, .destructive?):
        return .white
      case (.increased, _):
        return .black
      case (_, _):
        return nil
    }
  }

  func backgroundColor(for role: ButtonRole?) -> Color? {
    switch controlProminence {
      case .increased:
        return color(for: role)
      case .standard:
        fallthrough
      @unknown default:
        return nil
    }
  }

  func color(for role: ButtonRole?) -> Color {
    switch role {
      case .cancel?, .destructive?:
        return Color.red
      default:
        return Color.accentColor
    }
  }

  func borderColor(for role: ButtonRole?) -> Color? {
    switch controlProminence {
      case .standard:
        return color(for: role)
      case .increased:
        fallthrough
      @unknown default:
        return nil
    }
  }
}

Passing parameters

With the old API, it was easy to pass parameters to our styles. Let's say that we want to add a cornerRadius parameter to our style, to be used for the round corners:

struct FiveStarsButtonStyle: ButtonStyle {
  let cornerRadius: Double
  ...
}

With our new modern declaration, this is not possible:

extension ButtonStyle where Self == FiveStarsButtonStyle {
  static var fiveStars: FiveStarsButtonStyle {
    FiveStarsButtonStyle() // 👈🏻 we need to pass our cornerRadius here
  }
}

However, no body forbids us to further expand this extension and declare a static function:

extension ButtonStyle where Self == FiveStarsButtonStyle {
  static func fiveStars(cornerRadius: Double = 8) -> FiveStarsButtonStyle {
    FiveStarsButtonStyle(cornerRadius: cornerRadius)
  }
}

Which we can use as following:

Button("Radius 12") { 
  ...
}
.buttonStyle(.fiveStars(cornerRadius: 12))

Button("Default radius") { 
  ...
}
.buttonStyle(.fiveStars())

Since we have a default value, we can even keep the original static property:

extension ButtonStyle where Self == FiveStarsButtonStyle {
  static func fiveStars(cornerRadius: Double = 8) -> FiveStarsButtonStyle {
    FiveStarsButtonStyle(cornerRadius: cornerRadius)
  }

  static var fiveStars: FiveStarsButtonStyle {
    fiveStars()
  }
}

Which lets us use the more compact API when we want to use the default behavior:

Button("Tap me") { 
  ...
}
.buttonStyle(.fiveStars(cornerRadius: 12))

Button("Tap me") { 
  ...
}
.buttonStyle(.fiveStars) // 👈🏻

An alternative approach is to use environment values, in FiveStarsButtonStyle we're using Color.accentColor for example, if we'd like to change that value, we can do so via the accentColor(_:) modifier:

Button("Default accent") { 
  ...
}
.buttonStyle(.fiveStars)
.controlProminence(.increased)

Button("Purple accent") { 
  ...
}
.buttonStyle(.fiveStars)
.accentColor(.purple) // 👈🏻
.controlProminence(.increased)

.accentColor(_:) has been deprecated in favor of the new tint(_:) modifier. However, as of Xcode 13b2, it doesn't work as expected (FB9248929).

Etcetera

So far, FiveStarsButtonStyle only considers the new Xcode 13 SwiftUI additions. However, there's more that we can take care of, such as dynamic types, isEnabled state, platform-specific styles, etc.

Reminder: just because we have these powerful tools at our disposal, it doesn't mean that we have to support them all in our apps/styles. Add support to what makes sense to your product(s).

A more complete example is available here.

Conclusions

We built a reasonably advanced style with dynamics based on the button definition, environment values, etc. However, when it's time to use it, all we have to do is call .buttonStyle(.fiveStars).

This whole complexity becomes an implementation detail hidden behind a style name: developers using our style don't need to worry about any of that, and the goal is beautifully achieved thanks to SwiftUI styles.

Do you use custom styles in your apps? Are you going to take advantage of the new roles and control properties? Let me know via email or Twitter!

This article is part of a series exploring new SwiftUI features. We will cover many more during the rest of the summer: subscribe to Five Stars's feed RSS or follow @FiveStarsBlog on Twitter to never miss new content!

Generic views

In SwiftUI patterns: passing & accepting views we've explored how SwiftUI accepts views to embed within other views.
One of the main ways was accepting a generic view, used for example in Section's header and footer parameters:

extension Section where Parent: View, Content: View, Footer: View {

  /// Creates a section with a header, footer, and the provided section content.
  /// - Parameters:
  ///   - header: A view to use as the section's header.
  ///   - footer: A view to use as the section's footer.
  ///   - content: The section's content.
  public init(header: Parent, footer: Footer, @ViewBuilder content: () -> Content)
}

To be used as:

Section(
  header: Text("This is a header"), 
  footer: Text("This is a footer")
) {
  // section content
}

The original idea of this API was probably to indicate that Section expects a single simple view for those parameters. However, this limitation was easily bypassed, for example by using a Group or another view:

Section(
  header: Group {
    Text("This is not a simple header")
    ForEach(1..<100) { _ in
      Text("Five")
    }
  }, 
  footer: Group {
    Text("This is not a simple footer")
    ForEach(1..<100) { _ in
      Text("Stars")
    }
  }
) {
  // section content
}

// or 

Section(
  header: VeryComplicatedViewAsHeader(), 
  footer: VeryComplicatedViewAsFooter()
) {
  // section content
}

Moreover, accepting a generic view made things awkward in case we wanted to "just" add a condition:

Section(
  header: Group {
    if shouldShowHeader {
      Text("This is a header")
    }
  },
  footer: Text("This is a footer")
) {
  // section content
}

New this year, all APIs accepting a generic view parameter have been deprecated in favor of new alternatives using view builders:

@available(iOS 15.0, macOS 12.0, tvOS 15.0, watchOS 8.0, *)
extension Section where Parent: View, Content: View, Footer: View {

  /// Creates a section with a header, footer, and the provided section
  /// content.
  ///
  /// - Parameters:
  ///   - content: The section's content.
  ///   - header: A view to use as the section's header.
  ///   - footer: A view to use as the section's footer.
  public init(
    @ViewBuilder content: () -> Content, 
    @ViewBuilder header: () -> Parent, 
    @ViewBuilder footer: () -> Footer
  )
}

Which make all previous workarounds obsolete:

Section {
  // section content
} header: {
  if shouldShowHeader {
    Text("this is a header")
  }
} footer: {
  Text("this is a footer")
}

Views affected:

• Section

extension Section where Parent: View, Content: View, Footer: View {
  // From:
  public init(
    header: Parent, // 👈🏻 1
    footer: Footer, // 👈🏻 2
    @ViewBuilder content: () -> Content
  )

  // To:
  public init(
    @ViewBuilder content: () -> Content, 
    @ViewBuilder header: () -> Parent, // 👈🏻 1
    @ViewBuilder footer: () -> Footer // 👈🏻 2
  )
}

• Picker:

extension Picker {
  // From:
  public init(
    selection: Binding<SelectionValue>, 
    label: Label, // 👈🏻
    @ViewBuilder content: () -> Content
  )

  // To:
  public init(
    selection: Binding<SelectionValue>, 
    @ViewBuilder content: () -> Content, 
    @ViewBuilder label: () -> Label // 👈🏻
  )
}

• Slider:

extension Slider {
  // From:
  public init<V>(
    value: Binding<V>, 
    in bounds: ClosedRange<V> = 0...1, 
    onEditingChanged: @escaping (Bool) -> Void = { _ in }, 
    minimumValueLabel: ValueLabel, // 👈🏻 1
    maximumValueLabel: ValueLabel, // 👈🏻 2
    @ViewBuilder label: () -> Label
  ) where V: BinaryFloatingPoint, V.Stride: BinaryFloatingPoint

  // To:
  public init<V>(
    value: Binding<V>, 
    in bounds: ClosedRange<V> = 0...1, 
    @ViewBuilder label: () -> Label, 
    @ViewBuilder minimumValueLabel: () -> ValueLabel, // 👈🏻 1
    @ViewBuilder maximumValueLabel: () -> ValueLabel, // 👈🏻 2
    onEditingChanged: @escaping (Bool) -> Void = { _ in }
  ) where V: BinaryFloatingPoint, V.Stride: BinaryFloatingPoint
}

Interestingly, Stepper already used the view builders approach from the start. It clearly was ahead of its time!

• GroupBox:

extension GroupBox {
  // From:
  public init(
    label: Label, // 👈🏻
    @ViewBuilder content: () -> Content
  )

  // To:
  public init(
    @ViewBuilder content: () -> Content, 
    @ViewBuilder label: () -> Label // 👈🏻
  )
}

• NavigationLink:

extension NavigationLink {
  // From:
  public init(
    destination: Destination, // 👈🏻
    @ViewBuilder label: () -> Label
  )

  // To:
  public init(
    @ViewBuilder destination: () -> Destination, // 👈🏻
    @ViewBuilder label: () -> Label
  )

Unfortunately, this was the only change made to NavigationLink (FB8722348, FB8910787, FB8997675, FB9197698).

View Modifiers

This shift is not limited to just views. Modifiers have been updated as well:

• background and overlay:

extension View {
  // From:
  @inlinable public func background<Background: View>(
    _ background: Background, // 👈🏻
    alignment: Alignment = .center
  ) -> some View

  // To:
  @inlinable public func background<V: View>(
    alignment: Alignment = .center, 
    @ViewBuilder content: () -> V // 👈🏻
  ) -> some View
}

extension View {
  // From:
  @inlinable public func overlay<Overlay: View>(
    _ overlay: Overlay, // 👈🏻
    alignment: Alignment = .center
  ) -> some View

  // To:
  @inlinable public func overlay<V: View>(
    alignment: Alignment = .center, 
    @ViewBuilder content: () -> V // 👈🏻
  ) -> some View
}

• mask:

extension View {
  From:
  @inlinable public func mask<Mask: View>(
    _ mask: Mask // 👈🏻
  ) -> some View

  To:
  @inlinable public func mask<Mask: View>(
    alignment: Alignment = .center, // 🆕
    @ViewBuilder _ mask: () -> Mask // 👈🏻
  ) -> some View
}