DEV Community: Gualtiero Frigerio

Introducing NavigationPath in SwiftUI

Gualtiero Frigerio — Fri, 10 Jun 2022 16:17:13 +0000

I’m happy to share the news that this year at WWDC Apple finally gave us the navigation API for SwiftUI we’ve been waiting for since the framework was introduced in 2019.
If you follow me you may know I like programmatic navigation and I was never a fan of the API the team released with the first version of SwiftUI.
There are 3 blog post I wrote in the past: Navigation in SwiftUI deprecated, Navigation in SwiftUI and Dynamic navigation in SwiftUI where I proposed my solution to have a dynamic navigation in SwiftUI. Since the new API requires iOS 16 the latter post will still have reason to exist for compatibility reasons, the previous will stay on my blog just as a memento of what SwiftUI was at its very beginning.
In this article I’ll focus on stack based navigation and how you can perform it via NavigationStack and NavigationPath.

As usual, all you code of this post can be found on GitHub

NavigationStack

Suppose you want your app to have a stack based navigation. In the past you could have a NavigationView with a modifier, like this

NavigationView {
    // place your content here...
}
.navigationViewStyle(.stack)

while now you can simply use

NavigationStack {
    // place your content here...
}

in order to go to another view, you can still use NavigationLink

NavigationStack {
    NavigationLink("go to second page", destination: {
        SecondPage()
    })
}

and specifying a destination, you can go directly to that view.
This resemble the old API and as I wrote before I’m not a big fan of having NavigationLink decide the destination in its initialiser.
You know have another option, using the navigationDestination modifier.
Take a look at ContentView in my sample project

struct ContentView: View {
    var body: some View {
        NavigationStack {
            VStack {
                Text("Navigation stack")
                    .padding()
                NavigationLink("NavigationLink to enter first page", value: Destination.firstPage)
                    .padding()
                NavigationLink("NavigationLink to enter second page", value: Destination.secondPage)
                    .padding()
                List(1..<3) { index in
                    NavigationLink("Nav Link \(index)", value: index)
                }
            }
            .navigationDestination(for: Destination.self) { destination in
                ViewFactory.viewForDestination(destination)
            }
            .navigationDestination(for: Int.self) { index in
                Text("index \(index)")
            }
        }
    }
}

there are two NavigationLink, but this time you can specify a value, not a destination, so the destination view is not bound to the specific NavigationLink like before.
When you tap on a NavigationLink, the navigationDestination modifier gets the value, and in this example I have a ViewFactory to return the next view based on the value of the Destination enum for the first two links.
You can have multiple navigationDestination modifiers, for different types. In the example above I have a List with 2 NavigationLink based on an Int index, and there is a navigationDestination for Int that will take care of those links.

I think I like this approach, but there is something even better that allow us to go back and forth in our navigation hierarchy.

NavigationPath

All right, the title says introduction to NavigationPath so it is finally time to talk about it 🙂
The new NavigationStack can be initialised with a Content, like we did in the previous example, or with a NavigationPath.
The great thing about using a NavigationPath, is that we can have it stored int an ObservedObject, so by changing the variable we are able to programmatically push and pop View into the stack!
That’s great news, because it allow us to have a good separation of concerns, now our view can have a Button to trigger an action, but an object (in my example I call it the Coordinator) can take care of business logic and decided what to push on the stack or to pop to a previous view or even to the root.

This is the main entry point of our sample app:

@main
struct SwiftUI4App: App {
    @ObservedObject var coordinator = Coordinator()

    var body: some Scene {
        WindowGroup {
            NavigationStack(path: $coordinator.path) {
                MainView()
                    .navigationDestination(for: Destination.self) { destination in
                        ViewFactory.viewForDestination(destination)
                    }
            }
            .environmentObject(coordinator)
        }
    }
}

we have a NavigationStack, and this time it is initialised with a NavigationPath stored into our Coordinator.
For simplicity, I put the coordinator as environment object, so the Views will have access to it. In a more complex app architecture you have have different coordinators, but for the sake of this article a shared one will do just fine.
Just like the previous sample, we have the navigationDestination modifier with the Destination enum, and our ViewFactory returns the View for that particular destination.
But how do we push a view? Let’s have a look at MainView

struct MainView: View {
    @EnvironmentObject var coordinator: Coordinator

    var body: some View {
        VStack {
            Text("This is the initial screen")
                .padding()
            Button {
                coordinator.tapOnEnter()
            } label: {
                Text("Button to enter")
            }
        }
    }
}

all we need is a Button and a call to the coordinator.
This is the coordinator

class Coordinator: ObservableObject {
    @Published var path = NavigationPath()

    func gotoHomePage() {
        path.removeLast(path.count)
    }

    func tapOnEnter() {
        path.append(Destination.firstPage)
    }

    func tapOnFirstPage() {
        path.append(Destination.secondPage)
    }

    func tapOnSecondPage() {
        path.removeLast()
    }
}

it has @Published variabile of type NavigationPath. To push a View we simply append a new value to the NavigationPath, and this triggers the call to navigationDestination with the value we just pushed.
And what about popping views?
To get back to the previous View, you can call removeLast. The function has an optional parameter, so you can pop more than a View at a time.
To get back to the root view controller you can simply call removeLast(path.count) so it removes everything.

If, like in this example, your path depends on a single type, you can use an Array instead of NavigationPath and it works the same way.

class Coordinator: ObservableObject {
    @Published var path = [Destination]()

    func gotoHomePage() {
        path.removeLast(path.count)
    }

    func tapOnEnter() {
        path.append(Destination.firstPage)
    }

    func tapOnFirstPage() {
        path.append(Destination.secondPage)
    }

    func tapOnSecondPage() {
        path.removeLast()
    }
}

NavigationPath uses type erasure so you can have a collection of different types, in this case remember you’ll need multiple navigationDestination modifiers to handle all the possible types.

I like it! By putting a NavigationStack into our main entry point and place the necessary navigationDestination modifiers there, we are able to control the navigation of our app in a single point. Our Views only need to have Buttons to trigger actions on a coordinator, and by changing a single variable we can push and pop views into the stack.
For multiple columns layout you can use NavigationSplitView, but this is outside the scope of this article.

That’s it for now. I hope you are as excited as I am about the new additions to SwiftUI, stay tuned for more post about those and happy coding! 🙂

Original post

Take screenshots of SwiftUI Views

Gualtiero Frigerio — Sat, 29 Jan 2022 18:09:14 +0000

We all love SwiftUI for its declarative approach and the ability to quickly prototype a UI.
Its simplicity has a few drawbacks though, for example we don't have full access to the actual view in the hierarchy. One of the problems is taking a screenshot of a particular View.
If we deal with UIKit, getting a screenshot is quite easy, iOS 10 introduced UIGraphicsImageRenderer and before that UIGraphicsBeingImageContext was the way to go, but what about SwiftUI?
There is no built-in function to to accomplish the task, so we're stuck. If only we had access to a UIView we could take the screenshot from there... well, good news, we can!
As you probably know, you can use SwiftUI and UIKit together in your project, there's a way to display a UIKit view inside a SwiftUI View and viceversa.
That's how we'll get access to a UIKit view, we'll use UIViewRepresentable to add a UIView inside our SwiftUI View or UIHostingController to do the opposite, then we'll take the screenshot from it.
I'm going to show you two slightly different ways to capture a screenshot. The first requires less code by using UIHostingController and is easier in my opinion, but may not work in every scenario.

The alternative approach relays on UIViewRepresentable, and at least in my tests is more reliable especially with dynamic content.
As usual, all the code you find here is available on GitHub

UIHostingController

The first approach is the easiest and if it works for you, I guess it is the best to implement.
It involves UIHostingController, a UIKit view controller that can be seen as a container for a SwiftUI View. UIHostingController is necessary when you have a UIKit based app and want to start including SwiftUI into it, once you have your SwiftUI View you can create a UIHostingController by specifying a View as the rootView, and you can then add it as a child view controller, present it or access its UIView and add it as a subview into your UIKit hierarchy.
We can use this particular UIViewController to take a screenshot of a SwiftUI View. I found the code sample below on Hacking with Swift and if you didn't know about this great resource about Swift development do yourself a favour and check it out, it is full of amazing content!



extension View {
    func snapshot() -> UIImage {
        let controller = UIHostingController(rootView: self)
        let view = controller.view

        let targetSize = controller.view.intrinsicContentSize
        view?.bounds = CGRect(origin: .zero, size: targetSize)
        view?.backgroundColor = .clear

        let renderer = UIGraphicsImageRenderer(size: targetSize)

        return renderer.image { _ in
            view?.drawHierarchy(in: controller.view.bounds, afterScreenUpdates: true)
        }
    }
}

this extension adds a snapshot function to a SwiftUI View. As you can see it embeds the current View into a UIHostingController, then access its view (a UIView) property and use it to render a UIImage via UIGraphicsImageRenderer.
That's clever, and it usually works.
Take a look at this example, from my GitHub project



struct ToggleView: View {
    @State var darkBackground = false

    var body: some View {
        VStack {
            Toggle(isOn: $darkBackground) {
                Text("Switch to dark")
                    .foregroundColor(darkBackground ? .white : .black)
            }
            .background(darkBackground ? .black : .white)
            Button {
                snapshot().saveToDocuments()
            } label: {
                Text("Take screenshot ToggleView")
            }
        }
    }
}

the saveToDocuments function is an extension of UIImage that saves it as a PNG in your app's Document folder, so when you're testing the screenshot on the simulator you can have a copy of the PNG and open it on your Mac for checking that everything is fine.
As I said, this approach usually works, but there are some scenario where it doesn't. Let's see a couple of them, staring with ToggleView. If you take a screenshot with the extension using UIHostingController it always works, you see a black background when the toggle is on and a white one when is off.
Try embedding ToggleView inside another View though



struct ViewContainingToggle: View {    
    var body: some View {
        VStack {
            Text("ToggleView inside orange border")
            ToggleView()
                .border(.orange, width: 2.0)
            Button { 
                snapshot().saveToDocuments()
            } label: {
                Text("Take screenshot ViewContainingToggle")
            }
        }
    }
}

This is a screenshot taken by the simulator

And this is the image taken by snapshot.

As you can see, the image will always have the toggle switched off, and a white background as you can see in the image above. We took the picture of the right view, but with the wrong value.
What's going on? SwiftUI is recreating ToggleView, and since darkBaground default value is false, the View is initialised with a white background and the Toggle off.
Let's see another example with an EnvironmentObject passed to a View down in the hierarchy



struct ViewWithEnvironment: View {
    @EnvironmentObject var sharedModel: SharedModel

    var body: some View {
        VStack {
            Text("Counter = \(sharedModel.counter)")
            Button {
                self.snapshot().saveToDocuments()
            } label: {
                Text("Take screenshot inside ViewWithEnvironment")
            }
        }
    }
}

This time, is even worse. If you take a screenshot inside the view, you can get your nice PNG with the correct value of counter.
But try embedding the view inside another one and take a screenshot from there, you'll get a Fatal error



SwiftUI/EnvironmentObject.swift:70: Fatal error: No ObservableObject of type SharedModel found. A View.environmentObject(_:) for SharedModel may be missing as an ancestor of this view.

Looks like the EnvironmentObject is missing.
You could solve this problem by passing the environmentObject modifier to the UIHostingController like this:



func snapshot(environment: SharedModel) -> UIImage {
    let controller = UIHostingController(rootView: self.environmentObject(environment))
    let view = controller.view

    let targetSize = controller.view.intrinsicContentSize
    view?.bounds = CGRect(origin: .zero, size: targetSize)
    view?.backgroundColor = .clear

    let renderer = UIGraphicsImageRenderer(size: targetSize)

    return renderer.image { _ in
        view?.drawHierarchy(in: controller.view.bounds, afterScreenUpdates: true)
    }
}

and it would work, no crashes this time. But as you can see, this isn't a great workaround. What if you have different environment objects? The function should be made as generic as possible, and you'd still have the problem we saw before with Toggle.
Luckily, we can come up with a different implementation that allows us to capture a screenshot of the current view without reloading part of it.

UIViewRepresentable

The second approach, that should solve the problems listed above, involves UIViewRepresentable.
First, let's understand what it does.
UIViewRepresentable is, quoting from the documentation, a wrapper for a UIKit view that you use to integrate that view into your SwiftUI view hierarchy.
Once your own struct implements this protocol, you'll be able to add it as a View into your SwiftUI hierarchy.
SwiftUI will then call makeUIView and you'll return your UIKit view there.

Let's see an example from one of my projects FeedReader where I needed to display a WKWebView inside a SwiftUI project



struct WebKitView: UIViewRepresentable {
    let url: URL
    let delegate:WKNavigationDelegate

    func makeUIView(context: Context) -&gt; some UIView {
        let webView = WKWebView()
        webView.navigationDelegate = delegate
        webView.load(URLRequest(url: url))
        return webView
    }

    func updateUIView(_ uiView: UIViewType, context: Context) {

    }
}

struct ArticleView: View {
    @ObservedObject var viewModel:ArticleViewModel

    var body: some View {
        if viewModel.showError {
            Text(viewModel.errorMessage)
        }
        ZStack {
            if let url = viewModel.article.url {
                WebKitView(url: url, delegate: viewModel)
            }
            if viewModel.showSpinner {
                ProgressView()
            }
        }
    }
}

I can put WebKitView inside a ZStack, and a WKWebView will be rendered there.
So we have a way to add a UIKit view to our SwiftUI View, and we're going to use it for the screenshot.
Once we have access to a UIView, we can easily get its parent view, and we can go up in the hierarchy as much as we like.
The idea is adding a UIViewRepresentable to the View we want to take a screenshot of, then access the UIKit view, find the common ancestor and render the UIImage via UIGraphicsImageRenderer.
Let's start by creating a UIViewRepresentable



typealias ScreenshotMakerClosure = (ScreenshotMaker) -> Void

struct ScreenshotMakerView: UIViewRepresentable {
    let closure: ScreenshotMakerClosure

    init(_ closure: @escaping ScreenshotMakerClosure) {
        self.closure = closure
    }

    func makeUIView(context: Context) -> ScreenshotMaker {
        let view = ScreenshotMaker(frame: CGRect.zero)
        return view
    }

    func updateUIView(_ uiView: ScreenshotMaker, context: Context) {
        DispatchQueue.main.async {
            closure(uiView)
        }
    }
}

class ScreenshotMaker: UIView {
    /// Takes the screenshot of the superview of this superview
    /// - Returns: The UIImage with the screenshot of the view
    func screenshot() -> UIImage? {
        guard let containerView = self.superview?.superview,
              let containerSuperview = containerView.superview else { return nil }
        let renderer = UIGraphicsImageRenderer(bounds: containerView.frame)
        return renderer.image { (context) in
            containerSuperview.layer.render(in: context.cgContext)
        }
    }
}

the struct is initialised with a closure, and this closure has a UIView as a parameter. This is necessary because we need the SwiftUI View to have access to the UIView in order to take the screenshot.
makeUIView creates the UIView ScreenshotMaker, the frame is CGRect.zero as we don't need to draw anything there, we just need that UIView to access the ancestors.
When updateUIView is called, we can finally call the closure we were given. This is how we pass the UIView to SwiftUI. In order to have a convenient way to instantiate a new ScreenshotMakerView let's add an extension to View



extension View {
    func screenshotView(_ closure: @escaping ScreenshotMakerClosure) -> some View {
        let screenshotView = ScreenshotMakerView(closure)
        return overlay(screenshotView.allowsHitTesting(false))
    }
}

This function created a new ScreenshotMakerView with the closure, then returns a new View that will be attached to the one calling this function. What overlay does, is placing the new View in front of the one calling it. Note that we need to add allowHitTesting and set to false, otherwise the new view even if is transparent would block the interaction with the original view.
I hope you've followed me so far, but I guess an example is the best way to explain what's going on.
Let's change one of the previous views that didn't work with the first approach



struct ViewContainingToggle: View {
    @State var screenshotMaker: ScreenshotMaker?

    var body: some View {
        VStack {
            Text("ToggleView inside orange border")
            ToggleView()
                .border(.orange, width: 2.0)
            Button {
                if let screenshotMaker = screenshotMaker {
                    screenshotMaker.screenshot()?.saveToDocuments()
                }
                else { // first approach implementation with UIHostingController
                    snapshot().saveToDocuments()
                }
            } label: {
                Text("Take screenshot ViewContainingToggle")
            }
        }
        .screenshotView { screenshotMaker in
            self.screenshotMaker = screenshotMaker
        }
    }
}

this is the View that contains ToggleView. As we found out, ToggleView was initialised when we tried to take the screenshot with the snapshot extension.
Now we can add .screenshotView to the View we want to screenshot, then we have the closure returning the ScreenshotMaker, and once we have this object we can save it in a @State var. This is not mandatory, if you like you can take the screenshot inside the closure and it will be taken immediately, without waiting for a Button tap like in the example.
The same approach works for the view with the EnvironmentObject as well.

Screenshot taken by the simulator

Screenshot made by ScreenshotMaker

as you can see this time the screenshot was taken with the dark background. Note that the button is in the pressed state, so you may want to exclude a button from the screenshot or find a way to have it in the right state.

If you still have a minute, I want to explain to you how it works.
Try placing a breakpoint on the function screenshot of ScreenshotMaker.
Let's see a simple example with only a VStack containing a Text.



po self
<inspectswiftui.screenshotmaker: 0x7f7b3991d620;="" frame="(0" 0;="" 31.5="" 20.5);="" layer="<CALayer:" 0x6000037ba1c0="">&gt;

po containerView 
&lt;_TtC7SwiftUIP33_A34643117F00277B93DEBAB70EC0697116_UIInheritedView: 0x7f7b39918f50; frame = (524.5 456; 31.5 20.5); anchorPoint = (0, 0); autoresizesSubviews = NO; userInteractionEnabled = NO; layer = <calayer: 0x6000037bb7a0="">&gt;

po containerSuperview
&lt;_TtGC7SwiftUI14_UIHostingViewGVS_15ModifiedContentVS_7AnyViewVS_24NavigationColumnModifier__: 0x7f7b3991d140; frame = (0 0; 1080 810); gestureRecognizers = <nsarray: 0x600003959530="">; layer = <calayer: 0x6000037ba340="">&gt;

self is the UIView ScreenshotMaker, the one we placed on top of the VStack we want to take a screenshot of. Its frame is 31.5 20.5, the size of a simple text of 4 letters.
containerView is the common ancestor of ScreenshotMaker and the VStack, in this case the frame is exactly the one we want to capture as the origin is the right one, in the middle of the screen.
Finally, we have the superview that contains the whole screen except for the navigation bar, in this example is an iPad in landscape mode. We want to be precise, so we only capture the frame of the SwiftUI view were we placed .screenshotView as you have seen in the image.
If you need to capture the whole view, put .screenshotView on the NavigationView.



struct MainView: View {
    @StateObject var sharedModel = SharedModel()

    var body: some View {
        NavigationView {
            VStack {
                Text("Counter = \(sharedModel.counter)")
                Button {
                    sharedModel.counter += 1
                } label: {
                    Text("Increment counter")
                }
                Spacer()
                NavigationLink(destination: ContainerView()) {
                    Text("Show container view")
                }
                Spacer()
                NavigationLink(destination: ToggleView()) {
                    Text("Show view with toggle")
                }
                Spacer()
                NavigationLink(destination: ViewContainingToggle()) {
                    Text("Show view containing ToogleView")
                }
                Spacer()
            }
            .screenshotView { screenshotMaker in
                // take a screenshot only of the VStack without the title
                screenshotMaker.screenshot()?.saveToDocuments()
            }
            .navigationTitle("This is the title")
        }
        .screenshotView { screenshotMaker in
            // take a screenshot of the NavigationView including the title
            screenshotMaker.screenshot()?.saveToDocuments()
        }
        .navigationViewStyle(StackNavigationViewStyle())
        .environmentObject(sharedModel)
    }
}

Screenshot of VStack

Screenshot of NavigationView

the pictures above show two different screenshots. The one in the left is taken by placing .screenshotView on the VStack, the one on the right with .screenshotView on the NavigationView including the title.

Conclusion

In this article I've shown you two ways of capturing a screenshot of a SwiftUI view.
I think it would be great to have some sort of API from Apple to perform such a task, because especially the second approach I described here is not completely safe to use. It works today, it may break in future SwiftUI releases if Apple changes the way UIViewRepresentable is inserted into the hierarchy.
If the example doesn't work for you please reach out on Twitter or on Github so I'll be able to tweak it if necessary.

If you want to include the code in your project feel free to copy the struct and classes from the GitHub project I linked above, or you can add the package ScreenshotSwiftUI via SPM.

Happy coding :)

Custom URL schemes in a WKWebView

Gualtiero Frigerio — Wed, 29 Dec 2021 09:12:19 +0000

Sometimes you may need to display HTML content in your app, even if you don’t use a framework to make hybrid apps.
Usually you can just open the mobile version of your website to show a particular page, but what if your app need to work offline? Turns out it is still a requirement, even in the era of 5G.
This article is about handling custom URL schemes inside a WKWebView, and I’ll give you a couple of examples that allow you to serve HTML content offline if necessary.
First, I’ll show local assets inside the HTML page, then I’ll implement a simple REST service backed by a sqlite database.
As usual, all the code can be found on GitHub.

WKURLSchemeHandler

WKWebView was introduced back in 2014 with iOS 8 to replace the old UIWebView, but in order to implement custom url scheme we had to wait for iOS 11 that added WKURLSchemeHandler for that purpose.
Two functions must be implemented to conform to the protocol: a start function called when the handler needs to load a resource, and a stop function to stop loading data. My understanding is that the stop function may be used for cleanup, the most important one is the start where you need to respond with data loading. Note that didReceive and didFinish may raise an exception if stop was called, so you may need to store a state and avoid calling didReceive and didFinish in that case.

func webView(_ webView: WKWebView, start urlSchemeTask: WKURLSchemeTask) {
    guard let url = urlSchemeTask.request.url,
          let fileUrl = fileUrlFromUrl(url),
          let mimeType = mimeType(ofFileAtUrl: fileUrl),
          let data = try? Data(contentsOf: fileUrl) else { return }

    let response = HTTPURLResponse(url: url,
                                   mimeType: mimeType,
                                   expectedContentLength: data.count, textEncodingName: nil)

    urlSchemeTask.didReceive(response)
    urlSchemeTask.didReceive(data)
    urlSchemeTask.didFinish()
}

func webView(_ webView: WKWebView, stop urlSchemeTask: WKURLSchemeTask) {

}

the start function is passed a WKURLSchemeTask object. From it, you can get the URLRequest, and you can send back a response via didReceive(URLResponse) and send data by calling didReceive(Data). By calling didFinish we notify the web view that the task is completed and all the data is sent.
In order to add a custom scheme handler, we need to use a WKWebViewConfiguration.

let webView: WKWebView

init(withSchemeHandlers handlers: [SchemeHandlerEntry]) {
    let preferences = WKPreferences()

    let configuration = WKWebViewConfiguration()
    configuration.preferences = preferences

    for entry in handlers {
        configuration.setURLSchemeHandler(entry.schemeHandler,
                                          forURLScheme: entry.urlScheme)
    }

    webView = WKWebView(frame: CGRect.zero, configuration: configuration)
    webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
    webView.scrollView.bounces = false

    super.init()
}

each URL scheme handler has a custom URL scheme, so for example you can register the asset handler with the string “assets” and the one dealing with SQL with “sqlite”.

Serve local assets

Let’s start with the first example: serving local assets to an HTML page.
The code sample I pasted previously for the start function of the scheme handler is the one for serving local assets. This is the entire class

import Foundation
import UniformTypeIdentifiers
import WebKit

class AssetsSchemeHandler: NSObject, SchemeHandler {
    func webView(_ webView: WKWebView, start urlSchemeTask: WKURLSchemeTask) {
        guard let url = urlSchemeTask.request.url,
              let fileUrl = fileUrlFromUrl(url),
              let mimeType = mimeType(ofFileAtUrl: fileUrl),
              let data = try? Data(contentsOf: fileUrl) else { return }

        let response = HTTPURLResponse(url: url,
                                       mimeType: mimeType,
                                       expectedContentLength: data.count, textEncodingName: nil)

        urlSchemeTask.didReceive(response)
        urlSchemeTask.didReceive(data)
        urlSchemeTask.didFinish()
    }

    func webView(_ webView: WKWebView, stop urlSchemeTask: WKURLSchemeTask) {

    }

    // MARK: - Private

    private func fileUrlFromUrl(_ url: URL) -> URL? {
        guard let assetName = url.host else { return nil }
        return Bundle.main.url(forResource: assetName,
                               withExtension: "",
                               subdirectory: "assets")
    }

    private func mimeType(ofFileAtUrl url: URL) -> String? {
        guard let type = UTType(filenameExtension: url.pathExtension) else {
            return nil
        }
        return type.preferredMIMEType
    }
}

for the sake of this example, we assume the page will have an url like assets://test.jpg and test.jpg will be found in the assets folder of the app. This way we can extract the host part from the url (test.jpg) and look for this file into the app Bundle.
In order to set a correct MIME type to the HTTP response, I used UTType. It is a struct describing type information, by creating it with a file name extension I’m able to get the preferredMIMEType and use it for the response. For example test.jpg will return image/jpeg.
If you want to try some assets with my GitHub project just add files to the assets directory, and refer to them with assets:// in the HTML page

<html>
    <body>
        <h2>Test page</h2>
        <img src="assets://test.jpg"></img>
    </body>
</html>

this is a test page with an image called test.jpg

Support REST calls

As I mentioned at the beginning, we may need to support offline mode in our app. While serving local assets could be easy if the HTML and the assets are in the same directory, the page may need to make REST calls to a server. One way to support offline for REST call, is to implement a custom scheme and have a local DB like CoreData or, in this example, a SQLite DB so you can make queries and return a dictionary with the result to the page.

<html>
    <script>
        function getData() {
            var xhr = new XMLHttpRequest();
            xhr.open('GET', "sqlite://products", true);
            xhr.responseType = 'json';
            xhr.onload = function() {
              var status = xhr.status;
              if (status === 200) {
                console.log(xhr.response);
              } else {
                console.log("error")
              }
              document.getElementById("results").innerHTML = JSON.stringify(xhr.response);
            };
            xhr.send();
        }
    </script>
    <body>
        <h2>Test page</h2>
        <img src="assets://test.jpg"></img>
        <div id="button" onclick="getData()">Get data</div>
        <div id="results"></div>
    </body>
</html>

this is a simple page with some javascript to make a GET and expect a JSON back. We use the sqlite:// schema, in a real scenario you may try to call the https service first and fall back to the local DB if it fails, but you may also use the local DB every time. The advantage of this approach is that you can use the same code you have for calling a remote web service and only change the URL.
If you see a Access-Control-Allow-Origin in the console when trying to use the custom scheme, try enabling universal access from file URL in your WKWebView configuration like this

let configuration = WKWebViewConfiguration()
configuration.setValue(true, forKey: "allowUniversalAccessFromFileURLs")

The handler is similar to the one for local assets, let’s have a look

class SQLiteSchemeHandler: NSObject, SchemeHandler {
    init(databasePath: String) {
        sqlWrapper = SQLiteWrapper(path: databasePath)
    }

    func webView(_ webView: WKWebView, start urlSchemeTask: WKURLSchemeTask) {
        guard let url = urlSchemeTask.request.url else { return }
        let data = dataForURL(url)
        let response = HTTPURLResponse(url: url,
                                       mimeType: "application/json",
                                       expectedContentLength: data?.count ?? 0,
                                       textEncodingName: "utf-8")

        urlSchemeTask.didReceive(response)
        if let data = data {
            urlSchemeTask.didReceive(data)
        }
        urlSchemeTask.didFinish()
    }

    func webView(_ webView: WKWebView, stop urlSchemeTask: WKURLSchemeTask) {

    }
}

// MARK: - Private

private var sqlWrapper: SQLiteWrapper?

private func dataForURL(_ url: URL) -> Data? {
    var data: Data?
    guard let wrapper = sqlWrapper,
          let urlValue = url.host,
          let jsonObject = wrapper.performQuery("select * from \(urlValue)") else { return nil }
    if JSONSerialization.isValidJSONObject(jsonObject) {
        data = try? JSONSerialization.data(withJSONObject: jsonObject,
                                           options: .fragmentsAllowed)
    }
    return data
}

this time, the MIME type is always application/json. We then use the host part of the url to get the name of the table and perform a query, then try to convert the result to a JSON data and send it back to the page.
Not bad, but we can easily do better than that and allow the page to filter our data.

private func dataForURL(_ url: URL) -> Data? {
    var data: Data?
    guard let wrapper = sqlWrapper,
          let host = url.host else { return nil }
    let queryItems = URLComponents(string: url.absoluteString)?.queryItems ?? []
    var query: String = ""
    if queryItems.count > 0 {
        var whereStr = ""
        for item in queryItems {
            if let value = item.value {
                if whereStr != "" {
                    whereStr += " AND "
                }
                whereStr += "\(item.name) = \(value)"
            }
        }
        query = "select * from \(host) WHERE \(whereStr)"
    }
    else {
        query = "select * from \(host)"
    }

    guard let jsonObject = wrapper.performQuery(query) else { return nil }
    if JSONSerialization.isValidJSONObject(jsonObject) {
        data = try? JSONSerialization.data(withJSONObject: jsonObject,
                                           options: .fragmentsAllowed)
    }
    return data
}

in the function above, everything in query string will be converted to a WHERE statement in SQL.
For example, calling sqlite://products?name=test&brand=testbrand will become SELECT * from products where name = test and brand = testbrand
By adding more complexity, we could support other filters or even POST/PUT requests and convert them to INSERT or UPDATE in SQL.

Test custom schemes

We all love testing our code. Ok, maybe you don't really love it, but it is a good idea to cover your code with unit tests.
If you've implemented a custom scheme you need to interact with some HTML content, but testing that part is beyond the scope of this article.
Let's see how you can test the WKURLSchemeHandler to make sure it will be able to act correctly when invoked by your HTML content, and will respond with the correct data.
The first thing I needed to do was creating a concrete type for the WKURLSchemeTask protocol, in order to create a valid task to pass to the scheme handler and test the response. This is the implementation (link to the file on GitHub)

class WKURLSchemeTaskTest: NSObject {
    private (set) var request: URLRequest

    init(withRequest: URLRequest) {
        self.request = withRequest
    }

    func expectData(data: Data, completionHandler: @escaping (Bool) -> Void) {
        self.expectedData = data
        self.completionHandler = completionHandler
    }

    private var completionHandler: ((Bool) -> Void)?
    private var expectedData: Data?
    private var receivedData: Data?
}

extension WKURLSchemeTaskTest: WKURLSchemeTask {
    func didReceive(_ response: URLResponse) {

    }

    func didReceive(_ data: Data) {
        if receivedData == nil {
            receivedData = data
        }
        else {
            receivedData?.append(data)
        }
    }

    func didFinish() {
        if receivedData == expectedData {
            completionHandler?(true)
        }
        else {
            completionHandler?(false)
        }
    }

    func didFailWithError(_ error: Error) {
        completionHandler?(false)
    }
}

The test class can be initialised with a URLRequest to satisfy the requirement of WKURLSchemeTask, and I added a function to set the expected data. This way, when didFinish is called, I can check if the received data is equal to the expected data and use this information for my unit test.

func testCoreDataGet() {
    let productName = "Name1"
    guard let data = coreDataTest.dataArray(forProductName: productName) else {
        XCTFail("Cannot get data for product")
        return
    }
    guard let task = schemeHandlerTest.schemeTask(forProductName: productName) else {
        XCTFail("Cannot create scheme task")
        return
    }
    let expectation = expectation(description: "testCoreDataGet")

    task.expectData(data: data) { success in
        XCTAssertTrue(success)
        expectation.fulfill()
    }
    coreDataSchemeHandler.webView(webViewTest, start: task)

    waitForExpectations(timeout: 1.0)
}

the code sample above is for a test involving CoreData, first I generated the Data with an array of one Product, then I created the WKURLSchemeHandler object with the correct URLResponse to retrieve the data and I called the start function, the one that would be called after the HTML content asked for a resource in GET or POST.
I had to use expectation as expectData returns it result asynchronously, but I'm going to show you another way to test this kind of code by using async await

func testCoreDataGetAsync() async {
    let productName = "Name1"
    guard let data = coreDataTest.dataArray(forProductName: productName) else {
        XCTFail("Cannot get data for product")
        return
    }
    guard let task = schemeHandlerTest.schemeTask(forProductName: productName) else {
        XCTFail("Cannot create scheme task")
        return
    }
    let success: Bool = await withUnsafeContinuation{ continuation in
        task.expectData(data: data) { success in
            continuation.resume(returning: success)
        }
        coreDataSchemeHandler.webView(webViewTest, start: task)
    }
    XCTAssertTrue(success)
}

if you're interested, check out my previous article Test asynchronous code

Conclusion

I gave you a couple of example of custom scheme handlers, but you may have many more use cases, like making a bridge to Core Data, or to the user photo library, or assets you don’t have locally on your device but need to fetch with some custom code in Swift.
Happy coding 🙂

Original post

Test asynchronous code

Gualtiero Frigerio — Mon, 29 Nov 2021 09:51:33 +0000

One of the advantages of the introduction of async await in Swift 5.5 is the ability to test asynchronous code in a clear and concise way, and even if we’re not ready to introduce async await in our code base, we can at least start adopting it in our tests.
Before you start reading I leave you the links to some of the articles I’ve written before: introduction to async await and create your own AsyncSequence give you an introduction to async await while testing in Xcode is about writing unit tests.
As usual, all the code you see here is available on GitHub, the project is the same as the two previous articles about async await.

Test async functions

Let’s start with async functions. Turns out you can mark the functions inside a XCTestCase as async, so you can use await inside them.
Testing an async function is pretty straightforward: you can await for its return value and call the usual XCT assert functions.

func testGetDataAsync() async {
    let data = await RESTClient.getData(atURL: testURLUsers)
    XCTAssertNotNil(data)
}

That was easy, but we’re not done yet.
As I mentioned at the beginning, we can start adopting async await in our tests, even if the code base is still using completion handler based API or Combine.
Let’s see an example of a completion handler API

func testGetDataCompletion() {
    let expectation = expectation(description: "testGetDataCompletion")
    RESTClient.getDataCompletion(atURL: testURLUsers) { data in
        XCTAssertNotNil(data)
        expectation.fulfill()
    }

    waitForExpectations(timeout: 1.0)
}

to test a completion based API, we need to use an expectation and wait for it with a timeout.
While this usually works, it is not ideal. We need to set a timeout and place waitForExpectations after the asynchronous call, then we can fulfil the expectation inside the closure.
Testing a Combine API requires a similar approach

func testGetDataFuture() {
    let expectation = expectation(description: "testGetDataFuture")
    let publisher = RESTClient.getData(atURL: testURLUsers)
        .catch { error in
            Just<data>(Data())
        }
        .eraseToAnyPublisher()
    publisher.sink { data in
        expectation.fulfill()
    }
    .store(in: &cancellables)

    waitForExpectations(timeout: 1.0)
}

we still need an expectation in order to be able to fulfill it in the sink closure. If the closure isn’t called before the timeout, the test will fail.

Refactor existing tests

All right, we’re not happy with expectation, so let’s see how we can refactor those tests to use async await. There is a way to convert closure based APIs into async await, via the continuation system, and that’s what we’re going to use.

func testGetDataCompletionNoExpectation() async {
    let data: Data? = await withCheckedContinuation { continuation in
        RESTClient.getDataCompletion(atURL: testURLUsers) { data in
            continuation.resume(returning: data)
        }
    }

    XCTAssertNotNil(data)
}

I’ve already described how continuation works in introduction to async await so refer to that article for further details.
In this example I used withCheckedContinuation (there is the throwing version as well) to call a completion handler based api, then I can resume the execution returning the data.
We’re still waiting for the completion handler to be called, but this time we don’t need an expectation with an arbitrary timeout.
We can use the same approach for a Combine API

func testGetUsersNoExpectation() async {
    let dataSource = DataSource(baseURL: baseURLString)
    let users: [User]? = await withUnsafeContinuation { continuation in
        dataSource.getUsersWithMergedData().sink { users in
            continuation.resume(returning: users)
        }
        .store(in: &cancellables)
    }
    XCTAssertNotNil(users)
}

Test an AsyncSequence

In my previous article about AsyncSequence I talked about creating a custom AsyncSequence or use an AsyncStream instead of a custom implementation and this is how to test them

func testPicturesStream() async {
    let picturesTestArray = [pictureToTest]
    let picturesLoader = PicturesLoader(withPictures: picturesTestArray)
    var loaded = 0
    for await picture in picturesLoader.getPicturesStream() {
        XCTAssertNotNil(picture.image)
        loaded += 1
    }
    XCTAssertEqual(loaded, picturesTestArray.count)
}

If you remember, you can iterate via a for loop (or an iterator) through a AsyncSequence or a AsyncStream. The test function has to be marked as async, like in the previous examples, but this time we need to test two things. The first, is that at least the first result is valid via XCTAssertNotNil(picture.image), in the test we’re passing just one image so the for loop will be execute once.
You may wonder why I keeping track of the loaded pictures and check that the count is equal to the length of the array of pictures. In this particular example, the function doesn’t throw. If something goes wrong, not pictures are returned and we reach the end of the for loop. If we don’t keep the count, we don’t know if at least one picture was loaded.

Conclusion

I hope you share my enthusiasm about being able to test asynchronous code with the new async await addition in Swift 5.5
I don’t know about you but I’ve never liked the expectation based tests and the continuation API seems like a much better choice to wait for an asynchronous function to end.
Now, let’s write more test, and happy coding 🙂

Original article

Create your own AsyncSequence

Gualtiero Frigerio — Mon, 22 Nov 2021 14:37:17 +0000

One of the new features of async await I was really excited about is AsyncSequence, which provides a new way to receive data asynchronously in loops. It can be seen as an alternative to Combine, and I think both of them have reason to exist.
Before you continue reading, I suggest to get familiar with async await, and read my previous article on the topic. We’ll use the same GitHub repo where you’ll find all the code included here.

Let’s start with the definition: AsyncSequence is a protocol, and according to the documentation can provide asynchronous, sequential and iterated access to its elements.
The novelty is the asynchronous part, as Swift had a Sequence protocol since the beginning to provide access to elements.
Now that we have async await in Swift, we can iterate through a Sequence waiting for the single element to be ready.

Use an AsyncSequence

Before creating our custom AsyncSequence, I think it is better to understand how to use one of them.
Let’s see some examples. You’re likely familiar with URLSession, I bet you’ve used it somewhere to retrieve a JSON from a server, or to download something. As soon as async await was introduced, URLSession exposed the async version of its functions, and the one returning a sequence of bytes is perfect to see AsyncSequence in action.

class func getDataStream(atURL url: URL) async -> Data? {
    let request = URLRequest(url: url)
    var data: Data? = nil
    do {
        let (bytes, _) = try await URLSession.shared.bytes(for: request, delegate: nil)
        data = Data()
        for try await b in bytes {
            data?.append(b)
        }
    }
    catch (let error) {
        print("error while getting data \(error.localizedDescription)")
    }

    return data
}

// this is the definition of bytes

func bytes(for request: URLRequest, delegate: URLSessionTaskDelegate? = nil) async throws -> (URLSession.AsyncBytes, URLResponse)

As you can see, we can use a for loop awaiting each byte, then we can append it to a Data object.
Let’s have a look at the definition of bytes at the end of the code block. The function is async, so we have to await before getting the tuple back from it, and the first parameters is AsyncBytes. Turns out, AsyncBytes conform to the AsyncSequence protocol, that’s why we can iterate through its elements via a for loop.
You can use an Iterator as well, I don’t know if you’re familiar with it but this is the example

class func getDataIterator(atURL url: URL) async -> Data? {
    let request = URLRequest(url: url)
    var data: Data? = nil
    do {
        let (bytes, _) = try await URLSession.shared.bytes(for: request, delegate: nil)
        data = Data()
        var iterator = bytes.makeAsyncIterator()
        while let nextByte = try await iterator.next() {
            data?.append(nextByte)
        }
    }
    catch (let error) {
        print("error while getting data \(error.localizedDescription)")
    }

    return data
}

the only difference is the couple of lines after we call bytes on URLSession. We have the iterator via makeAsyncIterator and then we can use a while loop by calling next() on the iterator. Similarly to what happens in the for loop, we have to try await for the call to iterator.next(), as we’re dealing with an async iterator, conforming to the AsyncIteratorProtocol
I gave you the Iterator example as we’ll have to implement an iterator while creating our own AsyncSequence. Turns out, the IteratorProtocol is tightly coupled with Sequence, as a Sequence provide access to its element by creating an Iterator. So even if you don’t use an Iterator directly, as in the example above, you still have to implement one for your custom Sequence (or AsyncSequence)

Create an AsyncSequence

Now let’s see how to actually create our own AsyncSequence.
The example I chose is a class to load pictures. You provide an array of urls (I’m using a custom struct for that purpose) and you can await for each image to be loaded.
I used it to populate a UICollectionView, so a new cell is added only when the image is already loaded into a UIImage, instead of loading all the cells and having the images loaded and then added to an existing cell.
This is the code of PicturesLoader

class PicturesLoader: AsyncSequence, AsyncIteratorProtocol {
    typealias Element = PictureWithImage

    init(withPictures pictures: [PictureWithImage]) {
        self.pictures = pictures
    }

    // being of AsyncSequence and AsyncIteratorProtocol
    func next() async throws -> Element? {
        await getNextPicture()
    }

    func makeAsyncIterator() -> PicturesLoader {
        self
    }
    // end of AsyncSequence and AsyncIteratorProtocol

    private var pictures: [PictureWithImage] = []

    private func getNextPicture() async -> PictureWithImage? {
        guard let nextPicture = pictures.popLast(),
              let url = URL(string: nextPicture.imageUrl) else { return nil }
        if let data = await RESTClient.getData(atURL: url) {
            let image = UIImage(data: data)
            var picture = nextPicture
            picture.image = image
            return picture
        }
        return nil
    }
}

As you see, it conform to AsyncSequence and AsyncIteratorProtocol.

To conform to them, we need to add the next function that will return an Element, in this case the custom struct PictureWithImage but it could be anything like a String or custom type of yours.
Then we need the makeAsyncIterator, in this example we return self as this class conforms to AsyncSequence and AsyncIteratorProtocol. You may have a separate type like a struct conforming to AsyncIteratorProtocol and return that one instead of self.
Since the next function is async, we can await inside it.
Look at getNextPicture, that function is async as well, because is calling a RESTClient that will call an async version of URLSession to retrieve the data.
Of course you don’t have to await inside your async function, you may have all your values ready and return them. I wanted to show you a real asynchronous operation like a network call, but you may have an array of objects and return one at a time like a Sequence does.
How do we call our custom AsyncSequence? Just like we did for the URLSession example

let pictureLoader = PicturesLoader(withPictures: picturesWithImages)
Task {
    do {
        for try await picture in pictureLoader {
            loadedPictures.append(picture)
            await viewController?.collectionView.reloadData()
        }
    }
    catch {
        print("error while iterating on images")
    }
}

here I chose to use the for loop, but I could have used the iterator as well.
In this example we’re awaiting for the next picture, and when it is ready we can append its value to an array and call reload data on the collection view, so the new cell will be created with an image on it.

Use AsyncStream

It isn’t always necessary to create your own AsyncSequence, as Swift introduced two types conforming to AsyncSequence to make our lives easier. You can use AsyncStream and its counterpart AsyncThrowingStream (if your calls may throw) and then loop through them via a for loop just as we did in the previous example.
According to the documentation, both types provide a convenient way to create an asynchronous sequence without manually implementing an iterator. Sounds great, let’s see an example

func getPicturesStream() -> AsyncStream<PictureWithImage> {
    AsyncStream { continuation in
        Task {
            for picture in pictures {
                if let url = URL(string: picture.imageUrl),
                   let data = await RESTClient.getData(atURL: url),
                   let image = UIImage(data: data) {
                    var pictureToReturn = picture
                    pictureToReturn.image = image
                    continuation.yield(pictureToReturn)
                }
            }
            continuation.finish()
        }
    }
}

the implementation is similar to getNextPicture, it has a loop for the pictures, for each of them await for the RESTClient and then creates the UIImage and returns it. The difference is that we don’t actually return a value directly this time. The AsyncStream initialiser we are using is provided a Continuation, and as you see we call two functions on this type: yield and finish. Both resume the task awaiting for the next iteration, finish returns nil so the iteration ends, while yield has a value.
Let’s have a look at the call site

let picturesLoader = PicturesLoader(withPictures: picturesWithImages)
let stream = picturesLoader.getPicturesStream()
Task {
    for await picture in stream {
        loadedPictures.append(picture)
        await viewController?.collectionView.reloadData()
    }
}

this is similar to the previous example, we get the stream and we can iterate via a for loop.
The difference is that we didn’t have to provide a custom implementation of AsyncSequence so there is less code to write and we could avoid creating a custom type.

Conclusion

This was a quick introduction to AsyncSequence, I wanted to show you how to create your own one and most importantly how to consume an existing one.
As I said at the beginning, this isn’t the only alternative we have to deal with asynchronous values being emitted over time. Combine is great for that, comes with operators to manipulate the data and has some utilities like discarding results and debouncing the publisher.
Different tools that can help you achieve different goals, I think it is important to know all of them in order to pick the right one for your project.

Happy coding 🙂

Original article

Introduction to async await

Gualtiero Frigerio — Mon, 15 Nov 2021 08:48:05 +0000

When I found out about the addition of async await in Swift at 2021 WWDC I was eager to try it out, but the fact that is was iOS 15 only was a bummer, since some of my apps still support back to iOS 10.
The good news is that the amazing team behind Swift was able to back port the feature to iOS 13, and that means many more developers will be able to start adding the feature to their code base.
I’m not rushing to replace all of my asynchronous code just because I can, but I’m going to do is adopt it whenever I add something new, and slowly replace old implementations while refactoring code. There’s even a refactoring option in Xcode to automatically create an async version of an existing function and I'll show you how easy it is.

The sample app

I went back to a GitHub project I used for some articles in the past about Combine and Property Wrappers and I thought it would be interesting to see the use of async await as an alternative to the code I wrote back then. If you feel to, you can read Networking example with Combine to get an idea of the Combine implementation.
I’ve already described the APIs on the article about Future and Promises so here’s going to find only a quick recap. I make 3 calls: one for the pictures, the second for the albums and the third one to retrieve the users. Then I merge the pictures with the albums, and the albums with the users.
In order to return the array of users, the calls to pictures and albums must be completed, so I can return from the function with success, or with an error if one of the call fails.
All the code is available on the project, in particular in the class DataSourceAsync

Async functions

As I said, the function to retrieve all the data is asynchronous. We have some alternatives to deal with this kind of functions, we can pass a completion handler as a parameter so we'll be called back when the data is ready, use a Promise, or use Combine as described in the articles linked above.
Now in Swift we have a new alternative, a function can be marked as async

func getUsersWithMergedData() async -&gt; [User]? {
    guard let pictures = try? await getPictures(),
          let albums = try? await getAlbums(),
          let users = try? await getUsers() else {
              return nil
          }
    let mergedAlbums = DataSource.mergeAlbums(albums, withPictures: pictures)
    return DataSource.mergeUsers(users, withAlbums: mergedAlbums)
}

in order to make a function async, you have to put the async keyword just after the function name, before the return value. This tells the compiler your function is asynchronous, so it is expected to return a value, but not synchronously. The the caller will be blocked until the async function is done.
In order to call an async function, you have to use the new await keyword. In the example above, 3 async functions are called, and we need to wait (or should I say, await) for them to complete before moving on.
In the example, we try? and wait, because the functions may throw an exception. Let's see one of them

private func getAlbums() async throws -> [Album]  {
    guard let albumsData = try? await getEntity(.Album),
          let albums = try? JSONDecoder().decode([Album].self, from: albumsData) else {
              throw DataSourceError.conversionError
    }
    return albums
}

This function is marked as async throws, as it is asynchronous and may throw an error.
As you can see, in the function definition async comes before throws, while at call site you try and then await.

Error handling

I really like the fact we can define throwing async functions. With a callback base approach, one way to report an error to the caller is using the Result type.
If you're not familiar with it, it is an enum with two cases: success and failure, where failure conforms to Error. So you can return a Result and put the value in success, or the error in failure.
Throwing functions are different, you don't need an if or a switch at the caller site to know if there was an error, but you can use the try catch syntax.
In the code samples above, I actually used the try? syntax to avoid dealing with an error. When you try? you're telling the compiler you want to call a function that my throw an error, but if it does you don't care about it. You get an Optional back, so if an error is thrown the Optional is nil, otherwise you'll have the value.

do {
    let mergedAlbums = try await DataSource.mergeAlbums(albums, withPictures: pictures)
    return try await DataSource.mergeUsers(users, withAlbums: mergedAlbums)
}
catch DataSourceError.conversionError {
    print("error while converting data")
}
catch DataSourceError.urlError {
    print("malformed url")
}
catch (let error) {
    print("generic error \(error.localizedDescription)")
}
return nil

This is an example of handling errors in a do catch. We try await (try without the ? this time) for an async function and if it throws, we can catch the error. The nice thing about catch is you can specify the kind of error you want to handle and you can catch a generic error as you see in the last catch.
I like this, more than the switch over the Result type returned by a callback, as I can use the try? if I don't care about handling a specific error and my function may throw, letting the caller deal with an error.

Call async functions from a synchronous context

As we saw in the examples, if we are awaiting for an async function, our function has to be async as well.
You may wonder, where does it stop? You can't have only async functions on your code.
There is an answer for that, is called Task.
When you need to call an async function but you don't want your function to become async, just wrap the async call into a Task like this

@IBAction func showUsersTap(_ sender: Any) {
    if #available(iOS 15.0, *) {
        let dataSourceAsync = DataSourceAsync(baseURL: "https://jsonplaceholder.typicode.com")
        Task {
            if let users = await dataSourceAsync.getUsersWithMergedData() {
                DispatchQueue.main.async {
                    let usersVC = UsersTableViewControllerPW()
                    usersVC.setUsers(users)
                    self.navigationController?.pushViewController(usersVC, animated: true)
                }
            }
        }
    }
}

The IBActions wasn't supposed to be marked async, but Task let us deal with that in an easy and clear way.

Refactoring existing functions

As I said at the beginning, Xcode can help us refactor existing functions so we don't have to define the async versions of them.
If you right click on a function, and chose refactor, you have 3 alternatives as you can see in the picture

you can convert to Async, add a new async function or use a wrapper.
Convert and add alternative are similar, the former will replace your existing function while the latter will leave it there, changing it so it uses a Task, await for the result and then call the completion handler.
This is an example from another project where I implemented an XML parser

func parseXML(atURL url:URL,
              elementName:String,
              completion:@escaping (Array<XMLDictionary>?) -> Void) {
    guard let data = try? Data(contentsOf: url) else {
        completion(nil)
        return
    }
   parseXML(data: data, elementName: elementName, completion: completion)
}

and this is the async alternative made by Xcode

@available(*, deprecated, message: "Prefer async alternative instead")
func parseXML(atURL url:URL,
              elementName:String,
              completion:@escaping (Array<XMLDictionary>?) -> Void) {
    Task {
        let result = await parseXML(atURL: url, elementName: elementName)
        completion(result)
    }
}

func parseXML(atURL url:URL,
              elementName:String) async -> Array<XMLDictionary>? {
    guard let data = try? Data(contentsOf: url) else {
        return nil
    }
    return await parseXML(data: data, elementName: elementName)
}

so the original function was marked as deprecated, Task was inserted to call the the async function to wait for its result in order to call the completion handler.
This function didn't use the Result time mentioned before, this in an example of a refactoring from a function with a Result passed as a completion handler

class func loadData(atURL url:URL, completion: @escaping (Result<data, error="">) -> Void) {
    let task = URLSession.shared.dataTask(with: url) { data, response, error in
        if let error = error {
            completion(.failure(error))
            return
        }
        if let data = data {
            completion(.success(data))
        }
    }
    task.resume()
}

@available(*, deprecated, message: "Prefer async alternative instead")
class func loadData(atURL url:URL, completion: @escaping (Result<data, error="">) -> Void) {
    Task {
        do {
            let result = try await loadData(atURL: url)
            completion(.success(result))
        } catch {
            completion(.failure(error))
        }
    }
}

as you can see Xcode took care of handling the .success and .failure for us.
What about the third option? In this case, we are doing the other way round. We're not changing the original function to add Task and call the new async function. This time, the new async function will call our existing one.

func parseXML(atURL url:URL,
              elementName:String) async -> Array<XMLDictionary>? {
    return await withCheckedContinuation { continuation in
        parseXML(atURL: url, elementName: elementName) { result in
            continuation.resume(returning: result)
        }
    }
}

So this is an async function, but it has to wait for the completion handler of parseXML to return the result and we can do it by using a CheckedContinuation. You can wait for this continuation with withCheckedContinuation, call your sync function with the completion handler and call resume on the CheckedContinuation object, that will make our new function return. If the function throws, you can use withCheckedThrowingContinuation instead.
There is an withUnsafeContinuation if you don't care about some checks performed at runtime, for example if you call resume multiple times (which you shouldn't do). My understanding is that while developing is it better to have checks, so you can easily spot errors, and you can switch to the unsafe version when you're done.

Making calls in parallel

func getUsersWithMergedData() async -> [User]? {
    guard let pictures = try? await getPictures(),
          let albums = try? await getAlbums(),
          let users = try? await getUsers() else {
              return nil
          }
    let mergedAlbums = DataSource.mergeAlbums(albums, withPictures: pictures)
    return DataSource.mergeUsers(users, withAlbums: mergedAlbums)
}

The code is fine, but since we're using await, first we call getPictures, then once is done we call getAlbums and finally getUsers.
There is nothing wrong with that, but each of these function will eventually trigger a network call so we may want to make them at the same time and wait for all of them to finish before merging the results together.
Let's take a look at a different implementation

func getUsersWithMergedDataParallel() async -> [User]? {
    async let pictures = getPictures()
    async let albums = getAlbums()
    async let users = getUsers()

    do {
        let mergedAlbums = try await DataSource.mergeAlbums(albums, withPictures: pictures)
        return try await DataSource.mergeUsers(users, withAlbums: mergedAlbums)
    }
    catch DataSourceError.conversionError {
        print("error while converting data")
    }
    catch DataSourceError.urlError {
        print("malformed url")
    }
    catch (let error) {
        print("generic error \(error.localizedDescription)")
    }
    return nil
}

This time, we're using async let to define the variables. Doing so, we can make all this function calls without waiting for the result, as you can see there is no await keyword before getUsers, getPictures and getAlbums.
We still have to use await when we actually need to use the result of these function calls.
Look inside the do statement, we still need to try await DataSource.mergeAlbums, because we're using albums and pictures defined as async let.
The difference is that we were able to fire all the network calls at one, so we can have those running in parallel and hopefully save some time.

Conclusion

This was a quick, but I think exhaustive introduction to async await. There are more topic to explore but I'll leave them to future articles.
Hope you find this useful, let me know what you think about async await and I hope you'll have fun implementing it in your code base.
Happy coding :)

Original article

Refresh SwiftUI views

Gualtiero Frigerio — Mon, 02 Aug 2021 08:37:53 +0000

A nice addition to SwiftUI at WWDC21 is the new refreshable modifier to refresh view contents. This new feature is powered by maybe the biggest announcement at WWDC21: the new async/await pattern introduced in Swift 5.5.
While this isn’t an article about this specific topic is important to know that what we’re going to see here is powered by it, thus is not backwards compatible with older versions of SwiftUI.

One of the features iOS users love it the ability to pull down a list of content to refresh it. Up to this year, there wasn’t a first party API to implement this functionality, and if you’re interested in a solution compatible with the first version of SwiftUI you can check out my article about pull down to refresh.
We finally have that official API, is a modifier called refreshable and I’m going to show you how to use it on a List, and how to apply it to a custom view. As usual the code is available on GitHub
If you want to add the refreshable scroll view to your project via SwiftPM you can use this repository.

Refresh a List

Applying the new modifier to a List is straightforward

List(posts) { post in
    PostView(post: post)
}
.refreshable {
    await refreshListAsync()
}

you add the modifier .refreshable and you provide a function to refresh the content inside the closure.
As I told you, this feature is powered by async/await, so we need the new await keyword before the function call.
Let’s have a look at the declaration of refreshable

func refreshable(action: @escaping () async -> Void) -> some View

the action we are providing (our closure in the example above) is marked as async, that’s the reason why we need await. I haven’t written an article about async/await yet, but you’ll find plenty of them if you want to understand exactly what is going on.
For now, this is all you need to do to implement pull down to refresh with the new modifier. That’s because List implements the whole functionality and is able to display an indicator and hide it once the reload function (the one you implemented in the closure) ends.

Refresh a custom view

All right, refreshing a List is really easy but you may wonder how to use the new modifier in your view. Maybe you cannot use a List and you have an array of elements you display in a ForEach, the good news is that with a few more lines of code you can implement the same feature.
I’m going to show you a simple example from the repository I linked before, starting with my custom ScrollView implementing pull down to refresh. See the code here

struct ScrollViewPullRefresh<Content:View>: View {
    @Environment(\.refresh) var refreshAction: RefreshAction?

    init(@ViewBuilder content: @escaping () -> Content) {
        self.content = content
    }

    var body: some View {
        VStack {
            if isRefreshing {
                ProgressView()
            }
        }
        GeometryReader { geometry in
            ScrollView {
                content()
                    .anchorPreference(key: OffsetPreferenceKey.self, value: .top) {
                        geometry[$0].y
                    }
            }
            .onPreferenceChange(OffsetPreferenceKey.self) { offset in
                if offset > threshold && isRefreshing == false {
                    if let action = refreshAction {
                        Task {
                            isRefreshing = true
                            await action()
                            withAnimation {
                                isRefreshing = false
                            }
                        }
                    }
                }
            }
        }
    }

    private var content: () -> Content
    @State private var isRefreshing = false
    private let threshold = 50.0
}

this is the entire implementation. I won’t explain how to actually implement the pull down to refresh part, the onPreferenceChange modifier I applied to a ScrollView. Please refer to my previous article to find out more. In a nutshell, when the scroll view offset goes over a defined threshold I can perform an action, in this case the async action configured by the caller.
But how do I now what action to execute?
Alongside the refreshable modifier SwiftUI introduced a new environment value, called refresh

@Environment(\.refresh) var refreshAction: RefreshAction?

by referring to this value, we can call the async function passed to refreshable.
What is RefreshAction? Let’s take a look at its definition

public struct RefreshAction {
    ...
    public func callAsFunction() async
}

if you’re not familiar with callAsFunction, it is a way to treat objects as functions. In this case, you can call refreshAction() and execute the code passed to the closure of refreshable. It is not importa to know that, but I pasted the definition in case you were curious 🙂
Ok let’s get back to our example. We have refreshAction, so we know what to call when the user pulls down the ScrollView.

.onPreferenceChange(OffsetPreferenceKey.self) { offset in
    if offset > threshold && isRefreshing == false {
        if let action = refreshAction {
            Task {
                isRefreshing = true
                await action()
                withAnimation {
                    isRefreshing = false
                }
            }
        }
    }
}

his is the modifier. It is important to keep a @State variable to know whether we’re executing the refresh operation, otherwise we’d continue to call the async function as the user pulls down.
If we’re not refreshing and the action is set, we can call the async function.
What is Task? I won’t go into details, but tt is a way to execute asynchronous code inside a synchronous context. In this case we set the isRefreshing value to true, then we execute the async function (so we need the await keyword) and then set the refreshing value to false. I use withAnimation so the ProgressView disappears with an animation, otherwise you’d see the ScrollView jump at the top.

Let’s see how to refresh our custom ScrollView, full implementation here.

var body: some View {
    ScrollViewPullRefresh {
        VStack {
            ForEach(posts) { post in
                PostView(post: post)
            }
        }
    }
    .task {
        posts = await getPosts()
    }
    .refreshable {
        posts = await shufflePosts()
    }
}

As you see I added the refreshable modifier and inside I assign the posts variable the result of an async function to simply shuffle the posts. Let’s take a look at it

private func shufflePosts() async -> [Post] {
    await Task.sleep(2_000_000_000)
    return viewModel.allPosts.shuffled()
}

In order to simulate a network call, I use Task.sleep. As the name suggest, the function does nothing and sleeps for the given amount of microseconds. I find it useful to experiment with async await without setting up an API to retrieve data, you can simply have a JSON inside the project and await for the result.

Before ending, you may have noticed the .task modifier I applied to the custom view before refreshable.
This is another addition to SwiftUI, and gives us the ability to perform an asynchronous task when the view appears. In this example I load the list of posts when the view appears, and refresh them every time the user pulls down to refresh.
Of course you can implement alternative ways to refresh a list of contents. For example you can use a Button, like this

struct RefreshableView: View {
    @ObservedObject var viewModel: ListViewModel
    @Environment(\.refresh) var refreshAction: RefreshAction?

    var body: some View {
        VStack {
            Button {
                if let action = refreshAction {
                    Task {
                        await action()
                    }
                }
            } label: {
                Image(systemName: "arrow.counterclockwise")
            }
            ScrollView {
                ForEach(viewModel.beers) { beer in
                    HStack {
                        CustomImageView(url: URL(string: beer.imageUrl),
                                        placeHolder: Image(systemName: "xmark.octagon"))
                            .frame(width: 100, height: 100)
                        Text(beer.name)
                        Spacer()
                    }
                }
            }
        }
    }
}

and call the async function inside the Button’s action, wrapping it with Task.

That’s it, I really like the new API and hope you’ll find it easy to adopt in your projects.
Happy coding 🙂

Original article

Draw a clock with SwiftUI Canvas

Gualtiero Frigerio — Wed, 28 Jul 2021 07:57:01 +0000

My third article about the new features added to SwiftUI at WWDC21 is a mix between two of them I’ve already covered in my previous posts. This time my goal is to draw an analog clock with the new Canvas view. Since I’m building a clock I’ll need a way to refresh my SwiftUI view every second and WWDC21 brought us a new view for this purpose, the TimelineView.
My first post about WWDC21 was about that, and I decided to demonstrate its usage by drawing a simple clock in SwiftUI. I didn’t use Canvas back then, but some Path with rotation effect.
This time I want to achieve the same goal with Canvas.
As I told you at the beginning, I’ve already written something about Canvas, so if you want an introduction I suggest to read my previous post before continuing.

this image shows the result we want to achieve.
Let’s start diving into the code, you can find the implementation here

TimelineView(.periodic(from: .now, by: 1.0)) { timeContext in 
    Canvas { context, size in
        let date = timeContext.date
        let textTime = Text(date.formatted(date: .omitted, time: .standard))
        context.draw(textTime, at: CGPoint(x: size.width / 2, y: 10))

        let clockFrame = CGRect(x: 0,
                                y: 0,
                                width: 100,
                                height: 100)

        var clockContext = context
        clockContext.translateBy(x: (size.width / 2) - 50, y: (size.height / 2) - 50)

        addLabels(toContext: clockContext, frame: clockFrame)

        drawClockHands(inContext: clockContext, frame: clockFrame, date: date)                
    }
}

This is the SwiftUI view responsible to draw the clock. There is a TimelineView that refresh the inner content every second, and the date is stored inside timeContext.
Then we have the Canvas. Its closure has two parameters, the GraphicsContext and the size of the view itself.
First, I want to show the current time in a Text, but I’m drawing it inside the Canvas.
Remember the Canvas is not a usual SwiftUI view, the closure isn’t a ViewBuilder so we have to write imperative code here, not declarative. We need to specify the CGPoint each time we want to draw something on the screen, so if you’re used to building views in UIKit this should be familiar to you.
Note I copied context in the variable clockContext. This way I can apply a translation to the copied context without affecting the original one. I do it to center the clock inside the Canvas, so I can pass this context to the functions responsible to draw the clock hands and the marks.

private func addLabels(toContext context: GraphicsContext, frame: CGRect) {
    context.withCGContext { cgContext in
        let rect = CGRect(x: -frame.size.width / 2,
                      y: -frame.size.width / 2,
                      width: frame.size.width * 2,
                      height: frame.size.height * 2)
        cgContext.setStrokeColor(CGColor(red: 255, green: 0, blue: 0, alpha: 1.0))
        cgContext.setFillColor(CGColor(red: 255, green: 255, blue: 255, alpha: 1.0))
        cgContext.setLineWidth(2.0)
        cgContext.addEllipse(in: rect)
        cgContext.drawPath(using: .fillStroke)
    }
    // write the marks inside a smaller frame to avoid collision with the circle
    let innerFrame = getRect(fromRect: frame, ratio: 0.9)
    let radius = innerFrame.size.width
    let midX = innerFrame.size.width / 2 + (innerFrame.origin.x / 2)
    let midY = innerFrame.size.height / 2 + (innerFrame.origin.y / 2)
    let labels = [12, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
    for index in 0 .. < labels.count {
        let angle = CGFloat(index) * CGFloat.pi * 2 / 12 - (CGFloat.pi / 2)
        let x = round(cos(angle) * radius) + midX
        let y = round(sin(angle) * radius) + midY
        let text = Text("\(labels[index])")
        context.draw(text, at: CGPoint(x: x, y: y))
    }
}

This is the function to draw the marks. It starts with a CGContext, it isn't really necessary here but I put it to show how to integrate a CGContext inside a GraphicsContext. In this example I'm just drawing a circle, then I'll draw the hands with the new GraphicsContext API.
By using withCGContext you'll be able to reuse existing code in a Canvas. You may have some custom drawing made with CoreGraphics and this is the perfect way to bring it to SwiftUI by using Canvas, instead of wrapping a UIKit view inside UIViewRepresentable.

Let's move on. Now that we have a red circle, we want to write labels inside it. We can loop over the array of labels and with some trigonometry calculate where each of them will need to be drawn.
In order to avoid numbers to be drawn over the circle, I made a smaller CGRect and based all my calculation to its size instead of the original frame. Remember we need to specify the coordinates when we draw something in the GraphicsContext, so we need to be careful.

private func drawClockHands(inContext context: GraphicsContext, frame: CGRect, date: Date) {
    let hourPath = createPath(fromDate: date, type: .hour, frame: frame)
    context.stroke(hourPath, with: .color(Color.blue), lineWidth: 3.0)

    let minutePath = createPath(fromDate: date, type: .minute, frame: frame)
    context.stroke(minutePath, with: .color(Color.blue), lineWidth: 2.0)

    let secondPath = createPath(fromDate: date, type: .second, frame: frame)
    context.stroke(secondPath, with: .color(Color.red), lineWidth: 1.0)
}

This is the function responsible of drawing the clock hands. First we create a Path, then we can draw it in the context with the stroke function by specifying the Path, its color and the line width.

private func createPath(fromDate: Date, type: ClockHandType, frame: CGRect) -> Path {
    var timeDegree = 0.0
    var widthScale = 1.0
    let midX = frame.size.width / 2 + (frame.origin.x / 2)
    let midY = frame.size.height / 2 + (frame.origin.y / 2)

    let radius = frame.size.width

    let (degree, scale) = getDegreeAndScale(fromDate: fromDate, type: type)
    timeDegree = degree
    widthScale = scale

    timeDegree =  -timeDegree * CGFloat.pi * 2 / 60 - (CGFloat.pi)

    let startPoint = CGPoint(x: frame.size.width / 2, y: frame.size.height / 2)
    let endX = (widthScale * radius) * sin(timeDegree) + midX
    let endY = (widthScale * radius) * cos(timeDegree) + midY
    let endPoint = CGPoint(x: endX, y: endY)

    var path = Path()
    path.move(to: startPoint)
    path.addLine(to: endPoint)
    return path
}

The Path we need is just a line, and most of the function has to find out its origin and end points. The origin is the center of the frame, the end point depends on the time, we need to divide our circle in 60 points (60 seconds, 60 minutes, 12 hours so the hour is multiplied by 5). The radius you see here allow us to have clock hands of different sizes, the hours hand is shorter than the minutes and second.

That's it. If you compare this implementation to the one of my article about TimelineView you may find this one to be more complex, especially if you're more used to write SwiftUI views instead of UIKit.
What I like about Canvas is the freedom to draw every single pixel, pretty much what happened when overriding the draw method in a UIView. Canvas is indeed powerful, and allow you to recycle old code via CGContext. On the other hand, SwiftUI provide a declarative and simple way to draw views.
Personally, I'd use plain SwiftUI views whenever possible, but I'm glad Canvas is there to help us in some more complex scenario where we'd have an hard time achieving the result with SwiftUI.
As usual, it is better to use the right tool for the job.
Happy coding 🙂

Original post

Introduction to Canvas in SwiftUI

Gualtiero Frigerio — Tue, 27 Jul 2021 09:27:34 +0000

This article is about another nice introduction in SwiftUI at WWDC21, the Canvas view.
Canvas is also the name Apple gave to the live preview of SwiftUI views in Xcode, so you may find this post by accident while looking for that specific feature.
In a sentence, the new Canvas view is a particular view in SwiftUI that enables you to draw in GraphicContext in a more “traditional” way.
The Canvas is a SwiftUI view, but it doesn’t work with a ViewBuilder like other views. That’s why I said a more “traditional” way, you’re not going to put SwiftUI views inside a Canvas, maybe you can think of it like the draw method in a UIView.

In this article I’ll show the same example with Canvas (requires iOS 15 as you may guess) and without it, by using only SwiftUI views.
The example is quite simple, we want our user to draw on the screen with the finger. I’ll capture the user’s touches the same way, so you’ll only see a different way of drawing a set of shapes with SwiftUI.
As usual, all the code is available on GitHub. In particular you can find the Canvas part here and the old implementation in this project.

Capture touch

In order to get the user’s finger position on the screen we can use a gesture recogniser. This is the code of the old implementation (see here) but is it similar for Canvas except I don’t need the GeometryReader.



GeometryReader { geometry in
    Rectangle()
        .gesture(DragGesture(coordinateSpace:.local).onChanged( { value in
            addPoint(value, geometry:geometry)
        })
        .onEnded( { value in
            endGesture(size:geometry.size)
        }))
}

You can attach a gesture recogniser to a view with the .gesture modifier. In this case I’m using a DragGesture, so I can track the user moving its finger across the screen. The onChanged closure is called every time there is a new point to track, and once the user lifts the finger from the display onEnded is called.



private func addValue(_ value: DragGesture.Value) {
    let point = value.location
    let size = viewModel.size
    // we skip a point if x or y are negative
    // or if they are bigger than the width/height
    // so we don't draw points outside the view
    // I need to store size in the view model
    // to avoid the warning
    // Modifying state during view update, this will cause undefined behavior.
    if point.y < 0 ||
        point.y > size.height ||
        point.x < 0 ||
        point.x > size.width {
        viewModel.endPath()
        return
    }
    viewModel.addPoint(value.location)
}

private func endGesture() {
    viewModel.endPath()
}

as you can read in the comments by knowing the view size (that’s why I used a GeometryReader) I can ignore locations outside the view. All the points are needed to build a shape, as shown below.



// this is in the view model
func addPoint(_ point:CGPoint) {
    var shape = getCurrentShape()
    shape.points.append(point)
    shapes.removeLast()
    shapes.append(shape)
}

struct SimpleShape {
    var points:[CGPoint] // points to make a path
    var color:Color // stroke color
    var width:CGFloat // stroke line width
    var id:UUID = UUID() // necessary to use in ForEach

    mutating func addPoint(_ point:CGPoint) {
        points.append(point)
    }
}

Now that we have a collection of shapes, we need to draw them on screen.

Draw with SwiftUI views

Let’s start with the approach using SwiftUI views with a ViewBuilder. When I pasted the code to show you how to add a gesture recogniser I cut off the rest of the view you can see below



var body: some View {
    ZStack {
        GeometryReader { geometry in
            Rectangle()
                .gesture(DragGesture(coordinateSpace:.local).onChanged( { value in
                    addPoint(value, geometry:geometry)
                })
                .onEnded( { value in
                    endGesture(size:geometry.size)
                }))
        }
        ForEach(viewModel.shapes, id:\.id) { shape in
            DrawShape(points: shape.points)
                .stroke(lineWidth: shape.width)
                .foregroundColor(shape.color)
        }
    }
}

The Stack allows us to put the GeometryReader and the rectangle below the view we actually want to show to the user.
As we saw previously, the gesture has been translated to a set of shapes. We can now iterate them and draw every shape.



struct DrawShape: Shape {
    var points: [CGPoint]

    func path(in rect: CGRect) -> Path {
        var path = Path()
        if points.count == 0 {
            return path
        }

        path.move(to: points[0])
        for index in 1.. < points.count  { 
            path.addline(to: points[index]) 
        } 
        return path
    }
}

I don’t use a View but I use a Shape, when you implement a Shape in SwiftUI you need to provide a Path, as you can see I build the path from an array of points by adding a line between each one of them. The Path can be drawn on screen with a color and a line width, the .stroke and .foregroundColor modifiers you saw previously.

Draw with Canvas

All right, this is the part you were waiting for, the new Canvas view, you can find the code here.
As I said before we can collect the user’s drawing with a gesture recogniser and we have a view model to store the shapes.



Canvas { context, size in
    viewModel.size = size
    let frame = CGRect(x: 0, y: 0, width: size.width, height: size.height)
    for shape in viewModel.shapes {
        context.stroke(shape.path(in: frame),
                       with: .color(.primary),
                       lineWidth: 5.0)
    }
}
.gesture(DragGesture(coordinateSpace:.local).onChanged( { value in
    addValue(value)
})
.onEnded( { value in
    endGesture()
}))

This is all the code necessary to perform the same drawing.
Canvas provides a closure with two variables. We have a GraphicsContext we can use to draw on the screen and the CGSize of the view. This is why I don’t need a GeometryReader this time, the size is provided by Canvas itself.
As I mentioned at the beginning of the article this view is different from other SwiftUI views. There isn’t a view builder here, inside the closure you don’t return a View, we just interact with the context.
We can use a for loop instead of ForEach, and we call the stroke method on the context to draw a shape.
You can also fill a shape, or draw an image or text in the context. It is even possible to use a CGContext, so you may be able to use some old code that uses CGContext inside SwiftUI without bridging to UIKit.

Draw an image

Let’s end the article with another example: drawing some images on the screen inside a Canvas.

this is a sample effect, I want to draw 20 images of a clock with a different opacity. I can add some animation too, by moving them every second via a TimelineView. If you’re not familiar with it, here is my previous article on the subject.
In a sentence, the TimelineView allow us to refresh a SwiftUI view at a given time internal, like every minute, every second or specific dates in the future.



TimelineView(.periodic(from: Date(), by: 1.0)) { timeContext in
    Canvas { context, size in
        let date = timeContext.date
        var currentPoint = CGPoint(x: 0, y: 0)
        var image = context.resolve(Image(systemName: "clock"))
        image.shading = .color(.green)

        for i in 0..<20 {
            var innerContext = context
            innerContext.opacity = 0.1 * Double(i)
            currentPoint.x += 20
            currentPoint.y = offsetFromDate(date: date)
            innerContext.draw(image, at: currentPoint)
        }
    }
}

First, we need an image. If we plan to use the same image more than once in our GraphicsContext, we may want to create it with GraphicsContext.resolve, to improve performance. Otherwise, we can instantiate a SwiftUI image and ask the context to draw it.
Another interesting thing it the ability to copy the original GraphicsContext like I do in the for loop. This way, I can have a new context and change its opacity to obtain the effect you saw above. It is possibile to translate or rotate a GraphicsContext, so having a copy may be handy to perform certain operations only on a part of the original context instead of applying it to the whole Canvas. The code is available here

This was just a quick introduction to Canvas, I wanted to find an example to cover with SwiftUI with and without the Canvas. I plan to explore it more in the future so stay tuned and happy coding 🙂

Original post

Introduction to TimelineView

Gualtiero Frigerio — Mon, 26 Jul 2021 11:45:27 +0000

At WWDC21 Apple introduced TimelineView, a new SwiftUI View that update itself according to a schedule instead of relying on state variables.
It may be useful in some scenario, for example if you want to refresh a view only every X seconds, or if you want to animate something providing new frames at a given interval, or even if you just want to show a clock in your app.

Let’s see an example, a view that shows the time of day and changes every minute

TimelineView(.everyMinute) { context in
    Text(context.date.formatted())
}

This is a really simple example. TimelineView is instantiated with a particular TimelineScheduler called everyMinute which fires up, guess what, every minute.
This mean every minute the Text inside TimelineView is evaluated, and the context variable passed to the closure contains the date, so you can show the current time of day.
Note I used the formatted modifier, this is another nice addition of this year and you’ll see other examples.

PeriodicTimelineSchedule

What if we want to show the time, but update is every second?
We can use a PeriodicTimelineSchedule, instantiated via periodic(from:by:) so we can set a start date (if is in the past, the view updates immediately) and define how often we want the view to update.

TimelineView(.periodic(from: .now, by: 1.0)) { context in
    Text(context.date.formatted(date: .omitted, time: .standard))
}

in this example, the view updates every second. Note that I formatted the date differently, this time I omitted the date so it prints like this 4:30:25 PM

ExplicitTimelineSchedule

There is another tipe of schedule if we need more control, it is the ExplicitTimelineSchedule. You can provide an array of dates, and the TimelineView will be updated only at those given times.

TimelineView(.explicit(getDates())) { context in
    Text(context.date.formatted(date: .omitted, time: .standard))
}

private func getDates() -> [Date] {
    let date = Date()
    return [date,
            date.addingTimeInterval(2.0),
            date.addingTimeInterval(4.0),
            date.addingTimeInterval(6.0)]
}

Build an analog clock

Let’s have some fun and build an analog clock in SwiftUI with the help of TimelineView. You can find the code on GitHub.

As we just saw, TimelineView provides us with a convenient way to update our views with a schedule. That sounds perfect for a clock, we need our hands to move as the time passes. If we want to implement the seconds hand, we need the scheduler to refresh the content every second so let’s start with that

var body: some View {
    TimelineView(.periodic(from: Date(), by: 1.0)) { context in
        VStack {
            Text(context.date.formatted(date: .omitted, time: .standard))
            ZStack {
                clockHands(date: context.date)
            }
        }
        .frame(width: 300, height: 300)
    }
}

This TimelineView will refresh every seconds, now it is just a matter or placing the hands correctly

@ViewBuilder
private func clockHands(date: Date) -> some View {
    ClockHand(handScale: 0.5)
        .stroke(lineWidth: 5.0)
        .rotationEffect(angle(fromDate: date, type: .hour))
    ClockHand(handScale: 0.6)
        .stroke(lineWidth: 3.0)
        .rotationEffect(angle(fromDate: date, type: .minute))
    ClockHand(handScale: 0.8)
        .stroke(lineWidth: 1.0)
        .rotationEffect(angle(fromDate: date, type: .second))
}

Each ClockHand is a shape and has a different line width and even a different length, as you know the hours hand is shorter than the minutes and the seconds hand is the thinner and longer.
All we need to do is rotate each hand according to its value.

private func angle(fromDate: Date, type: ClockHandType) -> Angle {
    var timeDegree = 0.0
    let calendar = Calendar.current

    switch type {
    case .hour:
        // we have 12 hours so we need to multiply by 5 to have a scale of 60
        timeDegree = CGFloat(calendar.component(.hour, from: fromDate)) * 5
    case .minute:
        timeDegree = CGFloat(calendar.component(.minute, from: fromDate))
    case .second:
        timeDegree = CGFloat(calendar.component(.second, from: fromDate))
    }
    return Angle(degrees: timeDegree * 360.0 / 60.0)
}

there are 60 seconds in every minute and 60 minutes in every hour, but only 12 hours on the clock so we need to multiply the hour by 5 in order to make it work. That’s because I divide by 60 as you can see in the return statement.

That’s it, in a few lines of code we have an analog watch, simple but working.
Happy coding 🙂

Original post

Pull down to refresh in SwiftUI

Gualtiero Frigerio — Fri, 14 May 2021 12:06:03 +0000

UPDATE: WWDC21 introduced a new way to support pull to refresh, see the example at the end of the post. My custom implementation is still needed if you want to target iOS 13 and 14
I wrote a new article about pull down to refresh with the new additions.

Pull down to refresh a list is something quite common for an iOS app. We got used to that gesture over the years and I find it a quick and intuitive way to perform the task.
With the increasing adoption of SwiftUI people are looking at ways to implement the same mechanism, and this post is about my implementation of this very gesture.
The code is available on GitHub as usual, I updated an old repository I mentioned in my previous post about lazy loading.
I’m going to show you two ways of implementing the same thing, the first putting your content inside a particular view and the second is via a ViewModifier.

RefreshableScrollView

Let’s start with the first approach, putting your content inside a view. I called it RefreshableScrollView and you can find the implementation here.
The view has to be configured with an action, a function called when the user pulls down over a certain threshold (in my example I set 50 pixels). The component doesn’t show a progress view, so you can fully customise that part.

RefreshableScrollView(action: refreshList) {
    if isLoading {
        VStack {
            ProgressView()
            Text("loading...")
        }
    }
    LazyVStack {
        ForEach(posts) { post in
            PostView(post: post)
        }
    }
}

private func refreshList() {
    isLoading = true
    DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) {
        isLoading = false
    }
}

The example is very simple, I mimic the reloading of a set of data by calling asyncAfter to wait for a second. You’d likely have to interact with a view model to ask to fetch data again, and if the user pulls while you’re loading you may want to avoid fetching again, but you get the point.
Let’s see how RefreshableScrollView actually works

struct RefreshableScrollView<Content:View>: View {
    init(action: @escaping () -> Void, @ViewBuilder content: @escaping () -> Content) {
        self.content = content
        self.refreshAction = action
    }
    var body: some View {
        GeometryReader { geometry in
            ScrollView {
                content()
                    .anchorPreference(key: OffsetPreferenceKey.self, value: .top) {
                        geometry[$0].y
                    }
            }
            .onPreferenceChange(OffsetPreferenceKey.self) { offset in
                if offset > threshold {
                    refreshAction()
                }
            }
        }
    }

    // MARK: - Private

    private var content: () -> Content
    private var refreshAction: () -> Void
    private let threshold:CGFloat = 50.0
}

fileprivate struct OffsetPreferenceKey: PreferenceKey {
    static var defaultValue: CGFloat = 0

    static func reduce(value: inout CGFloat, nextValue: () -> CGFloat) {
        value = nextValue()
    }
}

As you can see I’m wrapping the content inside a ScrollView with a GeometryView.
The ScrollView is necessary to be able to pull down the content.
In my tests I found out that having a List inside a ScrollView doesn’t work, so use ForEach.
GeometryReader is necessary to compute the offset.
In order to get the offset, we need to use a PreferenceKey. You can see I implemented a struct OffsetPreferenceKey for that purpose, we need to provide a defaultValue and reduce, what reduce does in our example is basically keeping the value updated.
In order to use our PreferenceKey and get the offset we have to set .anchorPreference on our content. Unfortunately there isn’t documentation about this method (the notorious no overview available). You don’t need to know the details though, all you have to know is to set this preference and to implement .onPreferenceChange, where you can get the value from GeometryProxy. We asked for the .top value, and we get the y coordinate via subscript. We get a CGPoint, so we have x and y.
If the offset is bigger than the defined threshold, we can call the action to refresh the content.

RefreshableScrollViewModifier

The second approach is a ViewModifier. Internally this view modifier uses RefreshableScrollView

struct RefreshableScrollViewModifier: ViewModifier {
    var action: () -> Void

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

and this is how to use it in your view

var body: some View {
    LazyVStack {
        if isLoading {
            ProgressView()
        }
        ForEach(posts) { post in
            PostView(post: post)
        }
    }
    .modifier(RefreshableScrollViewModifier(action: refreshAction))
}

I think I like using the RefreshableScrollView directly more than implementing the modifier, but it is up to you.

refreshable

Apple introduced a new view modifier called refreshable at WWDC21 to provide the pull to refresh animation.
The modifier takes care of implementing the drag gesture and placing an activity indicator above the content of the List, all you have to do is provide a closure with a async function to call to refresh the content.
This is an example

var body: some View {
    VStack {
        Text("there are \(posts.count) posts")
        if #available(iOS 15.0, *) {
            List(posts) { post in
                PostView(post: post)
            }
            .refreshable {
                await refreshListAsync()
            }
        } else {
            List(posts) { post in
                PostView(post: post)
            }
        }
    }
}

// the async refresh function

@available(iOS 15.0, *)
private func refreshListAsync() async {
    if isRefreshing == false {
        isRefreshing = true
        self.posts = await shufflePosts(posts)
        isRefreshing = false
    }
}

My function doesn't do anything special, is just shuffles the array, but you can put an async function there to retrieve data from the network. The function doesn't have to be async, but if you provide an async function the indicator should stay there until the operation is finished, otherwise the function is called but the indicator is removed as soon as you complete the drag gesture.

Hope you’ll have fun implementing pull down to refresh in your SwiftUI apps, happy coding 🙂

Original post

Getting started with face recognition

Gualtiero Frigerio — Mon, 22 Feb 2021 10:22:14 +0000

Today I felt like experimenting with ARKit and I couldn’t figure out a sample project to start with. When I want to start exploring a new framework or a new API, my approach is usually to start with something simple, but starting with an actual use case.
So I though, what about a video player that pauses the video while I’m not in front of my device and resumes when I look at the screen again?
Sounds interesting? Keep reading, I’ll show you how to do it with ARKit. What about supporting devices without the TrueDepth camera on the front? No problem, I have a fallback implementation using AVFoundation.

Sample project

Here’s the link to the sample project on GitHub.
The app is very simple, a button starts the video player and face tracking at the same time. If ARKit is not available on the front camera, it uses the AVFoundation class. The ARKit and AV classes implement a protocol, so you can use both of them exactly the same way. Instead of a delegate, I preferred a Combine publisher, so the caller can subscribe and get status update from the face tracker.

protocol FaceTracker: UIViewController {
    var trackingStatus:AnyPublisher<Facetrackingstatus, Never> {get}
    static func isAvailable() -> Bool
    func start()
    func stop()
}

This is the protocol describing a FaceTracker.

As I said, we first check if the ARKit version is available, if not we fallback to the AVFoundation.
The FaceTracker is added as a child view controller. In many ARKit examples you see AR applied to a SceneKit view, in this case there is no view added to the hierarchy, you don’t see your face mirrored on the screen, but I found out you do have to add the ARSessionDelegate as a child view controller in order for the methods to be called. Not a big deal, but if you try and implement something in ARKit and your delegate is never called, you may try to use a ViewController. This is why the protocol requires the class to be a UIViewController.
Next, let’s see how to get updates via Combine. The protocol requires a trackingStatus var to be a publisher, it is a publisher that never fails and publishes FaceTrackingStatus, an enum describing the detection status.

private func startFaceTracking() {
    let tracker:FaceTracker = FaceTrackerAR.isAvailable() ? FaceTrackerAR() : FaceTrackerAV()
    addChild(tracker)
    tracker.start()
    cancellable = tracker.trackingStatus
        .debounce(for: 1.0,
                      scheduler: RunLoop.main)
        .sink(receiveValue: {[weak self] value in
            self?.processTrackingStatus(value)
    })
}

private func processTrackingStatus(_ value:FaceTrackingStatus) {
    switch value {
    case .faceDetected:
        playVideo()
    case .noFaceDetected:
        pauseVideo()
    // ...
}

This is the sample code. We instantiate the correct tracker so AV is the fallback if AR is not available. Then we start the tracker and use Combine to get updates.
If you’re not familiar with Combine you can check my previous post about it. For now let’s just say you need to store the object in order to interact with the publisher, that’s why we have the cancellable property in our class. Then, before receiving the value with sink, I put a debounce so if the tracker changes status the video is paused/resumed after a second.
Now that you know how to get status updates, let’s finally talk about ARKit.

Face tracking with ARKit

In order to use ARKit we need to create a ARSession. Before we start using it though let’s see how we can make sure our device has a TrueDepth camera on the front.

extension FaceTrackerAR: FaceTracker {
    static func isAvailable() -> Bool {
        ARFaceTrackingConfiguration.isSupported
    }

    func start() {
        let configuration = ARFaceTrackingConfiguration()
        session.run(configuration, options: [])
    }

    func stop() {
        session.pause()
    }
}

ARFaceTrackingConfiguration.isSupported is false if we can’t perform face tracking with ARKit, so we can easily perform this check before trying to start a ARSession.
ARKit doesn’t just perform face detection, there is much more, so when you start a session via run you have to provide a configuration. In our example we use ARFaceTrackingConfiguration, but you can track images, body, GPS and so on.
Once you run the session, you should start receiving data in your ARSessionDelegate

func session(_ session: ARSession, didUpdate anchors: [ARAnchor]) {
    guard let faceAnchor = anchors.first as? ARFaceAnchor else { return }

    if faceAnchor.isTracked == true && isTracking == false {
        isTracking = true
        status = .faceDetected
    } else if faceAnchor.isTracked == false && isTracking == true {
        isTracking = false
        status = .noFaceDetected
    }
}

The delegate receives update about detected ARAnchor which represents the position and orientation of something of interest in the observed environment. We actually want to detect faces, so we expect a ARFaceAnchor which contains information about the pose and expression of a face detected by ARKit. When using the TrueDepth camera, only one face at a time is detected, so you’ll get the anchor about only one of them if you point the device to multiple people.
ARFaceAnchor carries a lot of information, there is geometry describing the face and you have transform matrixes about both eyes, and even the position describing the direction of the face’s gaze, so you know where the user is looking.
As I stated at the beginning, let’s start simple.
We only need to know if a face is detected, and we can use the .isTracked property on the ARFaceAnchor. If isTracked is false, no face is currently being tracked, so we can send this update to our subscriber. If is true, there is a face pointing at the screen.
The variable status is @Published, so when we update it Combine will send the updated value to our subscribers, we don’t need to do anything more than setting the variable’s value.

Detect eye blink

I have another idea, wouldn’t it be cool to skip forward 30 seconds after I blink my right eye? And go backwards when I blink the left one?
It is possible and I’ll show you how.
First we need to add another value to our enum so we can handle the blink. We can then use seek on AVPlayer to change position in the video timeline going forward or backwards.
That is the easy part, now let’s see how to actually detect the blink with the help of ARKit.

var blinkStatus:BlinkStatus = .none
// check blink status
// the values are mirrored, .eyeBlinkLeft is referred to the right eye
if let leftEyeBlink = faceAnchor.blendShapes[.eyeBlinkLeft] as? Float {
    if leftEyeBlink > blinkThreshold {
        blinkStatus = .rightEye
    }
}
if let rightEyeBlink = faceAnchor.blendShapes[.eyeBlinkRight] as? Float {
    if rightEyeBlink > blinkThreshold {
        blinkStatus = blinkStatus == .rightEye ? .bothEyes : .leftEye
    }
}
if blinkStatus != .none {
    status = .blink(blinkStatus)
}

this is the ARSessionDelegate method we saw previously. This piece of code was added at the beginning, so if there is a blink we report this status, otherwise we execute the code to decide whether a face was detected or not. If we detect a blink, of course a face was detected as well.
How does ARKit help us detecting a blink? We can use the blendShapes property, which is a dictionary containing the detected facial expressions. There is eye blink (left and right) and we’re only interested in those values for the sake of the example, but there are a lot more involving eyes, mouth, nose, even the tongue.
I decided to set a threshold of 0.5, if the coefficient is lower than that I don’t report the value. The values from the dictionary are from 0.0 to 1.0
In this example, using the front facing camera, it looks like the image we have is mirrored, so if I blink my right eye the coefficient is higher on the .eyeLeftBlink key of the dictionary and viceversa.

Tracking with AVFoundation

What about older devices, or maybe not so old but without a TrueDepth camera?
Turns out, AVFoundation can do face detection. I’m not going into much details about using a AVCaptureSession here, you can refer to my previous article about detecting barcodes where I explained how to implement a barcode and QR code reader in Swift.

private func configureCaptureSession() {
    if captureSession != nil {
        return
    }
    let objectTypes:[AVMetadataObject.ObjectType] = [.face]
    let session = AVCaptureSession()
    let deviceDiscoverySession = AVCaptureDevice.DiscoverySession(deviceTypes:[.builtInWideAngleCamera],
                                                                  mediaType: AVMediaType.video,
                                                                  position: .front)

    guard let captureDevice = deviceDiscoverySession.devices.first,
        let videoDeviceInput = try? AVCaptureDeviceInput(device: captureDevice),
        session.canAddInput(videoDeviceInput)
        else { return }
    session.addInput(videoDeviceInput)

    let metadataOutput = AVCaptureMetadataOutput()
    session.addOutput(metadataOutput)
    metadataOutput.setMetadataObjectsDelegate(self, queue: queue)
    metadataOutput.metadataObjectTypes = objectTypes

    captureSession = session
}

This is the code to configure a AVCaptureSession. First you configure the device, you can use all the device’s camera, but in this example we want the front facing camera so we set position .front.
Then we need to look for metadata, in this case we need the AVMetadataObject .face but we can look for barcodes or QR codes or a human body, or even a dogs and cats.
Once we configured a session and started it, our delegate should start receiving values.

func metadataOutput(_ output: AVCaptureMetadataOutput,
                           didOutput metadataObjects: [AVMetadataObject],
                           from connection: AVCaptureConnection) {
    let isFaceDetected = metadataObjects.contains(where: { $0.type == .face })
    if isFaceDetected == true && isTracking == false {
        isTracking = true
        status = .faceDetected
    } else if isFaceDetected == false && isTracking == true {
        isTracking = false
        status = .noFaceDetected
    }
}

If the metadata detected is of type .face, we have a face detected, so we can change the status and notify our subscriber.
I haven’t tested it much, but I guess AVFoundation can detect multiple faces, while ARKit only detects one at a time when using the TrueDepth camera, so if two people are looking at the screen and one of them turns his face, the video should keep playing.
There is no blink detection here, AVFoundation doesn’t offer a live tracking comparable to ARKit via the TrueDepth camera.

Conclusion

This was just a quick introduction to face detection. Obviously, there are privacy implications about constantly detecting the user’s face, and of course you need to set the Privacy – Camera Usage Description key in your Info in order to use the front facing camera, otherwise the app will crash as soon as you start the tracking session.
As you can imagine, you can’t test this kind of stuff in your simulator so you need an actual device.
I do plan to keep playing with ARKit in the future, so stay tuned for more.

Happy coding 🙂

Link to original post