Forem: Sarun W.

Inset grouped List in SwiftUI

Sarun W. — Mon, 30 Dec 2019 00:00:00 +0000

In iOS 13, Apple brought a new style to the Tables, inset grouped.

let tableView = UITableView(frame: .zero, style: .insetGrouped)

The code above would result in a table view with rounded corners and are inset from the edges of the parent view.

Inset grouped table view style

SwiftUI has a List view to represent rows or data, just like UITableView. Too bad it doesn't have inset grouped style. You has only two styles (for iOS) PlainListStyle and GroupedListStyle which you can apply to list view like this:

List {
    Text("Item 1")
    Text("Item 2")
    Text("Item 3")
}.listStyle(GroupedListStyle())

iOS 13.2

In iOS 13.2, this is no longer a case. A grouped list will use an inset grouped style when it is presented under the horizontal size class environment.

You can make your grouped lists style present as an inset grouped style by overriding your list view with regular horizontal size class (.environment(\.horizontalSizeClass, .regular)).

List {
    Text("Item 1")
    Text("Item 2")
    Text("Item 3")
}.listStyle(GroupedListStyle())
.environment(\.horizontalSizeClass, .regular)

I can't find any reference for this change in official release notes, but in my test, this was introduced in iOS 13.2.

Apple choose not to introduce a new style like InsetGroupedListStyle, but adapt GroupedListStyle based on size class. I think the reason might lie in their Human Interface Guidelines, here is some part of Inset grouped's definition.

The inset grouped style works best in a regular width environment. Because there's less space in a compact environment, an inset grouped table can cause text wrapping, especially when content is localized.

– Apple's Human Interface Guidelines

As you can see, the explanation is well aligned with the implementation detail.

Originally published at https://sarunw.com.
Find out my latest article and more at https://sarunw.com I post articles weekly there.

Related Resources

You can check out my compiled cheat sheet at fuckingswiftui.com or goshdarnswiftui.com if you want more work-friendly url.
Human Interface Guidelines – Tables

SwiftUI Animation

Sarun W. — Wed, 18 Dec 2019 00:00:00 +0000

SwiftUI is a declarative UI framework. That's not only limited to how you position them, but also how you animate them. Animation is an essential part of UI these days. In this article, we will see how easy it is to animate SwiftUI view.

Let's start with an example of how we animate view In UIKit. In this article, we will play around with simple animation, an arrow button that rotates whenever users tap it.

class ViewController: UIViewController {
    var showDetail = false

    override func viewDidLoad() {
        super.viewDidLoad()
        view.backgroundColor = .white

        let conf = UIImage.SymbolConfiguration(font: .systemFont(ofSize: 50))
        let image = UIImage(systemName: "chevron.right.circle", withConfiguration: conf)
        let button = UIButton(type: .system)
        button.translatesAutoresizingMaskIntoConstraints = false
        button.setImage(image, for: .normal)
        button.addTarget(self, action: #selector(didTapButton(sender:)), for: .touchUpInside)
        view.addSubview(button)
        view.addConstraints([
            view.centerXAnchor.constraint(equalTo: button.centerXAnchor),
            view.centerYAnchor.constraint(equalTo: button.centerYAnchor)
        ])
    }

    @objc func didTapButton(sender: UIButton) {
        showDetail.toggle()

        UIView.animate(withDuration: 0.3) {
            if self.showDetail {
                let radian = 90 * CGFloat.pi / 180
                sender.transform = CGAffineTransform(rotationAngle: radian)
            } else {
                sender.transform = CGAffineTransform.identity
            }
        }
    }
}

If you write the above code in SwiftUI, you can reduce the line of code by more than a half.

struct CustomView: View {
    @Binding var showDetail: Bool

    var body: some View {
        Button(action: {
            self.showDetail.toggle()
        }) {
            Image(systemName: "chevron.right.circle").font(.system(size: 50))
                .rotationEffect(.degrees(showDetail ? 90 : 0))
        }
    }
}

SwiftUI changes with no animation

The above example has no animation yet. The default animation for state changes is fade in and out. There are many ways to make SwiftUI animate. We would go through all of them one by one.

Add Animations to Individual Views

To make view animate, you apply animation(_:)^[1] modifier to a view. The animation applies to all child views within the view that applied for animation.

struct CustomView: View {
    @Binding var showDetail: Bool

    var body: some View {
        Button(action: {
            self.showDetail.toggle()
        }) {
            Image(systemName: "chevron.right.circle").font(.system(size: 50))
                .rotationEffect(.degrees(showDetail ? 90 : 0))
                .animation(.spring())
        }
    }
}

Spring animation

Right now, the rotation effect is animate with sprint animation. animation(_:) modifier applies to all animatable changes within the views it wraps. Let's try to add one more animatable change by scale up the image.

struct CustomView: View {
    @Binding var showDetail: Bool

    var body: some View {
        Button(action: {
            self.showDetail.toggle()
        }) {
            Image(systemName: "chevron.right.circle").font(.system(size: 50))
                .rotationEffect(.degrees(showDetail ? 90 : 0))
                .scaleEffect(showDetail ? 1.5 : 1)
                .animation(.spring())

        }
    }
}

Rotate and scale animation

Multiple animations

You can apply multiple animations if you want different animation for each change. The following example would turn off rotation animation by applying nil animation to the rotation effect.

struct CustomView: View {
    @Binding var showDetail: Bool

    var body: some View {
        Button(action: {
            self.showDetail.toggle()
        }) {
            Image(systemName: "chevron.right.circle").font(.system(size: 50))
                .rotationEffect(.degrees(showDetail ? 90 : 0))
                .animation(nil)
                .scaleEffect(showDetail ? 1.5 : 1)
                .animation(.spring())

        }
    }
}

No animation on rotation effect, while scale effect still change with spring animation

An animation will apply to all animatable changes up until that point. Define two consecutive animations would result in the closest one take effect.

struct CustomView: View {
    @Binding var showDetail: Bool

    var body: some View {
        Button(action: {
            self.showDetail.toggle()
        }) {
            Image(systemName: "chevron.right.circle").font(.system(size: 50))
                .rotationEffect(.degrees(showDetail ? 90 : 0))
                .animation(nil) // This one will apply to .rotationEffect
                .animation(.spring()) // This won't animate .rotationEffect
                .scaleEffect(showDetail ? 1.5 : 1)
                .animation(.spring())             
        }
    }
}

Timing

In UIKit, you can specify the animation duration and delay. In SwiftUI, you can also do that.

Most SwiftUI animation comes with a duration parameter with one exception, spring animation. Spring animation design in a way that let us specify spring characteristic, e.g., damping and stiffness, then duration is derived from these characters. This makes spring animation don't have duration parameter. Luckily, Apple provides another way to indirect adjust duration. The way we can change the duration is by using .speed^[2].

.speed returns an animation that has its speed multiplied by speed. For example, if you had oneSecondAnimation.speed(0.25), it would be at 25% of its normal speed, so you would have an animation that would last 4 seconds. In brief, .speed with speed less than 1 would make animation slower, more than 1 would make animation faster.

newDuration = currentDuration / speed

.speed is an instance method of Animation, it can apply to every animation, not limited to spring.

There are more instance method to modify Animation like .delay and .repeat which quite straightforward. You can check it here.

Animate the Effects of State Changes

Many views might rely on the same state. Instead of apply animations to individual views, you can also apply animations to all views by add animations in places you change your state's value. By wrapping the change of state in withAnimation function, all views that depend on that state would be animated.

From our example, By wrapping the call to .toggle() with a call to the withAnimation function, every change related to that state would be animated.

Remove all .animation and wrap self.showDetail.toggle() in withAnimation function.

struct CustomView: View {
    @Binding var showDetail: Bool

    var body: some View {
        Button(action: {
            withAnimation {
                self.showDetail.toggle()
            }
        }) {
            Image(systemName: "chevron.right.circle").font(.system(size: 50))
                .rotationEffect(.degrees(showDetail ? 90 : 0))
                .scaleEffect(showDetail ? 1.5 : 1)

        }
    }
}

You can pass the same kinds of animations to the withAnimation function that you passed to the animation(_:) modifier. In the following example, we make use of spring animation.

struct CustomView: View {
    @Binding var showDetail: Bool

    var body: some View {
        Button(action: {
            withAnimation(.spring()) {
                self.showDetail.toggle()
            }
        }) {
            Image(systemName: "chevron.right.circle").font(.system(size: 50))
                .rotationEffect(.degrees(showDetail ? 90 : 0))
                .scaleEffect(showDetail ? 1.5 : 1)                
        }
    }
}

You can still keep .animation functions in views, and it will take precedence over withAnimation. The following code will only animate scale, but not rotation.

struct CustomView: View {
    @Binding var showDetail: Bool

    var body: some View {
        Button(action: {
            withAnimation(.spring()) {
                self.showDetail.toggle()
            }
        }) {
            Image(systemName: "chevron.right.circle").font(.system(size: 50))
                .rotationEffect(.degrees(showDetail ? 90 : 0))
                .animation(nil)
                .scaleEffect(showDetail ? 1.5 : 1)
        }
    }
}

I don't put the gif here since it looks quite the same as animate a view.

These are everything you need to know about animate changes in SwiftUI. The last thing you need to know about animation is transition.

Customize View Transitions

Transition is an animation that uses when view transition on- and offscreen (hidden and show). By default, views transition on- and offscreen by fading in and out. You can customize this transition by using the transition(_:) modifier.

As an example, we will show Text view when showDetail becomes true.

struct CustomView: View {
    @Binding var showDetail: Bool

    var body: some View {
        Button(action: {
            withAnimation(.spring()) {
                self.showDetail.toggle()
            }
        }) {
            VStack {
                Image(systemName: "chevron.right.circle").font(.system(size: 50))
                    .rotationEffect(.degrees(showDetail ? 90 : 0))

                if self.showDetail {
                    Text("Detail")                        
                }
                Spacer()
            }


        }
    }
}

Default transition is fading in and out

The default transition is fade in and out, which should be good enough for most cases, but you also modify the transition. We will specify a transition Animation that makes Text view move from the top edge.

struct CustomView: View {
    @Binding var showDetail: Bool

    var body: some View {
        Button(action: {
            withAnimation(.spring()) {
                self.showDetail.toggle()
            }
        }) {
            VStack {
                Image(systemName: "chevron.right.circle").font(.system(size: 50))
                    .rotationEffect(.degrees(showDetail ? 90 : 0))

                if self.showDetail {
                    Text("Detail").transition(.move(edge: .top))
                }
                Spacer()
            }


        }
    }
}

Move from top edge transition

By specify move animation .transition(.move(edge: .top)), we make the text slide from the top edge. As you can see, the dismiss animation is not smooth as you might be expected (it slide up and hang there for a few seconds before disappear).

My first thought is to add animation to Text, but it doesn't work. Show/hide animation rely only on .transition. Luckily SwiftUI has a lot of built-in transition^[3] which you can mix and match to meet your needs.

The following code won't make the transition fade in/out.

if self.showDetail {
    Text("Detail")
        .transition(.move(edge: .top))
        .opacity(showDetail ? 1: 0) // This doesn't affect transition animation.
}

Mix and match

You can mix two transitions with .combined^[4]. It will return a new transition that is the result of both transitions being applied.

We want to add fade effect, so we combine .move with .opacity.

Text("Detail").transition(
    AnyTransition.move(edge: .top).combined(with: .opacity)
)

Combination of move and opacity transition

Asymmetric animation

If you don't want the same animation for show and hide, you can create a new animation with a different show (insertion) and hide (removal) animations using .asymmetric.

The following example, we create a new animation with .asymmetric with a slide from top appear animation and scale dismissal animation.

extension AnyTransition {
    static var moveAndFade: AnyTransition {
        let insertion = AnyTransition.move(edge: .top).combined(with: .opacity)
        let removal = AnyTransition.scale
            .combined(with: .opacity)
        return .asymmetric(insertion: insertion, removal: removal)
    }
}

And use it like other animations.

if self.showDetail {
    Text("Detail").transition(.moveAndFade)
}

Asymmetric transition

Conclusion

SwiftUI's animation is very powerful. It can do what we can do in UIKit with less code, but that is not all. All animations in SwiftUI are also interruptible!^[5] If you have ever try interruptible animation in UIKit, you know how hard it is, this fact alone makes me want to use this in my project.

All SwiftUI's animations are interruptible

Originally published at https://sarunw.com/posts/swiftui-animation/.
Find out my latest article and more at http://sarunw.com I post articles weekly there.

Related Resources

SwiftUI's ViewModifier – Learn a crucial concept in SwiftUI, view modifier, and a guide of how to create your custom modifier.

Animating Views and Transitions – Official SwiftUI's tutorial

https://developer.apple.com/documentation/swiftui/view/3278508-animation ↩︎
https://developer.apple.com/documentation/swiftui/animation/3263784-speed ↩︎
https://developer.apple.com/documentation/swiftui/anytransition ↩︎
https://developer.apple.com/documentation/swiftui/anytransition/3076194-combined ↩︎
Tap mid-animation would reverse the animation state. ↩︎

Swift Documentation

Sarun W. — Sat, 30 Nov 2019 00:00:00 +0000

Any code of your own that you haven't looked at for six or more months might as well have been written by someone else.

– Eagleson's Law

When we work with Apple's class and not sure how to use it, we have many ways to find out that information. You can find it in an online document like Apple Developer Documentation or you can find in within Xcode.

It comes in many shapes and forms.

Quick help popover

You can ⌥ – Option + click on any class to open up quick help like this:

Quick help of UIButton

Symbol inspector Quick Help

Quick help also shows under the Quick Help inspector panel.

Quick help of UIButton

Code completion hint

When you start typing, Xcode will help you by suggesting a list of a function/property/enum of that class, along with a hint of what they do at the very bottom.

Short summary of a function showing up in auto-complete

Short summary of a property showing up in auto-complete

Short summary of an enum showing up in auto-complete

Do you know that we can have these comments for our code too? This article will tell you how.

Syntax

Writing documentation for your code is like writing a comment, but with a small syntax change. You need an extra slash for single-line documentation, so instead of two, you need three slashes (///).

/// This is your User documentation.
struct User { 
    let firstName: String
    let lastName: String
}

For multi-line documentation, you need extra asterisk (*) in the opening delimiter (/** ... */).

/** 
    This is your User documentation.
    A very long one.
*/
struct User {
    let firstName: String
    let lastName: String
}

Summary and Discussion

The above documentation comment will produce a document with a summary part.

The first paragraph will be used as a documentation summary.

To add a discussion section, what you need to do is write another paragraph. Anything other than the first paragraph will belong in the discussion section.

Documentation comments in Swift use Markdown-flavored markup syntax. So when we refer to the paragraph in the document, we mean the paragraph in markdown way.

A paragraph in markdown is one or more consecutive lines of text separated by one or more blank lines.

So the example above is a paragraph with two sentences. Which makes them belong in the summary section.

/** 
    This is your User documentation. 
    A very long one.
*/

If you want the second sentence in the discussion section, make it into another paragraph by adding a new line between those sentences.

/** 
    This is your User documentation (This is summary).

    A very long one (This will be shown in the discussion section).
*/

You can also use standard markdown in your documentation.

/**
 This is your User documentation.
 A very long one.

 # Text
 It's very easy to make some words **bold** and other words *italic* with Markdown. You can even [link to Google!](http://google.com)

 # Lists
 Sometimes you want numbered lists:

 1. One
 2. Two
 3. Three

 Sometimes you want bullet points:

 * Start a line with a star
 * Profit!

 Alternatively,

 - Dashes work just as well
 - And if you have sub points, put two spaces before the dash or star:
   - Like this
   - And this

 # Code
 `` `
 if (isAwesome){
   return true
 }
 `` `
*/
struct User {
    let firstName: String
    let lastName: String
}

The above example is valid documentation, which will produce the following quick help.

The first paragraph of a documentation comment becomes the documentation Summary. Any additional content is grouped into the Discussion section.

Summary and discussion would be enough for documenting a class, property, or simple function. For a complex function, we have a few more sections that we can add.

Parameters

For a function with parameters, you can add the parameter section to Quick Help. There are two methods of documenting parameters. A Parameters Section and separate Parameter Fields.

Separate Parameter Fields

- Parameter x: ...
- Parameter y: ...

Parameters Section

This declaration style suit for function with many parameters. Using separate Parameter Fields might be a bit repetitive if you have many parameters.

- Parameters:
  - x: ...
  - y: ...
  - z: ...

Returns

For a function with a return value, you can add the return section, like the one you did with parameters.

- Returns: ...

You may specify multiple Returns items at the top level, but only the last one will be shown in Xcode's QuickHelp.

Throws

The last and the most important one. Since you can't specify error type that will be throw when you declare a function with throws keyword, it is handy to have this information sit right next to that function.

- Throws: ...

Functions that are marked as Throws should contain the following describing what kind of errors are thrown and in what situations.

/// A way that this user greets others.
///
/// Use this method to get the greeting for the user. The person you specify don't affect the way user greet, just the first name, and last name will be used.
/// - Warning: The greeting is always in the caller localization.
/// - Throws:
///     - `MyError.invalidPerson`
///     if `person` is not known by the caller.
///     - `MyError.hardToPronounce`
///     if `person` name is longer than 20 characters.
/// - Parameter person: `User` you want to greet
/// - Returns: A greeting of the current `User`.
func greeting(person: User) throws -> String {
  return "Hello \(person.firstName) \(person.lastName)"
}

Throws section

There can be only one Throws delimiter in the comments for a symbol. The behavior for multiple Throws delimiters is undefined.

Auto-generate Quick Help documentation

Xcode provides an easy way to generate documentation. To use this feature, click on any class, property, function, or part you want to add a document. Then press ⌥ – Option + ⌘ - command + / or Editor > Structure > Add documentation from Xcode's menu. Xcode will generate a document template for you.

/// <#Description#>
/// - Parameter person: <#person description#>

This feature can vary based on your Xcode version. From what I remembered, it used to generate parameters, returns, and throws of the current function, but in Xcode Version 11.1 (11A1027) it only generates parameters.

Extra Fields

There are many more Callout ^[1] that you can add to the documentation. You add Callout with the following syntax:

- Callout: description

Following are all Callout that you can use:

- Attention: ...
- Author: ...
- Authors: ...
- Bug: ...
- Complexity: ...
- Copyright: ...
- Date: ...
- Experiment: ...
- Important: ...
- Invariant: ...
- Note: ...
- Postcondition: ...
- Precondition: ...
- Remark: ...
- Remarks: ...
- Requires: ...
- See: ...
- Since: ...
- Todo: ...
- Version: ...
- Warning: ...

The Callout will render in Quick Help under the discussion section as a bold header followed by a block of text.

Here is an example of our User documentation with Warning callout.

/// A way that this user greets others.
///
/// Use this method to get the greeting for the user. The person you specify don't affect the way user greet, just the first name, and last name will be used.
/// - Warning: The greeting is always in the caller localization.
/// - Parameter person: `User` you want to greet
/// - Returns: A greeting of the current `User`.
func greeting(person: User) -> String {
  return "Hello \(person.firstName) \(person.lastName)"
}

Warning Callout

Conclusion

It is only a matter of time before your code that once obvious, turns into someone else code. We all know it is not easy and quite a time-consuming task to come up with a good document, but having good documentation will pay off in the long run.

Originally published at https://sarunw.com/posts/swift-documentation/.
Find out my latest article and more at http://sarunw.com I post articles weekly there.

Related Resources

https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/Attention.html#//apple_ref/doc/uid/TP40016497-CH29-SW1 ↩︎