Finish SwiftUI tutorial

Sources/Documentation.docc/Resources/code-files/02-ContentView-10.swift

@@ -0,0 +1,34 @@
+@State var showAlert = false
+@State var cacheSizeResult: Result<UInt, KingfisherError>? = nil
+
+var body: some View {
+    List {
+        Button("Check Cache") {
+            KingfisherManager.shared.cache.calculateDiskStorageSize { result in
+                cacheSizeResult = result
+                showAlert = true
+            }
+        }
+        .alert(
+            "Disk Cache",
+            isPresented: $showAlert,
+            presenting: cacheSizeResult,
+            actions: { result in
+                // TODO: Actions
+            }, message: { result in
+                switch result {
+                case .success(let size):
+                    Text("Size: \(Double(size) / 1024 / 1024) MB")
+                case .failure(let error):
+                    Text(error.localizedDescription)
+                }
+            })
+        
+        ForEach(0 ..< 10) { i in
+            HStack {
+                KFImage(url(at: i))
+                // ...
+            }
+        }
+    }.listStyle(.plain)
+}

Sources/Documentation.docc/Resources/code-files/02-ContentView-11.swift

@@ -0,0 +1,42 @@
+@State var showAlert = false
+@State var cacheSizeResult: Result<UInt, KingfisherError>? = nil
+
+var body: some View {
+    List {
+        Button("Check Cache") {
+            KingfisherManager.shared.cache.calculateDiskStorageSize { result in
+                cacheSizeResult = result
+                showAlert = true
+            }
+        }
+        .alert(
+            "Disk Cache",
+            isPresented: $showAlert,
+            presenting: cacheSizeResult,
+            actions: { result in
+                switch result {
+                case .success:
+                    Button("Clear") {
+                        KingfisherManager.shared.cache.clearCache()
+                    }
+                    Button("Cancel", role: .cancel) {}
+                case .failure:
+                    Button("OK") { }
+                }
+            }, message: { result in
+                switch result {
+                case .success(let size):
+                    Text("Size: \(Double(size) / 1024 / 1024) MB")
+                case .failure(let error):
+                    Text(error.localizedDescription)
+                }
+            })
+        
+        ForEach(0 ..< 10) { i in
+            HStack {
+                KFImage(url(at: i))
+                // ...
+            }
+        }
+    }.listStyle(.plain)
+}

Sources/Documentation.docc/Resources/code-files/02-ContentView-5.swift

@@ -0,0 +1,27 @@
+import SwiftUI
+import Kingfisher
+
+struct ContentView: View {
+    func url(at index: Int) -> URL? {
+        let urlPrefix = "https://raw.githubusercontent.com/onevcat/Kingfisher-TestImages/master/DemoAppImage/Loading/kingfisher"
+        return URL(string: "\(urlPrefix)-\(index + 1).jpg")
+    }
+    
+    var body: some View {
+        List {
+            ForEach(0 ..< 10) { i in
+                HStack {
+                    KFImage(url(at: i))
+                        .resizable()
+                        .roundCorner(
+                            radius: .widthFraction(0.5),
+                            roundingCorners: [.topLeft, .bottomRight]
+                        )
+                        .serialize(as: .PNG)
+                        .frame(width: 64, height: 64)
+                    Text("Index \(i)")
+                }
+            }
+        }.listStyle(.plain)
+    }
+}

Sources/Documentation.docc/Resources/code-files/02-ContentView-6.swift

@@ -0,0 +1,33 @@
+import SwiftUI
+import Kingfisher
+
+struct ContentView: View {
+    func url(at index: Int) -> URL? {
+        let urlPrefix = "https://raw.githubusercontent.com/onevcat/Kingfisher-TestImages/master/DemoAppImage/Loading/kingfisher"
+        return URL(string: "\(urlPrefix)-\(index + 1).jpg")
+    }
+    
+    var body: some View {
+        List {
+            ForEach(0 ..< 10) { i in
+                HStack {
+                    KFImage(url(at: i))
+                        .resizable()
+                        .roundCorner(
+                            radius: .widthFraction(0.5),
+                            roundingCorners: [.topLeft, .bottomRight]
+                        )
+                        .serialize(as: .PNG)
+                        .onSuccess { result in
+                            print("Image loaded from cache: \(result.cacheType)")
+                        }
+                        .onFailure { error in
+                            print("Error: \(error)")
+                        }
+                        .frame(width: 64, height: 64)
+                    Text("Index \(i)")
+                }
+            }
+        }.listStyle(.plain)
+    }
+}

Sources/Documentation.docc/Resources/code-files/02-ContentView-7.swift

@@ -0,0 +1,10 @@
+var body: some View {
+    List {
+        ForEach(0 ..< 10) { i in
+            HStack {
+                KFImage(url(at: i))
+                // ...
+            }
+        }
+    }.listStyle(.plain)
+}

Sources/Documentation.docc/Resources/code-files/02-ContentView-8.swift

@@ -0,0 +1,20 @@
+var body: some View {
+    List {
+        Button("Check Cache") {
+            KingfisherManager.shared.cache.calculateDiskStorageSize { result in
+                switch result {
+                case .success(let size):
+                    print("Size: \(Double(size) / 1024 / 1024) MB")
+                case .failure(let error):
+                    print("Some error: \(error)")
+                }
+            }
+        }
+        ForEach(0 ..< 10) { i in
+            HStack {
+                KFImage(url(at: i))
+                // ...
+            }
+        }
+    }.listStyle(.plain)
+}

Sources/Documentation.docc/Resources/code-files/02-ContentView-9.swift

@@ -0,0 +1,19 @@
+@State var showAlert = false
+@State var cacheSizeResult: Result<UInt, KingfisherError>? = nil
+
+var body: some View {
+    List {
+        Button("Check Cache") {
+            KingfisherManager.shared.cache.calculateDiskStorageSize { result in
+                cacheSizeResult = result
+                showAlert = true
+            }
+        }
+        ForEach(0 ..< 10) { i in
+            HStack {
+                KFImage(url(at: i))
+                // ...
+            }
+        }
+    }.listStyle(.plain)
+}

Sources/Documentation.docc/Tutorials/GettingStartedSwiftUI.tutorial

@@ -16,7 +16,7 @@
             
             At the final stage of this tutorial, you will have a list like this:
             
-            @Image(source:preview-4.png, alt:"The first image is loaded into the image view in cell.")
+            @Image(source:preview-3-swiftui.png, alt:"The first image is loaded into the image view in cell.")
         }
     }
     
@@ -89,11 +89,93 @@
                     @Image(source: preview-2-swiftui.png, alt: "")
                 }
             }
+            @Step {
+                Kingfisher also comes with a bundle of useful processors and helper methods. For example, we can add 
+                some partial round corner effect in a simple way. 
+                @Code(name: "ContentView.swift", file: 02-ContentView-5.swift) {
+                    @Image(source:preview-3-swiftui.png, alt:"")
+                }
+                Besides of the `.roundCorner`, we also apply a `.serialize(as: .PNG)` to forcibly convert the
+                loaded JPG file to PNG format when storing in the disk cache. This is necessary since JPG format does
+                not contain an alpha channel, which is necessary when storing a round corner image.
+            }
+            @Step {
+                The `KFImage` has a few other modifiers too, including some life cycle handlers like 
+                `.onSuccess` or `.onFailure`.
+                @Code(name: "ContentView.swift", file: 02-ContentView-6.swift)
+                Restart the app. If the images were loaded during your previous use of the app, you should see 
+                "Image loaded from cache: disk" in the Xcode console.
+            }
         }
     }
         
-    @Section(title: "Loading Options") {
+    @Section(title: "Manipulating the Cache") {
+        @ContentAndMedia {
+            In this final part, we'll look at basic tasks related to image caching, like finding out the size of the 
+            disk cache and clearing all the cache. Usually, Kingfisher handles cache management automatically, so you 
+            don't need to think about it much. But if you need more detailed control over how caching works, this 
+            section will give you helpful tips and information.
+        }
         
+        @Steps {
+            @Step {
+                First, we need to find out how much space the image cache is using. Normally, you would check the cache 
+                size or clear the cache using a button. In this example, we will add a button to the first row of the 
+                list.
+                @Code(name: "ContentView.swift", file: 02-ContentView-7.swift)
+            }
+            @Step {
+                Add a `Button` at the top of the `List`. In its event block, call `calculateDiskStorageSize(completion:)` 
+                and print the disk cache size. 
+                @Code(name: "ContentView.swift", file: 02-ContentView-8.swift) {
+                    @Image(source:preview-4-swiftui.png, alt:"Added a button to the top of the list.")
+                }
+            }
+            @Step {
+                To trigger an alert in SwiftUI, we add two `@State` to the `ContentView`. In the `calculateDiskStorageSize`
+                handler, we set both states.
+                @Code(name: "ContentView.swift", file: 02-ContentView-9.swift)
+            }
+            @Step {
+                Add an `.alert` modifier to the `Button`. When the `showAlert` state is set, an alert with the information
+                of disk cache size is presented. 
+                @Code(name: "ContentView.swift", file: 02-ContentView-10.swift)
+            }
+            @Step {
+                Lastly, use the `clearCache` function to remove all images from both the memory and disk caches. After 
+                this, when you restart the app or trigger a full reloading for the `List`, the images will be downloaded 
+                again from the internet. You'll notice "Image loaded from cache: none" displayed in the console, 
+                indicating the images are not being loaded from the cache this time.
+                
+                @Code(name: "ContentView.swift", file: 02-ContentView-11.swift) {
+                    @Image(source:preview-5-swiftui.png, alt:"An alert which shows the disk cache size used by Kingfisher, with a button to purge the cache.")
+                }
+                
+                The cache cleaning is only for demonstration purpose. In practice, usually you do not need to call it 
+                yourself. Kingfisher will manage and purge the data based on its default policy.
+            }
+        }
+    }
+    
+    @Section(title: "Next Steps") {
+        @ContentAndMedia {
+            
+            Congratulations! 
+            
+            You have now mastered some basic uses of Kingfisher: including loading images from the web or cache using
+            the `KFImage` type, processing images before display using a modifier, and basic methods
+            for inspecting and clearing the cache. 
+            
+            Kingfisher also contains a considerable number of other features, and it has been designed to be simple to
+            use while considering flexibility. As you deepen your understanding of the framework, we hope you will
+            gradually grow to like it.
+            
+            Next, we recommend that you start using Kingfisher in your projects to help you accomplish tasks. You can 
+            also read the <doc:CommonTasks> or <doc:KingfisherInDepth> articles to get a better understanding. When 
+            you encounter problems, come back to consult the documentation or ask the community. 
+            
+            Have a nice day!
+        }
     }
     
 }

Sources/Documentation.docc/Tutorials/GettingStartedUIKit.tutorial

@@ -143,6 +143,9 @@
                 @Code(name: "ViewController.swift", file: 01-ViewController-8.swift) {
                     @Image(source:preview-4.png, alt:"The first image is loaded into the image view in cell.")
                 }
+                Besides of the `RoundCornerImageProcessor`, we also apply a `pngSerializer` to forcibly convert the
+                loaded JPG file to PNG format when storing in the disk cache. This is necessary since JPG format does
+                not contain an alpha channel, which is necessary when storing a round corner image.
             }
             @Step {
                 The `setImage(with:)` method accepts other parameters, including a completion handler too. Let us add
@@ -158,35 +161,41 @@
     
     @Section(title: "Manipulating the Cache") {
         @ContentAndMedia {
-            In this last section, we will check some basic operation of the image cache: checking the disk cache size, 
-            and clear the whole cache. By default, Kingfisher has its own policy when manage the cache itself. You don't
-            need to worry about it in most cases. If you require more fine-grained control over caching, the following
-            section will provide some insights on this topic.
+            In this final part, we'll look at basic tasks related to image caching, like finding out the size of the 
+            disk cache and clearing all the cache. Usually, Kingfisher handles cache management automatically, so you 
+            don't need to think about it much. But if you need more detailed control over how caching works, this 
+            section will give you helpful tips and information.
         }
         
         @Steps {
             @Step {
-                First we want to tell the space that is taken by the image cache. 
-                Usually, cache size calculation and cache clear is triggered by a
-                button or navigation. But for the sake of simplicity, we are 
-                not going to add any additional button to this sample.
-                
+                First, we need to find out how much space the image cache is using. Normally, you would check the cache 
+                size or clear the cache using a button. But to keep things simple, we won't add any extra buttons to 
+                this example.
                 @Code(name: "ViewController.swift", file: 01-ViewController-10.swift)
             }
             @Step {
-                In `viewDidLoad`, we call the `asyncAfter` method on the `DispatchQueue.main` queue, which triggers a calculation of the current disk cache size there. This value indicates the disk space taken by Kingfisher as the disk cache.
+                In the `viewDidLoad` method, we use the `asyncAfter` method on the `DispatchQueue.main` queue. There we 
+                start a process to calculate the current size of the disk cache. The size we get tells us how much disk 
+                space Kingfisher is using for caching images.
                 
                 @Code(name: "ViewController.swift", file: 01-ViewController-11.swift)
             }
             @Step {
-                To make it clear, we can create an alert and display it to the user, with a button to clear the cache manually.
+                To make it clear, we can create an alert and display it to the user, with a button to clear the cache 
+                manually.
                 @Code(name: "ViewController.swift", file: 01-ViewController-12.swift) {
                     @Image(source:preview-5.png, alt:"An alert which shows the disk cache size used by Kingfisher, with a button to purge the cache.")
                 }
             }
             @Step {
-                Finally, call `clearCache` to purge both the memory cache and the disk cache. Then, if we try to reload the data of the table view, we can see the images are downloaded again from the network: in this case, "Image loaded from cache: none" will be printed to the console.
+                Lastly, use the `clearCache` function to remove all images from both the memory and disk caches. After 
+                this, when you refresh the table view's data, the images will be downloaded again from the internet. 
+                You'll notice "Image loaded from cache: none" displayed in the console, indicating the images are not 
+                being loaded from the cache this time.
+                
                 @Code(name: "ViewController.swift", file: 01-ViewController-13.swift)
+                
                 The cache cleaning is only for demonstration purpose. In practice, usually you do not need to call it yourself. Kingfisher will manage and purge the data based on its default policy.
             }
         }