MacKuba.eu

The SwiftUI cookbook for navigation

2022-07-03T20:54:35+02:00

This year SwiftUI adds new APIs for handling navigation which scale well from simple to complex UIs, include support for programmatic navigation and deep linking

The existing API

The existing API is based on links (NavigationLink) embedded inside NavigationView

You have a list of navigation link buttons, each specifying the view it links to, and when the button is tapped, the specified view is pushed onto the stack

This works great for basic navigation, and you can continue using this pattern with the new API

To programmatically perform navigation, you could use the NavigationView initializer that binds the state of the navigation link to a variable (using isActive or selection)

However, this only worked well in simple cases and didn't let you easily do things like deep-linking deep into the navigation hierarchy straight from the root, or moving back to the root from there

It also required you to keep separate bindings for each link, or at least each level of the hierarchy

The new navigation APIs

The new API lets you bind the state of the whole navigation stack to a single array managed by the root container

Navigation links push additional values into that array when they're selected

This allows you to quickly move through the hierarchy by modifying that array binding, e.g. to deep-link to a specific view by assigning a collection of values to it, or to pop the stack to the root view immediately by removing all values

Navigation containers:

The new API consists of a couple of new container views and a new version of the navigation link

The first container is NavigationStack:

NavigationStack(path: $path) {
    RecipeDetail()
}

NavigationStack is used for simple push-pop navigation happening in a single container, like in iPhone apps

The second container is NavigationSplitView:

NavigationSplitView {
    RecipeCategories()
} detail: {
    RecipeGrid()
}

NavigationSplitView is perfect for multi-column apps like Mail or Notes on the Mac or iPad

It automatically adapts to a single-column view in contexts like iPhone, Apple TV or slide-over on the iPad

To create a three-column layout, use another version of the initializer:

NavigationSplitView {
    RecipeCategories()
} content: {
    RecipeList()
} detail: {
    RecipeDetail()
}

NavigationSplitView has plenty of options that let you customize things like column widths or sidebar presentation, or even programmatically show or hide columns

You can hear more about configuring a layout like this in the talk SwiftUI on iPad: Organize your interface

Navigation links:

Previously, a navigation link included a title and a destination view to be presented:

NavigationLink("Show detail") {
    DetailView()
}

NavigationLink("Show detail", destination: DetailView())

NavigationLink(destination: DetailView()) {
    Text(title)
}

The new version of NavigationLink still includes a title, but instead of a view to present, it provides a value associated with the link:

NavigationLink("Apple Pie", value: applePieRecipe)

Clicking the link pushes that value into its container's path array

However, the exact view that's pushed when the link is clicked is determined by the navigation stack that the link is contained in

Navigation patterns

Let's now look at the ways you can use these views to build navigation in your apps:

1. Basic stack:

The first pattern is a basic navigation stack like in the Settings app on the iPhone or Apple Watch

The main view presents a list of items, and when an item is selected, it pushes a detail view on the stack which fills the whole screen

This approach works on all platforms, but it's best suited for iPhone, Apple TV and Apple Watch

In the basic form, you can just replace the NavigationView with NavigationStack and use NavigationLinks like before, with the destination view inline:

var body: some View {
    NavigationStack {
        List(Category.allCases) { category in
            Section(category.localizedName) {
                ForEach(dataModel.recipes(in: category)) { recipe in
                    NavigationLink(recipe.name) {
                        RecipeDetail(recipe: recipe)
                    }
                }
            }
        }
        .navigationTitle("Categories")
    }
}

To be able to perform navigation programmatically, assign a value to the navigation link instead:

ForEach(dataModel.recipes(in: category)) { recipe in
    NavigationLink(recipe.name, value: recipe)
}

And the destination view definition is then pulled out of the link block and moved to a new .navigationDestination modifier defined on the NavigationStack container:

.navigationDestination(for: Recipe.self) { recipe in
    RecipeDetail(recipe: recipe)
}

The modifier describes what view should be pushed onto the stack when a given value is pushed into container's path by any of the navigation links anywhere in the view hierarchy (or programmatically), for all values of the given type

The navigation stack's path starts out initially as an empty array []

When the navigation link is clicked:

1. It appends the assigned value of Recipe type into the path
2. The navigation stack then checks the navigationDestination configuration which stores a mapping of Recipe -> some View to get an appropriate view to present
3. The new view is pushed onto the view stack

When you press the "Back" button, the last item is removed from the path array and the top view on the stack is popped

You also need to create a binding of the navigation stack's path to a local state variable:

@State private var path: [Recipe] = []

→ you can use an array of a specific type if you only use values of one type in the path; if you want to build mixed paths of multiple types, use the new NavigationPath wrapper type instead

Pass a binding to NavigationStack's initializer:

var body: some View {
    NavigationStack(path: $path) {
        ...
    }
}

You can now modify the view stack by assigning to the state variable:

func showRecipeOfTheDay() {
    path = [dataModel.recipeOfTheDay]
}

func popToRoot() {
    path.removeAll()
}

You can see the NavigationStack in action in the talk Build a productivity app for Apple Watch

2. Multi-column presentation without stacks:

This interface is similar to the Mail app on the Mac and iPad

The layout consists of:

a sidebar, initially hidden, which shows a list of categories
the second column that shows a list of recipes
the main area that shows the recipe details

This interface is great on larger devices like the iPad and Mac

It allows you to see more information at the same time on the screen

In the first column (sidebar), we add a list of navigation links for each category of recipes:

@State private var selectedCategory: Category?

var body: some View {
    NavigationSplitView {
        List(Category.allCases, selection: $selectedCategory) { category in
            NavigationLink(category.localizedName, value: category)
        }
        .navigationTitle("Categories")
    } content: {
        // ... second column ...
    } detail: {
        // ... detail view ...
    }
}

Instead of binding a property to the navigation view's path like before, here we bind it instead to the selected item in the list, on the root level only

When a NavigationLink is contained within a list with the same selection type as the navigation link's value, the link will automatically update the selection of the list when clicked

→ see more about this in the SwiftUI on iPad: Organize your interface talk

In the second column (content), we show the same kind of list, listing recipes in the selected category, and again, we use NavigationLinks inside with assigned values of the same type as the list's selection binding

When a recipe is selected in the second column, the recipe details will be shown in the main area:

@State private var selectedCategory: Category?
@State private var selectedRecipe: Recipe?

var body: some View {
    NavigationSplitView {
        // ...
    } content: {
        List(dataModel.recipes(in: selectedCategory), selection: $selectedRecipe) { recipe in
            NavigationLink(recipe.name, value: recipe)
        }
        .navigationTitle(selectedCategory?.localizedName ?? "Recipes")
    } detail: {
        RecipeDetail(recipe: selectedRecipe)
    }
}

Note: unlike NavigationStack, NavigationSplitView *does not* keep a path property with a list of selected items that you can bind to – the navigation on this level is managed only through the selection bindings of the two lists:

func showRecipeOfTheDay() {
    let recipe = dataModel.recipeOfTheDay

    selectedCategory = recipe.category
    selectedRecipe = recipe
}

NavigationSplitView also does not use the .navigationDestination modifier

In environments that don't support multi-pane views (iOS, tvOS and iPad apps in split view or slide-over), NavigationSplitView renders as a single-pane NavigationStack which pushes the selected views onto its stack

3. Putting the two modes together – a multi-column view with a stack:

Here, we're building a two-column layout like in the Photos app on the iPad and Mac:

the left column (sidebar) shows a list of categories
the main area will show recipe photos in a grid
when a recipe is selected, a recipe details view will be pushed on the navigation stack within the detail area

To build this kind of layout, we use NavigationSplitView and NavigationStack together:

1. The first column displays a list like in the three-pane version
2. The detail area contains a navigation stack like in the first example

We track the state of the navigation using two variables: a list selection binding for the split view's first column, and a path of values for the stack view inside the second column:

@State private var selectedCategory: Category?
@State private var path: [Recipe] = []

struct ContentView: {
    var body: some View {
        NavigationSplitView {
            List(Category.allCases, selection: $selectedCategory) { category in
                NavigationLink(category.localizedName, value: category)
            }
            .navigationTitle("Categories")
        } detail: {
            NavigationStack(path: $path) {
                RecipeGrid(category: selectedCategory)
            }
        }
    }
}

The detail view displays a grid of navigation buttons wrapping image tiles; when a tile is pressed, the detail screen for a recipe is pushed onto the stack within the detail pane, which is defined using NavigationLinks and the .navigationDestination modifier:

struct RecipeGrid: View {
    var category: Category?

    var body: some View {
        if let category = category {
            ScrollView {
                LazyVGrid(columns: columns) {
                    ForEach(dataModel.recipes(in: category)) { recipe in
                        NavigationLink(value: recipe) {
                            RecipeTile(recipe: recipe)
                        }
                    }
                }
            }
            .navigationTitle(category.name)
            .navigationDestination(for: Recipe.self) { recipe in
                RecipeDetail(recipe: recipe)
            }
        } else {
            Text("Select a category")
        }
    }
}

To update navigation programmatically, assign the two bound variables to modify selection in the two panes:

func showRecipeOfTheDay() {
    let recipe = dataModel.recipeOfTheDay

    selectedCategory = recipe.category
    path = [recipe]
}

Persisting navigation state

Navigation state can be persisted between launches with the use of Codable and @SceneStorage properties

We'll wrap the navigation state properties into a single model type, so that they can be persisted together to keep the state consistent

This model type will conform to Codable to let us save & restore it

@SceneStorage will be used to automatically persist it together with the scene

Looking at the last example (with both NavigationSplitView and NavigationStack), here's how we update it to bind the UI to the properties in the new model type:

@StateObject private var navModel = NavigationModel()

var body: some View {
    NavigationSplitView {
        List(Category.allCases, selection: $navModel.selectedCategory) { category in
            NavigationLink(category.localizedName, value: category)
        }
        .navigationTitle("Categories")
    } detail: {
        NavigationStack(path: $navModel.path) {
            RecipeGrid(category: navModel.selectedCategory)
        }
    }
}

One thing to note about the NavigationModel: the values used for navigation & list selection will often be your model data types, i.e. whole structs like Recipe here, but we don't want to store the whole structs with all their properties as a part of the navigation path – it would be redundant, because we probably have all the recipe data stored somewhere else in some kind of database.

To store the navigation state, we only need some kind of references to them, like their IDs – so we're going to customize the Codable conformance here to save the recipes in the path as their ID values and restore them back from that on load:

class NavigationModel: ObservableObject, Codable {
    @Published var selectedCategory: Category?
    @Published var path: [Recipe] = []

    enum CodingKeys: String, CodingKey {
        case selectedCategory
        case recipePathIds
    }

    func encode(to encoder: Encoder) throws {
        var container = encoder.container(keyedBy: CodingKeys.self)
        try container.encodeIfPresent(selectedCategory, forKey: .selectedCategory)
        try container.encode(path.map(\.id), forKey: .recipePathIds)
    }

    required init(from decoder: Decoder) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)
        self.selectedCategory = try container.decodeIfPresent(Category.self,
                                        forKey: selectedCategory)

        let recipePathIds = try container.decode([Recipe.ID].self, forKey: .recipePathIds)

        // some recipes might have been deleted in the meantime, so skip those
        self.path = recipePathIds.compactMap { DataModel.shared[$0] }
    }

    // helper to serialize the model to/from JSON Data
    var jsonData: Data? {
        get { ... }
        set { ... }
    }

    // async sequence of updates (from the sample code project)
    var objectWillChangeSequence: AsyncPublisher<Publishers.Buffer<ObservableObjectPublisher>> {
        objectWillChange
            .buffer(size: 1, prefetch: .byRequest, whenFull: .dropOldest)
            .values
    }
}

The one missing piece is persisting the model using @SceneStorage

Since SceneStorage can only hold values of simple types like URL, String or Data, and not complex object types, we need to manually restore the model from the persisted form and make sure it's kept in sync after every change; SceneStorage will handle the persistence of the encoded value for us, but we need to handle the conversion to/from it

We do this by providing a .task that will run when the view is displayed, which loads the model from the data

The task then subscribes to a sequence of changes from the model and encodes the model into storage every time it changes:

@StateObject private var navModel = NavigationModel()
@SceneStorage("navigation") private var data: Data?

var body: some View {
    NavigationSplitView {
        // ...
    }
    .task {
        if let data {
            navModel.jsonData = data
        }
        for await _ in navModel.objectWillChangeSequence {
            data = navModel.jsonData
        }
    }
}

For more details and examples about the new APIs, check out the "Migrating to new navigation types" documentation article

See also "Bring multiple windows to your SwiftUI app" for info about opening new windows and scenes

What's new in AppKit

2022-06-08T23:57:53+02:00

Stage Manager

New UI workflow that cleans up inactive windows in your workspace, while your active window takes center stage, letting you put the focus on one task at a time

You can also pull windows into sets that are swapped in and out as a group

This has an impact on how your app's windows present themselves:

newly presented windows replace those on the stage to keep the workspace tidy
auxiliary windows like panels, popovers, settings windows cohabitate with primary windows

This should mostly work as expected using existing NSWindow APIs:

Stage Manager won't swap out a window if it's a floating panel, a modal window, or a window with toolbarStyle set to .preference
it also obeys the window's collectionBehavior flags (an old API from OS X 10.5-10.7 which mostly defines how a window behaves within desktop spaces, Exposé and full screen mode): a window will not displace an active window in center stage if it includes the .auxiliary, .moveToActiveSpace, .stationary or .transient collection behavior flags

Preferences

The System Preferences app now has a whole new look, with a different navigation and new design

To align with Settings apps on other platforms, it's been renamed to System Settings

If you're shipping a custom preference pane bundle, it will continue to work in the new Settings app

Your custom pane will appear in the Settings app sidebar and will be loaded on first access, like in Monterey and earlier versions

In-app settings:

To match the newly renamed System Settings app, your app's Preferences menu entry in the app's main menu is now renamed to "Settings…"

The menu item's label is automatically updated if you build the app with the latest SDK

Check your app for any other uses of the word "Preferences" in the UI referring to the preferences window and update them accordingly

New form design:

There is a new interface style for control-rich forms like the views commonly used in settings windows

It's designed to present an interface that displays a lot of controls in a clear, organized way

In this kind of UI, the form provides a lot of visual structure, so many system controls (like popup buttons) automatically adapt to this context by drawing normally with a lower visual weight and only revealing a heavier border or background on hover

You can build a form like this using the SwiftUI Form element with an .insetGrouped style:

Form {
    TextField("Computer Name", text: $name)
    Toggle("Screen Sharing", isOn: $screenSharing)
    Toggle("File Sharing", isOn: $fileSharing)
    Picker("AirDrop", selection: $airdrop) {
        ForEach(AirDropVisibility.allCases) {
            Text($0.label).tag($0)
        }
    }
}
.formStyle(.insetGrouped)

This renders Picker as a borderless popup button, TextField as a borderless inline text field, and Toggle as tiny switches

SwiftUI automatically handles the visual style, layout and the scrolling behavior of such form

If you aren't using SwiftUI yet, then… well… this is a good moment to start 😅

Control updates

NSComboButton:

A combo button is a new control – a button which provides an immediate action and a menu for additional options

It combines a standard button and a pull-down menu into a single control

This design is commonly used for use cases like a "move to folder" button in Mail, which moves an email to the pre-selected folder if you click the main left part of the button (the primary action), but also lets you pick an alternative location from the menu if you click the arrow on the right side

There are two styles of the combo button which change its appearance and behavior:

split style (the default), with a separator between the main button part and the arrow part
unified style – looks like a normal button, performs the primary action on click, and only presents the menu if you click and hold

NSColorWell:

NSColorWell has a new default design, with a white border and rounded corners

There are also two optional new styles you can pick:

1) A "minimal" style:

no borders, filled completely with color
a disclosure arrow appears on hover
it shows a color selection UI in a popover – by default a standard system grid of colors, but you can customize what's shown there

2) An "expanded" style:

used in iWork apps previously
combines both interaction models: a borderless minimal style on the left, with a disclosure arrow and a popover, and a button part which shows the full color picker on the right

Select the style using the colorWellStyle property

The behavior of the popover in "minimal" and "expanded" modes is configured through a new target-action pair: pulldownTarget + pulldownAction (if nil, then a standard system popover is used)

→ you can use this to present a custom popover, or a completely different UI like a menu

Toolbars:

There are two new delegate methods of NSToolbar that let you customize the toolbar behavior:

1) toolbarImmovableItemIdentifiers(_:)

defines a list of toolbar items that the user shouldn't be able to move or remove (they also don't animate when you enter the toolbar editing view)
used e.g. in Mail app for a filter button that should always appear above the messages list

2) toolbar(_:, itemIdentifier:, canBeInsertedAt:)

allows you to manually approve any reordering, insertion or removal of a toolbar item
use this to implement a custom set of toolbar customization rules, e.g. an item that has to stay within one toolbar section

Centered toolbar section:

a new property centeredItemIdentifiers allows you to specify multiple centered items, which have to stay within the toolbar's center section
previously there could be only one centered item, specified using centeredItemIdentifier

Preventing item resizing:

if a toolbar item changes its label depending on the state (e.g. "Mute / Unmute" in Mail app), it may have to change its size and cause other nearby buttons to shift back and forth when switching
to prevent this, you can now list all possible labels in the possibleLabels property of an NSToolbarItem; the toolbar will automatically position items according to their longest possible label so that they don't have to be resized

Alerts design:

There is a slight update to the design of alerts

Alerts in macOS Big Sur and above have a new, compact layout with centered text, which is optimized for small amounts of text accompanied by a few clear choices

In general, this is how an alert should look: alerts work best with shorter text, which your users are more likely to read before dismissing the dialog

However, sometimes you really can't make the description shorter, especially when the alert is about something very important like deleting a disk volume

For these cases, there is now a new expanded look of alerts which is more optimal for longer text

The expanded style uses a wider window, horizontally arranged buttons, and left-aligned text

There is no option to enable this – expanded style is used automatically when:

the description text is too long to fit comfortably in the compact size
or if the alert has an accessory view that's too large to fit in a compact alert

Note: the layout variant is chosen at the time when the alert is presented, so the alert is not resized if the text is changed after it's displayed

You should still aim to reduce the length of the alert text whenever possible, but this should improve the UI for those cases when you can't do that

NSTableView performance updates:

NSTableView is designed to efficiently handle a very large number of rows

It does this by lazily populating and reusing views as the table is scrolled

This becomes a challenge when the views have different heights, because it needs to calculate the total height of the table and the position of each row

Previously, NSTableView did this be pre-calculating the size of each row in the table, which impacts the initial load time

In macOS Ventura NSTableView now calculates the row heights lazily:

row heights are calculated for rows which are in or near the scrolling viewport
for the rest of the rows, NSTableView estimates the height based on the row heights that it has already measured
as the table is scrolled, the table view requests more row heights as needed and replaces the estimates with real measurements

This optimization significantly improves load times for very large tables

It's automatically used for all apps on macOS Ventura and doesn't require any changes

Note that this might affect the timing of delegate callbacks like tableView(_:, heightOfRow:)

SF Symbols

SF Symbols 4 adds more than 450 new symbols, including things like new currency symbols, household items or sports objects

SF Symbols can be used with one of 4 styles: monochrome, hierarchical, palette and multicolor

In macOS Ventura, symbols may now specify a "preferred rendering mode" – one of these styles that is preferred for this specific symbol and is used automatically if not configured otherwise

You can still use NSImageSymbolConfiguration to override the preferred style

Variable symbols:

There is a new type of symbol which represents some value or quantity, like WiFi signal strength or volume

These symbols have several versions depending on the value, with a smaller or larger part of the symbol filled or colored

You configure these symbols by providing a floating point value between 0 and 1:

class NSImage {
    public init?(symbolName: String,
                 variableValue: Double,
                 accessibilityDescription: String?)

    public init?(systemSymbolName: String,
                 variableValue: Double,
                 accessibilityDescription: String?)
}

If the symbol doesn't define any thresholds depending on the value, the value is ignored

Sharing

macOS Ventura includes a new redesigned share sheet, which now looks similar to the one on iOS

It includes a list of suggested people to share with, like the iOS one

It also adds new APIs which apps can use to let the user invite their contacts to collaborate on a document

The share sheet is accessed using the existing API NSSharingServicePicker

You can still filter the list of services and add custom ones, use existing delegate callbacks etc.

If you share a file URL, the sheet will automatically display the file name, type, size and icon in the header

If you're sharing a custom item, you can manually provide details to be displayed in the header using a new protocol NSPreviewRepresentableActivityItem:

protocol NSPreviewRepresentableActivityItem: AnyObject {
    /* The item to be shared */
    var item: Any { get }

    /* A localized string representing the item's name or title */
    optional var title: String? { get }

    /* A provider for a full-sized image that represents the item */
    optional var imageProvider: NSItemProvider? { get }

    /* A provider for a thumbnail-sized icon that represents the item */
    optional var iconProvider: NSItemProvider? { get }
}

or the helper class NSPreviewRepresentingActivityItem which implements the protocol:

class NSPreviewRepresentingActivityItem: NSPreviewRepresentableActivityItem {
    init(item: Any, title: String?, image: NSImage?, icon: NSImage?)
    init(item: Any, title: String?, imageProvider: NSItemProvider?, iconProvider: NSItemProvider?)
}

Use the preview class if you already have all the data you need, and the protocol with NSItemProviders if it's too performance-intensive to generate it up front

If you want to launch the share sheet from a menu, like the main menu bar or a context menu when clicking a collection view item, the share sheet API now provides a standard "Share…" menu item that you can put in any menu to display the sheet:

class NSSharingServicePicker {
    var standardShareMenuItem: NSMenuItem
}

In case of context menus, the displayed popover will be anchored to the same view on which the context menu was shown

There's a lot more new features for managing collaboration

See more in separate talks: "Enhance collaboration experiences with Messages" and "Integrate your custom collaboration app with Messages"

Add rich graphics to your SwiftUI app

2022-06-04T22:50:55+02:00

Safe area

By default SwiftUI positions your content within the safe area, so that it doesn't get obscured by things at the top and the bottom of the screen, like the navigation bar and the home bar on Face ID phones

If you do want the view to extend to the whole screen, edge to edge, below the top/bottom bars (e.g. on screens that show some kind of graphics), you can opt out of the safe area using .ignoresSafeArea:

ContentView()
    .ignoresSafeArea()

You can also choose on which sides you want to extend the view into the safe area:

ContentView()
    .ignoresSafeArea(edges: .bottom)

You don't need to do this on most screens, since most content should be kept within the safe area

The keyboard, if visible, is also outside the safe area – it actually has its own inner safe area that's positioned inside the main "container safe area"

By default your view is positioned within the keyboard's safe area, so that it doesn't get covered by the keyboard – to opt out just of the keyboard safe area (but stay within container safe area), add the additional .keyboard parameter:

ContentView()
    .ignoresSafeArea(.keyboard)

Backgrounds

There are now new versions of the .background modifier where if you don't pass any specific color or style, it uses the default screen background (white or black, depending on light/dark mode):

HStack {
    ...
}
.background()

These backgrounds (and backgrounds like .background(Color.green) now automatically extend below the safe area, unless you customize it

You can also specify that the background should only be used within a defined shape around the view, like a rounded rectangle:

HStack {
    ...
}
.background(.cyan, in: RoundedRectangle(cornerRadius: 12))

In this case, the view and its entire background area both stay within the safe area

Materials and vibrancy

Materials are a new kind of backgrounds – the kind of translucent blur background used in various system areas:

.background(.regularMaterial)
.background(.thickMaterial, in: RoundedRectangle(cornerRadius: 12))

Materials are great if you want to show some of the colorful content positioned below some kind of panel bleeding into its background

There's a set of materials: .ultraThin, .thin, .regular, .thick, .ultraThick – the "thinner" the material, the more of the color from behind comes through

Some of the content displayed over a material background (using foreground colors of "secondary" and below) uses an effect called "vibrancy" – it blends the color of the text with the material background behind it in a specific way that makes it more readable

To apply the vibrancy effect, use the new .foregroundStyle modifier instead of .foregroundColor:

HStack {
    Text("\(stops.count) colors")
        .foregroundStyle(.secondary)
}
.background(.regularMaterial)

You can use .foregroundStyle with hierarchical styles like .secondary and with actual colors (or even gradients), and you can even use both together, in which case SwiftUI applies some alpha effect to the selected color:

VStack {
    Text("Primary").foregroundStyle(.primary)
    Text("Secondary").foregroundStyle(.secondary)
    Text("Tertiary").foregroundStyle(.tertiary)
    Text("Quaternary").foregroundStyle(.quaternary)
}
.foregroundStyle(.purple)

Use .foregroundColor if you want to opt out of vibrancy for a specific view and use an unmodified color

What's more, a Text can even present an attributed string that has multiple different colors applied to different ranges and use a vibrancy effect for the parts that don't have a specific color set (it can only have one single foregroundStyle though)

You can embed one Text inside another to construct a Text with multiple colors in different ranges:

Text("\(stops.count) \(Text("colors").foregroundColor(.red))")
    .foregroundStyle(.secondary)

It's ok to use .foregroundStyle on non-material backgrounds – the vibrancy effect is automatically disabled unless there is an appropriate background behind the text

Text views also automatically disable vibrancy for any embedded emoji

You can read more about vibrancy and materials in my old blog post about the introduction of dark mode in macOS Mojave – "Dark Side of the Mac: Appearance & Materials"

Safe area inset

There is a new view modifier .safeAreaInset that allows you to position a view on top of a ScrollView in a way that adjusts the scroll view's top/bottom content insets so that all the content can be reached and the beginning/end isn't obscured by the overlay

This is especially useful for views using the blur material background, since you want them to be z-stacked with some content on a layer below to show a hint of the colors behind it, but you want all the content in the view below to be accessible by scrolling it above the overlay

To position a view this way, put the whole overlay view inside the .safeAreaInset closure:

List {
    ...
}
.safeAreaInset(edge: .bottom) {
    HStack {
        Text("New gradient")
        Spacer()
        Text("\(stops.count) colors")
            .foregroundStyle(.secondary)    
    }
    .padding()
    .background(.thinMaterial)
}

Canvas

When drawing a large number of graphical elements in a shared area, we can use a ZStack and the .drawingGroup modifier:

var body: some View {
    GeometryReader { proxy in
        ZStack {
            ForEach(state.entries.indices, id: \.self) { index in
                let entry = state.entries[index]
                entry.symbol
                    .scaleEffect(...)
                    .position(...)
                    .onTapGesture {
                        withAnimation { ... }
                    }
            }
        }
    }
    .drawingGroup()
}

A .drawingGroup tells SwiftUI to combine all the views it contains on a single layer to improve performance

This can be used for graphical elements like images, but not for UI controls like text fields or lists

Using .drawingGroup still allows you to do things like setting accessibility properties or applying gestures to each element individually

However, keeping each view's separate identity adds a bit of overhead

When you draw a really large amount of elements and you need all the performance you can get, you can now use the new Canvas element

→ the tradeoff is that you can't attach gestures to individual drawings anymore

A Canvas is given a closure that's run every time the canvas is redrawn

This is a normal, imperative code closure, not a view builder

It works similarly to drawRect in AppKit or UIKit – the canvas gives you a context object that you can run some draw commands on:

Canvas { context, size in
    let image = Image(systemName: "sparkle")

    for i in 0..<10 {
        context.draw(image, at: CGPoint(
            x: 0.5 * size.width + Double(i) * 10,
            y: 0.5 * size.height
        ))
    }
}

When drawing an image, the context needs to "resolve" it to get the actual data it can draw, so if you use the same image multiple times in the canvas, you can resolve it manually up front just once

This also lets you access information like the image size:

Canvas { context, size in
    let image = context.resolve(Image(systemName: "sparkle"))
    let imageSize = image.size

    for i in 0..<10 {
        context.draw(image, at: CGPoint(
            x: 0.5 * size.width + Double(i) * imageSize.width,
            y: 0.5 * size.height
        ))
    }
}

To draw shapes in the canvas, use context.fill()

You can draw e.g. bezier curves or paths derived from standard SwiftUI shapes

You can also use standard SwiftUI color objects:

Canvas { context, size in
    let image = context.resolve(Image(systemName: "sparkle"))
    let imageSize = image.size

    for i in 0..<10 {
        let frame = CGRect(
            x: 0.5 * size.width + Double(i) * imageSize.width,
            y: 0.5 * size.height,
            width: imageSize.width,
            height: imageSize.height
        )

        context.fill(
            Ellipse().path(in: frame),
            with: .color(.cyan)
        )
        context.draw(image, in: frame)
    }
}

To change some properties globally on the context and revert them later, you can create a copy of the context on which you modify the settings, draw some elements using the new context, and the original context will not be affected:

Canvas { context, size in
    let image = context.resolve(Image(systemName: "sparkle"))
    let imageSize = image.size

    for i in 0..<10 {
        let frame = ...

        var innerContext = context
        innerContext.opacity = 0.5
        innerContext.fill(Ellipse().path(in: frame), with: .color(.cyan))

        // drawn with the original opacity
        context.draw(image, in: frame)
    }
}

You can set the color with which a symbol is drawn by setting the shading on the resolved image:

let image = context.resolve(Image(systemName: "sparkle"))
image.shading = .color(.blue)

The Canvas is supported on all platforms – it works the same way on iOS, watchOS, tvOS and macOS

Timeline view

Timeline view is a new tool that allows you to create animating views by describing exactly how the view should look at a given point in time

The timeline view requires a "schedule" – a description of how often it should change

For drawing an animated canvas, we'll use the .animation schedule, which redraws the view as often as possible

TimelineView gives you a timeline object from which you can read the current time using the date property:

TimelineView(.animation) { timeline in
    Canvas { context, size in
        let now = timeline.date.timeIntervalSinceReferenceDate

        let angle = Angle.degrees(now.remainder(dividingBy: 3) * 120)
        let x = cos(angle.radians)

        var image = context.resolve(Image(systemName: "sparkle"))
        let imageSize = image.size

        for i in 0..<count {
            let frame = CGRect(
                x: 0.5 * size.width
                    + Double(i) * imageSize.width * x,
                y: 0.5 * size.height,
                width: imageSize.width,
                height: imageSize.height
            )

            context.draw(image, in: frame)
        }
    }
}

Since there aren't any individual SwiftUI elements inside the Canvas, you can't specify accessibility information for each element, only for the whole canvas

If you want to include a more detailed description with separate elements, you can use the new .accessibilityChildren modifier to provide a completely separate SwiftUI view hierarchy used only for accessibility purposes

See more in "SwiftUI accessibility: Beyond the basics"

What's new in Foundation

2022-06-04T21:54:43+02:00

Attributed strings

An attributed string allows you to associate attributes in the form of key-value pairs with specific ranges of the string, in order to make a part of the text use a different style

A part of a string can have multiple attributes applied to it and the attribute ranges can overlap

Attributed strings are usually used with APIs that support rich text, like UITextView/NSTextView

String attributes are defined in the SDK, but you can also add your own

Attributed strings in Foundation previously used an ObjC-based reference type called NSAttributedString

This year, there is a completely new Swift-only struct type called AttributedString, which takes full advantage of Swift features

The Swift AttributedString is a value type, compatible with String, fully localizable and with a more type-safe API

ℹ️ I've replaced some of the code samples in this section to better demonstrate the use of the API in this form

Assigning attributes to strings:

To assign attributes to the whole string, simply assign an appropriate value (which is type-checked at compile time) to a property like font or foregroundColor on the attributed string object:

var thanks = AttributedString("Thank you!")
thanks.font = .body.bold()

var website = AttributedString("Please visit our website.")
website.font = .body.italic()
website.link = URL(string: "http://www.example.com")

To assign attributes to a range, use slicing:

let msg = AttributedString()
let start = msg.startIndex
let after5 = msg.index(start, offsetByCharacters: 5)

msg[start ..< after5].foregroundColor = .blue

You can also find a range by looking for a substring in the text:

var website = AttributedString("Please visit our website.")

if let range = message.range(of: "visit") {
    message[range].font = .body.italic().bold()
    message.characters.replaceSubrange(range, with: "surf")
}

It may also be useful to hold a set of attributes separately from the string itself and then apply it to one or more strings at some point – for that you can use an AttributeContainer:

var container = AttributeContainer()
container.foregroundColor = .red
container.underlineColor = .primary

website.mergeAttributes(container)

Iterating over an attributed string:

To iterate over the string's contents, you can use one of the provided "views" into the string:

characters, which provides a collection of separate characters
runs, which lists ranges of text, each having a single uniform set of attributes

These views are Swift collections, so you can use any standard collection methods on them

Here, we iterate over the collection of characters in a string, modifying the attributes of some of them:

let characters = message.characters

for i in characters.indices where characters[i].isPunctuation {
    message[i ..< characters.index(after: i)].foregroundColor = .orange
}

Now, assuming we have an attributed string like this:

var line1 = AttributedString("Thank you! ")
line1.font = .boldSystemFont(ofSize: 10)

var line2 = AttributedString("Please visit our website")

// make the word "website" a link
let range = line2.range(of: "website")!
line2[range].link = URL(string: "http://example.com")

let message = line1 + line2

If we iterate over the string's runs collection like this, we get 3 items, because there are three distinct sections in the string:

let parts = message.runs.map { run in
    String(message.characters[run.range])
}

// => ["Thank you! ", "Please visit our ", "website"]

However, we can also divide the string into runs only by looking at one specific attribute, e.g. .link – in this case, there will be only two separate runs:

let parts = message.runs[\.link].map { (value, range) in
    String(message.characters[range])
}

// => ["Thank you! Please visit our ", "website"]

The value provided for each one will be of URL? type in this case – the first run will have a value of nil, and the second one will have the URL we've assigned earlier:

for (value, range) in message.runs[\.link] {
    if let url = value {
        print(url.host!)    // => "example.com"
    }
}

Attributed string localization:

Attributed strings are fully localizable

The old ObjC-based NSAttributedString now also has localization support added

Attributed string localizations are listed in .strings files, just like for normal strings

Both plain strings and attributed strings can now be localized in Swift code using String interpolation, in a similar way to how it's done in SwiftUI:

func prompt(for document: String) -> AttributedString {
    AttributedString(localized: "Would you like to save the document '\(document)'?")
}

Xcode can now collect localizable strings for the .strings files from such initializers in your code using the Swift compiler

You can turn this on with the build setting: "Localization > Use Compiler to Extract Swift Strings"

Markdown support:

Attributed strings now automatically parse Markdown content and generate attributes from tags like **bold**:

struct ReceiptView: View {
    var body: some View {
        VStack {
            Text("**Thank you!**")
            Text("_Please visit [our website](https://example.com)._")
        }
    }
}

Conversion and archiving:

The new struct-based attributed strings can be easily converted to and from the old ObjC-based reference types:

let nsString = NSAttributedString(message)
let swiftString = AttributedString(nsString)

AttributedString conforms to Codable, so you can encode a string with all its attributes into whatever form that Codable supports

Custom attributes:

Apart from the built-in string attributes provided by AppKit, UIKit, SwiftUI and other system frameworks, you can also define your own attributes

A string attribute consists of a key and a value

The key is a type the conforms to the AttributedStringKey protocol

It defines the type used for the value (through the associated type Value) and the name used for archiving (static var name)

The key can also customize encoding and decoding by conforming to some other protocols

Here, we define a "rainbow" attribute which colors the range of the text with rainbow colors, whose value is one of the three enum cases that set the intensity:

enum RainbowAttribute: AttributedStringKey {
    enum Value: String {
        case plain
        case fun
        case extreme
    }

    public static var name = "rainbow"
}

If we want the attribute to be encoded & decoded with the string, it needs to be Codable:

enum RainbowAttribute: CodableAttributedStringKey {
    enum Value: String, Codable {
        case plain
        case fun
        case extreme
    }

    public static var name = "rainbow"
}

You can also make the custom attribute available to the Markdown parser, using a special custom attribute syntax

To use an attribute in Markdown, it needs to also conform to MarkdownDecodableAttributedStringKey

The attribute is added to a range of text using a similar syntax like images and URLs:

This text contains ^[an attribute](rainbow: 'extreme').

This text contains ^[two attributes](rainbow: 'extreme', otherValue: 42).

This text contains ^[an attribute with 2 properties](someStuff: {key: true, key2: false}).

The part in the square brackets is the marked text, and the part in parentheses are the attributes

The attribute values are written as a JSON5 object

Support for JSON5 parsing was also added to existing JSON parsing APIs like JSONSerialization and JSONDecoder (you need to enable a proper option first):

let json5text = "{ foo: 'bar' }"
let json5data = json5text.data(using: .utf8)!

let decoded = JSONSerialization.jsonObject(with: json5data, options: .json5Allowed)

The names of attributes from the attributes JSON object are looked up in "attribute scopes"

An attribute scope defines a list of attributes from one domain, e.g. SwiftUI or your app

When creating an AttributedString from Markdown, you need to specify one single attribute scope from which attributes will be looked up

However, attribute scopes can be nested in one another, so you can include e.g. a scope of all SwiftUI attributes inside your scope (which in turn includes Foundation attributes)

An attribute scope is defined as a type conforming to AttributeScope, nested inside the AttributeScopes namespace:

extension AttributeScopes {

    // attribute scope for our "Caffe" app

    struct CaffeAppAttributes: AttributeScope {
        // this is our "rainbow" attribute
        let rainbow: RainbowAttribute

        // here, we include standard SwiftUI attributes
        let swiftUI: SwiftUIAttributes
    }

    // expose our attribute scope on a keypath in AttributeScopes
    var caffeApp: CaffeAppAttributes.Type { CaffeAppAttributes.self }
}

// now, pass the keypath to our scope when creating a string:

let header = AttributedString(
    localized: "^[Fast & Delicious](rainbow: 'extreme') Food",
    including: \.caffeApp
)

To actually render a text marked with custom attributes in a specific way, you need to create a custom view that takes an AttributedString with those attributes and displays it – see the example RainbowText SwiftUI view in the "Building a Localized Food-Ordering App sample code project

New formatter APIs

Formatters are used for converting values like dates or numbers into localized and user-presentable strings

Current formatters (NSFormatter) are quite heavy objects, so it's a common pattern to create them once, cache them and reuse them, often across different parts of the app, which isn't always convenient

This year, there is a completely new API for formatters in Swift, which is aimed to improve both their usability and efficiency

The formatting is now done by calling a format method on the formatted value directly

Instead of formatting a date with a date formatter:

let dateFormatter = DateFormatter()
dateFormatter.dateStyle = .medium
dateFormatter.timeStyle = .medium

...

dateLabel.text = dateFormatter.string(from: quakeTime)

We ask the date for a formatted representation:

dateLabel.text = quakeTime.formatted(date: .abbreviated, time: .standard)

Formatting floating point numbers, before:

magnitudeLabel.text = String(format: "%.1f", magnitude)

after:

magnitudeLabel.text = magnitude.formatted(.number.precision(.fractionLength(1)))

This is not only more readable, but also safer – the old version requires using string format specifiers that have to be written in a specific way, aren't checked by the compiler and can't be easily remembered, and if the value is not a floating point number – you will get a wrong output instead of a compiler error

You also now get autocompletion in Xcode for the formatting options

There are new formatting API equivalents for all existing formatters in Foundation – for lists, date components and intervals, measurements, data sizes etc.

They're designed to help you avoid some common pitfalls when using string-based format specifiers, like using a wrong date format field that only fails in some specific cases

Formatting dates:

Simplest version:

let formatted = date.formatted()
// => "6/7/2021, 9:42 AM"

Configure time and date styles:

let onlyDate = date.formatted(date: .numeric, time: .omitted)
// => "6/7/2021"

let onlyTime = date.formatted(date: .omitted, time: .shortened)
// => "9:42 AM"

List specific fields to include:

let formatted = date.formatted(.dateTime.year().day().month())
// => "Jun 7, 2021"

Customize field styles:

let formattedWide = date.formatted(.dateTime.year().day().month(.wide))
// => "June 7, 2021"

let weekday = date.formatted(.dateTime.weekday(.wide))
// => "Monday"

Standardized formats:

let logFormat = date.formatted(.iso8601)
// => "20210607T164200Z"

let fileNameFormat =
    date.formatted(.iso8601.year().month().day().dateSeparator(.dash))
// => "2021-06-07"

Setting a specific locale:

let formatted = date.formatted(.dateTime.locale(myLocale))

The general pattern is:

start with the value to be formatted
call one of the formatted methods
pass a style in the argument (e.g. for dates it's .dateTime or .iso8601)
call methods on the format to customize it

The order of the fields in the chained call doesn't matter – it just lists the fields that should be included somewhere in the final output, and the formatter decides on the order based on the locale

Formatting date ranges:

let range = (now..<later).formatted()
// => "6/7/21, 9:42 - 11:05 AM"

let noDate = (now..<later).formatted(date: .omitted, time: .complete)
// => "9:42:00 AM PDT - 11:05:20 AM PDT"

let timeDuration = (now..<later).formatted(.timeDuration)
// => "1:23:20"

let components = (now..<later).formatted(.components(style: .wide))
// => "1 hour, 23 minutes, 20 seconds"

let relative = later.formatted(.relative(presentation: .named, unitsStyle: .wide))
// => "in 1 hour"

Formatting values as attributed strings:

You can ask a formatter to create an attributed string instead by calling .attributed()

The generated attributed string does not have any visual styles applied to it, but it marks all ranges of text that contain specific fields like month or year with formatter-specific properties

You can then analyze the returned AttributedString and use these format properties to mark different tokens within the generated string with different colors or text styles

var dateString: AttributedString {
    var str = date.formatted(.dateTime
                .minute()
                .hour()
                .weekday()
                .locale(locale)
                .attributed())

    // alternative way to create an AttributeContainer
    let weekday = AttributeContainer.dateField(.weekday)
    let color = AttributeContainer.foregroundColor(.orange)

    // we can ask an AttributedString to replace the attributes
    // in one container set with those in another container

    // here, the text range marked with a "weekday" attribute
    // will have an orange text color applied to it
    str.replaceAttributes(weekday, with: color)

    return str
}

Parsing dates from strings:

To convert the values the other way, you can use a new Date initializer that takes a "strategy" argument

The strategy is an object that tells the parser what kind of fields to expect in the input

You can use one of the format objects shown earlier as a parsing strategy:

let format = Date.FormatStyle().year().day().month()
let formatted = date.formatted(format)
// formatted is "Jun 7, 2021"

if let date = try? Date(formatted, strategy: format) {
  // date is 2021-06-07 07:00:00 +0000
}

You can also use a more specialized strategy object, like this one for parsing dates sent from the server in a specific strict format:

let strategy = Date.ParseStrategy(
    format: "\(year: .defaultDigits)-\(month: .twoDigits)-\(day: .twoDigits)",
    timeZone: TimeZone.current
)

if let date = Date("2021-06-07", strategy: strategy) {
    // date is 2021-06-07 07:00:00 +0000
}

Instead of using magic string format specifiers, ParseStrategy lets you specify the fields using string interpolation – checking the format at compile time, and helping you in Xcode with autocomplete and inline documentation

"No more guessing how many Y characters you should use to parse a year"

Formatting numbers:

let value = 12345

var formatted = value.formatted()
// => "12,345"

let percent = 25
let percentFormatted = percent.formatted(.percent)
// => "25%"

let scientific = 42e9
let sciFormatted = scientific.formatted(.number.notation(.scientific))
// => "4.2E10"

let price = 29
let priceFormatted = price.formatted(.currency(code: "usd"))
// => "$29.00"

Formatting lists:

To format a list of things, call .formatted() on an array and specify which of the formats should be used for each member:

let list = [25, 50, 75].formatted(.list(memberStyle: .percent, type: .or))
// => "25%, 50%, or 75%"

Formatting text field content in SwiftUI:

In SwiftUI, you can assign a format to a text field

The text field will automatically parse and reformat the value entered by the user, and if a correct value of a given type can be parsed from the input, it will assign it through the binding to the connected state property as e.g. a number or a date value:

struct ReceiptTipView: View {
    @State var tip = 0.15

    var body: some View {
        HStack {
            Text("Tip")
            Spacer()
            TextField("Amount",
                value: $tip,
                format: .percent)
        }
    }
}

Automatic grammar agreement

In some languages, like in Spanish, there needs to be a grammatical agreement between the words in a sentence, e.g. in a phrase "two small salads" the number, the noun and the adjective need to have not only the same pluralization, but also same grammatical gender

This makes it often extremely complex to provide full and correct localization for all combinations of UI strings, and either makes the localization process more time-consuming, or makes the translation less correct or less natural

E.g. instead of just translating "small", "large", "juice" and "salad" you need each combination of "small juice", "large salad" etc. (and then add another dimension for pluralizations)

Foundation in iOS 15 adds a new feature called "automatic grammar agreement" that handles a lot of these problems automatically (available in English and Spanish at the moment)

You can now write a string like this:

Text("Add ^[\(quantity) \(size) \(food)](inflect: true) to your order")

The custom attribute Markdown syntax for Attributed Strings is used to mark a part of the text that needs to be automatically inflected with the "inflect" attribute

This will be exported to an English strings file like this:

"Add ^[%lld %@ %@](inflect: true) to your order" =
    "Add ^ [%lld %@ %@](inflect: true) to your order";

"Pizza" = "Pizza";
"Juice" = "Juice";
"Salad" = "Salad";

"Small" = "Small";
"Large" = "Large";

And to a Latin American Spanish strings file like this:

/* in Spanish the order of the noun and adjective is reversed */

"Add ^[%lld %@ %@](inflect: true) to your order" =
    "Añadir ^[%1$lld %3$@ %2$@](inflect: true) a tu pedido";

"Pizza" = "Pizza";
"Juice" = "Jugo";
"Salad" = "Ensalada";

"Small" = "Pequeño";
"Large" = "Grande";

The key change is that you don't need to provide separate translations for e.g. "pequeño" (masculine) and "pequeña" (feminine) – the grammar agreement engine handles this automatically

User's term of address:

In some languages some of the localized text also needs to change depending on the person reading it, because it needs to be adjusted for the person's term of address (depending on the gender)

Now, users using supported languages (currently Spanish) can specify their term of address in the iOS Settings app, under "Language & Region", and can choose to share it with apps

This is done the same way as in the previous example:

^[Bienvenido](inflect: true) a Notas

Such text can be displayed as "Bienvenido…" or "Bienvenida…" depending on the user's gender

You can also provide a default text to be used if this information is not available:

^[Bienvenido](inflect: true, inflectionAlternative: "Te damos la bienvenida") a Notas

Discover concurrency in SwiftUI

2022-06-01T21:24:26+02:00

The SwiftUI run loop and Observable Objects

The SwiftUI engine runs a loop that receives some events, lets you update your models, checks them for changes, recreates necessary view objects and re-renders the parts of the UI that should be updated

The run loop runs in "ticks" happening in regular intervals, and all of it executes on the main thread / main actor

The events sent from ObservableObject's @Published also need to be sent on the main actor for this to work correctly

Let's see exactly why:

With such update method:

class Photos: ObservableObject {
    @Published private(set) var items: [SpacePhoto] = []

    func updateItems() {
        let fetched = fetchPhotos()
        items = fetched
    }

    func fetchPhotos() -> [SpacePhoto] { ... }
}

the update goes like this:

when we assign the items property, which is @Published, the Published wrapper automatically sends an objectWillChange event that is observed by SwiftUI, before the changes happen
at that point SwiftUI records a snapshot of the data before it changes
then, the new value is written to the property
at the next "tick" of the run loop – which might happen immediately afterwards, or a bit later – SwiftUI compares the current value of the property to the saved snapshot, and this tells it what exactly was changed
since some of the data was changed, the appropriate parts of the UI are re-rendered

If all of the above happens on the main thread, these steps are guaranteed to happen in order

However, if the code takes some time to run, this may cause the run loop to miss the next tick, because the main thread will be busy calculating the data – which will result in dropped frames and a possibly degraded user experience

So you may want to run the calculations on a background queue:

func updateItems() {
    DispatchQueue.global().async {
        let fetched = fetchPhotos()
        self.items = fetched
    }
}

This way, the main thread isn't blocked, the run loop is free to run the next ticks there until the data is ready

However, if the assignment (and the resulting notification) happens outside of the main thread, this could mess up the order of operations and could result in the view not being updated

For example:

the long-running operation finishes running on the background thread
it sends the objectWillChange event
SwiftUI takes a snapshot of the data
*but* because this is all happening on the background thread, the run loop is free to perform another tick on the main thread in the meantime, which it might possibly do at this very moment, right after objectWillChange
in this case, SwiftUI compares the snapshot to the current data, but the data hasn't changed yet, so there's nothing to update
now, the value of the property is updated on the background thread
but SwiftUI has already compared the snapshots, so it has forgotten about the previous state and will not compare the data again…

To make sure the order of operations is always right:

1. objectWillChange,
2. the state changes,
3. and the run loop runs a tick,

all of these need to be done on the same thread – the main thread

Previously, the solution would have been to jump back to the main thread before saving the data:

func updateItems() {
    DispatchQueue.global().async {
        let fetched = fetchPhotos()
        DispatchQueue.main.async {
            self.items = fetched
        }
    }
}

With Swift 5.5, a better approach is to instead make the fetching an asynchronous operation and use await to wait for the result

By using await we "yield" the current (main) thread instead of blocking it and it's free to perform next run loop ticks in the meantime, and when the response is received, the method continues execution – on the same thread where it started, automatically:

func updateItems() async {
    let fetched = await fetchPhotos()
    items = fetched
}

To make sure that all of the updates to properties in the Photos class happen on the main thread and that we don't make a mistake somewhere, we can mark the class with the global actor @MainActor:

@MainActor
class Photos: ObservableObject {
    @Published private(set) var items: [SpacePhoto] = []

    ...
}

This way the Swift compiler guarantees that the code in this class runs on the main thread, at compile time

Associating async tasks with views

SwiftUI provides a new .task modifier that can be used to associate an asynchronous task with a given view

The task is run at the beginning of the view's lifetime, like .onAppear, but the closure your provide to it is asynchronous, which makes it easier to make asynchronous calls with await inside

In this app, we can use the .task modifier to run the method which prepares the photo data in the model that we've written above:

struct CatalogView: View {
    @StateObject private var photos = Photos()

    var body: some View {
        NavigationView {
            List {
                ...
            }
        }
        .task {
            await photos.updateItems()
        }
    }
}

What's more, the task's lifetime is tied to the view's lifetime, so the task is also automatically cancelled when the view is removed from the UI

You can use this to e.g. create a task that continuously reads data from an async sequence for the whole duration of the view's lifetime

Async images

SwiftUI now includes an AsyncImage() view that automatically loads the contents of the image for you from a given URL:

AsyncImage(url: photo.url)

You can customize both the look of the resulting image and the placeholder that is displayed while the image is loading:

AsyncImage(url: photo.url) { image in
    image
        .resizable()
        .aspectRatio(contentMode: .fill)
} placeholder: {
    ProgressView()
}

You can also customize the error handling – for that, check out the AsyncImage(url:scale:transaction:content:) initializer of this view

Running async code from SwiftUI action handlers

To call asynchronous code from inside a button handler closure, which is synchronous, use a Task block to execute a piece of asynchronous code in synchronous context:

struct SavePhotoButton: View {
    var photo: SpacePhoto
    @State private var isSaving = false

    var body: some View {
        Button {
            Task {
                isSaving = true
                await photo.save()
                isSaving = false
            }
        } label: {
            Text("Save")
                .opacity(isSaving ? 0 : 1)
                .overlay {
                    if isSaving {
                        ProgressView()
                    }
                }
        }
        .disabled(isSaving)
        .buttonStyle(.bordered)
    }
}

💡 Tip: to show a spinner inside a button like this, use .opacity() to hide its label while the spinner is displayed – since the label is still there, just with 0 opacity, it makes sure that the button stays at the same size in the loading state

ℹ️ In the talk, the asynchronous code was instead wrapped in a call to an async {} function, which was later replaced with the Task initializer

Reloading the data using pull-to-refresh

SwiftUI adds a new .refreshable modifier this year which automatically implements a pull-to-refresh behavior in your view, where scrolling the contents of the view beyond the top edge triggers a reload of the data

Inside the closure passed to .refreshable, provide the reloading code that should be run on refresh – the code can be asynchronous, so it can use await:

List {
    ForEach(photos.items) { item in
        ...
    }
}
.refreshable {
    await photos.updateItems()
}

Customize and resize sheets in UIKit

2022-05-28T21:42:00+02:00

iOS 13 introduced a refined appearance for sheets, which don't cover the full screen anymore on the iPhone, but instead show a curved top edge that can be used to dismiss the sheet by pulling it down

iOS 15 expands the sheets API adding a lot of new customizations:

you can make vertically resizable sheets that only cover half of the screen
you can remove the dimming view, creating non-modal UIs where the user can interact with the content behind the sheet
you can display non-full-screen sheets on iPhones in landscape position

Creating sheets

Sheet appearance is managed through a new presentation controller class, named UISheetPresentationController

You don't create a sheet controller instance yourself, but instead get it from the view controller managing the modal screen that you want to present:

if let sheet = viewController.sheetPresentationController {
    // customize the sheet...
}

present(viewController, animated: true)

The sheetPresentationController property will always return a non-nil value as long as the view controller's modalPresentationStyle is formSheet or pageSheet (which it is by default unless you override it)

Detents

A sheet can be configured with a list of so-called "detents"

Detents are positions at which the end of the sheet can rest after it's opened or resized

There are currently two system-defined detents available:

large, which is the normal full size of a sheet, as in previous versions of iOS (the sheet going up almost to the top of the screen on the iPhone)
medium, which is about half the standard height (the sheet filling bottom half of the screen on the iPhone)

You can set the detents property of a sheet to either or both of these:

// standard full-height sheet - the default value
sheet.detents = [.large()]

// a sheet that can be switched between half-height and full-height
// the order matters - the first detent is the initial position
sheet.detents = [.medium(), .large()]

// a sheet that is medium height and cannot be made larger
sheet.detents = [.medium()]

This can even be used on system modal views that normally expect to be presented in a full-height sheet, like the PHPhotoPicker:

func showImagePicker()
    let picker = PHPickerViewController()
    picker.delegate = self

    if let sheet = picker.sheetPresentationController {
        sheet.detents = [.medium(), .large()]
    }

    present(picker, animated: true)
}

func picker(_ picker: PHPickerViewController,
    didFinishPicking results: [PHPickerResult]) {

    // assign result to imageView.image
    // do not dismiss the picker
}

In this example:

calling the first function shows a system photo picker in a half-height sheet, in the bottom half of the screen
the top half of the screen shows the parent screen behind it, which displays the previously selected photo
when a photo is selected, we display it in the parent view, but we do not dismiss the picker sheet, allowing the user to quickly test different photos
the sheet can be closed by pressing the Cancel button inside the sheet or by dragging the sheet down
the sheet can also be resized by the user by dragging it up or down, switching between half height and full height

The sheet can also be resized by scrolling the scrollable contents inside the sheet, e.g. the grid of photos in the picker in this case

This is normally useful, but it might not be what you want

To disable this behavior, turn off this option in the sheet:

sheet.prefersScrollingExpandsWhenScrolledToEdge = false

In the example above, if we do not dismiss the dialog when the user makes a selection, it will work fine in "medium" half-height mode, but in the "large" full-height mode it might seem like the app is broken, because the user will not see the view behind the dialog

In such cases, it makes sense to programmatically adjust the detent position

You can do that by setting selectedDetentIdentifier:

func picker(_ picker: PHPickerViewController,
    didFinishPicking results: [PHPickerResult]) {

    // assign result to imageView.image

    if let sheet = picker.sheetPresentationController {
        sheet.animateChanges {
            sheet.selectedDetentIdentifier = .medium
        }
    }
}

The sheet.animateChanges does exactly what you'd expect – if you want to change the detent position instantly, without animation, then just set the property without using an animateChanges block

Sheets also automatically adjust when the software keyboard is shown or hidden – if the sheet is in half-height mode and the keyboard slides up, it will automatically move to the top of the screen, and back to the medium position when the keyboard goes away

Removing dimming overlay:

You can choose to hide the overlay covering the view behind the sheet

This makes the back view more visible, and also makes it possible to interact with it while the sheet is open, making the sheet non-modal

To hide the overlay, you set the largest detent level at which the dimming overlay should be hidden; at detent levels higher than this, the overlay will be visible

sheet.largestUndimmedDetentIdentifier = .medium

So:

setting it to .medium means that .medium is the largest detent with no overlay, and .large will still show an overlay
setting it to .large means that it will show no overlay in either .medium or .large
leaving it at the default value (nil) means the overlay will be shown in all positions

ℹ️ In the talk, the property was called smallestUndimmedDetentIdentifier, which didn't really make sense – the name was changed in one of the betas

Sheets in horizontal mode

When the iPhone is in horizontal orientation, presented view controllers are normally displayed in full screen mode, without the cut-off rounded edge at the top and covering full width of the device

You can now request to show a modal view as a sheet also in horizontal position by setting:

sheet.prefersEdgeAttachedInCompactHeight = true

The sheet will by default use the whole available width within in the safe area

If you want the sheet to have a custom width, you can additionally set:

sheet.widthFollowsPreferredContentSizeWhenEdgeAttached

You can customize the preferred sheet width using preferredContentSize, just like on the iPad

Additional customizations

You can show a "grabber" bar at the top edge of the sheet, like on the bottom sheet in the Maps app, in order to make it more obvious that a sheet can be dragged by moving the top edge:

sheet.prefersGrabberVisible = true

You can also customize the corner radius of the top corners of the sheet:

sheet.preferredCornerRadius = 20.0

Note that when the screen behind the sheet is shown in a stacked sheet, it will also use the same corner radius for consistency

Popovers adapting into sheets

It's possible to present the same view as a popover on the iPad and as a sheet on the iPhone and in partial-width modes on the iPad (automatically adjusting between the two as you resize the window)

To do that, customize the popover presentation controller and use adaptiveSheetPresentationController to configure its sheet presentation:

func showImagePicker(_ sender: UIBarButtonItem) {
    let picker = PHPickerViewController()
    picker.delegate = self

    // show the view as a popover by default
    picker.modalPresentationStyle = .popover

    // picker.sheetPresentationController is nil
    if let popover = picker.popoverPresentationController {
        popover.barButtonItem = sender

        // access the sheet controller of the popover
        let sheet = popover.adaptiveSheetPresentationController

        sheet.detents = [.medium(), .large()]
        sheet.smallestUndimmedDetentIdentifier = .medium
    }

    present(picker, animated: true)
}

Note that if modalPresentationStyle is set to .popover, the sheetPresentationController of the presented view will always be nil, so you need to access it through popoverPresentationController.adaptiveSheetPresentationController

Updating your app

How you can update your app for iOS 15:

review your app for areas that would benefit from medium-height or non-modal sheets
if you have any custom built half-height sheet views, replace them with built-in sheets

Improve access to Photos in your app

2022-05-28T16:10:23+02:00

Improvements to the Photo Picker

Privacy:

When an app doesn't ask for a Photo Library access and only presents the Photo Picker – which runs out of process and automatically has access to the whole library, from which the user can pick some photos for the app – it was possible for people to misinterpret this workflow and assume that the app itself had a full access to the whole photo library, even if it didn't

So now, in the Settings app, on the Photos Privacy screen, there is a new section for apps that only use the Photos Picker, titled "Apps with one-time photo selection"

Ordered selection:

In some apps, users may need to be able to select a few photos in a specific order (e.g. when adding them to a social media post)

In iOS 15, your app can configure the picker to show selection order as badges ① ② ③ etc.

To do that, set the selection property in the picker configuration to .ordered:

var configuration = PHPickerConfiguration()
configuration.selectionLimit = 0
configuration.selection = .ordered

Selection adjustment:

You can now preselect some photos in the picker to display user's previous selection that they can edit, adding additional photos or removing some previously selected ones

To preselect photos, pass an array of asset identifiers to the picker configuration:

let assetIdentifiers: [String] = previousSelection

var configuration = PHPickerConfiguration(photoLibrary: .shared)
configuration.selectionLimit = 0
configuration.preselectedAssetIdentifiers = assetIdentifiers

⚠️ One caveat: when the picker returns updated results, all photos that have been previously selected (and included in the preselection config you provide) will not include the item providers

So you need to keep the original list of photos with their data until after the updated picker results are returned

If the preselected picker dialog is cancelled, it will return the preselected assets you've provided with all item providers empty

In the delegate callback, you need to merge together the old results with the new results, taking the value from the old results for any photo that was selected previously (since there won't be an item provider in the new one):

func picker(
    _ picker: PHPickerViewController,
    didFinishPicking newResults: [PHPickerResult]
) {
    dismiss(animated: true)

    let existingSelection: [String: PHPickerResult] = self.lastSelection
    var newSelection = [String: PHPickerResult]()

    for result in results {
        let identifier = result.assetIdentifier!
        newSelection[identifier] = existingSelection[identifier] ?? result
    }

    self.lastSelection = newSelection

    // do something with selected assets
}

Reporting progress:

Some assets that the user selects in the picker may not be immediately available and need to be downloaded from the cloud first, which may take a moment (especially for videos) – this can happen if they're selecting something from their iCloud Photos and the "Optimize Storage" option is turned on

In that case, previously your app could only show a spinner indicator, since it didn't have access to information about the download progress

Now, the asset's item provider can give you a Progress object that you can use to track download progress and show a more appropriate loading UI:

let result: PHPickerResult = ...
let provider: NSItemProvider = result.itemProvider
let identifier: String = UTType.movie.identifier

if provider.hasItemConformingToTypeIdentifier(identifier) {
    let progress: Progress = provider.loadFileRepresentation(
        forTypeIdentifier: identifier
    ) { url, error in
        // Do something with the video, or handle the error
    }

    // Show progress in the meantime
}

New cloud identifier APIs

There are some categories of apps that require full or partial direct access to the user's photo library, e.g. photo editing apps, camera apps or apps whose purpose is to display the photo library in some specific way

Those apps use the PhotoKit APIs to access and modify the photo library

When using those APIs, assets are returned with unique identifiers that your app can save for later and then use again to retrieve the same assets on the next launch

These identifiers are specific to each device, even if some of the assets are synced between devices using iCloud Photos

If your app syncs some user-generated data that references user's photos between devices, and you want to access the same photos on multiple devices, you can use the new cloud identifiers that identify the same photo globally

There is a mapping between local identifiers and cloud identifiers and you can use a cloud identifier to look up a local copy of the photo

Cloud identifiers work even if the device is not signed into iCloud Photos (or even never was)

The new identifiers are represented by PHCloudIdentifier objects

How to use cloud identifiers:

1) Get some local photos from a device's library using CloudKit

2) Map local identifiers to cloud identifiers:

let cloudMappings = PHPhotoLibrary.shared()
        .cloudIdentifierMappings(forLocalIdentifiers: localIdentifiers)

for (localIdentifier, cloudMapping) in cloudMappings {
    if let cloudIdentifier = cloudMapping.cloudIdentifier {
        // save the cloudIdentifier for later
        resolved[localIdentifier] = cloudIdentifier
    } else {
        // handle the cloudMapping error
    }
}

3) Transfer the cloud identifiers to other devices using whatever communication method you want to use (iCloud / CloudKit etc.)

→ use stringValue to encode the identifier to a string

4) Look up local identifiers on each device based on the cloud identifiers in the same way:

let localMappings = PHPhotoLibrary.shared()
        .localIdentifierMappings(for: cloudIdentifiers)

for (cloudIdentifier, localMapping) in localMappings {
    if let localIdentifier = localMapping.localIdentifier {
        // add the localIdentifier to our resolved assets
        resolved[cloudIdentifier] = localIdentifier
    } else {
        // handle the localMapping error
    }
}

5) Use the local identifiers to fetch the assets and display them

Error handling:

The mapping in both directions may return an error instead of the identifier, so you need to be able to handle that case

There are two possible kinds of errors to take into account:

1) Identifier Not Found – if the app isn't able to find or access the relevant record:

let error = localMapping.error! as NSError

if error.code == PHPhotosError.identifierNotFound.rawValue {
    // couldn't find this photo, add it to the missing photos list
    missingPhotos.append(cloudIdentifier)
}

2) Multiple Identifiers Found – this can happen if the cloud state isn't completely in sync, and the app tries to find the image using content match and finds multiple copies; in this case, the error info will contain the list of matching identifiers under PHLocalIdentifiersErrorKey

let error = localMapping.error! as NSError

if error.code == PHPhotosError.multipleIdentifiersFound.rawValue {
    // found multiple matches, prompt the user to pick one
    let matches = error.userInfo[PHLocalIdentifiersErrorKey] as! [String]
    multipleMatches[cloudIdentifier] = matches
}

Note: looking up cloud identifiers takes some work, so use local identifiers for normal app interactions and map them to cloud identifiers only for syncing with other devices

Updates to the limited library

The limited library is when you access the user's photo library using PhotoKit after the user has requested to only share selected photos with your app

This is designed to work transparently for your app – all PhotoKit APIs work fine, but they work as if the photo library only contained those selected photos and nothing else

See last year's talk Handle the Limited Photos Library in Your App for more info

In iOS 15, apps can now create, fetch and update their own photo albums within the user's photo library when running in the limited library mode

Also, when you call photoLibrary.presentLimitedLibraryPicker() to let the user adjust a previous selection of photos shared with your app, you can now provide a callback which will be given a list of photos that have just been added to the selection:

let library = PHPhotoLibrary.shared()
library.presentLimitedLibraryPicker(from: controller) { addedIdentifiers in
   // fetch the newly added photos and use them in your app 
}

If your app still uses the old Assets Library framework that was deprecated in iOS 9 (ALAssets*) – please switch to PhotoKit and the Photos Picker, the old API will be removed in a future SDK

Craft search experiences in SwiftUI

2022-05-17T22:39:39+02:00

This year, SwiftUI adds a .searchable view modifier which adds a search UI appropriate for the current platform

Here's how it's used in the new Weather app written in SwiftUI:

NavigationView {
    WeatherList(text: $text) {
        ForEach(data) { item in
            WeatherCell(item)
        }
    }
}
.searchable(text: $text)

What happens behind the scenes is that the .searchable modifier puts the search field configuration into the Environment, and the views within the hierarchy look for the search field configuration there and apply it in the best way for the given platform

In this case, the NavigationView knows how to display the search field and will show it e.g. at the top of one of its panes on iOS, or on the right side of the window toolbar on macOS

If no view knows how to display the search field, a default rendering is used which puts it in the toolbar

A search field isn't very useful without another piece of UI that displays the search results, which is something that you need to implement yourself

The Weather app does it this way:

struct WeatherList: View {
    @Binding var text: String

    @Environment(\.isSearching) private var isSearching: Bool

    var body: some View {
        WeatherCitiesList()
        .overlay {
            if isSearching && !text.isEmpty {
                WeatherSearchResults()
            }
        }
    }
}

the .searchable modifier puts an \.isSearching key in the Environment, which you can check to see if a search field is focused somewhere on the screen, and show a different UI with search results if it is
the view checks the text property (which you need to pass yourself) and if it's not empty, displays a list of matching locations
the results list is displayed as an overlay on top of the standard UI – this is done so that when the user leaves the search field and the results list is hidden, the main UI below remains unchanged (unless they user has picked something from the results)

The second example is the "Colors" app:

NavigationView {
    Sidebar()
    DetailView()
}
.searchable(text: $text)

Here's how we implement search here:

when you apply .searchable to a two-pane NavigationView, it will add the search field to its first pane (the master view); if you want it to be added to the detail view, add the modifier to the detail view directly
on iOS and iPad OS, the Sidebar view uses the \.isSearching Environment key to display search results as an overlay over the list sidebar
on macOS, NavigationView puts the search field in the right side of the sidebar, automatically collapsing it into a button if the window is too small
on the Mac we display the search results instead in the main window pane, on top of the DetailView
on tvOS, we use a slightly different layout structure, adding a tab bar with one tab used for the standard navigation and the other for search, and putting the search UI in the second tab above a results list:

NavigationView {
    TabView {
        Sidebar()
        ColorsSearch()
            .searchable(text: $text)
    }
}

In most cases, the .searchable modifier applied to NavigationView will automatically render the search field in the appropriate place of the hierarchy

However, you always need to decide how and where to display the search results in a way appropriate for your app (which may vary between platforms)

In some cases you may want to use a different layout between platforms, as we do here in case of tvOS

Search suggestions

You can provide search suggestions for the search UI, which are examples of search queries that may be autocompleted into the field when the user picks them; suggestions give the user an idea of the types of things they can search for

Search suggestions also render in a platform-appropriate way:

as a menu popover below the field on macOS
as a complete search results screen on iOS
as a button that opens the list on watchOS

Suggestions are provided as an optional view builder closure that returns a set of buttons:

.searchable(text: $text) {
    ForEach(suggestions) { suggestion in
        Button {
            text = suggestion.text
        } label: {
            ColorsSuggestionLabel(suggestion)
        }
    }
}

There is also a shorthand version available, using the .searchCompletion modifier

The modifier should be applied to a non-interactive element like a Label, and it transforms it into a button which:

updates the search text, like the button above
dismisses the suggestions view

.searchable(text: $text) {
    ForEach(suggestions) { suggestion in
        ColorsSuggestionLabel(suggestion)
            .searchCompletion(suggestion.text)
    }
}

If you want to run a search query only when the user submits the search field, not live while they're typing (e.g. because it requires a request to a server), you can use the new .onSubmit modifier:

.searchable(text: $text) {
    ForEach ...
}
.onSubmit(of: .search) {
    fetchResults()
}

Direct and reflect focus in SwiftUI

2022-05-17T22:23:54+02:00

SwiftUI in most cases manages focus automatically on your behalf based on given platform's conventions

In more complex cases, where SwiftUI can't figure this out by itself, there are APIs that let you customize the focus behavior

Example situations:

focusing the text editor of a new note when the "New" button is pressed in Notes
moving focus from a vertical list of buttons in the sidebar to a horizontal list of items in the main area on tvOS
programmatically dismissing the keyboard on iOS

The @FocusState API

A view property marked @FocusState is a special type of state that changes depending on which of the view's subviews is currently focused:

enum Field: Hashable {
    case email
    case password
}

struct ContentView: View {
    @FocusState private var focusedField: Field?

    var body: some View {
        VStack {
            TextField("Email", text: $email)
                .focused($focusedField, equals: .email)

            SecureField("Password", text: $password)
                .focused($focusedField, equals: .password)
        }
    }
}

In this case, the Field type is a custom enum type, but you can also use strings, integers or any other Hashable type

Notice that the property is an optional, since it's set to nil if none of the fields is focused – in general, a @FocusState should always be optional

The binding is two-way – the value changes when the focus changes, but you can also move the focus by modifying the value

For example, you can move the focus back to the email field if the user tries to submit the form, but the email is invalid:

VStack {
    ...
}
.onSubmit {
    if !isEmailValid {
        focusedField = .email
    }
}

You can also dismiss the keyboard when the form is submitted by setting the value to nil:

VStack {
    ...
}
.onSubmit {
    if !isEmailValid {
        focusedField = .email
    } else {
        focusedField = nil
        logIn()
    }
}

Creating navigation targets (tvOS)

On tvOS, all navigation is done by moving focus and then selecting the focused element

You may sometimes want to be able to move focus between two parts of a screen with different content, and the default focus navigation will not work automatically if the two elements in two sections are not directly adjacent to each other

You can fix this by extending the effective focusable area of some elements like buttons to a larger area that is not normally focusable by itself

This is done using the new .focusSection API:

HStack {
    VStack {
        TextField("Email", text: $email)
        SecureField("Password", text: $password)
        SignInWithAppleButton(...)
    }
    .onSubmit { ... }
    .focusSection()

    VStack {
        Image(photoName)
        BrowsePhotosButton()
    }
    .focusSection()
}

When the .focusSection() view modifier is applied to a view like the VStack here, the view becomes capable of accepting focus as long as it contains any focusable subviews (the browse button)

Now, the user is able to move from the "Browse photos" button to the login sidebar on the left, even though the buttons in the sidebar aren't directly to the left of the button, and to move right from the email/password fields to the browse button, even though the button isn't directly to the right

What's new in SwiftUI

2022-05-15T00:48:11+02:00

Async images

Built-in support for loading images asynchronously:

AsyncImage(url: photo.url)

AsyncImage provides a default placeholder, but it can also be customized:

AsyncImage(url: photo.url) { image in
    image
        .resizable()
        .aspectRatio(contentMode: .fill)
} placeholder: {
    Color.blue
}

Custom animations and error handling:

AsyncImage(
    url: photo.url,
    transaction: .init(animation: .spring())
) { phase in
    switch phase {
        case .empty: ...
        case .success(let image): ...
        case .failure(let error): ...
    }
}

Improvements to lists

Pull to refresh:

Support for pull-to-refresh in lists on iOS:

List {
    ...
}
.refreshable {
    await items.reload()
}

Tasks:

Asynchronous task associated with a view:

.task {
    await items.load()
}

The task is run when the view appears and is automatically cancelled when the view is removed

This can be also used to load data from an async sequence that produces items continuously for the whole duration of the view being visible

See more about new concurrency features in "Discover concurrency in SwiftUI"

Bindings to list items:

A List can now accept a binding to an array property and will pass a binding to each specific item to the closure

This lets you use controls that require a binding (like TextField) within list items:

List($items) { $item in
    Text(item.title)
    TextField("Item", text: $item.text)
}

The previous solution for cases like this was to iterate over list indexes and bind to e.g. $list[index].text, but this causes SwiftUI to reload the list after every change anywhere

This is actually a Swift language change, so it works in all previous versions of SwiftUI too

Also works in ForEach and some other places

Customizing lists:

.listRowSeparatorTint(Color.blue) – customizing the color of separators

→ can be defined on the item to give each item a different separator

.listRowSeparator(.hidden) – hide separators completely

Same for customizing separators between sections: .listSectionSeparator, .listSectionSeparatorTint

Swipe actions:

You can now define custom swipe actions on list items:

CharacterProfile(character)
.swipeActions {
    Button {
        character.isPinned.toggle()
    } label: {
        Label("Pin", systemImage: "pin")
    }
    .tint(.yellow)
}

By default the action is on the right edge – use .swipeActions(edge: .leading) to put the action on the left edge

Add multiple .swipeActions modifiers to include swipe actions on both sides

Improvements on the Mac:

List style with alternating backgrounds, like in standard NSTableView:

.listStyle(.inset(alternatesRowBackgrounds: true))

New control for full-featured multi-column tables:

Table(characters) {
    TableColumn("<>") { CharacterIcon($0) }
      .width(20)
    TableColumn("Villain") { Text($0.isVillain ? "Villain" : "Hero") }
      .width(40)
    TableColumn("Name", value: \.name)
    TableColumn("Powers", value: \.powers)
}

Like a List, a Table presents a list of rows rendered from the given content, except a Table has a defined list of columns

Table supports single- and multi-row selection:

@State private var singleSelection: StoryCharacter.ID?
@State private var multiSelection = Set<StoryCharacter.ID>()

Table(characters, selection: $multiSelection) { ... }

You can sort the table by selected column – to support sorting in a column, provide a key-path to a model value which should be used for sorting:

@State private var sortOrder = [KeyPathComparator(\StoryCharacter.name)]

Table(characters, selection: $selection, sortOrder: $sortOrder) {
    TableColumn("Name", value: \.name)
    ...
}

Tables also support various visual styles and allow you to customize the appearance of each column

Integration with Core Data fetch requests:

Fetch requests now provide a binding to their sort descriptors, which lets you build a sortable multi-column table backed by a Core Data request:

@FetchRequest(sortDescriptors: [SortDescriptor(\.name)])
private var characters: FetchedResults<StoryCharacter>

Table(characters, selection: $selection, sortOrder: $characters.sortDescriptors) {
    ...
}

New @SectionedFetchRequest which lets you build a list divided into sections from a Core Data request:

@SectionedFetchRequest(
    sectionIdentifier: \.isPinned,
    sortDescriptors: [
        SortDescriptor(\.isPinned, order: .reverse),
        SortDescriptor(\.lastModified)
    ],
    animation: .default
)
private var characterSections: SectionedFetchResults<...>

The value of the property is a list of sections, each containing a list of items:

List {
    ForEach(characterSections) { section in
        Section(section.id)
        ForEach(section) { character in
            CharacterRowView(character)
        }
    }
}

Support for search in lists:

.searchable(text: $characters.filterText)

SwiftUI automatically adds a search field in the appropriate place depending on the platform, and may automatically provide suggestions based on the context

The modifier takes a binding to the entered filter text, which you should use to filter the results

See more in "Craft search experiences in SwiftUI"

Sharing data with other apps

Support for customized previews during drag & drop operation:

CharacterIcon(character)
.onDrag {
    character.itemProvider
} preview: {
    CharacterDragPreview(character)
}

New ways to import and export data to/from your app using Item Providers

Importing items from outside:

.importsItemProviders(StoryCharacter.imageAttachmentTypes) { itemProviders in
    guard let firstItem = itemProviders.first else { return false }

    Task {
        selectedCharacter.imageAttachment = await StoryCharacter.loadImage(from: firstItem)
    }

    return true
}

This lets you e.g. import an image taken with an iPhone's camera to a Mac app using the Continuity Camera feature

The new ImportFromDevicesCommands() helper lets you add the necessary menu entries (File > Import from iPhone or iPad):

WindowGroup { ... }
    .commands {
        ImportFromDevicesCommands()
    }
}

Exporting items to another app, e.g. to Shortcuts:

.exportsItemProviders(StoryCharacter.contentTypes) {
    if let selectedCharacter = selectedCharacter {
        return [selectedCharacter.itemProvider]
    } else {
        return []
    }
}

Graphics

SF Symbols:

Many new symbols

Two new rendering modes:

hierarchical – uses one color like monochrome, but adds multiple levels of opacity to emphasize key elements of the symbol
palette – gives you fine grained control over which parts of the symbol should be filled with what color

New SwiftUI colors: mint, teal, cyan, indigo, brown

Symbol variants like "filled" are now automatically chosen for you depending on the context

So if e.g. filled symbols should be used in tab bars, you can just use "person.circle" instead of "person.circle.fill" and the framework will choose the right variant automatically

This makes your code more reusable – e.g. you can use the same tab bar on macOS and it will use the outline versions of the same symbols there

More in "What's new in SF Symbols" and "SF Symbols in SwiftUI"

Canvas view:

A new view that gives you a rectangular canvas for free drawing, like custom NSViews/UIViews with drawRect: in AppKit/UIKit

You can use this to draw a specific custom element, or to draw multiple elements like a grid of small icons that don't need individual tracking and invalidation

Canvas { context, size in
    for symbol in symbols {
        let image = context.resolve(symbol.image)
        context.draw(image, in: symbol.rect)
    }
}

To provide accessibility to a Canvas element, you can use the new .accessibilityChildren modifier:

Canvas {
    ...
}
.accessibilityChildren {
    List(symbols) { Text($0.name) }
}

This provides a completely separate view hierarchy to accessibility interfaces which is more readable than the actual view

Timeline view:

TimelineView is a new view that generates different content based on the time of rendering

Can be used to build e.g. an animated screen saver for tvOS

TimelineView(.animation) {
    let time = $0.date.timeIntervalSince1970

    Canvas { context, size in
        // draw items differently based on the time parameter
    }
}

The timeline takes a TimelineSchedule parameter, which specifies when or how often it should be updated

Timeline view can also be used to provide a view for a Watch app which automatically updates when the app is in dimmed mode on always-on displays

Also in the dimmed mode on watchOS you can use the new .privacySensitive modifier to blur out elements which can include private information and should be hidden when the Watch is not being used:

VStack(alignment: .center) {
    Text("Favorite Symbol")
    Image(systemName: favoriteSymbol)
        .privacySensitive(true)
}

The .privacySensitive modifier can also be used in widgets – in this case some content may be hidden (blurred) when the widget is shown on the lock screen while the device is locked

More info in "What's new in watchOS 8" and "Principles of great widgets"

Materials:

You can now create views with material backgrounds (the ones with a translucent blur effect):

VStack {
    Text("Symbol Browser")
        .font(.largeTitle)
    Text("\(symbols.count) symbols")
        .foregroundStyle(.secondary)
        .font(.title2)
}
.padding()
.background(.ultraThinMaterial,
  in: RoundedRectangle(cornerRadius: 16.0))

When you use semantic styles like .foregroundStyle(.secondary) for the text, the content of a container with material background uses the appropriate "vibrancy" effect

The effect is applied to text, with the exception of emoji, which are excluded because this would render them an in incorrect way

On the Mac, system controls like sidebars and popups use the material background and now also apply the vibrancy effect to their content

More about canvas and materials in the "Add rich graphics to your SwiftUI app" talk

You can also read more about vibrancy and materials in my old blog post about the introduction of dark mode in macOS Mojave – "Dark Side of the Mac: Appearance & Materials"

Safe area inset:

There is a new view modifier .safeAreaInset that allows you to position a view on top of a ScrollView in a way that adjusts the scroll view's top/bottom insets so that all the content can be reached and the beginning/end isn't obscured by the overlay:

ScrollView {
    ...
}
.safeAreaInset(edge: .bottom, spacing: 0) {
    VStack {
        Text("\(symbols.count) symbols selected")
    }
    .padding()
    .background(.regularMaterial)
}

See more in the "Add rich graphics to your SwiftUI app" talk

Preview enhancements:

New .previewInterfaceOrientation modifier for choosing portrait/landscape orientation:

static var previews: some View {
    ColorList()
        .previewInterfaceOrientation(.vertical)

    ColorList()
        .previewInterfaceOrientation(.horizontal)
}

The Attributes Inspector in the preview now includes a section for accessibility attributes, and there is a new inspector tab that shows the accessibility properties of all view elements at a glance

Text and keyboard

Markdown support:

Text now automatically interprets Markdown formatting:

Text("**Hello**, [WWDC](https://developer.apple.com/wwdc21)!")
Text("`print(helloText)`")

This is built on top of the new Swift-native AttributedString in Foundation

It has a new rich, type-safe API for adding attributes, and even allows defining custom attributes that can be applied to text through the Markdown syntax

See more in "What's new in Foundation"

Localization:

Xcode 13 can now automatically extract strings for localization using the Swift compiler (see option in build settings)

See more in "Localize your SwiftUI app"

Dynamic Type:

You can now restrict some content to only a specified range of Dynamic Type text sizes – so that when the user picks one of the extra large sizes which would make your text too large to fit, it stays at the maximum allowed size:

Header("Today's Activities")
    .dynamicTypeSize(.large .. .extraExtraLarge)

Text selection:

You can enable selection of non-editable text:

Text(activity.description)
    .textSelection(.enabled)

This allows the user to select and copy any part of the text on macOS

On iOS this only allows copying the whole text though

New formatter APIs:

Foundation now includes new .formatted() APIs for various values like dates that allow you to specify the format in a type-safe way:

Text(date.formatted())

Text(date.formatted(date: .omitted, time: .shortened))

Text(date.formatted(
    .dateTime.weekday(.wide).day().month().hour().minute()))

There's even a list formatter API like ListFormatter:

people.map(\.nameComponents).formatted(
    .list(memberStyle: .name(style: .short), type: .and))

// => "Matt, Jacob, and Taylor"

Format styles can also be specified in TextField:

@State private var newAttendee = PersonNameComponents()

var body: some View {
    ...
    TextField("New Person", value: $newAttendee, format: .name(style: .medium))
    ...
}

The entered text is automatically validated and reformatted according to the specified format, and then parsed into a value of a correct type if possible

See more about the new format styles in "What's new in Foundation"

Text field prompts:

TextField now includes a prompt: parameter, which allows you to specify a placeholder value (an example text to enter) that is different from the label (which normally should specify the name or meaning of the field)

Text fields inside a Form on macOS now display with labels outside on the left, right-aligned to the text field, with the prompt (if any) shown as the placeholder

→ previously they were rendered like on iOS, with the label used as the placeholder inside the field

Text field submission:

New .onSubmit modifier allows you to specify an action to execute when a text field is submitted by pressing a physical or virtual Return key:

TextField(
    "New Person",
    value: $newAttendee,
    format: .name(style: .medium)
)
.onSubmit {
    people.append(Person(newAttendee))
}

This can also be applied to the entire form:

Form {
    TextField("Username", text: $viewModel.userName)
    SecureField("Password", text: $viewModel.password)
}
.onSubmit(of: .text) {
    guard viewModel.validate() else { return }
    viewModel.login()
}

You can now also configure the title of the Return key on the iOS keyboard (which gives it a blue background):

TextField(...)
.onSubmit {
    ...
}
.submitLabel(.done)

Keyboard accessory views:

Adding accessory views to the iOS keyboard – configure toolbar items with the placement of .keyboard:

Form {
    ...
}
.toolbar {
    ToolbarItemGroup(placement: .keyboard) {
        Button(action: selectPreviousField) {
            Label("Previous", systemImage: "chevron.up")
        }
        .disabled(!hasPreviousField)

        Button(action: selectNextField) {
            Label("Next", systemImage: "chevron.down")
        }
        .disabled(!hasNextField)
    }
}

→ on macOS the buttons will be shown in the Touch Bar instead

Focus state:

New property wrapper @FocusState that reflects the state of focus and provides precise control over it

A @FocusState property is bound to a field's focus using .focused

The value of the property will then show if and which view is currently focused, and you can move the focus by modifying the value

Simple form: declare a boolean property, and it will be set to true when the view is focused:

@FocusState private var newPersonIsFocused: Bool

var body: some View {
    TextField("New Person", value: $newAttendee,
        format: .name(style: .medium)
    )
    .focused($newPersonIsFocused)

    Button {
        newPersonIsFocused = true
    } label: {
        Label("Add Attendee", systemImage: "plus")
    }
}

In a more advanced version, the focus property can use any Hashable as its type, e.g. an enum, and be used to show which of the possible fields is currently focused:

private enum Field: Int, Hashable {
    case name, location, date, addAttendee
}

@FocusState private var focusedField: Field?

var body: some View {
    TextField("New Person", value: $newAttendee,
        format: .name(style: .medium)
    )
    .focused(focusedField, equals: .addAttendee)

    Button {
        focusedField = .addAttendee
    } label: {
        Label("Add Attendee", systemImage: "plus")
    }
}

This allows you to build any kind of complex screen with multiple focusable fields that you may want to move between programmatically

You can also use .focused to dismiss the keyboard on iOS by unfocusing a focused field:

@FocusState private var newPersonIsFocused: Bool

var body: some View {
    TextField(...).focused($newPersonIsFocused)
}

func endEditing() {
    newPersonIsFocused = false
}

See more about the new focus API in "Direct and reflect focus in SwiftUI"

Buttons

Support for bordered buttons on iOS:

Button("Add") { ... }
    .buttonStyle(.bordered)

Like all modifiers, this can be added to a larger container and applies to all buttons inside

Choose a color for a bordered button by specifying a tint:

Button("Buy") { ... }
    .buttonStyle(.bordered)
    .tint(.green)

Make buttons smaller or larger by using the .controlSize modifier, previously used only on macOS:

ForEach(entry.tag) { tag in
    Button(tag.name) { ... }
        .tint(tag.color)
}
.controlSize(.small)

→ this only seems to work for buttons at the moment

You can also make "prominent" bordered buttons which use a style that stands out more (stronger background):

Button("Submit", action: submitForm)
    .buttonStyle(.borderedProminent)

ℹ️ In the video, this is shown as .controlProminence(.increased). The .controlProminence modifier was replaced in a later beta with a separate .borderedProminent button style.

Buttons with a .large size can be used to build a menu of action buttons at the bottom of a screen/form, with the default button marked as prominent:

VStack {
    Button(action: addtoJar) {
        Text("Add to Jar").frame(maxWidth: 300)
    }
    .buttonStyle(.borderedProminent)
    .keyboardShortcut(.defaultAction)

    Button(action: addToWatchlist) {
        Text("Add to Watchlist").frame(maxWidth: 300)
    }
    .tint(.accentColor)
    .buttonStyle(.bordered)
}
.controlSize(.large)

Note: do not add .borderedProminent to every single button on the screen – this should be only used for single primary actions

→ this is the equivalent of a blue-colored default button in a dialog on macOS, one that is bound to the Return key shortcut, of which by definition there can be only one within a dialog

Buttons using the new styles like .controlSize, .borderedProminent and .tint automatically provide appropriate pressed states and automatically adapt to dark mode, Dynamic Type font sizes etc.

You can now specify a "role" for a button, currently .cancel or .destructive:

Button("Delete...", role: .destructive) { ... }

Marking a button as destructive adds a red foreground and/or background depending on the context, to emphasize that the action is potentially dangerous

Cancel and destructive buttons are often used in confirmation dialogs, which now have a new view modifier made specifically for them:

RowCell(entry)
.contextMenu {
    Button("Delete...", role: .destructive) {
        showConfirmation = true
    }
}
.confirmationDialog("Are you sure you want to delete \(title)?",
    isPresented: $showConfirmation
) {
    Button("Delete", role: .destructive) {
        deleteEntry(entry)
    }
} message:
    Text("Deleting \(title) will remove it from all of your jars.")
}

A confirmation dialog is shown as an action sheet on iOS, as a popover on the iPad, and as an alert on macOS

Another type of button is a menu button (available before):

Menu("Add") {
    ForEach(jarStore.allJars) { jar in
        Button("Add to \(jar.name)") {
            jarStore.add(buttonEntry, to: jar)
        }
    }
}
.menuStyle(.borderedButton)

ℹ️ In the video, this is shown as .menuStyle(.button). There is however no such menu style as .button – use .borderedButton on macOS and .borderlessButton elsewhere (or just keep the default).

A bordered button menu is rendered as a button with a down arrow on the right on macOS (a pull-down menu button)

A new option for button menus (both macOS and iOS) is to provide a "primary action":

Menu("Add") {
    ForEach(jarStore.allJars) { jar in
        Button("Add to \(jar.name)") {
            jarStore.add(buttonEntry, to: jar)
        }
    }
} primaryAction: {
    jarStore.add(buttonEntry)
}

This makes the button act as both a normal button and a menu:

on iOS, a normal tap runs the primary action, and a long press shows the menu
on macOS, the button uses a slightly different style and lets you either click the main button part for the primary action, or click the arrow on the right to show the menu (without a primary action, clicking either of the parts shows the menu)

You can also choose to hide the arrow indicator of a menu button on macOS using .menuIndicator:

Menu("Add") {
    ...
}
.menuStyle(.borderedButton)
.menuIndicator(.hidden)

Such menu button looks like a completely plain button, but still acts as a menu button:

without a primary action, it always shows the menu when pressed
with a primary action, it runs the primary action when pressed, and to show the menu you need to do a long-press like on iOS

You can use such buttons with a hidden indicator to decrease the visual prominence of the button, e.g. if there are a lot of them in the same view

A Toggle can now also be displayed as a toggle button:

Toggle(isOn: $showOnlyNewFilter) {
    Label("Show Only New", systemImage: "sparkles")
}
.toggleStyle(.button)

This works like a toggle button on macOS (NSButton.ButtonType.toggle) – one that cycles between an "on" state (with a blue background) and an "off" state when pressed; it works the same way on iOS – in the "on" state it's rendered as a bordered button with a blue background

There is also a new control that groups buttons, mainly toolbar buttons – ControlGroup:

ControlGroup {
    Button(action: archive) {
        Label("Archive", systemImage: "archiveBox")
    }
    Button(action: delete) {
        Label("Delete", systemImage: "trash")
    }
}

Toolbar buttons in a ControlGroup are displayed grouped together visually, as a kind of segmented control – as opposed to buttons in ToolbarItemGroup, which are only arranged side by side, but not joined visually in any way

ControlGroup with menu buttons can be used to create a pair of standard back/forward navigation buttons:

ControlGroup {
    Menu {
        ForEach(history) { ... }
    } label: {
        Label("Back", systemImage: "chevron.backward")
    } primaryAction: {
        goBack(to: history[0])
    }
    .disabled(history.isEmpty)

    Menu {
        ForEach(forwardHistory) { ... }
    } label: {
        Label("Forward", systemImage: "chevron.forward")
    } primaryAction: {
        goForward(to: forwardHistory[0])
    }
    .disabled(forwardHistory.isEmpty)
}

App essentials in SwiftUI

2022-05-09T22:47:08+02:00

You can now build the entire app using just SwiftUI

New APIs for defining apps and their scenes and views

Defining apps & scenes

An app consists of one or more "scenes"

→ see "Introducing Multiple Windows on iPad" from 2019 for an introduction to the UIKit scenes API

A scene roughly maps to a window:

on iOS, watchOS and tvOS the app can present one scene at a time
on iPadOS you can see multiple scenes from the same or different apps side by side
on macOS, each scene is displayed in a different window or inside tabs within a window

Each scene contains a view hierarchy and/or a hierarchy of child scenes

An app declaration looks similar to a view declaration:

it's also a lightweight struct
it implements the App protocol similar to View
the struct can include properties defining data dependencies, marked with wrappers like @State
the protocol requires a single body property which returns some Scene
inside the body definition, a DSL similar to the one for views is used to define the scene hierarchy:

@main
struct BookClubApp: App {
  @StateObject private var store = ReadingListStore()

  var body: some Scene {
    WindowGroup {
      ReadingListView(store: store)
    }
  }
}

The @main attribute is a new feature of Swift 5.3 – it allows a type to serve as the program entry point

This replaces the @NSApplicationMain/@UIApplicationMain or main.swift file

The code above is a complete declaration of the app structure

Even though it's just a few lines of code, this automatically provides quite a lot of functionality for free

Window Group

The most common type of scene is a WindowGroup, which defines the primary interface (main view) of your app

A WindowGroup displays its view in the expected way or each platform:

on iPhone, tvOS and watchOS it's shown as a single full-screen window
on the iPad it supports the new multi-window scene system
on the Mac it creates multiple Mac windows

The lifecycle of scenes depends on the platform

On iPadOS, the app switcher shows the app name and an optional scene title above each scene/window – this can be the document title, title of the open web page etc.

In latest SwiftUI, you can set that scene title using the new .navigationTitle("Name") view modifier, which replaces .navigationBarTitle (it sets both the title seen in the navigation bar and the scene name in the app switcher)

On the Mac, WindowGroup automatically provides a "File > New Window" command that opens a new window and a Window menu that lists all windows

The scene title is used as the window title in the title bar and the Window menu

Scene windows can also me merged into a single window with tabs by choosing Window > Merge All Windows

Scene storage

@SceneStorage is a new property wrapper that helps you manage persistence and restoration of view state in scenes

Provide a unique key under which the given value should be saved, and it will be saved and restored at appropriate times automatically

struct ReadingListViewer: View {
  @SceneStorage("selectedItem") var selectedItem: String?

  var body: some View {
    NavigationView {
      ReadingList(selectedItem: $selectedItem)
    }
  }
}

Document Group

Another basic kind of scene in the app definition is DocumentGroup, which defines documents in a document-based app:

@main
struct ShapeEditApp: App {
  var body: some Scene {
    DocumentGroup(newDocument: SketchDocument()) { file in
      DocumentView(file.$document)
    }
  }
}

See more in "Build document-based apps in SwiftUI"

Preferences windows

The last scene type, Settings, is Mac-only and defines standard Mac Preferences windows:

var body: some Scene {
  WindowGroup {
    ...
  }

  Settings {
    BooksSettingsView()
  }
}

The Preferences window is automatically linked to from the main app menu with the standard Cmd+, keyboard shortcut

Menu commands

The new .commands view modifier allows you to define menus and menu items with shortcuts for the macOS app menu:

WindowGroup {
  ...
}
.commands {
  BookCommands()
}

struct BookCommands: Commands {
  @FocusedBinding(\.selectedBook) private var selectedBook: Book?

  var body: some Commands {
    CommandMenu("Book") {
      Section {
        Button("Update Progress...", action: updateProgress)
          .keyboardShortcut("u")
        Button("Mark Completed", action: markCompleted)
          .keyboardShortcut("C")
      }
      .disabled(selectedBook == nil)
    }
  }

  private func updateProgress() { selectedBook?.recordNewProgress() }
  private func markCompleted() { selectedBook?.markCompleted() }
}

The commands are also used on the iPad and are displayed in the keyboard shortcuts help popup

The @FocusedBinding property wrapper used in this commands block allows you to selectively enable/disable some groups of commands based on your focus, similar to how the responder chain is used in AppKit or UIKit

See more about commands in the reference documentation

What's new in AppKit

2021-06-11T12:41:10+02:00

Design & control updates

There are design updates for some system controls:

popovers appear with an animation
sliders smoothly glide into position when clicked
smaller things like increased spacing between table sections or slightly wider toolbar buttons

Control tinting:

Individual controls like buttons, segmented controls or sliders can have a custom tint

Properties: NSButton.bezelColor, NSSegmentedControl.selectedSegmentBezelColor, NSSlider.trackFillColor

These properties have been introduced in macOS Sierra for Touch Bar controls; in macOS Monterey they’re functional also for normal app controls

This is useful for specific controls that need to have some kind of semantically meaningful color

→ e.g. a green “Accept Call” and a red “End Call” buttons in a video call app

Avoid confusion with the default button if there is one in the same view, since it will also be colorful

Make sure to indicate purpose with more than just the color (using a clear label or an icon), since some of your users may not be able to distinguish buttons by color

Push buttons:

Push buttons no longer highlight using the accent color on click – they behave just like e.g. segmented controls in macOS Big Sur

Don’t make assumptions about how the highlight state looks (e.g. drawing white text over a button that should be blue when pressed, but will now be light gray)

Instead, check the interior background style NSButtonCell.interiorBackgroundStyle:

.normal = colorless state
.emphasized = colorful state

The old “regular square button” aka “bevel button” has now been refreshed as “Flexible push style button” and can be used as a variable height push button

It supports the same kind of configuration as a regular push button, so it can serve as a default button and can be tinted

Its corner radius and padding now match other button styles

It can contain larger icons or multi-line text

The vast majority of buttons should still use the standard fixed height push button – the variable height button is meant for special cases

Localizing keyboard shortcuts

Some keyboard shortcuts should be localized for different keyboard layouts, because in some layouts they may be hard or impossible to type, or it may make sense to adapt them for right-to-left languages

E.g. Cmd + \ is not possible to type on the Japanese keyboard, which doesn’t have a backslash key

AppKit can now handle this for you

In macOS Monterey, the system automatically remaps such shortcuts to different ones that are more natural on the given keyboard layout

Shortcuts like Cmd + [ and Cmd + ] to go back and forward will be swapped in right-to-left languages

→ this applies to brackets, braces, parentheses and arrow keys

You can opt out using:

NSMenuItem.allowsAutomaticKeyEquivalentMirroring – for directional keys like brackets
NSMenuItem.allowsAutomaticKeyEquivalentLocalization – turns off all key localization, including mirroring
if you really don’t want to use this feature at all, you can also disable it completely in your app by implementing the NSApplicationDelegate method: applicationShouldAutomaticallyLocalizeKeyEquivalents(_:)

Update to SF Symbols

New version – SF Symbols 3

Expands capabilities of the SF Symbols app

Some symbols now have multiple layers that can be individually colored

Updated format for custom symbols – allows you to annotate distinct layers within an image

Big Sur had two coloring modes for symbols:

traditional monochrome template style, drawing the whole symbol using one accent color
a multicolor style that uses multiple colors that are predefined in the symbol itself

SF Symbols 3 in macOS Monterey adds two new rendering modes:

"hierarchical" – uses a single tint color, but draws different layers of the image in an emphasized or deemphasized way (lighter or darker than the base color)
"palette" – lets you assign each layer any custom color independently

APIs for the new rendering modes:

NSImage.SymbolConfiguration(hierarchicalColor: .red)
NSImage.SymbolConfiguration(paletteColors: […])
NSImage.SymbolConfiguration.preferringMulticolor()

Symbol variants:

There are also new APIs for mapping between symbol variants, e.g. outline heart symbol ⭤ filled heart symbol, or variants with circles etc.

Useful e.g. when you’re building a picker control that uses outline icons for unselected states and filled variants of the same icons for the selected item

To convert between variants, call e.g.: baseImage.image(with: .fill)

There are constants for each kind of symbol variant, and you can combine multiple variants together (e.g. circle + fill)

See “Design and build SF Symbols” for more info

TextKit 2

Huge update to the text system

TextKit is a great text engine with a long track record, used across all Apple systems

However, TextKit is a linear text layout engine, which means it typesets a block of text from the beginning to the end

There are a lot of use cases where a non-linear layout engine is more useful

TextKit 2 always uses a non-linear layout system

This means it can perform layout on a more granular level, which allows it to avoid some unnecessary work

For example, when you’re looking at a middle fragment of a long document, a linear layout system needs to process all text from the beginning up to the given fragment in order to render it; a non-linear system can start at the nearest start of a paragraph

The non-linear layout system also makes it easier to mix text with non-text elements, and improves performance for large documents

TextKit 2 provides a lot of customization points, which allow you to extend its behavior

The new version coexists with TextKit 1, you can choose which engine to use for each view

TextKit 2 has actually already been used in some system apps and controls in Big Sur

See “Meet TextKit 2” for more info

New Swift features

Swift 5.5 introduces some important new features for managing concurrency: async/await and actors

In AppKit, many asynchronous methods that return value through a completion handler now have variants that work with async/await:

@IBAction func pickColor(_ sender: Any?) {
  async {
    guard let color = await NSColorSampler().sample() else { return }
    textField.textColor = color
  }
}

The actor model is a great fit for a UI framework like AppKit where most APIs should be called on a single main thread

The macOS SDK now has a @MainActor property wrapper that marks all types that have to be accessed from the main thread

Classes such as NSView, NSView/WindowController, NSApplication, NSCell, NSDocument etc. are now marked with @MainActor

Code running in the main actor can freely call methods on other main actor types

However, code that isn’t running on the main thread needs to use async/await to run code on a @MainActor type

This is enforced at the compiler level, which lets you avoid common errors that happen when mixing concurrency with UI code

See “Meet async/await in Swift” and “Protect mutable state with Swift actors” for more info

AttributedString:

Swift 5.5 also adds a new value type AttributedString

It has type-safe attributes and a more swifty API for reading & writing attributes

You can easily convert between AttributedString and NSAttributedString

See “What’s new in Foundation” for more info

Updating NSViews:

There is a new Swift property wrapper which should reduce boilerplate around view properties

Let’s say we have a custom view class like this:

class BadgeView: NSView {
  var fillColor: NSColor
  var shadow: NSShadow
  var scaling: NSImageScaling
  …
}

These properties will usually need to have a didSet which updates properties like needsDisplay or needsLayout when they’re modified:

var fillColor: NSColor {
  didSet { needsDisplay = true }
}

The new @Invalidating attribute in NSView lets you easily specify which other view properties should be updated when the given property is modified:

@Invalidating(.display) var fillColor: NSColor

Properties that can be invalidated include: display, layout, constraints, intrinsic content size, restorable state

The marked property needs to be Equatable, since AppKit checks if the value was actually changed before triggering a view update

You can extend the invalidation system by conforming to NSViewInvalidating protocol

Shortcuts

iOS Shortcuts are now available on the Mac

Shortcuts appear in all the places where you can access services today – if your app supports services, it will also support Shortcuts

AppKit decides which shortcuts are available at the given place by checking the responder chain

It asks each responder whether it can provide or receive the type of data used by each shortcut

The types of data are represented by NSPasteboard.PasteboardType (usually a UTI)

To support shortcuts in a given responder object, implement the method:

func validRequestor(forSendType sendType: NSPasteboard.PasteboardType?,
                              returnType: NSPasteboard.PasteboardType?) -> Any

In that method return an instance of a type implementing NSServicesMenuRequestor (usually the same object):

protocol NSServicesMenuRequestor {
  func writeSelection(to pasteboard: NSPasteboard,
                              types: [NSPasteboard.PasteboardType]) -> Bool

  func readSelection(from pasteboard: NSPasteboard) -> Bool
}

Siri Intents

You can now use Siri Intents in a Mac app by adding an Intents Extension

You can also return an intents handler from the application delegate:

protocol NSApplicationDelegate {
  optional func application(_ application: NSApplication,
                        handlerFor intent: INIntent) -> Any?
}

The returned object should conform to an appropriate intent handler protocol, depending on the intent type

CloudKit Best Practices

2020-11-14T15:47:57+01:00

Short CloudKit overview

Apple uses CloudKit in their applications, so you can be confident that it scales, because for Apple it scales to hundreds of millions of users

CloudKit lets you focus on building your applications and not worry about building backend services for them

It provides your users automatic authentication – if the user is logged in to iCloud on their device, they don’t need to log in separately in your app

A CloudKit container now includes 3 databases:

public database for data visible to everyone
private database for a given user’s private data
new this year: shared database for user data that they decided to share with others

Zones:

public database has 1 default zone
private database has a default zone and it can have one or more custom zones
shared database includes some number of shared zones

A record always exists in a specific zone

Building an app with a sync feature

A common use case (e.g. Notes app):

user creates some data/records/documents on one of their devices
later, they open another device and they expect to see these documents there and be able to read/edit them

The way this is implemented is that CloudKit needs to be the source of truth, and the devices should maintain a local cache of all the app data and synchronize it using CloudKit

The recommended workflow:

1. On app launch, fetch changes from the server
2. Subscribe to any future changes
3. Fetch changes when you receive a push

Subscriptions:

Subscriptions let you ask the server to notify you whenever a change happens in the specified set of data. Previously you could subscribe to a specific query to a record type or to all changes in a zone.

New in iOS 10 – CKDatabaseSubscription – lets you subscribe to all changes in the whole database (private or shared).

Types of subscription notifications:

1. Silent push:

let notificationInfo = CKNotificationInfo()

// we only set this, but none of the UI related keys
notificationInfo.shouldSendContentAvailable = true

// do this once. no need to ask the user for push notifications permission,
// since we won't show any visible notifications
application.registerForRemoteNotifications(…)

2. Visual notification:

let notificationInfo = CKNotificationInfo()

// set any of these
notificationInfo.shouldBadge = true
notificationInfo.alertBody = "alertBody"
notificationInfo.soundName = "default"

// we need to prompt the user for push notification access:
application.registerUserNotificationSettings(…)
application.registerForRemoteNotifications(…)

Remember that push notifications can be coalesced, so you may only get one out of a series. Push notifications tell you that *something* has changed, but not necessarily every single thing that has changed.

Creating a subscription:

This only needs to be done the first time you launch an app – so we set a flag when we create a subscription and the next time we skip this part.

if subscriptionIsLocallyCached { return }

let subscription = CKDatabaseSubscription(subscriptionID: "shared-changes")

let notificationInfo = CKNotificationInfo()
notificationInfo.shouldSendContentAvailable = true
subscription.notificationInfo = notificationInfo

let operation = CKModifySubscriptionsOperation(
    subscriptionsToSave: [subscription],
    subscriptionIDsToDelete: []
)

operation.modifySubscriptionsCompletionBlock = { …
    if error != nil {
        …
    } else {
        self.subscriptionIsLocallyCached = true
    }
}

operation.qualityOfService = .utility
self.sharedDB.add(operation)

Listening for pushes:

turn on “Remote notifications” and “Background fetch” capabilities

func application(_ application: UIApplication,
    didReceiveRemoteNotification userInfo: [NSObject: AnyObject],
    fetchCompletionHandler completionHandler: (UIBackgroundFetchResult) -> Void) {

    let dict = userInfo as! [String: NSObject]
    let notification = CKNotification(fromRemoteNotificationDictionary: dict)

    if notification.subscriptionID == "shared-changes" {
        fetchSharedChanges {
              completionHandler(.newData)
        }
    }
}

Fetching the changes:

Steps:

ask in which zones something was changed (in shared db – because there may be new zones added when a new user shares some content)
ask which records have changed in each relevant zone

The server will not send you pushes about the changes you’re doing on this device, but you may receive those changes you’ve done on the list when fetching a delta download

fetchAllChanges: previously, in some operations you had to manually check for a flag that says there are more results waiting for you that you need to manually request (i.e. another page)

Now, CloudKit does the paging automatically for you if fetchAllChanges = true (which is the default)

func fetchSharedChanges(_ callback: () -> Void) {
    let changesOperation = CKFetchDatabaseChangesOperation(
        previousServerChangeToken: sharedDBChangeToken  // cached between runs
    )

    // this gives you IDs of changed zones
    changesOperation.recordZoneWithIDChangedBlock = { … }

    // this gives you IDs of deleted zones
    changesOperation.recordZoneWithIDWasDeletedBlock = { … }

    // this gives you the current change token which you need to save
    // may be called multiple times if the operation fetches multiple pages of content
    // save the token each time, so in case of an error you don"t repeat all work
    changesOperation.changeTokenUpdatedBlock = { … }

    changesOperation.fetchDatabaseChangesCompletionBlock = {
        (newToken: CKServerChangeToken?, more: Bool, error: NSError?) -> Void in

        self.sharedDBChangeToken = newToken
        self.fetchZoneChanges(callback)
    }

    self.sharedDB.add(operation)
}

fetchZoneChanges looks very similar, but fetches changes for a specific zone using CKFetchRecordZoneChangesOperation (you pass it a list of zones)

CloudKit best practices:

Automatic authentication:

CloudKit allows you to authenticate users (if they’re logged in to iCloud) without requiring any private information

You use the CloudKit user record for authentication

The user record is unique per container and never changes for that user

container.fetchUserRecordID(completionHandler: (CKRecordID?, NSError?) -> Void)

CKOperation API:

The convenience API works on single items and it’s simpler to use

Every convenience API call has a CKOperation counterpart that lets you perform an operation on a batch of records

The CKOperation also has other advantages – for example, it lets you:

set up dependencies between operations
specify quality of service and queue priorities
cancel operations that have started executing
specify if you want the operation to work over cellular network
limit the number of records or set of fetched keys
report progress
… and everything that NSOperation provides

(*) watch the Advanced NSOperations talk from 2015 to learn more about NSOperation

Quality of service:

QoS: select a quality of service (.userInteractive / .userInitiated / .utility / .background) depending on the task priority

default is .utility
.utility and below enable discretionary networking

Discretionary networking means that:

the system decides when is the best moment to run your request, so it may take longer than you expect
however, all network failures will be automatically retried for you
the request gets a timeout period of 7 days by default

Long lived operations:

If you have some operations that you want to continue/retry if they don’t manage to complete by the time your app is terminated, iOS 9.3 adds “CloudKit long lived operations”

Once you run such operation, the system will finish it even if the app is killed by the system or the user

The request is executed even if your app isn’t running, the result is cached and is returned to you once the app restarts

Results are kept by the OS for at least 24 hours

To use this API:

set isLongLived = true on CKOperation
save the operation’s operationID
use CKContainer.fetchLongLivedOperation(withId:) to get the operation object back
set completion blocks and run it again just like a new one

CKContainer.default().fetchLongLivedOperation(withID: myOpID) {
    (operation: CKOperation?, error: NSError?) in

    let fetchRecords = operation as! CKFetchRecordsOperation
    fetchRecords.fetchRecordsCompletionBlock = { … }

    CKContainer.default().privateCloudDatabase.add(fetchRecords)
}

Parent references:

A new type of reference added this year to help you better model data, especially with sharing in mind

If your app supports sharing, it’s recommended that you set the parent reference to create a hierarchy between records

Example: Album ⭢ list of photos

let photoRecord = CKRecord(recordType: "photo")
photoRecord.setParent(albumRecordID)

What this gives you: when the user shares the album record, the whole record hierarchy under this album (photos and other data) will also be shared

Types of errors:

1) Fatal error (bad request)

Error codes like:

.internalError
.serverRejectedRequest
.invalidArguments
.permissionFailure

→ in this case, you should show an alert to the user and tell them this can’t be executed

2) Connection/server error

Error codes like:

.zoneBusy
.serviceUnavailable
.requestRateLimited

→ in this case, check for CKErrorRetryAfterKey and retry after specified time

3) Errors that are returned before connection is even made

.networkUnavailable

you should monitor network reachability (SCNetworkReachability) and retry when the device is connected again

.notAuthenticated

when the user is not logged in and can’t access their private database
you should register at startup for CKAccountChangedNotification, and when it fires, recheck account status and update the UI

CloudKit Tips and Tricks

2020-11-11T18:39:56+01:00

Error Handling

Accounts:

To check the account status of the current user:

container.accountStatusWithCompletionHandler { status, error in … }

All APIs that fail because they require an authenticated user return CKErrorNotAuthenticated

You can now subscribe for CKAccountChangedNotification to be notified when account status changes

You should avoid showing alerts to the user about a missing account – simply disable parts of the UI that require an account, and reenable them when you get a notification that an account is now available

Network errors:

Network connection errors that you may sometimes get: CKErrorNetworkFailure, CKErrorServiceUnavailable, CKErrorZoneBusy, CKErrorRequestRateLimited

These errors include a key CKErrorRetryAfterKey in their user info dictionary that tells you how long you should wait before retrying

Handling conflicts:

If you try to save a record that has been modified in the meantime on the server (meaning: the record change tag you’re sending with the save request is outdated), you will receive the error CKErrorServerRecordChanged

There is no magic happening behind the scenes in such case, iCloud doesn’t make assumptions about how you want to resolve conflicts, you need to handle this yourself

However, the SDK provides you the necessary information in the userInfo:

CKRecordChangedErrorClientRecordKey – what you tried to save
CKRecordChangedErrorAncestorRecordKey – the original version
CKRecordChangedErrorServerRecordKey – what is currently on the server

Usually you will want to resolve the conflict by applying the same changes that you did on the original record to the current server version of the record

CloudKit Operations

Batch operations:

If you create and save a lot of records in one go, each of them will create a separate network request, and making a lot of requests in a short period means you’re likely to hit some kind of rate limit and they will be queued up

To avoid making multiple similar requests, you can use the CKOperation API

Almost every convenience API method that works on one record at a time has a CKOperation counterpart that allows you to work on a batch of records

For saving multiple records, use CKModifyRecordsOperation:

class CKModifyRecordsOperation: CKDatabaseOperation {
  convenience init(recordsToSave: [CKRecord]?, recordIDsToDelete: [CKRecordID]?)
}

Note: there are certain limits on how large batch operations you can make (number of items in the request and total request size)

This doesn’t include the size of saved binary assets, just the record field data

If you hit this limit, you will get the CKErrorLimitExceeded error

In that case, the best solution is usually to try to divide the batch in half and make two requests

If one or more records in the batch can’t be saved, you will get CKErrorPartialFailure

From this error’s userInfo you can get a dictionary with specific record errors under CKPartialErrorsByItemIDKey

In a standard zone, in such scenario some records will be saved and those with errors won’t

In a custom zone you can make an atomic update – in this case, in case of a problem with some of the records, no records will actually be saved, but instead you will get an error CKErrorBatchRequestFailed for those that could have been saved but weren’t

Queries:

If you expect a query to return a large number of records, but you only need a small number of them at a time, you can use the CKQueryOperation.resultsLimit property

Also available on CKFetchRecordChangesOperation, CKFetchNotificationChangesOperation

When limiting the number of records, you will usually also want to set the query's sortDescriptors to e.g. sort records by oldest or newest first

You can use the creationDate key which is automatically added to all saved records regardless of type

To implement pagination and get further pages beyond the first one, use the CKQueryCursor object that you get in response to the queryCompletionBlock callback

Then, initialize the next CKOperation passing it the cursor object in the argument to the initializer

If you don’t need all information contained in a record immediately, you can also use the desiredKeys property to only download the keys you want

E.g. download the record’s thumbnail image but not a full-size photo

Also available on CKFetchRecordsOperation, CKFetchRecordChangesOperation

Maintaining a local cache:

Let's say you want to keep some subset of all data completely cached on all local devices for quicker access (e.g. user’s personal notes)

You have two options:

use CKQueryOperation to fetch all records and synchronize them manually
make a custom zone and use delta downloads using CKFetchRecordChangesOperation

When saving fetched records to a local database, you should save CKRecord’s system fields like the change tag together with your own data

To do that, you can use encodeSystemFieldsWithCoder:

let data = NSMutableData()
let archiver = NSKeyedArchiver(forWritingWithMutableData: data)
archiver.requiresSecureCoding = true
record.encodeSystemFieldsWithCoder(archiver)
archiver.finishEncoding()

When restoring a record from the local storage, you don’t have to set all its data fields – it’s fine to only set those you want to change

To synchronize any changes from the server, create a subscription subscribing to a given record type using silent notifications, and use CKFetchRecordChangesOperation to fetch all recent changes when notified

Subscriptions (CKSubscription) are persistent queries on the server that send remote notifications about a relevant change – either in a specific record set (query subscription) or in the whole zone (zone subscription)

To get CloudKit subscription notifications, you need to follow the usual setup for push notifications:

have push notification capability enabled for your app
call registerForRemoteNotifications()
call registerUserNotificationSettings(…) if you want to show notifications to the user

To ask for silent subscription notifications, configure the CKNotificationInfo object appropriately:

set the shouldSendContentAvailable key
do not set any of the UI-related keys: alertBody, shouldBadge, soundName

Notification priorities: a notification is high priority if it has any UI keys set, otherwise it’s medium priority

For silent notifications, the UIApplicationDelegate will receive the following callback:

func application(application: UIApplication,
	didReceiveRemoteNotification: [NSObject: AnyObject],
	fetchCompletionHandler: (UIBackgroundFetchResult) -> Void) { … }

Remember that push notification delivery in general is “best effort” – pushes can be dropped if many are received in a short period of time or because of network issues

Silent notifications may also be additionally delayed if the system is waiting for better conditions

When you receive a notification, use CKFetchNotificationChangesOperation to check the server’s notification collection for any notifications you might have missed

You may want to use a UIApplication background task (beginBackgroundTaskWithName(…)) for syncing tasks

Interactive notifications: you can now make CloudKit notifications interactive (e.g. show action buttons) by setting the category key on CKNotificationInfo

Other performance tips

CloudKit is a highly asynchronous API, most operations require a network call and take some time to execute

You will often want to make a series of operations that have some dependencies between them

Things to keep in mind:

however you implement task handling, remember to always handle all errors
never block the main thread with an operation in progress

Don’t nest calls to the convenience API methods, creating a “callback hell”

Don’t use locks/semaphores to wait for an API call to finish

Instead, use the addDependency() API in CKOperation to add dependencies between operations:

let firstFetch = CKFetchRecordsOperation(…)
let secondFetch = CKFetchRecordsOperation(…)
secondFetch.addDependency(firstFetch)

let queue = NSOperationQueue()
queue.addOperations([firstFetch, secondFetch], waitUntilFinished: false)

Use the qualityOfService property on NSOperation to indicate which operations are something you need in the UI and which are low priority background operations

there used to be a usesBackgroundSession property on CKOperation too, but it’s deprecated now ⭢ use quality of service for this

QoS = .utility and .background use discretionary networking, use .userInteractive and .userInitiated for high priority tasks

Note: .background QoS is the default if you don’t change it!

update: now it's .utility

Advanced CloudKit

2020-11-03T14:57:14+01:00

CloudKit API is designed to be asynchronous, all calls return through a callback, because they all require a network connection

The main API (“operational API”) is based on NSOperation

You use it by creating special NSOperation objects for a given use case, e.g. CKFetchRecordsOperation, and specifying parameters and callbacks in their properties

Apart from the final result callback, you can set callbacks e.g. for reporting download progress or to get records one by one as they’re downloaded

Operation lifecycle (cancelling, suspending etc.) can be managed through standard NSOperation methods and NSOperationQueue

There are separete fetch/modify operation types for records, subscriptions, zones, users and notifications

You can set dependencies between operations (also if they’re in different queues), e.g. make a fetch operation and then a modify operation that needs to wait for the object to load

Operations can also have different priority levels

Starting an operation:

(ℹ️ Note: this wasn’t in the video, but it really should have been, because it's completely not obvious.)

How to start an operation once you prepare the CKOperation object:

1) Use the database’s built-in queue:

let fetchOperation = ...
CKContainer.default().privateCloudDatabase.add(fetchOperation)

2) Use your own operation queue and assign a reference to the database:

let operationQueue = NSOperationQueue()

let fetchOperation = ...
fetchOperation.database = CKContainer.default().privateCloudDatabase
operationQueue.addOperation(fetchOperation)

Custom zones

Custom zones (in the private database) let you compartmentalize data and add some special features

Records can’t be moved between zones or have cross-zone relationships

There are some operations that can only be done in custom zones:

Atomic commits:

Objects in the CloudKit database have relationships between them, and you want to keep all data consistent

Atomic commits are kind of like transactions in a relational database: batch operations succeed or fail together

Only available in the private database (because public database may be accessed by millions of users at the same time)

If an operation fails, you get a CKErrorPartialFailure response, with the user info containing info about errors on specific records (CKPartialErrorsByItemID)

Error CKErrorBatchRequestFailed means that this record wasn’t saved because of a problem with another record in the batch

Delta downloads:

Allow you to download a list of all changes since the last time the app was online, to let you perform a full sync

When a device connects, you can send a “change token” to the server asking for all changes since that version

This lets you implement an offline cache of the whole dataset and sync any changes when possible

To do that:

track all local changes
send changes to the server when connected
resolve conflicts
fetch server changes with CKFetchRecordChangesOperation
remember the received new server change token and send it back next time

Zone subscriptions:

Let you subscribe for notifications about any change in the zone

When you get a notification, you request a delta download

Advanced record operations

Record changes:

When you change some fields in a CKRecord, the changes are automatically tracked locally and only the changed fields are transmitted when you save it

By default CloudKit performs a “locked update”, which makes sure that the update is only saved on the server if the record wasn’t modified in the meantime by another client (this uses record change tokens)

After you execute a save, the server returns your record with a new change token – so you should use that returned version for any subsequent changes

Unlocked update ⭢ just overwrites server data regardless what is there

Locked update ⭢ if the record was changed in the meantime, you get back an error (CKErrorServerRecordChanged)

The userInfo of the CKErrorServerRecordChanged error contains info that lets you perform a 3-way merge:

CKRecordChangedErrorClientRecordKey – what you tried to save
CKRecordChangedErrorAncestorRecordKey – the original version
CKRecordChangedErrorServerRecordKey – what is currently on the server

Based on the values from these 3 copies of the record you can decide what state the record should be in, and then retry the save

You can modify the behavior with “save policies”:

SaveIfServerUnchanged ⭢ default, performs a locked update and sends only changed keys
SaveChangedKeys ⭢ unlocked update, sends only changed keys
SaveAllKeys ⭢ unlocked update, overwrites all keys in the record (note: this doesn’t affect keys that aren’t present in the local copy at all)

You should almost always use the default locked update (SaveIfServerUnchanged), use unlocked updates only to forcefully resolve serious conflicts

Use SaveAllKeys if the user requests to overwrite server data with local data

Partial records:

The desiredKeys field present in most operation types lets you specify that you only want to download selected keys from the server

This is useful if the whole record is very large and you don’t need all of it

Partial records can be normally saved after a change

CloudKit data modeling

References:

Forward reference ⭢ a parent object keeps an array of references to children in its property

Backward reference ⭢ only child objects have a reference to the parent

It’s recommended to use backward references – with a forward reference you need to update the parent object every time a new child is added, and you will run into conflicts if multiple clients are adding records

To get a list of all children using backward references, make a query for all child records with a predicate “owner = X”

References give you cascading deletes – when you delete the parent object, all child objects and their children are deleted

If an object has two parent references, it’s deleted when the first parent is deleted

When batch uploading a tree of objects, CloudKit makes sure that parent objects are uploaded first so that you don’t get inconsistent data during upload (important in the public database)

Your data objects:

CloudKit is only a transport mechanism and requires you to keep and manage your own local copy of all data

It’s recommended that you don’t subclass CK* objects to build your models – make your own completely independent model classes and translate to/from CloudKit objects when fetching and saving

Handling push notifications:

You need to remember that push notifications in general aren’t guaranteed to be delivered

The server only stores one push per client, so if you reconnect e.g. after a flight, you might miss some previous notifications

You can find pushes that you’ve missed in a “Notification Collection” where every notification is saved

The Notification Collection works kind of like delta updates – you ask for notifications since a given change token and you get a list of everything added since then

You can mark a notification as read, which notifies all other clients that they can ignore it

You should check the Notification Collection every time you get a push, since you never know what you might have missed (this doesn’t only happen with airplane mode)

The iCloud Dashboard

The dashboard lets you browse data saved by your app – the whole public database and the private database for your developer account (but not anyone else’s private database)

You can view saved records, run queries with any filters, and add new records

You can define roles in the public database and define for each model who can create/read/modify records (e.g. specify that records are publicly readable but only an admin can create them)

You will also see a list of all user ids and first/last names of those users that marked themselves as discoverable

Schema:

The CloudKit database has two separate “environments”: development and production

The schema for each record type is “just in time” during development, i.e. when you save a new type of record, it automatically creates a new schema for that record type, recording every field type, and when you save a record with a new field, it adds a field to the list

However, once you’re ready to release a new version of your app, you need to save the schema to production and at that point it’s locked – a production version of the app can’t save records or fields that aren’t defined in the schema

CloudKit also automatically creates indexes for each field in each record type – when you’re done with development, you can delete some indexes that you won’t need so they don’t waste space in the production database

Tips & tricks

Please handle all errors :)

Remember that you can get partial errors (when atomic commits aren’t used), so some records might be saved while others aren’t

Retry any “server busy” errors (CKErrorRetryAfterKey tells you the amount of time you should wait)

Don’t waste space in your users’ iCloud in private databases, they may be paying real money for it

Limits in the public database are mostly to prevent abuse, they should be fine for most normal use (the limits scale with the number of users)

iCloud Storage Overview

2020-11-01T20:52:45+01:00

iCloud Storage APIs allow you to store your app’s data in iCloud

System services sync your data automatically even when your app isn’t running

3 different types of storage:

key-value storage – simple storage for things like preferences, game state (“it’s so simple, we actually don’t have another session talking about it”)
document storage – a filesystem in the cloud scoped for your application, where you can store any kinds of files and folders, synced between devices; ideal for productivity apps like iWork
Core Data storage – an extension for Core Data that lets you store Core Data databases in the cloud [note: deprecated in 2016]

What iCloud handles for you:

account setup – users don’t need to create a new account for your service, they already have an iCloud account
APIs for your apps integrated into the OSX/iOS SDKs
server code you don’t have to write, for things like load balancing, replication, backup and recovery
the personnel handling the servers, support etc.

“If you happen to know some friends, who like writing server code that scales to hundreds of millions of users, send them our way – we’re hiring” :D

How it works:

Key-value storage:

Accessed through NSUbiquitousKeyValueStore

Lets you put simple plist-type values into the cloud

It talks to a key-value service running on the device which talks to iCloud on your behalf

Document storage:

Use UIDocument (iOS) / NSDocument (OSX) / UIManagedDocument (Core Data)

You can also use lower level file storage APIs like NSFileCoordination, NSFilePresenter, NSMetadataQuery

All these APIs (also the Core Data iCloud API) talk to OS’s document service which talks to the iCloud for you

You never actually interact with the iCloud servers yourself, you just use these APIs in the SDK and system services

How to enable iCloud in your project:

your app needs to be distributed through the App Store [note: no longer true for Mac apps]
enable the relevant entitlement: com.apple.developer.ubiquity-kvstore-identifier and/or com.apple.developer.ubiquity-container-identifiers

Working with Key Value Storage:

NSUbiquitousKeyValueStore

Lets you store simple plist values – strings, numbers, booleans, dictionaries and arrays of those

Similar API to UserDefaults

Simple conflict resolution: if two devices independently change or add a value for a given key, the latest change wins

Works even if iCloud isn’t configured – in this case it just acts as local user defaults that don’t sync

Improvements from last year’s initial release:

increased capacity – now up to 1024 keys, up to 1 MB per application (not part of the total user quota); it’s fine to have just one key of 1 MB
improved responsiveness (allows around 15 requests every 90 seconds)

How to set up:

// get a reference to the store
NSUbiquitousKeyValueStore *store = [NSUbiquitousKeyValueStore defaultStore];

// observe changes
NSNotificationCenter *center = [NSNotificationCenter defaultCenter];
[center addObserver:self
           selector:@selector(kvStoreDidChange:)
               name:NSUbiquitousKeyValueStoreDidChangeExternallyNotification
             object:nil];

// ask for any changes since the last launch
[store synchronize];

Making changes:

[store setObject:someObject forKey:@"someKey"];
[store setBool:YES forKey:@"someOtherKey"];

[store synchronize];

It’s recommended to also store another copy of the same data locally, so that you can do conflict resolution manually in case if just keeping the latest change isn’t always the right strategy for your app

Handling notifications about a change:

- (void)kvStoreDidChange:(NSNotification *)notification {
    NSDictionary *userInfo = [notification userInfo];

    // get change reason
    int reason = [userInfo objectForKey:NSUbiquitousKeyValueStoreChangeReasonKey];
    NSArray *changedKeys = [userInfo objectForKey:NSUbiquitousKeyValueStoreChangedKeysKey];

    // … store values locally, do conflict resolution etc.
}

Working with document storage:

Apart from your app’s container, each app has a separate “ubiquity container” (or iCloud container)

The app can put any files inside that container, and whatever is put there is synced with other devices via iCloud, kind of like Dropbox

When you put a file in the ubiquity container, the file is broken into chunks and the chunks that are new or modified are uploaded to iCloud – so if you only change a few bytes of the file, most of it doesn’t need to be uploaded again

Metadata about the file is uploaded first – info about the file name, type, size etc.

So every device knows about each file that’s uploaded, but it doesn’t necessarily have to download each file – the decision is made independently on the device depending on the platform and settings: OSX usually downloads all files if it has space, iOS only downloads files on demand

Once a file is downloaded to the device, all later changes are also automatically synced

Local peer to peer communication is used if possible – e.g. if you have a file on the Mac, your iPhone will copy it from the Mac instead of the iCloud network

Automatic conflict resolution – if a file is edited on two devices in parallel, the system picks a winner automatically, but your application gets access to both versions and can override it if needed

URL publishing: you can make the current version of the document public and available through a URL which you can share with others (if it’s changed later in the iCloud, the URL still downloads that previous version)

URLs are not permanent, they expire after some time

Detecting an iCloud account:

Unlike key-value storage, using this API requires that the user has an iCloud account

You can check for an “Ubiquity Identity Token” to see if they have an account configured

The token is anonymous so it doesn’t tell you anything about the user, but it will change if the user switches to another account (you also get a notification then)

The token is also unique to your app and to this specific device, so the same app will get a different token from that user on another device

id token = [[NSFileManager defaultManager] ubiquityIdentityToken];
if (token) {
    // cache the token
    // the next time the app launches, check if it has changed
}

// register for the identity changed notification
NSNotificationCenter *center = [NSNotificationCenter defaultCenter];
[center addObserver:self
           selector:@selector(handleUbiquityIdentityChanged:)
               name:NSUbiquityIdentityDidChangeNotification
             object:nil];

When the account changes, clear any local caches specific to this account and refresh the UI

To access the ubiquity container, you ask for the container URL – note that the container will be created on demand the first time you ask for it; this should ideally not be called on the main thread

dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
    containerURL = [fileManager URLForUbiquityContainerIdentifier:nil];
});

Types of documents you can store in the document storage:

normal files, also symlinks
directories of files
packages – bundles of files that act as a single document
Core Data stores

File extended attributes are also synced

Watch out for filesystem case sensitivity issues – users running on a Mac might have a case-sensitive filesystem

For packages, iCloud updates only the files from a package that have been changed, but it handles updates to the whole package atomically, so you will not get a package in an inconsistent state

Core Data:

Useful for so-called “shoebox style applications”, like iPhoto or iTunes, which work with a single database in app’s own format

The Core Data store remains local and only change logs are uploaded to iCloud

Not recommended to use binary and XML stores, because in those cases every change modifies the whole file (only use those for small data sets that don’t change often) – use SQLite stores for iCloud sync instead

UIManagedDocument – a subclass of UIDocument for managing Core Data stores that supports syncing them with iCloud

Note: NSPersistentDocument, the AppKit equivalent, does not support iCloud

Designing your document format for iCloud:

Design with network efficiency in mind – don’t write a lot of changes very often

Keep in mind any possible differences between platforms

Plan for future app upgrades – include version number in the format and keep compatibility if possible

Beware of sync loops – when one instance of the app receives a change, merges it and writes back the result, and the other side does the same and triggers a change in the first copy again

“And you have two versions of the app playing ping-pong with the user’s iCloud account”

Avoid making rapid changes to the file, e.g. updating some position tag while the user is scrolling the document

Don’t put the last open date into the document itself, so that opening it doesn’t count as making a change

Use iCloud for user data only: don’t put any caches, temporary files or auto-generated content there

Think about privacy when allowing the user to publish a document: don’t include any sensitive info or things they might not be aware they’re publishing (e.g. undo history) in the publicly accessible view

APIs:

NSFileManager

NSFileCoordinator & NSFilePresenter

NSMetadataQuery – use a live metadata query to be notified of new files and changes before the file contents are downloaded

NSDocument & UIDocument

UIManagedDocument

NSDocument/UIDocument handle most of the integration with iCloud for you:

using the ubiquity container
coordinating with the OS
tracking files and their versions
resolving conflicts

Tips:

subclass native document types
use the default auto-save behavior
if the app provides a prepopulated Core Data store on first launch, use a migration instead of copying a packaged store file
track documents using NSMetadataQuery
if it makes sense for your app, manually control conflict resolution (UIDocumentStateInConflict); avoid user involvement if possible

Tips for debugging:

test with multiple devices
monitor network traffic
use Airplane Mode to create conflicts artificially
there will be a configuration profile available that makes the document service log additional messages
developer.icloud.com – a web tool that shows you all iCloud storage on your account from various apps [note: not available anymore, replaced with CloudKit dashboard, but it only shows CloudKit data]

Introducing CloudKit

2020-11-01T20:52:04+01:00

CloudKit lets you write client applications without having to build and host a server part to handle things like database, accounts or push notifications

Usage is free for the developer up to pretty big limits

CloudKit gives you more direct access to iCloud servers

It’s the framework that’s used behind the scenes by iCloud Photo Library and iCloud Drive

Uses the same iCloud account as iCloud documents or key-value storage

Two types of databases:

public – accessible to everyone
private – private data of a specific user

It’s only a transport technology, it does not deal with local data persistence – you need to decide how you store the data that you load from the cloud

To enable iCloud in your app, set it up in the Capabilities tab in Xcode just like with other iCloud APIs

Containers:

Each app’s data is kept in a separate container (CKContainer)

Containers give you the safety that your app’s data will not be mixed with someone else’s app’s data

A container’s ID needs to be unique in the whole iCloud, so use reverse-domain style identifiers

By default each app has one container of its own, but apps can additionally use shared containers

Containers are managed by the developer through the WWDR portal

Databases:

A container contains one shared public database for everyone, and separate private databases for each user

An app running on the device has access to one public and one private database (CKDatabase)

The database is the initial entry point to CloudKit (from a container)

CKDatabase *publicDatabase = [[CKContainer defaultContainer] publicCloudDatabase];
CKDatabase *privateDatabase = [[CKContainer defaultContainer] privateCloudDatabase];

Private database:

requires a logged in iCloud account
data stored counts against the user’s iCloud account quota
default permission for data is user readable
the data your users store in your app’s CloudKit container is *not* accessible to you

Public database:

can be accessed anonymously even if the user isn’t logged in
data stored counts against the developer’s app quota
default permission for data is world readable
permissions can be customized using iCloud Dashboard Roles

Records:

A record (CKRecord) is a single “object” in the CloudKit database, essentially a list of key-value pairs

Records have a Record Type (~ table name)

There is no defined up front schema, you can just save a record of any type with any keys and the schema will be updated based on that

→ note: this only works in development, the schema is fixed in production, see "Advanced CloudKit"

Records can have metadata: who created it & modified it and when, also includes a “change tag” (version id) – for determining if two sides have the same version of a record

Record values can be: strings, numbers, dates, NSData, CLLocation, CKReference, CKAsset, arrays of any of these

- (instancetype)initWithRecordType:(NSString *)recordType;
- (id)objectForKey:(NSString*)key;
- (void)setObject:(id)object forKey:(NSString *)key;
- (NSArray *)allKeys;

Subscripts also work:

CKRecord *party = [[CKRecord alloc] initWithRecordType:@"Party"];
party[@"start"] = [NSDate date];

Record zones:

Records are grouped within a database inside “zones” (CKRecordZoneID)

The public database has one zone, the private database has one default zone, but it can have additional custom zones

Record identifiers:

Record identifier (CKRecordID) is a tuple grouping: a “record name” + zone ID

You can provide a recordID when creating a record instance

If you don’t provide a recordID, a random UUID will be assigned

References:

A reference (CKReference) is a pointer from one record to another, as an id of the “parent” record contained in a child record’s field

References allow you to do cascade deletes, deleting child records when parent is deleted

You can create a reference from a CKRecord object or from a CKRecordID if you know the ID but don’t have the object in memory

Assets:

An asset (CKAsset) is an unstructured piece of data, basically a binary file

Assets are downloaded and uploaded from/to files on disk, not from memory

An asset is always owned by a record, and is deleted when the record is deleted

Transport of assets is optimized so that only the minimal amount of data is transferred

APIs:

There are two different APIs for managing CloudKit data: “operational API” and “convenience API”

The operational API has every possible operation you might need, the convenience API is more convenient

Start with the convenience API, use operational API for tweaking and overriding options if needed

CloudKit APIs for saving/fetching data are asynchronous – there is no SDK-managed local data, everything needs to go over the network unless you manually cache it

In CloudKit it’s absolutely necessary to properly handle error cases – every network call can fail and your app needs to be prepared for this

Convenience API:

[publicDatabase saveRecord:obj completionHandler: { … }];
[publicDatabase retchRecordWithID:recordID completionHandler: { … }];

Queries:

For any large database, or the shared public database, you shouldn’t try to keep a copy of the whole database on disk and sync all of it, but instead fetch what you need on demand – for this you can use queries

A query (CKQuery) allows you to fetch a list of records matching some conditions

Query can specify a RecordType, NSPredicate and optionally NSSortDescriptors

A subset of NSPredicate language is supported, if something is not supported you’ll get an exception

Predicates such as “equal”, “greater than”, “distance to location”, string tokenizing, and OR / AND are supported

[publicDatabase performQuery:query inZoneWithID:nil completionHandler: { … }];

Subscriptions:

If you repeatedly run the same query, polling for the same data, you can ask the server to run the query for you and notify you immediately when a new record is added

You do that by creating a subscription (CKSubscription)

A subscription includes: RecordType, NSPredicate and push configuration (CKNotificationInfo)

Your app is notified of changes through a push notification with some additional data

CKSubscription *subscription =
  [[CKSubscription alloc] initWithRecordType:@"Party"
                                   predicate:predicate
                                     options:CKSubscriptionOptionsFiresOnRecordCreation];

[publicDatabase saveSubscription:subscription completionHandler: { … }];

Pushes are handled through the usual push API:

- (void)application:(UIApplication *)application
    didReceiveRemoteNotification:(NSDictionary *)userInfo;

Build a CKNotification object from the user info:

CKNotification *cloudKitNotification =
    [CKNotification notificationFromRemoteNotificationDictionary:userInfo];

NSString *alertBody = cloudKitNotification.alertBody;

if (cloudKitNotification.notificationType == CKNotificationTypeQuery) {
    CKQueryNotification *queryNotification = cloudKitNotification;
    CKRecordID *recordID = [queryNotification recordID];
}

Handling user accounts:

Your application does not get direct access to any user identifiers like iCloud email address

Instead, in each container each user is represented as a unique ID within that container that doesn’t change unless the user switches to another account

The same user will have a different ID in a different CloudKit container

The ID is an instance of CKRecordID

[[CKContainer defaultContainer] fetchUserRecordIDWithCompletionHandler: { … }];

Each user has a user record representing them (which is almost like any other record) with their user id and record type = CKRecordTypeUserRecord, one in the private database, and another with the same ID in the public database

You can set and read any key-value data on this record like on other records

However, these records aren’t created by you and can’t be queried to get a list of users

[publicDatabase fetchRecordWithID:userRecordID completionHandler: { … }];

User discovery:

You can ask the user to allow you to make them discoverable by other users (they get a request popup)

If they agree, they can be looked up by user ID, specific email, or by fetching a list of all users matching your user’s contacts from the address book (this doesn’t give your app access to the address book itself, just a list of matching users)

You get back record IDs, first & last names of users, but no emails

[defaultContainer discoverAllContactUserInfosWithCompletionHandler: { … }];

Returns an array of CKDiscoveredUserInfo objects with properties userRecordID, firstName, lastName

[note: this API has been replaced since then with a new one that returns CKUserIdentity objects]

When to use CloudKit vs. other APIs?

CloudKit doesn’t replace or deprecate any existing iCloud APIs [yet ;P], it’s just an additional tool

Key-value store:

asynchronous, small amounts of data
mostly for application preferences

iCloud Drive:

works on files and folders
on OSX it makes a full offline cache of the drive
good for document-centric apps

iCloud Core Data:

built on top of iCloud Drive
good for keeping private, structured data (custom databases) in sync
note: the whole data set is downloaded to each device

CloudKit:

good for sharing public data between users, both structured data and large files
good for large data sets where not every device needs to have a copy of the whole database
for attaching some data to the user’s identity and sharing info between users that know each other
more low-level, your app is in control of when any information is downloaded or uploaded to the iCloud servers, and has responsibility for handling sync

SwiftUI on watchOS

2020-09-08T13:56:24+02:00

SwiftUI offers apps some capabilities that were not possible before, e.g. swipe to delete and reordering in lists, or an easy way to do custom graphics and animations

Fully integrated with WatchKit, both ways

SwiftUI allows you to use the same code on all platforms

However, Apple Watch is a very special platform; a watchOS app should not be just a tiny version of the iOS app, it should be specifically designed for the Watch by only picking the right elements of the experience

Building an Apple Watch app is building the whole experience, not just the main app, but also complications, notifications, Siri interface – depending on the app

Use subclasses of WKHostingController to embed SwiftUI views in an interface controller that WatchKit can use

.font(.system(.headline, design: .rounded)) – uses a rounded version of San Francisco

.listRowPlatterColor(topic.color) – sets the color of the list cell background

.listStyle(.carousel) – a list design which centers the currently focused item on the screen

.onMove { } – enables drag to reorder

.onDelete { } – enables swipe to delete

For notification UI, inherit from WKUserNotificationHostingController

When a notification is received (didReceive(_:)), the view body is automatically invalidated and reloaded

Using digital crown:

Fluent scrolling between the beginning and the end:

.digitalCrownRotation($binding, from:, through:)

→ lets you create some kind of custom scrollable container

Discrete values:

.digitalCrownRotation($binding, from:, through:, by:)

→ for building interfaces where e.g. some value moves up or down by 1 when scrolling

Going around in a circle:

.digitalCrownRotation($binding, from:, through:, by:, sensitivity:, isContinuous: true)

→ sensitivity says how fast it rotates

.focusable(true) – lets the user switch focus between elements; digital crown events go to the focused item

Explore logging in Swift

2020-09-07T18:31:28+02:00

Xcode 12 introduces new APIs for the unified logging system:

import os

let logger = Logger(subsystem: "com.example.Fruta", category: "giftcards")
logger.log("Started a task")

It's now much easier to pass arguments to logs using new Swift interpolation than the old os_log API with C-style formatters:

logger.log("Started a task \(taskId)")

Like in os_log, it does not generate the resulting formatted string at the moment of logging, but stores an optimized representation and defers formatting to a later moment

You can pass any values like numeric types, ObjC types that implement description and any type conforming to CustomStringConvertible

Non-numeric data is private by default:

logger.log("Paid with bank account \(accountNr)")
// -> Paid with bank account <private>

To actually display the values, use the privacy: parameter:

logger.log("Ordered smoothie \(smoothieName, privacy: .public)")

You can also log private data in an obfuscated form, but hashed in such a way that each value gets its unique hash which you can track through a chain of logs:

logger.log("Paid with bank account: \(accountNumber, privacy: .private(mask: .hash))")
// -> Paid with bank account <mask.hash:'CSvWylJ63...'>

Collecting recent logs from a connected device to a file:

log collect --device --start "2020-06-22 9:41" --output fruta.logarchive

Log levels:

debug – useful only during debugging
info – helpful but not essential for troubleshooting
notice (default) – essential for troubleshooting
error – expected errors
fault – unexpected errors, assumptions that weren’t true, potential bugs

The Logger has a separate method for each log level:

logger.debug(…)
logger.error(…)
// etc.

Take into account that not all logs are persisted after the app finishes execution, some can only be live streamed

debug ⭢ not persisted by default

info ⭢ saved to memory, only persisted if collected using log collect before they disappear

notice ⭢ persisted up to a storage limit, older messages are purged after some time

error, fault ⭢ persisted for a longer time than notice messages (typically a few days)

The level also affects logging performance: debug logs are the fastest, error and fault are the slowest

It’s safe to call even some slower code within log messages that will not be logged – the code isn’t run unless the log is enabled:

logger.debug("\(slowFunction(data))")

Logger provides a number of built-in formatters that let you customize how an interpolated value is displayed:

logger.log("\(cardId, align: .left(columns: 5))")
logger.log("\(seconds, format: .fixed(precision: 2))")
logger.log("\(data, format: .hex, align: .right(columns: 4))")

+ others like decimal, exponential, octal

Existing os_log(…) function also accepts the new interpolating parameters (when running on latest OS versions)

Measuring Performance Using Logging

2020-09-07T18:01:44+02:00

Signposts – a new feature of the os_log API

Useful for debugging performance issues

Integrated with Instruments, which can visualize activity over time using signposts

Signposts allow you to mark the beginning and end of a piece of work and mark it with some kind of label

import os.signpost

let refreshLog = OSLog(subsystem: "…", category: "…")

os_signpost(.begin, log: refreshLog, name: "Fetch Asset")
// …do actual work…
os_signpost(.end, log: refreshLog, name: "Fetch Asset")

Ranges of signposts with different names can overlap – e.g. you can have one signpost covering the whole process and smaller signposts covering specific single tasks that it consists of:

os_signpost(.begin, log: log, name: "Load Data")

os_signpost(.begin, log: log, name: "Fetch Asset")
// …
os_signpost(.end, log: log, name: "Fetch Asset")

os_signpost(.begin, log: log, name: "Parse JSON")
// …
os_signpost(.end, log: log, name: "Parse JSON")

os_signpost(.end, log: log, name: "Load Data")

If you run multiple tasks of the same kind, to let the system differentiate between them and know which begin matches which end, you can add a “signpost ID”:

os_signpost(.begin, log: log, name: "Load Data")

for asset in assets {
    let spid = OSSignpostID(log: log)

    os_signpost(.begin, log: refreshLog, name: "Fetch Asset", signpostID: spid)
    // …do actual work…
    os_signpost(.end, log: refreshLog, name: "Fetch Asset", signpostID: spid)
}

os_signpost(.end, log: log, name: "Load Data")

You can also pass your model object when generating the signpost ID – then it will always use the same signpost ID for the same object, and you don't have to store the signpost object, just your model:

let spid = OSSignpostID(log: log, object: asset)

There is also an option of passing an additional string argument to begin/end to provide some context (e.g. to differentiate between different possible ways to finish an activity, like success/failure)

The string also accepts format arguments like os_log:

os_signpost(.begin, log: log, name: "Compute Physics",
    "Calculating %{public}s: %d %d %d %d", description, x1, y2, x2, y2)

Apart from marking the beginning and end, you can also mark specific points in time during the process using the .event signpost type:

os_signpost(.event, log: log, name: "Fetch Asset",
    "Received chunk of data, size %d", size)

Signposts are very optimized internally, they’re built to minimize the time spent when logging, same as the whole os_log API

This means you can emit a lot of signposts even in a very tight window, when investigating a performance bottleneck

If you still really want to enable or disable some signpost logs based on some conditions, you can swap your logger object with OSLog.disabled:

let refreshLog: OSLog

if ProcessInfo.processInfo.environment.keys.contains("SIGNPOSTS_REFRESH") {
    refreshLog = OSLog(…)
} else {
    refreshLog = .disabled
}

To conditionally disable some expensive code that is only useful for debugging, you can check the signpostsEnabled property:

if refreshLog.signpostsEnabled {
    let information = collectInfo()
    os_signpost(…, information)
}

All APIs are also available in C & ObjC:

#include <os/signpost.h>

os_signpost_interval_begin()
os_signpost_interval_end()
os_signpost_event_emit()
os_signpost_id_t
OS_LOG_DISABLED

Use the formatter %{xcode:size-in-bytes}u to let Xcode & Instruments know that the logged value is a byte size of some data

→ This is one of so called “Engineering types” – find more in the Instruments Help menu, in the Instruments developer guide

Instruments:

Use the “os_signpost” instrument to profile using signposts

After recording some data, you can see the signpost names in the sidebar on the left and signpost ranges with the optional begin/end comments marked on the chart

In the bottom pane you can see count and duration statistics, grouped by category, signpost, id and comment

Clicking the arrow button next to a specific message row shows you a list of all instances of this specific message (selecting them highlights them on the timeline)

For metadata like logged byte sizes of downloads, you can choose “Summary: Metadata Statistics” to see total/min/max/avg of each type of value

Live streaming signpost logs to Instruments (“Immediate mode”) adds some overhead, so if you want to avoid that while debugging some performance-critical code, click and hold the Record button to access recording options and change mode to “Last n seconds”

Points of interest:

Points of interest is a special log category of OSLog

It’s meant for logging important actions taken by the user, like opening some specific screen

Normal os_log logs and signpost logs logged to this category appear in a special separate Instruments timeline, which lets you visualize what was happening in the app at the moment when something happened on other charts like CPU usage

Custom Instruments packages:

You can now build your custom Instruments packages, defined as an XML file in a separate target, which appear as a new kind of template when starting Instruments

This lets you process and present collected signpost data in a different way that makes sense for the specific problem you’re analyzing