Manual View

To supply a UIViewController’s view manually, in code, override its loadView method. Your job here is to obtain an instance of UIView (or a subclass of UIView) and assign it to self.view. You must not call super (for reasons that I’ll make clear later on).

Let’s try it:

1. We need a UIViewController subclass, so choose File → New → File; specify iOS → Source → Cocoa Touch Class. Click Next.

2. Name the class RootViewController, and specify that it is to be a UIViewController subclass. Uncheck “Also create XIB file” (if it happens to be checked). Click Next.

3. Confirm that we’re saving into the appropriate folder and group, and that these files will be part of the app target. Click Create.

We now have a RootViewController class, and we proceed to edit its code. In RootViewController.swift, we’ll implement loadView. To convince ourselves that the example is working correctly, we’ll give the view that we create manually an identifiable color, and we’ll put some interface inside it, namely a “Hello, World” label:

override func loadView() {
    let v = UIView()
    v.backgroundColor = .green
    self.view = v
    let label = UILabel()
    v.addSubview(label)
    label.text = "Hello, World!"
    label.autoresizingMask = [
        .flexibleTopMargin,
        .flexibleLeftMargin,
        .flexibleBottomMargin,
        .flexibleRightMargin]
    label.sizeToFit()
    label.center = CGPoint(v.bounds.midX, v.bounds.midY)
    label.frame = label.frame.integral
}

In order to see that that code works, we need to instantiate RootViewController and place that instance into our view controller hierarchy. As I explained a moment ago, we’ll do that by making RootViewController the app’s root view controller. Edit AppDelegate.swift to look like this:

import UIKit
@UIApplicationMain
class AppDelegate : UIResponder, UIApplicationDelegate {
    var window : UIWindow?
    func application(_ application: UIApplication,
        didFinishLaunchingWithOptions
        launchOptions: [UIApplicationLaunchOptionsKey : Any]?)
        -> Bool {
            self.window = self.window ?? UIWindow()
            let theRVC = RootViewController() // *
            self.window!.rootViewController = theRVC // *
            self.window!.backgroundColor = .white
            self.window!.makeKeyAndVisible()
            return true
        }
}

The two starred lines are the key: we instantiate RootViewController and make that instance the app’s root view controller. Build and run the app. Sure enough, there’s our green background and our “Hello, world” label!

When we created our view controller’s view (self.view), we never gave it a reasonable frame. This is because we are relying on someone else to frame the view appropriately. In this case, the “someone else” is the window, which responds to having its rootViewController property set to a view controller by framing the view controller’s view appropriately as the root view before putting it into the window as a subview. In general, it is the responsibility of whoever puts a view controller’s view into the interface to give the view the correct frame — and this will never be the view controller itself (although under some circumstances the view controller can express a preference in this regard). Indeed, the size of a view controller’s view may be changed as it is placed into the interface, and you must keep in mind, as you design your view controller’s view and its subviews, that this can happen. (That’s why, in the preceding code, I used autoresizing to keep the label centered in the view, no matter how the view may be resized.)

Generic Automatic View

We should distinguish between creating a view and populating it. The preceding example fails to draw this distinction. The lines that create our RootViewController’s view are merely these:

let v = UIView()
self.view = v

Everything else configures and populates the view, turning it green and putting a label into it. A more appropriate place to populate a view controller’s view is its viewDidLoad implementation, which, as I’ve already mentioned, is called after the view exists and can be referred to as self.view. We could therefore rewrite the preceding example like this (just for fun, I’ll use autolayout this time):

override func loadView() {
    let v = UIView()
    self.view = v
}
override func viewDidLoad() {
    super.viewDidLoad()
    let v = self.view!
    v.backgroundColor = .green
    let label = UILabel()
    v.addSubview(label)
    label.text = "Hello, World!"
    label.translatesAutoresizingMaskIntoConstraints = false
    NSLayoutConstraint.activate([
        label.centerXAnchor.constraint(equalTo:v.centerXAnchor),
        label.centerYAnchor.constraint(equalTo:v.centerYAnchor)
    ])
}

But if we’re going to do that, we can go even further and remove our implementation of loadView entirely! It turns out that if you don’t implement loadView, and if no view is supplied in any other way, then UIViewController’s default implementation of loadView will do exactly what we are doing: it creates a generic UIView object and assigns it to self.view.

If we needed our view controller’s view to be a particular UIView subclass, that wouldn’t be acceptable; but in this case, our view controller’s view is a generic UIView object, so it is acceptable. Comment out or delete the entire loadView implementation from the preceding code, and build and run the app; our example still works!

View in a Separate Nib

In the preceding examples, we supplied and designed our view controller’s view in code. That works, but of course we’re missing out on the convenience of configuring and populating the view by designing it graphically in Xcode’s nib editor. So now let’s see how a view controller can obtain its view, ready-made, from a nib file.

To make this work, the nib file must be properly configured in accordance with the demands of the nib-loading mechanism. The view controller instance will already have been created. It will load the nib, setting itself as the nib’s owner. The nib itself must be prepared to match this situation. In the nib, the owner object must have same class as the view controller, and its view outlet must point to the view object in the nib. Thus, when the view controller loads the nib, it automatically obtains its view through the nib-loading mechanism!

Suppose the nib is a .xib file. (Storyboards are discussed in the next section.) In a .xib file, the owner object is the File’s Owner proxy object. Therefore, in a .xib file that is to serve as the source of a view controller’s view, the following two things must be true:

• The File’s Owner class must be set to a UIViewController subclass corresponding to the class of the view controller whose view this will be. This will also cause the File’s Owner to have a view outlet.

• The File’s Owner proxy object’s view outlet must be connected to the view.

Let’s try it. We can use the example we’ve already developed, with our RootViewController class. Delete the implementation of loadView (if you haven’t already) and viewDidLoad from RootViewController.swift, because we want the view to come from a nib and we’re going to populate it in the nib. Then:

1. Choose File → New → File and specify iOS → User Interface → View. This will be a .xib file containing a UIView object. Click Next.

2. Name the file MyNib (meaning MyNib.xib). Confirm the appropriate folder and group, and make sure that the file will be part of the app target. Click Create.

3. Edit MyNib.xib. Prepare it in the way I described a moment ago:

   1. Select the File’s Owner object; in the Identity inspector, set its class to RootViewController.

   2. Connect the File’s Owner view outlet to the View object.

4. Design the view. To make it clear that this is not the same view we were creating previously, perhaps you should give the view a red background color (in the Attributes inspector). Drag a UILabel into the middle of the view and give it some text, such as “Hello, World!”

When our RootViewController instance wants its view, we want it to load the MyNib nib. To make it do that, we must associate this nib with our RootViewController instance. Recall these two lines from application(_:didFinishLaunchingWithOptions:) in AppDelegate.swift:

let theRVC = RootViewController()
self.window!.rootViewController = theRVC

We’re going to change the first of those two lines. A UIViewController has a nibName property that tells it what nib, if any, it should load to obtain its view. However, we are not allowed to set the nibName property of theRVC (it is read-only). Instead, as we instantiate the view controller, we use the designated initializer, init(nibName:bundle:), like this:

let theRVC = RootViewController(nibName:"MyNib", bundle:nil)
self.window!.rootViewController = theRVC

(The nil argument to the bundle: parameter specifies the main bundle, which is almost always what you want.)

To prove that this works, build and run. The red background appears! Our view is loading from the nib.

Now I’m going to describe a shortcut, based on the name of the nib. It turns out that if the nib name passed to init(nibName:bundle:) is nil, a nib will be sought automatically with the same name as the view controller’s class. Moreover, UIViewController’s init() turns out to be a convenience initializer: it actually calls init(nibName:bundle:), passing nil for both arguments. This means, in effect, that we can return to using init() to initialize the view controller, provided that the nib file’s name matches the name of the view controller class.

Let’s try it. Rename MyNib.xib to RootViewController.xib, and change the code that instantiates and initializes our RootViewController back to what it was before:

let theRVC = RootViewController()
self.window!.rootViewController = theRVC

Build and run. It works!

There’s an additional aspect to this shortcut based on the name of the nib. It seems ridiculous that we should end up with a nib that has “Controller” in its name merely because our view controller, as is so often the case, has “Controller” in its name. A nib, after all, is not a controller. It turns out that the runtime, in looking for a view controller’s corresponding nib, will in fact try stripping “Controller” off the end of the view controller class’s name. Thus, we can name our nib file RootView.xib instead of RootViewController.xib, and it will still be properly associated with our RootViewController instance.

When we created our UIViewController subclass, RootViewController, we saw in the Xcode dialog a checkbox offering to create an eponymous .xib file at the same time: “Also create XIB file.” We deliberately unchecked it. Suppose we had checked it; what would have happened? In that case, Xcode would have created RootViewController.swift and RootViewController.xib. Moreover, it would have configured RootViewController.xib for us: the File’s Owner’s class would already be set to the view controller’s class, RootViewController, and its view outlet would already be hooked up to the view. Thus, this view controller and .xib file are ready for use together: you instantiate the view controller with a nil nib name, and it gets its view from the eponymous nib.

Another convention involving the nib name has to do with the rules for loading resources by name generally. The same naming rule that I mentioned in Chapter 2 for an image file extended by the suffix ~ipad applies to nib files. A nib file named RootViewController~ipad.xib will be loaded on an iPad when a nib named "RootViewController" is sought. This principle can greatly simplify your life when you’re writing a universal app, as you can easily use one nib on iPhone and another nib on iPad — though you might not need to do that, since conditional interface design, described in Chapter 1, may permit you to construct an interface differing on iPad and iPhone in a single nib.

Summary

We are now in a position to summarize the sequence whereby a view controller’s view is obtained. It turns out that the entire process is driven by loadView:

1. When the view controller first decides that it needs its view, loadView is always called:

   • If we override loadView, we supply and set the view in code, and we do not call super. Therefore the process of seeking a view comes to an end.

   • If we don’t override loadView, UIViewController’s built-in default implementation of loadView takes over, and performs the rest of the process.

2. UIViewController’s default implementation of loadView looks for a nib:

   • If the view controller was instantiated with an explicit nibName:, a nib with that name is sought, and the process comes to an end. (If there is no such nib, the app will crash at launch.)

   • If the view controller was instantiated with a nil nibName:, then:

     1. An eponymous nib is sought. If it is found, it is loaded and the process comes to an end.

     2. If the view controller’s name ends in “Controller,” an eponymous nib without the “Controller” is sought. If it is found, it is loaded and the process comes to an end.

3. If we reach this point, UIViewController’s default implementation of loadView creates a generic UIView.

How a View Controller Nib is Loaded

To instantiate a view controller from a storyboard’s view controller nib, we have only to load that nib. The view controller is the nib’s sole top-level object. Loading a nib provides a reference to the instances that come from the nib’s top-level objects, so now we have a reference to the view controller instance.

Loading a view controller nib from a storyboard starts with a reference to the storyboard. You can get a reference to a storyboard either by calling the UIStoryboard initializer init(name:bundle:) or through the storyboard property of a view controller that has already been instantiated from that storyboard.

When a view controller instance stored in a storyboard nib is needed, the nib can be loaded and the view controller instantiated in one of four main ways:

Initial view controller

At most one view controller in the storyboard is designated the storyboard’s initial view controller (also called its entry point). To instantiate that view controller, call the UIStoryboard instance method instantiateInitialViewController. The view controller instance is returned.

For an app with main storyboard, that happens automatically at launch time. The main storyboard is designated the app’s main storyboard by the Info.plist key “Main storyboard file base name” (UIMainStoryboardFile). As the app launches, UIApplicationMain gets a reference to this storyboard by calling the UIStoryboard initializer init(name:bundle:), instantiates its initial view controller by calling instantiateInitialViewController, and makes that instance the window’s rootViewController.

By identifier

A view controller in a storyboard can be assigned an arbitrary string identifier; this is its Storyboard ID in the Identity inspector. To instantiate that view controller, call the UIStoryboard instance method instantiateViewController(withIdentifier:). The view controller instance is returned.

By relationship

A parent view controller in a storyboard may have immediate children, such as a UINavigationController and its initial child view controller. The nib editor will show a relationship connection between them. When the parent is instantiated (the source of the relationship), the initial children (the destination of the relationship) are instantiated automatically at the same time.

By triggered segue

A view controller in a storyboard may be (or may contain) the source of a segue whose destination is a future child view controller or a future presented view controller. When the segue is triggered and performed, it instantiates the destination view controller.

Thus, you can set up your app in such a way that a storyboard is the source of every view controller that your app will ever instantiate. Indeed, by starting with a main storyboard and by configuring relationships and triggered segues in the storyboard, you can arrange that every view controller your app will ever need will be instantiated automatically. One downside to that sort of configuration is that the storyboard can become large and overwhelming. To prevent that from happening, you can use a storyboard for some view controllers but instantiate other view controllers in code (perhaps getting their views from corresponding .xib files). Another way to keep storyboards small is to have multiple storyboards containing different view controllers; in fact, a segue in one storyboard can lead through a storyboard reference to a view controller in another storyboard, which will then be loaded automatically.

I’ll go into much greater detail about storyboards and segues and storyboard references later in this chapter.

How a View Nib is Loaded

One way or another, a view controller has now been instantiated from its storyboard nib — but its view has not. Views are loaded lazily, as we know. Sooner or later, the view controller will probably want its view (typically because it is time to put that view into the interface). How will it get it?

Recall that the view nib has been assigned a special name. Well, there’s something I didn’t tell you: the view controller, in its nib, was handed that special name, so that when it was instantiated, its nibName property was set to the name of the view nib.

Thus, when the view controller wants its view, it loads it in the normal way! It has a non-nil nibName, so it looks for a nib by that name — and finds it. The nib is loaded and the view becomes the view controller’s view.

This is true for every scene. A storyboard consists ultimately of pairs of nib files, each pair consisting of a view controller and its view. As a result, a storyboard has all the memory management advantages of nib files: none of these nib files are loaded until the instances that they contain are needed, and they can be loaded multiple times to give additional instances of the same nib objects. At the same time, you get the convenience of being able to see and edit a lot of your app’s interface simultaneously in one place.

You don’t have to use the default scene structure in a storyboard. The default is that a view controller in a storyboard scene contains its view — but you can delete the view. If you do, then that view controller will obtain its view in any of the other ways we’ve already discussed: by an implementation of loadView in the code of that view controller class, or by loading an eponymous nib file (which you supply as a .xib file) — or even, if all of that fails, by creating a generic UIView.

View Size in the Nib Editor

When you design your interface in the nib editor, every view controller’s view has to be displayed at some definite size. But that size may not be the size at which the view will appear at runtime. If you design the interface only for the size you see in the nib editor, you can get a rude surprise when you actually run the app and the view appears at some other size. Failing to take account of this possibility is a common beginner mistake. On the contrary, you should assume that the size at which a view controller’s main view is portrayed in the nib editor canvas is probably not the size it will assume at runtime.

In the nib editor, you can display the view at the size of any actual device. You can also specify an orientation. Using the Simulated Metrics pop-up menus in the Attributes inspector, you can even adjust for the presence or absence of interface elements that can affect layout (status bar, top bar, bottom bar). But no single device size, orientation, or metrics can reflect all the possible sizes the view may assume when the app runs on different devices, in different orientations, and with different surroundings.

To compensate for this uncertainty, you should take advantage of autolayout, along with conditional interface (see “Conditional Interface Design”), together with the nib editor’s ability to switch between displaying different device sizes (using the View As button at the lower left of the canvas), to make sure that your layout is coming out as you hope in every size and orientation. Your code can also take a hand in layout, and later in this chapter I’ll talk about where you might put such code; in that case you’ll probably need to run in the simulators of different device sizes to see your code at work.

Bars and Underlapping

A view controller’s view will often have to adapt to the presence of bars at the top and bottom of the screen:

The status bar is underlapped

The status bar is transparent, so that the region of a view behind it is visible through it. The root view, and any other fullscreen view, must occupy the entire window, including the status bar area, the top of the view being visible behind the transparent status bar. You’ll want to design your view so that its top doesn’t contain any interface objects that will be overlapped by the status bar.

Top and bottom bars may be underlapped

The top and bottom bars displayed by a navigation controller (navigation bar, toolbar) or tab bar controller (tab bar) can be translucent. When they are, your view controller’s view is, by default, extended behind the translucent bar, underlapping it. Again, you’ll want to design your view so that this underlapping doesn’t conceal any of your view’s important interface.

The status bar may be present or absent. Top and bottom bars may be present or absent, and, if present, their height can change. How will your interface cope with such changes? The primary coping mechanism is the view controller’s layout guides.

Recall (from Chapter 1) that a view controller supplies two properties, its topLayoutGuide and its bottomLayoutGuide. The edges of these guide objects move automatically at runtime to reflect the view’s environment:

topLayoutGuide

The topLayoutGuide’s bottom is positioned as follows:

• If there is a status bar and no top bar, at the bottom of the status bar.

• If there is a top bar, at the bottom of the top bar.

• If there is no top bar and no status bar, at the top of the view.

bottomLayoutGuide

The bottomLayoutGuide’s top is positioned as follows:

• If there is a bottom bar, at the top of the bottom bar.

• If there is no bottom bar, at the bottom of the view.

The easiest way to involve the layout guides in your view layout is through autolayout and constraints. By constraining a view by its top to the bottom of the topLayoutGuide, or by its bottom to the top of the bottomLayoutGuide, you guarantee that the view will move when the layout guide changes. Such constraints are easy to form in the nib editor — they are the default. When you’re using anchor notation for creating a constraint in code, you’ll use the topLayoutGuide’s bottomAnchor and the bottomLayoutGuide’s topAnchor.

If you need actual numbers in order to perform layout-related calculations, a layout guide’s spacing from the corresponding edge of the view controller’s main view is reported by its length property. If you are constructing a constraint relative to the height of a layout guide, you can use its heightAnchor property.

var hide = false
override var prefersStatusBarHidden : Bool {
    return self.hide
}
@IBAction func doButton(_ sender: Any) {
    self.hide = !self.hide
    UIView.animate(withDuration:0.4) {
        self.setNeedsStatusBarAppearanceUpdate()
        self.view.layoutIfNeeded()
    }
}

Resizing Events

A UIViewController receives events that notify it of pending view size changes. (Trait collections, size classes, and view layout events were discussed in Chapter 1.)

The following events are associated primarily with rotation of the interface (as well as with iPad multitasking; see Chapter 9); UIViewController receives them by virtue of adopting the appropriate protocol:

willTransition(to:with:) (UIContentContainer protocol)

The first parameter is the new trait collection (a UITraitCollection). Sent when the app is about to undergo a change in the trait collection (because the size classes will change). Common examples are rotation of 90 degrees on an iPhone, or a change between fullscreen and splitscreen on an iPad. This event is not sent on launch or when your view controller’s view is first embedded into the interface. If you override this method, call super.

viewWillTransition(to:with:) (UIContentContainer protocol)

The first parameter is the new size (a CGSize). Sent when the app is about to undergo rotation (even if the rotation turns out to be 180 degrees and the size won’t actually change) or an iPad multitasking size change. The old size is still available as self.view.bounds.size. This event is not sent on launch or when your view controller’s view is first embedded into the interface. If you override this method, call super.

traitCollectionDidChange(_:) (UITraitEnvironment protocol)

Sent after the trait collection changes. The parameter is the old trait collection; the new trait collection is available as self.traitCollection. Sent after the trait collection changes, including on launch or when the trait collection is set for the first time (in which case the old trait collection will be nil).

(The with: parameter in the first two methods is a transition coordinator; I’ll describe its use later in this chapter.)

In addition, a UIViewController receives these events related to the layout of its view:

updateViewConstraints

The view is about to be told to update its constraints (updateConstraints), including at application launch. If you override this method, call super.

viewWillLayoutSubviews

viewDidLayoutSubviews

These events surround the moment when the view is sent layoutSubviews, including at application launch.

In a situation where all these events are sent, the order is:

1. willTransition(to:with:) (the trait collection)

2. viewWillTransition(to:with:) (the size)

3. updateViewConstraints

4. traitCollectionDidChange(_:)

5. viewWillLayoutSubviews

6. viewDidLayoutSubviews

There is no guarantee that any of these events, if sent, will be sent exactly once. Your code should take some care to do nothing if nothing relevant has changed.

Rotation

Your app can rotate, moving its top to correspond to a different edge of the device’s screen. Rotation expresses itself in two ways:

The status bar orientation changes

You can hear about this (though this will rarely be necessary) by way of these app delegate events and notifications:

• application(_:willChangeStatusBarOrientation:duration:)

• .UIApplicationWillChangeStatusBarOrientation notification

• application(_:didChangeStatusBarOrientation:)

• .UIApplicationDidChangeStatusBarOrientation notification

The current orientation (which is also the app’s current orientation) is available from the UIApplication as its statusBarOrientation; the app delegate methods also provide the other orientation (the one we are changing to or from, respectively) as the second parameter. Possible values (UIInterfaceOrientation) are:

• .portrait

• .portraitUpsideDown

• .landscapeLeft

• .landscapeRight

Two global convenience functions, UIInterfaceOrientationIsLandscape and UIInterfaceOrientationIsPortrait, take a UIInterfaceOrientation and return a Bool.

The view controller’s view is resized

The view controller receives events related to resizing, as I described in the preceding section. These may or may not include a change in the trait collection. Thus, the most general way to learn that rotation is taking place is by detecting the size change, through viewWillTransition(to:with:). On the other hand, you are more likely to care about a 90 degree rotation on an iPhone than any other kind of rotation, and in that case detection of the trait collection change, through willTransition(to:with:), may be appropriate.

There are two complementary uses for rotation:

Compensatory rotation

The app rotates to compensate for the orientation of the device, so that the app appears right way up with respect to how the user is holding the device.

Forced rotation

The app rotates when a particular view appears in the interface, or when the app launches, to indicate that the user needs to rotate the device in order to view the app the right way up. This is typically because the interface has been specifically designed, in the face of the fact that the screen is not square, to appear in just one orientation (portrait or landscape).

In the case of the iPhone, no law says that your app has to perform compensatory rotation. Most of my iPhone apps do not do so; indeed, I have no compunction about doing just the opposite, namely forced rotation. My view controller views often look best in just one orientation (either just portrait or just landscape), and they stubbornly stay there regardless of how the user holds the device. A single app may contain view controller views that work best in different orientations; thus, my app forces the user to rotate the device differently depending on what view is being displayed. This is reasonable, because the iPhone is small and easily reoriented with a twist of the user’s wrist, and it has a natural right way up. iPhone apps do not generally rotate to an upside-down orientation, because the user is unlikely to hold the device that way.

On the other hand, Apple thinks of an iPad as having no natural top, and would prefer iPad apps to rotate to at least two opposed orientations (such as portrait with the button on the bottom and portrait with the button on the top), and preferably to all four possible orientations, so that the user isn’t restricted in how the device is held.

It’s trivial to let your app rotate to two opposed orientations, because once the app is set up to work in one of them, it can work with no change in the other. But allowing a single interface to rotate between two orientations that are 90 degrees apart is trickier, because its dimensions must change — roughly speaking, its height and width are transposed — and this may require a change of layout and might even call for more substantial alterations, such as removal or addition of part of the interface. A good example is the behavior of Apple’s Mail app on the iPad: in landscape, the master pane and the detail pane appear side by side, but in portrait, the master pane is removed and must be summoned as a temporary overlay on top of the detail pane.

override var supportedInterfaceOrientations : UIInterfaceOrientationMask {
    return .portrait
}

let orientation = UIDevice.current.orientation

Presentation and Dismissal

The two key methods for presenting and dismissing a view controller are:

present(_:animated:completion:)

To make a view controller present another view controller, you send the first view controller this message, handing it the second view controller, which you will probably instantiate for this very purpose. (The first view controller is very typically self.)

We now have two view controllers that stand in the relationship of being one another’s presentingViewController and presentedViewController respectively. The presented view controller is retained, and its view effectively replaces or covers the presenting view controller’s view in the interface (I’ll talk later about ways to refine that arrangement).

dismiss(animated:completion:)

The “presented” state of affairs described in the previous paragraph persists until the presenting view controller is sent this message. The presented view controller’s view is then removed from the interface, the original interface is restored, and the presented view controller is released; it will thereupon typically go out of existence, together with its view, its child view controllers and their views, and so on.

As the view of the presented view controller appears, and again when it is dismissed, there’s an option for animation to be performed as the transition takes place (the animated: argument, a Bool). The completion: parameter, which can be nil, lets you supply a function to be run after the transition (including the animation) has occurred. I’ll talk later about how to govern the nature of the animation.

The presenting view controller (the presented view controller’s presentingViewController) is not necessarily the view controller to which you sent present(_:animated:completion:). It will help if we distinguish three roles that view controllers can play in presenting a view controller:

Presented view controller

The first argument to present(_:animated:completion:).

Original presenter

The view controller to which present(_:animated:completion:) was sent. Apple sometimes refers to this view controller as the source; “original presenter” is my own term.

The presented view controller is set as the original presenter’s presentedViewController.

Presenting view controller

The view controller whose view is replaced or covered by the presented view controller’s view. By default, it is the view controller whose view is the entire interface — namely, either the root view controller or an already existing presented view controller. It might not be the same as the original presenter.

This view controller is set as the presented view controller’s presentingViewController. The presented view controller is set as the presenting view controller’s presentedViewController. (Thus, the presented view controller might be the presentedViewController of two different view controllers.)

The receiver of dismiss(animated:completion:) may be any of those three objects; the runtime will use the linkages between them to transmit the necessary messages up the chain on your behalf to the presentingViewController.

You can test whether a view controller’s presentedViewController or presentingViewController is nil to learn whether presentation is occurring. For example, a view controller whose presentingViewController is nil is not a presented view controller at this moment.

A view controller can have at most one presentedViewController. If you send present(_:animated:completion:) to a view controller whose presentedViewController isn’t nil, nothing will happen and the completion function is not called (and you’ll get a warning from the runtime). However, a presented view controller can itself present a view controller, so there can be a chain of presented view controllers.

If you send dismiss(animated:completion:) to a view controller in the middle of a presentation chain — a view controller that has both a presentingViewController and a presentedViewController — then its presentedViewController is dismissed.

If you send dismiss(animated:completion:) to a view controller whose presentedViewController is nil and that has no presentingViewController, nothing will happen (not even a warning in the console), and the completion function is not called.

Let’s make one view controller present another. We could do this simply by connecting one view controller to another in a storyboard with a modal segue, but I don’t want you to do that: a modal segue calls present(_:animated:completion:) for you, whereas I want you to call it yourself.

So start with an iPhone project made from the Single View app template. This contains one view controller class, called ViewController. Our first move must be to add a second view controller class, an instance of which will function as the presented view controller:

1. Choose File → New → File and specify iOS → Source → Cocoa Touch Class. Click Next.

2. Name the class SecondViewController, make sure it is a subclass of UIViewController, and check the XIB checkbox so that we can design this view controller’s view quickly and easily in the nib editor. Click Next.

3. Confirm the folder, group, and app target membership, and click Create.

4. Edit SecondViewController.xib, and do something there to make the view distinctive, so that you’ll recognize it when it appears; for example, give it a red background color.

5. In ViewController.swift, add some code that instantiates SecondViewController and presents it:

   @IBAction func doPresent(_ sender: Any?) {
       let svc = SecondViewController(nibName: nil, bundle: nil)
       self.present(svc, animated:true)
   }

6. Finally, let’s put a button into the interface that triggers doPresent. Edit Main.storyboard and add a button to the ViewController’s view’s interface. Connect that button to ViewController’s doPresent.

Run the project. In ViewController’s view, tap the button. SecondViewController’s view slides into place over ViewController’s view.

In our lust for instant gratification, we have neglected to provide a way to dismiss the presented view controller. If you’d like to do that, edit SecondViewController.xib, put a button into SecondViewController’s view, and connect it to an action method in SecondViewController.swift:

@IBAction func doDismiss(_ sender: Any?) {
    self.presentingViewController!.dismiss(animated:true)
}

Run the project. You can now alternate between ViewController’s view and SecondViewController’s view, presenting and dismissing in turn. Go ahead and play for a while with your exciting new app; I’ll wait.

Configuring a Presentation

This section describes some configurable aspects of how a view controller’s view behaves as the view controller is presented.

@IBAction func doPresent(_ sender: Any?) {
    let vc = ExtraViewController(nibName: nil, bundle: nil)
    vc.modalTransitionStyle = .flipHorizontal
    self.definesPresentationContext = true // *
    vc.modalPresentationStyle = .currentContext // *
    self.present(vc, animated: true)
}

@IBAction func doPresent(_ sender: Any?) {
    let vc = ExtraViewController(nibName: nil, bundle: nil)
    vc.modalTransitionStyle = .flipHorizontal
    self.definesPresentationContext = true
    self.providesPresentationContextTransitionStyle = true // *
    self.modalTransitionStyle = .coverVertical // *
    vc.modalPresentationStyle = .currentContext
    self.present(vc, animated: true)
}

Communication with a Presented View Controller

In real life, it is highly probable that the original presenter will have additional information to impart to the presented view controller as the latter is created and presented, and that the presented view controller will want to pass information back to the original presenter as it is dismissed. Knowing how to arrange this exchange of information is very important.

Passing information from the original presenter to the presented view controller is usually easy, because the original presenter typically has a reference to the presented view controller before the latter’s view appears in the interface. For example, suppose the presented view controller has a public data property. Then the original presenter can easily set this property, especially if the original presenter is the one instantiating the presented view controller in the first place:

@IBAction func doPresent(_ sender: Any?) {
    let svc = SecondViewController(nibName: nil, bundle: nil)
    svc.data = "This is very important data!" // *
    self.present(svc, animated:true)
}

Indeed, if you’re instantiating the presented view controller in code, as we are here, you might even give its class a designated initializer that accepts — and thus requires — this data. In my Latin vocabulary app, for example, I’ve given DrillViewController a designated initializer init(data:) precisely so that whoever creates it must pass it the data it will need to do its job while it exists.

Passing information back from the presented view controller to the original presenter is a more interesting problem. The presented view controller will need to know who the original presenter is, but it doesn’t automatically have a reference to it (the original presenter, remember, is not necessarily the same as the presentingViewController). Moreover, the presented view controller will need to know the signature of some method, implemented by the original presenter, which it can call in order to hand over the information — and this needs to work regardless of the original presenter’s class.

The standard solution is to use delegation, as follows:

1. The presented view controller defines a protocol declaring a method that the presented view controller wants to call before it is dismissed.

2. The original presenter conforms to this protocol: it declares adoption of the protocol, and it implements the required method.

3. The presented view controller provides a means whereby it can be handed a reference to an object conforming to this protocol. Think of that reference as the presented view controller’s delegate. Very often, this will be a property — perhaps called delegate — typed as the protocol. (Such a property should probably be weak, since an object usually has no business retaining its delegate.)

4. As the original presenter creates and configures the presented view controller, it hands the presented view controller a reference to itself, in its role as adopter of the protocol, by assigning itself as the presented view controller’s delegate.

This sounds elaborate, but with practice you’ll find yourself able to implement it very quickly. And you can see why it works: because its delegate is typed as the protocol, the presented view controller is guaranteed that this delegate, if it has one, implements the method declared in the protocol. Thus, the desired communication from the presented view controller to whoever configured and created it is assured.

Let’s modify our earlier example — the one where the root view controller, ViewController, presents SecondViewController — to embody this architecture. First, edit SecondViewController.swift to look like this:

protocol SecondViewControllerDelegate : class {
    func accept(data:Any!)
}
class SecondViewController : UIViewController {
    var data : Any?
    weak var delegate : SecondViewControllerDelegate?
    @IBAction func doDismiss(_ sender: Any?) {
        self.delegate?.accept(data:"Even more important data!")
    }
}

It is now ViewController’s job to adopt the SecondViewControllerDelegate protocol, and to set itself as the SecondViewController’s delegate. If it does so, then when the delegate method is called, ViewController will be handed the data, and it should then dismiss the SecondViewController:

class ViewController : UIViewController, SecondViewControllerDelegate {
    @IBAction func doPresent(_ sender: Any?) {
        let svc = SecondViewController(nibName: nil, bundle: nil)
        svc.data = "This is very important data!"
        svc.delegate = self // *
        self.present(svc, animated:true)
    }
    func accept(data:Any!) {
        // do something with data here
        self.dismiss(animated:true)
    }
}

That is a perfectly satisfactory implementation, and we could stop at this point. For completeness, I’ll just show a variation that I consider slightly better. One might object that too much responsibility rests upon the original presenter (the delegate): it is sent the data and then it must also dismiss the presented view controller. Perhaps the presented view controller should hand back any data and should then dismiss itself (as it did in my earlier example). Even better, the presented view controller should hand back any data automatically, regardless of how it is dismissed.

We can arrange that by putting all the responsibility on the presented view controller:

1. Edit ViewController’s accept(data:) so that it accepts the data and no more — that is, delete the self.dismiss call.

2. Back in SecondViewController, we will implement both the task of dismissal and the task of handing back the data, separately. To make the latter task automatic, SecondViewController will arrange to hear about its own dismissal by implementing viewWillDisappear (discussed later in this chapter), which will then call accept(data:) to ensure that the data is handed across. There is more than one reason why viewWillDisappear might be called; we can ensure that this really is the moment of our own dismissal by consulting isBeingDismissed.

Here is what SecondViewController should look like now:

protocol SecondViewControllerDelegate : class {
    func accept(data:Any!)
}
class SecondViewController : UIViewController {
    var data : Any?
    weak var delegate : SecondViewControllerDelegate?
    @IBAction func doDismiss(_ sender: Any?) {
        self.presentingViewController!.dismiss(animated:true)
    }
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        if self.isBeingDismissed {
            self.delegate?.accept(data:"Even more important data!")
        }
    }
}

If you’re using a storyboard and a Present Modally segue, things are a bit different. You don’t have access to the presented view controller at the moment of creation; instead, in the original presenter (the source of the segue) you implement prepare(for:sender:) as a moment when the original presenter and the presented view controller will meet, and the former can hand across any needed data, set itself as delegate, and so forth. If you dismiss the presented view controller automatically by way of an unwind segue, the same is true in reverse: the presented view controller calls the delegate method in its own prepare(for:sender:). I’ll give more details later in this chapter.

Adaptive Presentation

When a view controller with a modalPresentationStyle of .pageSheet or .formSheet is about to appear, you get a second opportunity to change its effective modalPresentationStyle, and even to substitute a different view controller, based on the current trait collection environment. This is called adaptive presentation. The idea is that your presented view controller might appear one way for certain trait collections and another way for others — for example, on an iPad as opposed to an iPhone.

To implement adaptive presentation, you use a view controller’s presentation controller (presentationController, a UIPresentationController). Before presenting a view controller, you set its presentation controller’s delegate (adopting the UIAdaptivePresentationControllerDelegate protocol). Before the presented view controller’s view appears, the delegate is sent these messages:

adaptivePresentationStyle(for:traitCollection:)

Asks for a modal presentation style. The first parameter is the presentation controller; you can consult its presentationStyle to learn what the modalPresentationStyle would be. Return .none if you don’t want to change the presentation style.

presentationController(_:willPresentWithAdaptiveStyle:transitionCoordinator:)

Called just before the presentation takes place. If the adaptiveStyle: is .none, adaptive presention is not going to take place.

presentationController(_:viewControllerForAdaptivePresentationStyle:)

Called only if adaptive presention is going to take place. Return a view controller to be presented, substituting it for the current presented view controller (or nil to keep the current presented view controller).

What adaptations are you permitted to perform? First, as I’ve already said, the original modalPresentationStyle should be .pageSheet or .formSheet. It isn’t illegal to try to adapt from other presentation styles, but it isn’t going to work either. Then the possibilities are as follows:

Adapt sheet to full screen

You can adapt .pageSheet or .formSheet to .fullScreen or .overFullScreen.

(If the trait collection’s horizontal size class is .compact — an iPhone, including an iPhone 6 Plus in portrait — then if you adapt .pageSheet or .formSheet to .pageSheet, .currentContext, .overCurrentContext, or even .popover, the runtime behaves as if you had adapted to .fullScreen.)

Adapt page sheet to form sheet

You can adapt .pageSheet to .formSheet.

On an iPad, the difference is clearly visible; on an iPhone 6 Plus in landscape, the two sheet types are indistinguishable.

On an iPhone (including an iPhone 6 Plus in portrait), the result is something a little unusual and unexpected. It’s similar to .pageSheet on the iPad in portrait orientation: it is full width, but a little shorter than full height, leaving a gap behind the status bar. (You can also obtain this configuration by adapting .pageSheet or .formSheet to .none.)

For example, here’s how to present a view controller as a .pageSheet on iPad but as .overFullScreen on iPhone:

extension ViewController : UIAdaptivePresentationControllerDelegate {
    @IBAction func doPresent(_ sender: Any?) {
        let svc = SecondViewController(nibName: nil, bundle: nil)
        svc.modalPresentationStyle = .pageSheet
        svc.presentationController!.delegate = self // *
        self.present(svc, animated:true)
    }
    func adaptivePresentationStyle(for controller: UIPresentationController,
        traitCollection: UITraitCollection) -> UIModalPresentationStyle {
            if traitCollection.horizontalSizeClass == .compact {
                return .overFullScreen
            }
            return .none // don't adapt
    }
}

Now let’s extend that example by also replacing the view controller presented on iPad with a different view controller to be presented on iPhone (this method won’t be called when adaptivePresentationStyle returns .none):

extension ViewController : UIAdaptivePresentationControllerDelegate {
    func presentationController(_ controller: UIPresentationController,
        viewControllerForAdaptivePresentationStyle: UIModalPresentationStyle)
        -> UIViewController? {
            let newvc = ThirdViewController(nibName: nil, bundle: nil)
            return newvc
    }
}

In real life, of course, when substituting a different view controller, you might need to prepare it before returning it (for example, giving it data and setting its delegate). A common scenario is to return the same view controller wrapped in a navigation controller; I’ll illustrate in Chapter 9.

Presentation and Rotation

When the presenting view controller is the top-level view controller — the root view controller, or a fullscreen presented view controller — the presented view controller becomes the new top-level view controller. This means that its supportedInterfaceOrientations is consulted and honored. If these supportedInterfaceOrientations do not intersect with the app’s current orientation, the app’s orientation will rotate, as the presented view appears, to an orientation that the presented view controller supports — and the same thing will be true in reverse when the presented view controller is dismissed.

Thus, a presented view controller allows you to force the interface to rotate. In fact, a presented view controller is the only officially sanctioned way to force the interface to rotate.

Forced rotation is a perfectly reasonable thing to do, especially on the iPhone, where the user can easily rotate the device to compensate for the new orientation of the interface. Some views work better in portrait than landscape, or better in landscape than portrait (especially on the small screen). Forced rotation lets you ensure that each view appears only in the orientation in which it works best.

The presented view controller’s supportedInterfaceOrientations bitmask might permit multiple possible orientations. The view controller may then also wish to specify which of those multiple orientations it should have initially when it is presented. To do so, override preferredInterfaceOrientationForPresentation; this property is consulted before supportedInterfaceOrientations, and its value is a single UIInterfaceOrientation (not a bitmask).

Tab Bar Items

For each view controller you assign as a tab bar controller’s child, you’re going to need a tab bar item, which will appear as its representative in the tab bar. This tab bar item will be your child view controller’s tabBarItem. A tab bar item is a UITabBarItem; this is a subclass of UIBarItem, an abstract class that provides some of its most important properties, such as title, image, and isEnabled.

There are two ways to make a tab bar item:

By borrowing it from the system

Instantiate UITabBarItem using init(tabBarSystemItem:tag:), and assign the instance to your child view controller’s tabBarItem. Consult the documentation for the list of available system items. Unfortunately, you can’t customize a system tab bar item’s title; you must accept the title the system hands you. (You can’t work around this restriction by somehow copying a system tab bar item’s image.)

By making your own

Instantiate UITabBarItem using init(title:image:tag:) and assign the instance to your child view controller’s tabBarItem. Alternatively, use the view controller’s existing tabBarItem and set its image and title. Instead of setting the title of the tabBarItem, you can set the title property of the view controller itself; doing this automatically sets the title of its current tabBarItem (unless the tab bar item is a system tab bar item), though the converse is not true.

You can add a separate selectedImage later, or possibly by initializing with init(title:image:selectedImage:). The selectedImage will be displayed in place of the normal image when this tab bar item is selected in the tab bar.

The image (and selectedImage) for a tab bar item should be a 30×30 PNG; if it is larger, it will be scaled down as needed. By default, it will be treated as a transparency mask (a template): the hue of its pixels will be ignored, and the transparency of its pixels will be combined with the tab bar’s tintColor, which may be inherited from higher up the view hierarchy. However, you can instead display the image as is, and not as a transparency mask, by deriving an image whose rendering mode is .alwaysOriginal (see Chapter 2).

You can also give a tab bar item a badge (see the documentation on the badgeValue property). Other ways in which you can customize the look of a tab bar item are discussed in Chapter 12. For example, you can control the font and style of the title, or you can give it an empty title and offset the image.

Configuring a Tab Bar Controller

Basic configuration of a tab bar controller is very simple: just hand it the view controllers that will be its children. To do so, collect those view controllers into an array and set the UITabBarController’s viewControllers property to that array. The view controllers in the array are now the tab bar controller’s child view controllers; the tab bar controller is the parent of the view controllers in the array. The tab bar controller is also the tabBarController of the view controllers in the array and of all their children; thus a child view controller at any depth can learn that it is contained by a tab bar controller and can get a reference to that tab bar controller. The tab bar controller retains the array, and the array retains the child view controllers.

Here’s a simple example from one of my apps, in which I construct and display a tab bar interface in code:

func application(_ application: UIApplication,
    didFinishLaunchingWithOptions
    launchOptions: [UIApplicationLaunchOptionsKey : Any]?)
    -> Bool {
        self.window = self.window ?? UIWindow()
        let vc1 = GameBoardController()
        let vc2 =
            UINavigationController(rootViewController:SettingsController())
        let tabBarController = UITabBarController()
        tabBarController.viewControllers = [vc1, vc2]
        tabBarController.selectedIndex = 0
        tabBarController.delegate = self
        self.window!.rootViewController = tabBarController
        self.window!.makeKeyAndVisible()
        return true
}

The tab bar controller’s tab bar will automatically display the tabBarItem of each child view controller. The order of the tab bar items is the order of the view controllers in the tab bar controller’s viewControllers array. Thus, a child view controller will probably want to configure its tabBarItem property early in its lifetime, so that the tabBarItem is ready by the time the view controller is handed as a child to the tab bar controller. Observe that viewDidLoad is not early enough! That’s because the view controllers (other than the initially selected view controller) have no view when the tab bar controller initially appears. Thus it is common to implement an initializer for this purpose.

Here’s an example from the same app as the previous code (in the GameBoardController class):

init() {
    super.init(nibName:nil, bundle:nil)
    // tab bar configuration
    self.tabBarItem.image = UIImage(named: "game")
    self.title = "Game"
}

If you change the tab bar controller’s view controllers array later in its lifetime and you want the corresponding change in the tab bar’s display of its items to be animated, call setViewControllers(_:animated:).

Initially, by default, the first child view controller’s tab bar item is selected and its view is displayed. To ask the tab bar controller which tab bar item the user has selected, you can couch your query in terms of the child view controller (selectedViewController) or by index number in the array (selectedIndex). You can also set these properties to switch between displayed child view controllers programmatically. (In fact, it is legal to set a tab bar controller’s tab bar’s isHidden to true and take charge of switching between children yourself — though if that’s your desired architecture, a UIPageViewController might be more appropriate.)

You can also set the UITabBarController’s delegate (adopting UITabBarControllerDelegate). The delegate gets messages allowing it to prevent a given tab bar item from being selected, and notifying it when a tab bar item is selected and when the user is customizing the tab bar from the More item.

If the tab bar contains few enough items that it doesn’t need a More item, there won’t be one, and the tab bar won’t be user-customizable. If there is a More item, you can exclude some tab bar items from being customizable by setting the customizableViewControllers property to an array that lacks them; setting this property to nil means that the user can see the More list but can’t rearrange the items. Setting the viewControllers property sets the customizableViewControllers property to the same value, so if you’re going to set the customizableViewControllers property, do it after setting the viewControllers property. The moreNavigationController property can be compared with the selectedViewController property to learn whether the user is currently viewing the More list; apart from this, the More interface is mostly out of your control, but I’ll discuss some sneaky ways of customizing it in Chapter 12.

(If you allow the user to rearrange items, you would presumably want to save the new arrangement and restore it the next time the app runs. You might use UserDefaults for this; you could also take advantage of the built-in automatic state saving and restoration facilities, discussed later in this chapter.)

You can configure a UITabBarController in a .storyboard or .xib file. The UITabBarController’s contained view controllers can be set directly — in a storyboard, there will be a “view controllers” relationship between the tab bar controller and each of its children — and the contained view controllers will be instantiated together with the tab bar controller. Moreover, each contained view controller has a Tab Bar Item; you can select this and set many aspects of the tabBarItem, such as its system item or its title, image, selected image, and tag, directly in the nib. (If a view controller in a nib doesn’t have a Tab Bar Item and you want to configure this view controller for use in a tab bar interface, drag a Tab Bar Item from the Object library onto the view controller.)

To start a project with a main storyboard that has a UITabBarController as its root view controller, begin with the Tabbed app template.

Bar Button Items

The items in a UIToolbar or a UINavigationBar are bar button items — UIBarButtonItem, a subclass of UIBarItem. A bar button item comes in one of two broadly different flavors:

Basic bar button item

The bar button item behaves like a simple button.

Custom view

The bar button item has no inherent behavior, but has (and displays) a customView.

UIBarItem is not a UIView subclass. A basic bar button item is button-like, but it has no frame, no UIView touch handling, and so forth. A UIBarButtonItem’s customView, however, is a UIView — indeed, it can be any kind of UIView. Thus, a bar button item with a customView can display any sort of view in a toolbar or navigation bar, and that view can implement touch handling as appropriate, or it can be informational.

Let’s start with the basic bar button item (no custom view). A bar button item, like a tab bar item, inherits from UIBarItem the title, image, and isEnabled properties. The title text color, by default, comes from the bar button item’s tintColor, which may be inherited from the bar itself or from higher up the view hierarchy. Assigning an image removes the title. The image should usually be quite small; Apple recommends 22×22. By default, it will be treated as a transparency mask (a template): the hue of its pixels will be ignored, and the transparency of its pixels will be combined with the bar button item’s tintColor. However, you can instead display the image as is, and not as a transparency mask, by deriving an image whose rendering mode is .alwaysOriginal (see Chapter 2).

A basic bar button item has a style property (UIBarButtonItemStyle); this will usually be .plain. The alternative, .done, causes the title to be bold. You can further refine the title font and style. In addition, a bar button item can have a background image; this will typically be a small, resizable image, and can be used to provide a border. Full details appear in Chapter 12.

A bar button item also has target and action properties. These contribute to its button-like behavior: tapping a bar button item can trigger an action method elsewhere.

There are three ways to make a bar button item:

By borrowing it from the system

Make a UIBarButtonItem with init(barButtonSystemItem:target:​action:). Consult the documentation for the list of available system items; they are not the same as for a tab bar item. You can’t assign a title or change the image. (But you can change the tint color or assign a background image.)

By making your own basic bar button item

Make a UIBarButtonItem with init(title:style:target:action:) or with init(image:style:target:action:).

An additional initializer, init(image:landscapeImagePhone:style:target:​action:), lets you supply two images, one for portrait orientation, the other for landscape orientation; this is because by default, the bar’s height might change when the interface is rotated. Alternatively, you can use size class–aware images to handle this situation (see Chapter 2).

By making a custom view bar button item

Make a UIBarButtonItem with init(customView:), supplying a UIView that the bar button item is to display. The bar button item has no action and target; the UIView itself must somehow implement button behavior if that’s what you want. For example, the customView might be a UISegmentedControl, but then it is the UISegmentedControl’s target and action that give it button behavior.

Bar button items in a toolbar are horizontally positioned automatically by the system. You can provide hints to help with this positioning. If you know that you’ll be changing an item’s title dynamically, you’ll probably want its width to accommodate the longest possible title right from the start; to arrange that, set the possibleTitles property to a Set of strings that includes the longest title. Alternatively, you can supply an absolute width. Also, you can incorporate spacers into the toolbar; these are created with init(barButtonSystemItem:target:action:), but they have no visible appearance, and cannot be tapped. Place .flexibleSpace system items between the visible items to distribute the visible items equally across the width of the toolbar. There is also a .fixedSpace system item whose width lets you insert a space of defined size.

Navigation Items and Toolbar Items

What appears in a navigation bar (UINavigationBar) depends upon the navigation items (UINavigationItem) in its stack. In a navigation interface, the navigation controller will manage the navigation bar’s stack for you, but you must still configure each navigation item by setting properties of the navigationItem of each child view controller. The UINavigationItem properties are as follows (see also Chapter 12):

title or titleView

Determines what is to appear in the center of the navigation bar when this navigation item is at the top of the stack.

The title is a string. Setting the view controller’s title property sets the title of the navigationItem automatically, and is usually the best approach.

The titleView can be any kind of UIView; if set, it will be displayed instead of the title. The titleView can implement further UIView functionality; for example, it can be tappable. Even if you are using a titleView, you should still give your view controller a title, as it will be needed for the back button when a view controller is pushed onto the stack on top of this one.

Figure 6-1 shows the TidBITS News master view, with the navigation bar displaying a titleView which is a (tappable) image view; the master view controller’s title, which is "TidBITS", is therefore not displayed. In the TidBITS News detail view controller’s navigation item, the titleView is a UISegmentedControl providing a Previous and Next button; when it is pushed onto the stack, the back button displays the master view controller’s title (Figure 6-8).

Figure 6-8. A segmented control in the center of a navigation bar

prompt

An optional string to appear centered above everything else in the navigation bar. The navigation bar’s height will be increased to accommodate it.

rightBarButtonItem or rightBarButtonItems

A bar button item or, respectively, an array of bar button items to appear at the right side of the navigation bar; the first item in the array will be rightmost.

In Figure 6-8, the text size button is a right bar button item; it has nothing to do with navigation, but is placed here merely because space is at a premium on the small iPhone screen.

backBarButtonItem

When a view controller is pushed on top of this view controller, the navigation bar will display at its left a button pointing to the left, whose title is this view controller’s title. That button is this view controller’s navigation item’s backBarButtonItem. That’s right: the back button displayed in the navigation bar belongs, not to the top item (the navigationItem of the current view controller), but to the back item (the navigationItem of the view controller that is one level down in the stack). In Figure 6-8, the back button in the detail view is the master view controller’s default back button, displaying its title.

The vast majority of the time, the default behavior is the behavior you’ll want, and you’ll leave the back button alone. If you wish, though, you can customize the back button by setting a view controller’s navigationItem.backBarButtonItem so that it contains an image, or a title differing from the view controller’s title. The best technique is to provide a new UIBarButtonItem whose target and action are nil; the runtime will add a correct target and action, so as to create a working back button. Here’s how to create a back button with a custom image instead of a title:

let b = UIBarButtonItem(
    image:UIImage(named:"files"), style:.plain, target:nil, action:nil)
self.navigationItem.backBarButtonItem = b

A Bool property, hidesBackButton, allows the top navigation item to suppress display of the back item’s back bar button item. If you set this to true, you’ll probably want to provide some other means of letting the user navigate back.

The visible indication that the back button is a back button is a left-pointing chevron (the back indicator) that’s separate from the button itself. This chevron can also be customized, but it’s a feature of the navigation bar, not the bar button item: set the navigation bar’s backIndicatorImage and backIndicatorTransitionMask. (I’ll give an example in Chapter 12.) But if the back button is assigned a background image — not an internal image, as in the example I just gave, but a background image, by calling setBackButtonBackgroundImage — then the back indicator is removed; it is up to the background image to point left, if desired.

leftBarButtonItem or leftBarButtonItems

A bar button item or, respectively, an array of bar button items to appear at the left side of the navigation bar; the first item in the array will be leftmost. The leftItemsSupplementBackButton property, if set to true, allows both the back button and one or more left bar button items to appear.

A view controller’s navigation item can have its properties set at any time while being displayed in the navigation bar. This (and not direct manipulation of the navigation bar) is the way to change the navigation bar’s contents dynamically. For example, in one of my apps, we play music from the user’s library using interface in the navigation bar. The titleView is a progress view (UIProgressView, Chapter 12) that needs updating every second to reflect the playback position in the current song, and the right bar button should be either the system Play button or the system Pause button, depending on whether we are paused or playing. So I have a timer that periodically checks the state of the music player; observe how we access the progress view and the right bar button by way of self.navigationItem:

// change the progress view
let prog = self.navigationItem.titleView!.subviews[0] as! UIProgressView
if let item = self.nowPlayingItem {
    let current = self.mp.currentPlaybackTime
    let total = item.playbackDuration
    prog.progress = Float(current / total)
} else {
    prog.progress = 0
}
// change the bar button
let whichButton : UIBarButtonSystemItem? = {
    switch self.mp.currentPlaybackRate {
    case 0..<0.1:
        return .play
    case 0.1...1.0:
        return .pause
    default:
        return nil
    }
}()
if let which = whichButton {
    let bb = UIBarButtonItem(barButtonSystemItem: which,
        target: self, action: #selector(doPlayPause))
    self.navigationItem.rightBarButtonItem = bb
}

Each view controller to be pushed onto the navigation controller’s stack is responsible also for supplying the items to appear in the navigation interface’s toolbar, if there is one. To configure this, set the view controller’s toolbarItems property to an array of UIBarButtonItem instances. You can change the toolbar items even while the view controller’s view and current toolbarItems are showing, optionally with animation, by sending setToolbarItems(_:animated:) to the view controller.

Configuring a Navigation Controller

You configure a navigation controller by manipulating its stack of view controllers. This stack is the navigation controller’s viewControllers array property, though you will rarely need to manipulate that property directly.

The view controllers in a navigation controller’s viewControllers array are the navigation controller’s child view controllers; the navigation controller is the parent of the view controllers in the array. The navigation controller is also the navigationController of the view controllers in the array and of all their children; thus a child view controller at any depth can learn that it is contained by a navigation controller and can get a reference to that navigation controller. The navigation controller retains the array, and the array retains the child view controllers.

The normal way to manipulate a navigation controller’s stack is by pushing or popping one view controller at a time. When the navigation controller is instantiated, it is usually initialized with init(rootViewController:); this is a convenience method that assigns the navigation controller a single initial child view controller, the root view controller that goes at the bottom of the stack:

let fvc = FirstViewController()
let nav = UINavigationController(rootViewController:fvc)

Instead of init(rootViewController:), you might choose to create the navigation controller with init(navigationBarClass:toolbarClass:), in order to set a custom subclass of UINavigationBar or UIToolbar. Typically, this will be in order to customize the appearance of the navigation bar and toolbar; sometimes you’ll create, say, a UIToolbar subclass for no other reason than to mark this kind of toolbar as needing a certain appearance. I’ll explain about that in Chapter 12. If you use this initializer, you’ll have to set the navigation controller’s root view controller separately.

You can also set the UINavigationController’s delegate (adopting UINavigationControllerDelegate). The delegate receives messages before and after a child view controller’s view is shown.

A navigation controller will typically appear on the screen initially containing just its root view controller, and displaying its root view controller’s view. There will be no back button, because there is no back item; there is nowhere to go back to. Subsequently, when the user asks to navigate to a new view, you (typically meaning code in the current view controller) obtain the next view controller (typically by creating it) and push it onto the stack by calling pushViewController(_:animated:) on the navigation controller. The navigation controller performs the animation, and displays the new view controller’s view:

let svc = SecondViewController(nibName: nil, bundle: nil)
self.navigationController!.pushViewController(svc, animated: true)

The command for going back is popViewController(animated:), but you might never need to call it yourself; when the user taps the back button to navigate back, the runtime will call it for you. When a view controller is popped from the stack, the viewControllers array removes and releases the view controller, which is usually permitted to go out of existence at that point.

Alternatively, there’s a second way to push a view controller onto the navigation controller’s stack, without referring to the navigation controller: show(_:sender:). This UIViewController method lets the caller be agnostic about the current interface situation; for example, it pushes onto a navigation controller if the view controller to which it is sent is in a navigation interface, but performs view controller presentation if not. I’ll talk more about this method in Chapter 9; meanwhile, I’ll continue using pushViewController(_:animated:) in my examples.

Instead of tapping the back button, the user can go back by dragging a pushed view controller’s view from the left edge of the screen. This is actually a way of calling popViewController(animated:), with the difference that the animation is interactive. (Interactive view controller transition animation is the subject of the next section.) The UINavigationController uses a UIScreenEdgePanGestureRecognizer to detect and track the user’s gesture. You can obtain a reference to this gesture recognizer as the navigation controller’s interactivePopGestureRecognizer; thus you can disable the gesture recognizer and prevent this way of going back, or you can mediate between your own gesture recognizers and this one (see Chapter 5).

You can manipulate the stack more directly if you wish. You can call popViewController(animated:) explicitly; to pop multiple items so as to leave a particular view controller at the top of the stack, call popToViewController(_:animated:), or to pop all the items down to the root view controller, call popToRootViewController(animated:). All of these methods return the popped view controller (or view controllers, as an array), in case you want to do something with them.

To set the entire stack at once, call setViewControllers(_:animated:). You can access the stack through the viewControllers property. Manipulating the stack directly is the only way, for instance, to delete or insert a view controller in the middle of the stack.

The view controller at the top of the stack is the topViewController; the view controller whose view is displayed is the visibleViewController. Those will normally be the same, but they needn’t be, as the topViewController might present a view controller, in which case the presented view controller will be the visibleViewController. Other view controllers can be accessed through the viewControllers array by index number. The root view controller is at index 0; if the array’s count is c, the back view controller (the one whose navigationItem.backBarButtonItem is currently displayed in the navigation bar) is at index c-2.

The topViewController may need to communicate with the next view controller as the latter is pushed onto the stack, or with the back view controller as it itself is popped off the stack. The problem is parallel to that of communication between an original presenter and a presented view controller, which I discussed earlier in this chapter (“Communication with a Presented View Controller”), so I won’t say more about it here.

A child view controller will probably want to configure its navigationItem early in its lifetime, so as to be ready for display in the navigation bar by the time the view controller is handed as a child to the navigation controller. Apple warns (in the UIViewController class reference, under navigationItem) that loadView and viewDidLoad are not appropriate places to do this, because the circumstances under which the view is needed are not related to the circumstances under which the navigation item is needed. Apple’s own code examples routinely violate this warning, but it is probably best to override a view controller initializer for this purpose.

A navigation controller’s navigation bar is accessible as its navigationBar, and can be hidden and shown with setNavigationBarHidden(_:animated:). (It is possible, though not common, to maintain and manipulate a navigation stack through a navigation controller whose navigation bar never appears.) Its toolbar is accessible as its toolbar, and can be hidden and shown with setToolbarHidden(_:animated:).

A view controller also has the power to specify that its ancestor’s bottom bar (a navigation controller’s toolbar, or a tab bar controller’s tab bar) should be hidden as this view controller is pushed onto a navigation controller’s stack. To do so, set the view controller’s hidesBottomBarWhenPushed property to true. The trick is that you must do this very early, before the view loads; the view controller’s initializer is a good place. The bottom bar remains hidden from the time this view controller is pushed to the time it is popped, even if other view controllers are pushed and popped on top of it in the meantime.

A navigation controller can perform automatic hiding and showing of its navigation bar (and, if normally shown, its toolbar) in response to various situations, as configured by properties:

When tapped

If the navigation controller’s hidesBarsOnTap is true, a tap that falls through the top view controller’s view is taken as a signal to toggle bar visibility. The relevant gesture recognizer is the navigation controller’s barHideOnTapGestureRecognizer.

When swiped

If the navigation controller’s hidesBarsOnSwipe is true, an upward or downward swipe respectively hides or shows the bars. The relevant gesture recognizer is the navigation controller’s barHideOnSwipeGestureRecognizer.

In landscape

If the navigation controller’s hidesBarsWhenVerticallyCompact is true, bars are automatically hidden when the app rotates to landscape on the iPhone (and hidesBarsOnTap is treated as true, so the bars can be shown again by tapping).

When the user is typing

If the navigation controller’s hidesBarsWhenKeyboardAppears is true, bars are automatically hidden when the onscreen keyboard appears (see Chapter 10).

You can configure a UINavigationController, or any view controller that is to serve in a navigation interface, in a .storyboard or .xib file. In the Attributes inspector, use a navigation controller’s Bar Visibility and Hide Bars checkboxes to determine the presence of the navigation bar and toolbar. The navigation bar and toolbar are themselves subviews of the navigation controller, and you can configure them with the Attributes inspector as well. A navigation controller’s root view controller can be specified; in a storyboard, there will be a “root view controller” relationship between the navigation controller and its root view controller. The root view controller is automatically instantiated together with the navigation controller.

A view controller in a .storyboard or .xib file has a Navigation Item where you can specify its title, its prompt, and the text of its back button. (If a view controller in a nib doesn’t have a Navigation Item and you want to configure this view controller for use in a navigation interface, drag a Navigation Item from the Object library onto the view controller.) You can drag Bar Button Items into a view controller’s navigation bar in the canvas to set the left buttons and right buttons of its navigationItem. Moreover, the Navigation Item has outlets, one of which permits you to set its titleView. Similarly, you can give a view controller Bar Button Items that will appear in the toolbar.

To start an iPhone project with a main storyboard that has a UINavigationController as its root view controller, begin with the Master–Detail app template. Alternatively, start with the Single View app template, remove the existing view controller from the storyboard, and add a Navigation Controller in its place. Unfortunately, the nib editor assumes that the navigation controller’s root view controller should be a UITableViewController. If that’s not the case, here’s a better way: start with the Single View app template, select the existing view controller, and choose Editor → Embed In → Navigation Controller. A view controller to be subsequently pushed onto the navigation stack can be configured in the storyboard as the destination of a push segue; I’ll talk more about that later in the chapter.

Noninteractive Custom Transition Animation

In the base case, you provide a custom animation that is not interactive. Configuring your custom animation requires three steps:

1. Before the transition begins, you must have given the view controller in charge of the transition a delegate.

2. As the transition begins, the delegate will be asked for an animation controller. You will supply a reference to some object adopting the UIViewControllerAnimatedTransitioning protocol (or nil to specify that the default animation, if any, should be used).

3. The animation controller will be sent these messages:

   transitionDuration(using:)

   The animation controller must return the duration of the custom animation.

   animateTransition(using:)

   The animation controller should perform the animation.

   interruptibleAnimator(using:)

   Optional; if implemented, the animation controller should return an object adopting the UIViewImplicitlyAnimating protocol, which may be a property animator.

   animationEnded(_:)

   Optional; if implemented, the animation controller may perform cleanup following the animation.

Here’s the strategy we’ll use to implement the animation controller methods. We’ll implement all four of them, as follows:

transitionDuration(using:)

We’ll return a constant.

animateTransition(using:)

We’ll call interruptibleAnimator(using:) to obtain a property animator and tell it to start animating.

interruptibleAnimator(using:)

We’ll form the property animator and return it. We’ll also assign the property animator to an instance property of our view controller, so that it persists throughout the animation. That way, if we are asked for the animator again during this animation, we can just return the instance property.

animationEnded(_:)

We’ll clean up any instance properties; at a minimum, we’ll set our property animator to nil.

Now let’s get down to the nitty-gritty of what the interruptibleAnimator implementation actually does to form the property animator’s animation. In general, a custom transition animation works as follows:

1. The using: parameter is an object called the transition context (adopting the UIViewControllerContextTransitioning protocol). By querying the transition context, you can obtain:

   • The container view, an already existing view within which all the action is to take place.

   • The outgoing and incoming view controllers.

   • The outgoing and incoming views. These are probably the main views of the outgoing and incoming view controllers, but you should obtain the views directly from the transition context, just in case they aren’t. The outgoing view is already inside the container view.

   • The initial frame of the outgoing view, and the ultimate frame where the incoming view must end up.

2. Having gathered this information, your mission is to put the incoming view into the container view and animate it in such a way as to end up at its correct ultimate frame. You may also animate the outgoing view if you wish.

3. When the animation ends, your completion function must call the transition context’s completeTransition to tell it that the animation is over. In response, the outgoing view is removed automatically and the animation comes to an end (and our animationEnded will be called).

As a simple example, I’ll use the transition between two child view controllers of a tab bar controller, when the user taps a different tab bar item. By default, this transition isn’t animated; one view just replaces the other. Let’s animate the transition.

A possible custom animation is that the new view controller’s view should slide in from one side while the old view controller’s view should slide out the other side. The direction of the slide should depend on whether the index of the new view controller is greater or less than that of the old view controller. Let’s implement that.

Take the steps in order. First, configure a delegate for the tab bar controller. Assume that the tab bar controller is our app’s root view controller. For simplicity, I’ll set its delegate in code, in the app delegate’s application(_:didFinishLaunchingWithOptions:), and I’ll make that delegate be the app delegate itself:

(self.window!.rootViewController as! UITabBarController).delegate = self

On to the second step. The app delegate, in its role as UITabBarControllerDelegate, will be sent a message whenever the tab bar controller is about to change view controllers. That message is:

• tabBarController(_:animationControllerForTransitionFrom:to:)

We must return our animation controller, namely, some object implementing UIViewControllerAnimatedTransitioning. I’ll return self. Here we go:

func tabBarController(_ tabBarController: UITabBarController,
    animationControllerForTransitionFrom fromVC: UIViewController,
    to toVC: UIViewController) -> UIViewControllerAnimatedTransitioning? {
        return self
}

(There is no particular reason why the animation controller should be self; I’m just using self to keep things simple. The animation controller can be any object — even a dedicated lightweight object instantiated just to govern this transition. There is also no particular reason why the animation controller should be the same object every time this method is called; depending on the circumstances, we could readily provide a different animation controller, or we could return nil to use the default transition — meaning, in this case, no animation.)

On to the third step! Here we are in the animation controller (UIViewControllerAnimatedTransitioning). Our first job is to reveal in advance the duration of our animation:

func transitionDuration(using ctx: UIViewControllerContextTransitioning?)
    -> TimeInterval {
        return 0.4
}

(Again, the value returned needn’t be a constant; we could decide on the duration based on the circumstances. But the value returned here must be the same as the duration of the animation we’ll actually be constructing in interruptibleAnimator.)

As promised, our animateTransition simply calls interruptibleAnimator and tells the resulting animator to animate:

func animateTransition(using ctx: UIViewControllerContextTransitioning) {
    let anim = self.interruptibleAnimator(using: ctx)
    anim.startAnimation()
}

At last we come to interruptibleAnimator itself:

func interruptibleAnimator(
    using ctx: UIViewControllerContextTransitioning)
    -> UIViewImplicitlyAnimating {
        // ...
}

I take a plodding, boilerplate approach, and I suggest you do the same. First, look to see if we’ve already formed this property animator. There is a danger that interruptibleAnimator may be called multiple times during the animation, and in that case we don’t want to reconfigure the animator and form it again; we want to return the same animator. So we have a property, self.anim, typed as an Optional wrapping a UIViewImplicitlyAnimating object. If that isn’t nil, we unwrap it and return it, and that’s all:

if self.anim != nil {
    return self.anim!
}

If we haven’t returned, we need to form the property animator. First, we thoroughly query the transition context ctx to learn all about the parameters of this animation:

let vc1 = ctx.viewController(forKey:.from)!
let vc2 = ctx.viewController(forKey:.to)!
let con = ctx.containerView
let r1start = ctx.initialFrame(for:vc1)
let r2end = ctx.finalFrame(for:vc2)
let v1 = ctx.view(forKey:.from)!
let v2 = ctx.view(forKey:.to)!

Now we can prepare for our intended animation. In this case, we are sliding the views, so we need to decide the final frame of the outgoing view and the initial frame of the incoming view. We are sliding the views sideways, so those frames should be positioned sideways from the initial frame of the outgoing view and the final frame of the incoming view, which the transition context has just given us. Which side they go on depends upon the relative place of these view controllers among the children of the tab bar controller — is this to be a leftward slide or a rightward slide? Since the animation controller is the app delegate, we can get a reference to the tab bar controller the same way we did before:

let tbc = self.window!.rootViewController as! UITabBarController
let ix1 = tbc.viewControllers!.index(of:vc1)!
let ix2 = tbc.viewControllers!.index(of:vc2)!
let dir : CGFloat = ix1 < ix2 ? 1 : -1
var r1end = r1start
r1end.origin.x -= r1end.size.width * dir
var r2start = r2end
r2start.origin.x += r2start.size.width * dir

Now we’re ready to animate! We put the second view controller’s view into the container view at its initial frame, and animate our views:

v2.frame = r2start
con.addSubview(v2)
let anim = UIViewPropertyAnimator(duration: 0.4, curve: .linear) {
    v1.frame = r1end
    v2.frame = r2end
}

We must not neglect to supply the completion function that calls completeTransition:

anim.addCompletion { _ in
    ctx.completeTransition(true)
}

Our property animator is now formed. We retain it in our self.anim property, and we also return it:

self.anim = anim
return anim

That’s all there is to it. Our example animation wasn’t very complex, but an animation needn’t be complex to be interesting, significant, and helpful to the user; I use this exact same animation in my own apps, and I think it enlivens and clarifies the transition. And even a more complex animation would be implemented along the same basic lines. One possibility that I didn’t illustrate in my example is that you are free to introduce additional views temporarily into the container view during the course of the animation; you’ll probably want to remove them in the completion function. For example, you might make some interface object appear to migrate from one view controller’s view into the other (in reality you’d probably use a snapshot view; see Chapter 1).

Interactive Custom Transition Animation

With an interactive custom transition animation, the idea is that we track something the user is doing, typically by means of a gesture recognizer (see Chapter 5), and perform the “frames” of the transition in response.

(There are actually two ways to write an interactive custom transition animation. One is to use an object that I call a percent driver, which is an instance of the built-in UIPercentDrivenInteractiveTransition class. The other is to implement interactivity yourself. Thanks to the iOS 10 property animator, the second way is just as easy as the first way — in a very real sense, the property animator is a sort of percent driver — so I won’t discuss the first way.)

To make a custom transition animation interactive, you supply, in addition to the animation controller, an interaction controller. This is an object adopting the UIViewControllerInteractiveTransitioning protocol. This object needn’t be the same as the animation controller, though in my examples it will be. This, in turn, causes the runtime to call the interaction controller’s startInteractiveTransition(_:) instead of the animation controller’s animateTransition(using:).

Thus, configuring your custom animation requires the following steps:

1. Before the transition begins, you must have given the view controller in charge of the transition a delegate.

2. You’ll have a gesture recognizer that tracks the interactive gesture. When the gesture recognizer recognizes, it triggers the transition.

3. As the transition begins, the delegate will be asked for an animation controller and you’ll return a UIViewControllerAnimatedTransitioning object.

4. If you didn’t return nil as the animation controller, the delegate will also be asked for an interaction controller. You’ll return a UIViewControllerInteractiveTransitioning object (or nil if you don’t want interactivity).

5. If you didn’t return nil as the interaction controller, the transition is now interactive! In addition to the animation controller messages, the interaction controller will be sent startInteractiveTransition(_:).

6. The gesture recognizer continues by constantly updating the transition context, by calling updateInteractiveTransition(_:), as well managing the frames of the animation.

7. Sooner or later the gesture will end. At this point, we must decide whether to declare the transition completed or cancelled. A typical approach is to say that if the user performed more than half the full gesture, that constitutes completion; otherwise, it constitutes cancellation. We finish the animation accordingly.

8. The animation is now completed, and its completion function is called. We must call the transition context’s finishInteractiveTransition or cancelInteractiveTransition, and then call completeTransition(_:), with the argument stating whether the transition was finished or cancelled. Our animationEnded is then called, and we clean up.

As an example, I’ll describe how to make an interactive version of the tab bar controller transition animation that we developed in the previous section, such that the user can drag from the edge of the screen to bring the tab bar controller’s adjacent view controller in from the right or from the left. All the code we’ve already written can be left more or less as is! In fact, we can easily expand the previous example so that the transition is either noninteractive (the user taps a tab bar item, just as before) or interactive (the user drags from one edge).

I’m going to need two more instance properties, in addition to self.anim:

var interacting = false
var anim : UIViewImplicitlyAnimating?
var context : UIViewControllerContextTransitioning?

The self.interacting property will be used a signal that our transition is to be interactive. The self.context property is needed because the gesture recognizer’s action method is going to need access to the transition context. (Sharing the transition context through a property may seem ugly, but the elegant alternatives would make the example more complicated, so we’ll just do it this way.)

To track the user’s gesture, I’ll put a pair of UIScreenEdgePanGestureRecognizers into the interface. The gesture recognizers are attached to the tab bar controller’s view (tbc.view), as this will remain constant while the views of its view controllers are sliding across the screen. In addition to making myself the target for the gesture recognizers’ action messages, I also make myself their delegate so I can dictate which gesture recognizer is applicable to the current situation:

let sep =
    UIScreenEdgePanGestureRecognizer(target:self, action:#selector(pan))
sep.edges = UIRectEdge.right
tbc.view.addGestureRecognizer(sep)
sep.delegate = self
let sep2 =
    UIScreenEdgePanGestureRecognizer(target:self, action:#selector(pan))
sep2.edges = UIRectEdge.left
tbc.view.addGestureRecognizer(sep2)
sep2.delegate = self

Acting as the delegate of the two gesture recognizers, we prevent either pan gesture recognizer from operating unless there is another child of the tab bar controller available on that side of the current child:

func gestureRecognizerShouldBegin(_ g: UIGestureRecognizer) -> Bool {
    let tbc = self.window!.rootViewController as! UITabBarController
    var result = false
    if (g as! UIScreenEdgePanGestureRecognizer).edges == .right {
        result = (tbc.selectedIndex < tbc.viewControllers!.count - 1)
    } else {
        result = (tbc.selectedIndex > 0)
    }
    return result
}

If the gesture recognizer action method pan is called, our interactive transition animation is to take place. I’ll break down the discussion according to the gesture recognizer’s states. In .began, I raise the self.interacting flag and trigger the transition by changing the tab bar controller’s selectedIndex:

func pan(_ g:UIScreenEdgePanGestureRecognizer) {
    switch g.state {
    case .began:
        self.interacting = true
        let tbc = self.window!.rootViewController as! UITabBarController
        if g.edges == .right {
            tbc.selectedIndex = tbc.selectedIndex + 1
        } else {
            tbc.selectedIndex = tbc.selectedIndex - 1
        }
    // ...
    }
}

The transition begins. We are asked for our animation controller and our transition controller; we will supply a transition controller only if the self.interacting flag was raised (and if the self.interacting flag is not raised, the user tapped a tab bar item and everything is like the preceding example):

func tabBarController(_ tabBarController: UITabBarController,
    animationControllerForTransitionFrom fromVC: UIViewController,
    to toVC: UIViewController) -> UIViewControllerAnimatedTransitioning? {
        return self
}
func tabBarController(_ tabBarController: UITabBarController,
    interactionControllerFor ac: UIViewControllerAnimatedTransitioning)
    -> UIViewControllerInteractiveTransitioning? {
        return self.interacting ? self : nil
}

We are interactive, so our startInteractiveTransition(_:) is called instead of our animateTransition(using:). It sets up our other two instance properties; so now we have our transition context and our property animator. But it does not tell the property animator to animate! We are interactive; that means we intend to manage the “frames” of the animation ourselves:

func startInteractiveTransition(_ ctx:UIViewControllerContextTransitioning){
    self.context = ctx
    self.anim = self.interruptibleAnimator(using: ctx)
}

We are now back in the gesture recognizer’s action method, in the .changed state. We calculate the completed percentage of the gesture, and update both the property animator’s “frame” and the transition context:

case .changed:
    let v = g.view!
    let delta = g.translation(in:v)
    let percent = abs(delta.x/v.bounds.size.width)
    self.anim?.fractionComplete = percent
    self.context?.updateInteractiveTransition(percent)

Finally, the gesture ends. This is where the use of the property animator really pays off. Our goal is to “hurry home” to the start of the animation or the end of the animation, depending on how far the user got through the gesture. Well, with a property animator, that’s really easy (see “Canceling a View Animation”):

case .ended:
    let anim = self.anim as! UIViewPropertyAnimator
    anim.pauseAnimation()
    if anim.fractionComplete < 0.5 {
        anim.isReversed = true
    }
    anim.continueAnimation(
        withTimingParameters:
        UICubicTimingParameters(animationCurve:.linear),
        durationFactor: 0.2)

The animation comes to an end, and the completion function that we gave our property animator in interruptibleAnimator is called. This is the one place in our interruptibleAnimator that needs to be a little different from the preceding example; we must send different messages to the transition context, depending on whether we finished to the end or reversed to the start:

anim.addCompletion { finish in
    if finish == .end {
        ctx.finishInteractiveTransition()
        ctx.completeTransition(true)
    } else {
        ctx.cancelInteractiveTransition()
        ctx.completeTransition(false)
    }
}

Finally, our animationEnded is called, and we clean up our instance properties:

func animationEnded(_ transitionCompleted: Bool) {
    self.interacting = false
    self.context = nil
    self.anim = nil
}

You may be asking: why must we keep talking to our transition context throughout the process, calling updateInteractiveTransition throughout the progress of the gesture, and finishInteractiveTransition or cancelInteractiveTransition at the end? For a tab bar controller’s transition, these calls have little or no significance. But in the case, say, of a navigation controller, the animation has a component separate from what you’re doing — the change in the appearance of the navigation bar, as the old title departs and the new title arrives and so forth. The transition context needs to coordinate that animation with the interactive gesture and with your animation. So you need to keep telling it where things are in the course of the interaction.

Interruptible Custom Transition Animation

A property animator (UIViewPropertyAnimator) makes interruptible animations possible. While a view is in the middle of being animated, the property animator implements touchability of the animated view, and allows you to pause the animation. You can incorporate these features into a custom transition animation.

As an example, I’ll describe a navigation controller custom push animation that will be interruptible. A custom transition animation for a navigation controller is similar to a custom transition animation for a tab bar controller, so there’s no need to repeat the details from the preceding examples. The chief difference is that a navigation controller delegate has its own methods that will be called to discover whether there’s an animation controller and an interaction controller:

• navigationController(_:animationControllerFor:from:to:)

• navigationController(_:interactionControllerFor:)

In the first method, the for: parameter is a UINavigationControllerOperation, allowing you to distinguish a push from a pop. In my example, we’re going to have a custom push animation without a custom pop animation; to keep things simple, the animation won’t be interactive:

func navigationController(_ navigationController: UINavigationController,
    animationControllerFor operation: UINavigationControllerOperation,
    from fromVC: UIViewController, to toVC: UIViewController)
    -> UIViewControllerAnimatedTransitioning? {
        if operation == .push {
            return self
        }
        return nil
}

The user will tap as usual to trigger the push transition (a push segue, or pushViewController, or show). Our delegate method is called and returns an animation controller, so the animation controller’s transitionDuration and animateTransition are called. Our animateTransition calls interruptibleAnimator, which, if the instance property self.anim doesn’t already exist, creates the property animator, stores it in self.anim, and returns it; animateTransition then starts the property animator’s animation. So far, this is exactly like the tab bar controller example from the preceding section. In fact, they are so exactly alike that there is no need for me to show you any of that code! Just imagine that we have implemented interruptibleAnimator to provide a UIViewPropertyAnimator that animates the pushed view controller’s view onto the scene somehow.

Now I’ll make that animation interruptible. I’ll allow the user to grab the animated view and drag it around. To keep things simple, when the user lets go of the view, I’ll just finish the animation. (The idea is silly, but it demonstrates interruptibility.)

The animated view can be grabbed because I’ve given it a pan gesture recognizer — and because the property animator makes the view touchable during animation. The gesture recognizer’s action method starts by pausing the property animator, and then proceeds as for any draggable-view action method:

func drag (_ g : UIPanGestureRecognizer) {
    let v = g.view!
    switch g.state {
    case .began:
        self.anim?.pauseAnimation()
        fallthrough
    case .changed:
        let delta = g.translation(in:v.superview)
        var c = v.center
        c.x += delta.x; c.y += delta.y
        v.center = c
        g.setTranslation(.zero, in: v.superview)
    // ...
    }
}

(If this were an interactive transition, my .began case would also need to call the transition context’s pauseInteractiveTransition.)

The interesting part is what happens when the user lets go of the draggable view. We want to continue animating from here to the goal. When I created the property animator in interruptibleAnimator, I stored the transition context in a property, self.context; now, I query the transition context to learn what the goal is:

case .ended:
    let anim = self.anim as! UIViewPropertyAnimator
    let ctx = self.context!
    let vc2 = ctx.viewController(forKey:.to)!
    anim.addAnimations {
        v.frame = ctx.finalFrame(for: vc2)
    }
    let factor = 1 - anim.fractionComplete
    anim.continueAnimation(withTimingParameters: nil, durationFactor: factor)

When the animation reaches its end, the property animator’s completion function is called, and it calls the transition context’s completeTransition; our animationEnded is then called, and we clean up by setting self.anim and self.context to nil.

Custom Presented View Controller Transition

Customizing what happens when a view controller is presented is more complex, and more powerful, than customizing a tab bar controller or navigation controller transition. With a presented view controller, you can customize not only the animation but also the final position of the presented view. Moreover, you can introduce extra views which remain in the scene while the presented view is presented, and are not removed until after dismissal is complete; for example, if the presented view is smaller than the presenting view and covers it only partially, you might add a dimming view between them, to darken the presenting view (just as a .formSheet presentation does).

What the runtime must do while a view is being presented in order to make the presentation customizable is also more complex. There is no existing view to serve as the container view; therefore, when the presentation starts, the runtime must construct the container view and insert it into the interface and leave it there for only as long as the view remains presented. In the case of a .fullScreen presentation, the runtime must also rip the presenting view out of the interface and insert it into the container view, because you might want the presenting view to participate in the animation. For other styles of presentation, the container view is in front of the presenting view, which can’t be animated and is left in place as the presentation proceeds.

The work of customizing a presentation is distributed between two objects: the animation controller (or interaction controller) on the one hand, and the presentation controller on the other. The idea is that the animation controller should be responsible for only the animation, the movement of the presented view into its final position. The determination of that final position is the job of the presentation controller. The presentation controller is also responsible for inserting any extra views, such as a dimming view, into the container view; Apple says that the animation controller animates the content, while the presentation controller animates the “chrome.” This distribution of responsibilities simplifies considerably the task of customizing the animation itself.

required init?(coder aDecoder: NSCoder) {
    super.init(coder:aDecoder)
    self.transitioningDelegate = self
}

func animationController(forPresented presented: UIViewController,
    presenting: UIViewController, source: UIViewController)
    -> UIViewControllerAnimatedTransitioning? {
        return self
}

func interruptibleAnimator(using ctx: UIViewControllerContextTransitioning)
    -> UIViewImplicitlyAnimating {
        if self.anim != nil {
            return self.anim!
        }
        let vc2 = ctx.viewController(forKey:.to)
        let con = ctx.containerView
        let r2end = ctx.finalFrame(for:vc2!)
        let v2 = ctx.view(forKey:.to)!
        v2.frame = r2end
        v2.transform = CGAffineTransform(scaleX: 0.1, y: 0.1)
        v2.alpha = 0
        con.addSubview(v2)
        let anim = UIViewPropertyAnimator(duration: 0.4, curve: .linear) {
            v2.alpha = 1
            v2.transform = .identity
        }
        anim.addCompletion { _ in
            ctx.completeTransition(true)
        }
        self.anim = anim
        return anim
}

let v1 = ctx.view(forKey:.from)
let v2 = ctx.view(forKey:.to)
if let v2 = v2 { // presenting
    // ...
} else if let v1 = v1 { // dismissing
    // ...
}

required init?(coder aDecoder: NSCoder) {
    super.init(coder:aDecoder)
    self.transitioningDelegate = self
    self.modalPresentationStyle = .custom // *
}

func presentationController(forPresented presented: UIViewController,
    presenting: UIViewController?, source: UIViewController)
    -> UIPresentationController? {
        let pc = MyPresentationController(
            presentedViewController: presented, presenting: presenting)
        return pc
}

override var frameOfPresentedViewInContainerView : CGRect {
    return super.frameOfPresentedViewInContainerView.insetBy(dx:40, dy:40)
}

override func presentationTransitionWillBegin() {
    let con = self.containerView!
    let shadow = UIView(frame:con.bounds)
    shadow.backgroundColor = UIColor(white:0, alpha:0.4)
    con.insertSubview(shadow, at: 0)
    shadow.autoresizingMask = [.flexibleWidth, .flexibleHeight]
}

override func dismissalTransitionWillBegin() {
    let con = self.containerView!
    let shadow = con.subviews[0]
    let tc = self.presentedViewController.transitionCoordinator!
    tc.animate(alongsideTransition: { _ in
        shadow.alpha = 0
    })
}

override var presentedView : UIView? {
    let v = super.presentedView!
    v.layer.cornerRadius = 6
    v.layer.masksToBounds = true
    return v
}

override func presentationTransitionDidEnd(_ completed: Bool) {
    let vc = self.presentingViewController
    let v = vc.view
    v?.tintAdjustmentMode = .dimmed
}
override func dismissalTransitionDidEnd(_ completed: Bool) {
    let vc = self.presentingViewController
    let v = vc.view
    v?.tintAdjustmentMode = .automatic
}

Transition Coordinator

Earlier in this chapter, we encountered resizing-related methods such as viewWillTransition(to:with:), whose second parameter is a UIViewControllerTransitionCoordinator. As I suggested at that time, you can use this transition coordinator to add your own animation to the runtime’s animation when the app rotates. Now it turns out that the view controller itself can obtain its transition coordinator during a view controller transition, through its transitionCoordinator property.

The transition coordinator adopts the UIViewControllerTransitionCoordinatorContext protocol, just like the transition context; indeed, it is a kind of wrapper around the transition context. Thus, in effect, view controllers can find out about the transition they are involved in.

In addition to the methods that it implements by virtue of adopting the UIViewControllerTransitionCoordinatorContext protocol, a transition coordinator implements the following methods:

animate(alongsideTransition:completion:)

Takes an animations function and a completion function. The animation you supply is incorporated into the transition coordinator’s animation. Returns a Bool, informing you in case your commands couldn’t be animated. Both functions receive the transition context as a parameter. (See also “View Controller Manual Layout”, where I discussed this method in connection with rotation.)

A view controller’s use of this method will typically be to add animation of its view’s internal interface as part of a transition animation. This works equally for a custom animation or a built-in animation; in fact, the point is that the view controller can behave agnostically with regard to how its own view is being animated. In this example, a presented view controller animates part of its interface into place as the animation proceeds (whatever that animation may be):

override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    if let tc = self.transitionCoordinator {
        tc.animate(alongsideTransition:{ _ in
            self.buttonTopConstraint.constant += 200
            self.view.layoutIfNeeded()
        })
    }
}

notifyWhenInteractionChanges(_:)

The parameter is a function to be called; the transition context is the function’s parameter. New in iOS 10, this method supersedes notifyWhenInteractionEnds(_:). The older method arranged for your function to be called when the user abandons an interactive gesture and the transition is about to be either completed or cancelled. This is useful particularly if the interactive transition is being cancelled, as it may well be that what your view controller wants to do will differ in this situation. The new method is needed because an interactive transition might be interruptible; your function is now called whenever the transition changes between being interactive and being noninteractive.

In this example, a navigation controller has pushed a view controller, and now the user is popping it interactively (using the default drag-from-the-left-edge gesture). If the user cancels, the back view controller can hear about it, like this:

override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    let tc = self.transitionCoordinator
    tc?.notifyWhenInteractionChanges { ctx in
        if ctx.isCancelled {
            // ...
        }
    }
}

Preparing a Page View Controller

To create a UIPageViewController, use its designated initializer:

• init(transitionStyle:navigationOrientation:options:)

Here’s what the parameters mean:

transitionStyle:

The animation type during navigation (UIPageViewControllerTransitionStyle). Your choices are:

• .pageCurl

• .scroll (sliding)

navigationOrientation:

The direction of navigation (UIPageViewControllerNavigationOrientation). Your choices are:

• .horizontal

• .vertical

options:

A dictionary. Possible keys are:

UIPageViewControllerOptionSpineLocationKey

If you’re using the page curl transition, this is the position of the pivot line around which those page curl transitions rotate. The value (UIPageViewControllerSpineLocation) is one of the following:

• .min (left or top)

• .mid (middle; this is the configuration where there are two children, and two pages are shown at once)

• .max (right or bottom)

UIPageViewControllerOptionInterPageSpacingKey

If you’re using the scroll transition, this is the spacing between successive pages, visible as a gap during the transition (the default is 0).

You configure the page view controller’s initial content by handing it its initial child view controller(s). You do that by calling this method:

• setViewControllers(_:direction:animated:completion:)

Here’s what the parameters mean:

viewControllers:

An array of one view controller — unless you’re using the page curl transition and the .mid spine location, in which case it’s an array of two view controllers.

direction:

The animation direction (UIPageViewControllerNavigationDirection). This probably won’t matter when you’re assigning the page view controller its initial content, as you are not likely to want any animation. Possible values are:

• .forward

• .backward

animated:, completion:

A Bool and a completion function.

To allow the user to page through the page view controller, and to supply the page view controller with a new page at that time, you also assign the page view controller a dataSource, which should conform to the UIPageViewControllerDataSource protocol. The dataSource is told whenever the user starts to change pages, and should respond by immediately providing another view controller whose view will constitute the new page. Typically, the data source will create this view controller on the spot.

Here’s a minimal example. Each page in the page view controller is to portray an image of a named Pep Boy. The first question is where the pages will come from. My data model consists of an array (self.pep) of the string names of the three Pep Boys:

let pep : [String] = ["Manny", "Moe", "Jack"]

To match these, I have three eponymous image files, portraying each Pep Boy. I’ve also got a UIViewController subclass called Pep, capable of displaying a Pep Boy. I initialize a Pep object with Pep’s designated initializer init(pepBoy:), supplying the name of a Pep Boy from the array; the Pep object sets its own boy property:

init(pepBoy boy:String) {
    self.boy = boy
    super.init(nibName: nil, bundle: nil)
}

Pep’s viewDidLoad then fetches the corresponding image and assigns it as the image of a UIImageView within its own view:

override func viewDidLoad() {
    super.viewDidLoad()
    self.pic.image = UIImage(named:self.boy.lowercased())
}

At any given moment, then, our page view controller will have one Pep instance as its child, and thus will portray a Pep Boy. Here’s how I create the page view controller itself (in my app delegate):

// make a page view controller
let pvc = UIPageViewController(
    transitionStyle: .scroll, navigationOrientation: .horizontal)
// give it an initial page
let page = Pep(pepBoy: self.pep[0])
pvc.setViewControllers([page], direction: .forward, animated: false)
// give it a data source
pvc.dataSource = self
// put its view into the interface
self.window!.rootViewController = pvc

The page view controller is a UIViewController, and its view must get into the interface by standard means. You can make the page view controller the window’s rootViewController, as I do here; you can make it a presented view controller; you can make it a child view controller of a tab bar controller or a navigation controller. If you want the page view controller’s view to be a subview of a custom view controller’s view, that view controller must be a custom container view controller, as I’ll describe later.

Page View Controller Navigation

We now have a page view controller’s view in our interface, itself containing and displaying the view of one Pep view controller that is its child. In theory, we have three pages, because we have three Pep Boys and their images — but the page view controller knows about only one of them. Just as with a navigation controller, you don’t supply (or even create) a page until the moment comes to navigate to it. When that happens, one of these data source methods will be called:

• pageViewController(_:viewControllerAfter:)

• pageViewController(_:viewControllerBefore:)

The job of those methods is to return the requested successive view controller — or nil, to signify that there is no further page in this direction. Your strategy for doing that will depend on how your model maintains the data.

My data is an array of unique strings, so all I have to do is find the previous name or the next name in the array. Here’s one of my data source methods:

func pageViewController(_ pvc: UIPageViewController,
    viewControllerAfter vc: UIViewController) -> UIViewController? {
        let boy = (vc as! Pep).boy
        let ix = self.pep.index(of:boy)! + 1
        if ix >= self.pep.count {
            return nil
        }
        return Pep(pepBoy: self.pep[ix])

The other data source method is completely parallel, so there’s no point showing it. We now have a working page view controller! The user, with a sliding gesture, can page through it, one page at a time. When the user reaches the first page or the last page, it is impossible to go further in that direction.

You can also, at any time, call setViewControllers to change programmatically what page is being displayed, possibly with animation. In this way, you can “jump” to a page other than a successive page (something that the user cannot do with a gesture).

func presentationCount(for pvc: UIPageViewController) -> Int {
    return self.pep.count
}
func presentationIndex(for pvc: UIPageViewController) -> Int {
    let page = pvc.viewControllers![0] as! Pep
    let boy = page.boy
    return self.pep.index(of:boy)!
}

let proxy = UIPageControl.appearance()
proxy.pageIndicatorTintColor = UIColor.red.withAlphaComponent(0.6)
proxy.currentPageIndicatorTintColor = .red
proxy.backgroundColor = .yellow

for g in pvc.gestureRecognizers {
    if let g = g as? UITapGestureRecognizer {
        g.numberOfTapsRequired = 2
    }
}

@IBAction func tap (_ sender: UIGestureRecognizer?) {
    NotificationCenter.default.post(name:.tap, object: sender)
}

NotificationCenter.default.addObserver(
    forName:.tap, object: nil, queue: .main) { n in
        let g = n.object as! UIGestureRecognizer
        let which = g.view!.tag
        let vc0 = pvc.viewControllers![0]
        guard let vc = (which == 0 ?
            self.pageViewController(pvc, viewControllerBefore: vc0) :
            self.pageViewController(pvc, viewControllerAfter: vc0))
            else {return}
        let dir : UIPageViewControllerNavigationDirection =
            which == 0 ? .reverse : .forward
        pvc.setViewControllers([vc], direction: dir, animated: true)
    }
}

Other Page View Controller Configurations

It is possible to assign a page view controller a delegate (UIPageViewControllerDelegate), which gets an event when the user starts turning the page and when the user finishes turning the page, and can change the spine location dynamically in response to a change in device orientation. As with a tab bar controller’s delegate or a navigation controller’s delegate, a page view controller’s delegate also gets messages allowing it to specify the page view controller’s rotation policy, so there’s no need to subclass UIPageViewController solely for that purpose.

One further bit of configuration applicable to a .pageCurl page view controller is the isDoubleSided property. If it is true, the next page occupies the back of the previous page. The default is false, unless the spine is in the middle, in which case it’s true and can’t be changed. Your only option here, therefore, is to set it to true when the spine isn’t in the middle, and in that case the back of each page would be a sort of throwaway page, glimpsed by the user during the page curl animation.

A page view controller in a storyboard lets you configure its transition style, navigation orientation, page spacing, spine location, and isDoubleSided property. (It also has delegate and data source outlets, but you’re not allowed to connect them to other view controllers, because you can’t draw an outlet from one scene to another in a storyboard.) It has no child view controller relationship, so you can’t set the page view controller’s initial child view controller in the storyboard; you’ll have to complete the page view controller’s initial configuration in code.

Adding and Removing Children

A view controller has a childViewControllers array. This is what gives it the power to be a parent! You must not, however, just wantonly populate this array. A child view controller needs to receive certain definite events at particular moments:

• As it becomes a child view controller

• As its view is added to and removed from the interface

• As it ceases to be a child view controller

Therefore, to act as a parent view controller, your UIViewController subclass must fulfill certain responsibilities:

Adding a child

When a view controller is to become your view controller’s child, your view controller must do these things, in this order:

1. Send addChildViewController(_:) to itself, with the child as argument. The child is automatically added to your childViewControllers array and is retained.

2. Get the child view controller’s view into the interface (as a subview of your view controller’s view), if that’s what adding a child view controller means.

3. Send didMove(toParentViewController:) to the child with your view controller as its argument.

Removing a child

When a view controller is to cease being your view controller’s child, your view controller must do these things, in this order:

1. Send willMove(toParentViewController:) to the child with a nil argument.

2. Remove the child view controller’s view from your interface.

3. Send removeFromParentViewController to the child. The child is automatically removed from your childViewControllers array and is released.

This is a clumsy and rather confusing dance. The underlying reason for it is that a child view controller must always receive willMove(toParentViewController:) followed by didMove(toParentViewController:) (and your own child view controllers can take advantage of these events however you like). But it turns out that you don’t always send both these messages explicitly, because:

• addChildViewController(_:) sends willMove(toParentViewController:) for you automatically.

• removeFromParentViewController sends didMove(toParentViewController:) for you automatically.

Thus, in each case you must send manually the other message, the one that adding or removing a child view controller doesn’t send for you — and of course you must send it so that everything happens in the correct order, as dictated by the rules I just listed.

When you do this dance correctly, the proper parent–child relationship results: the container view controller can refer to its children as its childViewControllers, and any child has a reference to the parent as its parent. If you don’t do it correctly, all sorts of bad things can happen; in a worst-case scenario, the child view controller won’t even survive, and its view won’t work correctly, because the view controller was never properly retained as part of the view controller hierarchy (see “View Controller Hierarchy”). So do the dance correctly!

Example 6-1 provides a schematic approach for how to obtain an initial child view controller and put its view into the interface, where no child view controller’s view was previously. (Alternatively, a storyboard can do this work for you, with no code, as I’ll explain later in this chapter.)

let vc = // whatever; this is the initial child view controller
self.addChildViewController(vc) // "will" called for us
// insert view into interface between "will" and "did"
self.view.addSubview(vc.view)
vc.view.frame = // whatever, or use constraints
// when we call add, we must call "did" afterward
vc.didMove(toParentViewController: self)

In many cases, the situation I’ve just described is all you’ll need. You have a parent view controller and a child view controller, and they are paired permanently, for the lifetime of the parent. That’s how Figure 6-3 behaves: RootViewController has a page view controller as its child, and the page view controller’s view as its own view’s subview, for the entire lifetime of the app.

To show how that’s done, I’ll use the same the page view controller that I used in my earlier examples, the one that displays Pep Boys. My root view controller will be called RootViewController. I’ll create and configure my page view controller as a child of RootViewController, in RootViewController’s viewDidLoad:

let pep : [String] = ["Manny", "Moe", "Jack"]
override func viewDidLoad() {
    super.viewDidLoad()
    let pvc = UIPageViewController(
        transitionStyle: .scroll, navigationOrientation: .horizontal)
    pvc.dataSource = self
    self.addChildViewController(pvc)
    self.view.addSubview(pvc.view)
    // ... configure frame or constraints here ...
    pvc.didMove(toParentViewController: self)
    let page = Pep(pepBoy: self.pep[0])
    pvc.setViewControllers([page], direction: .forward, animated: false)
}

It is also possible to replace one child view controller’s view in the interface with another (comparable to how UITabBarController behaves when a different tab bar item is selected). The simplest, most convenient way to do that is for the parent view controller to send itself this message:

• transition(from:to:duration:options:animations:completion:)

That method manages the stages in good order, adding the view of one child view controller (to:) to the interface before the transition and removing the view of the other child view controller (from:) from the interface after the transition, and seeing to it that the child view controllers receive lifetime events (such as viewWillAppear(_:)) at the right moment. Here’s what the last three arguments are for:

options:

A bitmask (UIViewAnimationOptions) comprising the same possible options that apply to any view transition (see “Transitions”).

animations:

An animations function that may be used for view animations other than the transition animation specified in the options: argument. Alternatively, if none of the built-in transition animations is suitable, you can animate the views yourself here; they are both in the interface during this function.

completion:

This function will be important if the transition involves the removal or addition of a child view controller. At the time when transition is called, both view controllers must be children of the parent view controller; so if you’re going to remove one of the view controllers as a child, you’ll do it in the completion function. Similarly, if you owe a new child view controller a didMove(toParentViewController:) call, you’ll use the completion function to fulfill that debt.

Here’s an example. To keep things simple, suppose that our view controller has just one child view controller at a time, and displays the view of that child view controller within its own view. So let’s say that when our view controller is handed a new child view controller, it substitutes that new child view controller for the old child view controller and replaces the old child view controller’s view with the new child view controller’s view. Here’s code that does that correctly; the view controllers are fromvc and tovc:

// we have already been handed the new view controller
// set up the new view controller's view's frame
tovc.view.frame = // ... whatever
// must have both as children before we can transition between them
self.addChildViewController(tovc) // "will" called for us
// when we call remove, we must call "will" (with nil) beforehand
fromvc.willMove(toParentViewController: nil)
// then perform the transition
self.transition(
    from:fromvc, to:tovc,
    duration:0.4, options:.transitionFlipFromLeft,
    animations:nil) { _ in
        // when we call add, we must call "did" afterward
        tovc.didMove(toParentViewController: self)
        fromvc.removeFromParentViewController() // "did" called for us
}

If we’re using constraints to position the new child view controller’s view, where will we set up those constraints? Before transition is too soon, as the new child view controller’s view is not yet in the interface. The completion function is too late: if the view is added with no constraints, it will have no initial size or position, so the animation will be performed and then the view will suddenly seem to pop into existence as we provide its constraints. The animations function turns out to be a very good place:

// must have both as children before we can transition between them
self.addChildViewController(tovc) // "will" called for us
// when we call remove, we must call "will" (with nil) beforehand
fromvc.willMove(toParentViewController: nil)
// then perform the transition
self.transition(
    from:fromvc, to:tovc,
    duration:0.4, options:.transitionFlipFromLeft,
    animations: {
        tovc.view.translatesAutoresizingMaskIntoConstraints = false
        // ... configure tovc.view constraints here ...
    }) { _ in
        // when we call add, we must call "did" afterward
        tovc.didMove(toParentViewController: self)
        fromvc.removeFromParentViewController() // "did" called for us
}

Alternatively, you can use a layout-related event, such as viewWillLayoutSubviews; still, I prefer the animations function, as it is called just once at exactly the right moment.

If the built-in transition animations are unsuitable, you can omit the options: argument and provide your own animation in the animations function, at which time both views are in the interface. In this example, I animate a substitute view (an image view showing a snapshot of tovc.view) to grow from the top left corner; then I configure the real view’s constraints and remove the substitute:

// tovc.view.frame is already set
let r = UIGraphicsImageRenderer(size:tovc.view.bounds.size)
let im = r.image { ctx in
    let con = ctx.cgContext
    tovc.view.layer.render(in:con)
}
let iv = UIImageView(image:im)
iv.frame = CGRect.zero
self.view.addSubview(iv)
tovc.view.alpha = 0 // hide the real view
// must have both as children before we can transition between them
self.addChildViewController(tovc) // "will" called for us
// when we call remove, we must call "will" (with nil) beforehand
fromvc.willMove(toParentViewController: nil)
// then perform the transition
self.transition(
    from:fromvc, to:tovc,
    duration:0.4, // no options:
    animations: {
        iv.frame = tovc.view.frame // animate bounds change
        // ... configure tovc.view constraints here ...
    }) { _ in
        tovc.view.alpha = 1
        iv.removeFromSuperview()
        // when we call add, we must call "did" afterward
        tovc.didMove(toParentViewController: self)
        fromvc.removeFromParentViewController() // "did" called for us
}

If your parent view controller is going to be consulted about the status bar (whether it should be shown or hidden, and if shown, whether its text should be light or dark), it can elect to defer the decision to one of its children, by overriding these properties (just as a UITabBarController does):

• childViewControllerForStatusBarStyle

• childViewControllerForStatusBarHidden

Container View Controllers, Traits, and Resizing

A container view controller participates in trait collection inheritance and view resizing. In fact, you may well insert a container view controller into your view controller hierarchy for no other purpose than to engage in such participation.

Thus far, I have treated trait collection inheritance as immutable; and for the most part, it is. A UITraitEnvironment (an object with a traitCollection property: UIScreen, UIView, UIViewController, or UIPresentationController) ultimately gets its trait collection from the environment, and the environment is simply a fact. Nevertheless, a parent view controller has the amazing ability to lie to a child view controller about the environment, thanks to this method:

• setOverrideTraitCollection(_:forChildViewController:)

The first parameter is a UITraitCollection that will be combined with the inherited trait collection and communicated to the specified child.

This is a UIViewController instance method, so only view controllers have this mighty power. Moreover, you have to specify a child view controller, so only parent view controllers have this mighty power. However, UIPresentationController has a similar power, through its overrideTraitCollection property; setting this property combines the override trait collection with the inherited collection and communicates it to the presented view controller.

Why would you want to do such a thing as lie to a child view controller about its environment? Well, imagine that we’re writing an iPad app, and we have a view controller whose view can appear either fullscreen or as a small subview of a parent view controller’s main view. The view’s interface might need to be different when it appears in the smaller size. You could configure that using size classes (conditional constraints) in the nib editor, with one interface for a .regular horizontal size class (iPad) and another interface for a .compact horizontal size class (iPhone). Then, when the view is to appear in its smaller size, we lie to its view controller and tell it that this is an iPhone:

let vc = // the view controller we're going to use as a child
self.addChildViewController(vc) // "will" called for us
let tc = UITraitCollection(horizontalSizeClass: .compact)
self.setOverrideTraitCollection(tc, forChildViewController: vc) // heh heh
vc.view.frame = // whatever
self.view.addSubview(vc.view)
vc.didMove(toParentViewController: self)

Apple’s own motivating example involves UISplitViewController, a class that behaves differently depending on its trait environment. For example, by lying to a split view controller and making it believe we’re on an iPad, you can cause the split view controller to look like a split view controller (displaying two subviews, such as a master table view and a detail view) even on an iPhone. I’ll talk more about that in Chapter 9.

A parent view controller sets the size of a child view controller’s view. A child view controller, however, can express a preference as to what size it would like its view to be, by setting its own preferredContentSize property. The chief purpose of this property is to be consulted by a parent view controller when this view controller is its child. This property is a preference and no more; no law says that the parent must consult the child, or that the parent must obey the child’s preference.

If a view controller’s preferredContentSize is set while it is a child view controller, the runtime automatically communicates this fact to the parent view controller, by calling this UIContentContainer method:

• preferredContentSizeDidChange(forChildContentContainer:)

The parent view controller may implement this method to consult the child’s preferredContentSize and change the child’s view’s size in response. Again, no law requires the parent to do this. This method, and the preferredContentSize property, are ways of allowing a child view controller a voice in its view’s size; it is the parent who dictates what that size will actually be.

A parent view controller, as an adopter of the UIContentContainer protocol (along with UIPresentationController), is also responsible for communicating to its children that their sizes are changing and what their new sizes will be. It is the parent view controller’s duty to implement this method:

size(forChildContentContainer:withParentContainerSize:)

Should be implemented to return each child view controller’s correct size at any moment. Failure to implement this method will cause the child view controller to be handed the wrong size in its implementation of viewWillTransition(to:with:) — it will be given the parent’s new size rather than its own new size!

If your parent view controller implements viewWillTransition(to:with:), calling super is sufficient to get the same message passed on to the children. This works even if your implementation explicitly changed the size of a child view controller at this time, provided that you implemented size(forChildContentContainer:withParentContainerSize:) to return the new size.

Triggered Segues

A triggered segue is a true segue. (Relationships are not really segues at all.) The most common types, as I’ve just explained, are a push segue (show) or a modal segue (present modally). A segue is a full-fledged object, an instance of UIStoryboardSegue, and it can be configured in the nib editor through its Attributes inspector. In a storyboard, however, it is not a nib object, in the sense that it is not instantiated by the loading of a nib, and it cannot be pointed to by an outlet. Rather, it will be instantiated when the segue is triggered, at which time its designated initializer will be called, namely init(identifier:source:destination:).

A segue’s source and destination are the two view controllers between which it runs. The segue is directional, so the source and destination are clearly distinguished. The source view controller is the one that will exist already, before the segue is triggered; the destination view controller will be instantiated together with the segue itself, when the segue is triggered.

A segue’s identifier is a string. You can set this string for a segue in a storyboard through its Attributes inspector; this can be useful when you want to trigger the segue manually in code (you’ll specify it by means of its identifier), or when you have code that can receive a segue as parameter and you need to distinguish which segue this is.

class MyCoolSegue: UIStoryboardSegue {
    override func perform() {
        let dest = self.destination
        dest.modalPresentationStyle = .custom
        dest.transitioningDelegate = self
        super.perform()
    }
}

let svc = SecondViewController(nibName: nil, bundle: nil)
svc.data = "This is very important data!"
svc.delegate = self
self.present(svc, animated:true)

override func prepare(for segue: UIStoryboardSegue, sender: Any?) {
    if segue.identifier == "second" {
        let svc = segue.destination as! SecondViewController
        svc.data = "This is very important data!"
        svc.delegate = self
    }
}

Container Views and Embed Segues

The only parent view controllers for which you can create relationship segues specifying their children in a storyboard are the built-in UITabBarController and UINavigationController. That’s because the nib editor understands how they work. If you write your own custom container view controller, the nib editor doesn’t even know that your view controller is a container view controller, so it can’t be the source of a relationship segue.

Nevertheless, you can perform some initial parent–child configuration of your custom container view controller in a storyboard, if your situation conforms to these assumptions:

• Your parent view controller will have one initial child view controller.

• You want the child view controller’s view placed somewhere in the parent view controller’s view.

Those are reasonable assumptions, and you can work around them if they don’t quite give the desired effect. For example, if your parent view controller is to have additional children, you can always add them later, in code; and if the child view controller’s view is not to be initially visible in the parent view controller’s view, you can always hide it.

To configure your parent view controller in a storyboard, drag a Container View object from the Object library into the parent view controller’s view in the canvas. The result is a view, together with an embed segue leading from it to an additional child view controller. You can then assign the child view controller its correct class in its Identity inspector. Alternatively, delete the child view controller, replace it with a different view controller, and Control-drag from the container view to this view controller and, in the HUD, specify an embed segue.

When an embed segue is triggered, the destination view controller is instantiated and made the source view controller’s child, and its view is placed exactly inside the container view as its subview. Thus, the container view is not only a way of generating the embed segue, but also a way of specifying where you want the child view controller’s view to go. The entire child-addition dance is performed correctly and automatically for you: addChildViewController(_:) is called, the child’s view is put into the interface, and didMove(toParentViewController:) is called.

An embed segue is a triggered segue. It can have an identifier, and the standard messages are sent to the source view controller when the segue is triggered. At the same time, it has this similarity to a relationship: when the source (parent) view controller is instantiated, the runtime wants to trigger the segue automatically, instantiating the child view controller and embedding its view in the container view now. If that isn’t what you want, override shouldPerformSegue(withIdentifier:sender:) in the parent view controller to return false for this segue, and call performSegue(withIdentifier:sender:) later when you do want the child view controller instantiated.

The parent view controller is sent prepare(for:sender:) before the child’s view loads. At this time, the child has not yet been added to the parent’s childViewControllers array. If you allow the segue to be triggered when the parent view controller is instantiated, then by the time the parent’s viewDidLoad is called, the child’s viewDidLoad has already been called, the child has already been added to the parent’s childViewControllers, and the child’s view is already inside the parent’s view.

If you subsequently want to replace the child view controller’s view with another child view controller’s view in the interface, you will do so in code, probably by calling transition(from:to:duration:options:animations:completion:) as I described earlier in this chapter. If you really want to, you can configure this through a storyboard as well, by using a custom segue and a UIStoryboardSegue subclass.

Storyboard References

Starting in Xcode 7 and iOS 9, when you create a segue in the storyboard (a triggered segue or a relationship), you don’t have to Control-drag to a view controller as the destination; instead, you can Control-drag to a storyboard reference which you have previously placed in the canvas of this storyboard. A storyboard reference is a placeholder for a specific view controller. Thus, instead of a large and complicated network of segues running all over your storyboard, possibly crisscrossing in confusing ways, you can effectively jump through the storyboard reference to the actual destination view controller.

To specify what view controller a storyboard reference stands for, you need to perform two steps:

1. Select the view controller and, in the Identity inspector, give it a Storyboard ID.

2. Select the storyboard reference and, in the Attributes inspector, enter that same Storyboard ID as its Referenced ID.

But wait — there’s more! The referenced view controller doesn’t even have to be in the same storyboard as the storyboard reference. You can use a storyboard reference to jump to a view controller in a different storyboard. This allows you to organize your app’s interface into multiple storyboards. That was always possible, but loading any storyboards apart from the automatically loaded main storyboard was up to you (in code). With a storyboard reference that leads into a different storyboard, that storyboard is loaded automatically.

To configure a storyboard reference to refer to a view controller in a different storyboard, use the Storyboard pop-up menu in its Attributes inspector. The rule is that if you specify the Storyboard but not the Referenced ID, the storyboard reference stands for the target storyboard’s initial view controller (the one marked as the Storyboard Entry Point in that storyboard’s document outline). If you do specify the Referenced ID, then of course the storyboard reference stands for the view controller with that Storyboard ID in the target storyboard. (I find that as a practical matter, things work best if you always specify both the storyboard reference’s Storyboard and its Referenced ID.)

Unwind Segues

Here’s an interesting puzzle: Storyboards and segues would appear to be useful only half the time, because segues are asymmetrical. There is a push segue but no pop segue. There is a present modally segue but no dismiss segue.

The reason, in a nutshell, is that you can’t possibly use a normal segue to mean “go back.” Triggering a triggered segue instantiates the destination view controller; it creates a new view controller instance. But when dismissing a presented view controller or popping a pushed view controller, we don’t need any new view controller instances. We want to return, somehow, to an existing instance of a view controller.

The solution is an unwind segue. An unwind segue does let you express the notion “go back” in a storyboard. Basically, it lets you jump to any view controller that is already instantiated further up your view controller hierarchy, destroying the source view controller and any intervening view controllers in good order.

Creating an unwind segue

Before you can create an unwind segue, you must implement an unwind method in the class of any view controller represented in the storyboard. This should be a method marked @IBAction as a hint to the storyboard editor, and taking a single parameter, a UIStoryboardSegue. You can call it unwind if you like, but the name doesn’t really matter:

@IBAction func unwind(_ seg:UIStoryboardSegue!) {
    // ...
}

Think of this method as a marker, specifying that the view controller in which it appears can be the destination for an unwind segue. It is, in fact, a little more than a marker: it will also be called when the unwind segue is triggered. But its marker functionality is much more important — so much so that, in many cases, you won’t give this method any code at all. Its presence, and its name, are what matters.

Now you can create an unwind segue. Doing so involves the use of the Exit proxy object that appears in every scene of a storyboard. Control-drag from the view controller you want to go back from, or from something like a button in that view controller’s view, connecting it to the Exit proxy object in the same scene (Figure 6-10). A little HUD appears, listing all the known unwind methods (similar to how action methods are listed in the HUD when you connect a button to its target). Click the name of the unwind method you want. You have now made an unwind segue, bound to that unwind method.

Figure 6-10. Creating an unwind segue

Incoherencies in View Controller Events

Unfortunately, the exact sequence of events and the number of times they will be called for any given view controller transition situation sometimes seems nondeterministic or incoherent. For example:

• Sometimes didMove(toParentViewController:) arrives without a corresponding willMove(toParentViewController:).

• Sometimes didMove(toParentViewController:) arrives even though this view controller was previously the child of this parent and remains the child of this parent.

• Sometimes the layout events updateViewConstraints, viewWillLayoutSubviews, and viewDidLayoutSubviews arrive more than once for the same view controller for the same transition.

• Sometimes viewWillAppear(_:) or viewWillDisappear(_:) arrives without a corresponding viewDidAppear(_:) or viewDidDisappear(_:). A notable case in point is when an interactive transition animation begins and is cancelled.

I regard all such behaviors as bugs, but Apple clearly does not. The best advice I can offer is that you should try to structure your code in such a way that incoherencies of this sort don’t matter.

Appear and Disappear Events

The appear and disappear events are particularly appropriate for making sure that a view reflects the model or some form of saved state whenever it appears. Changes to the interface performed in viewDidAppear(_:) or viewWillDisappear(_:) may be visible to the user as they occur! If that’s not what you want, use the other member of the pair. For example, in a certain view containing a long scrollable text, I want the scroll position to be the same when the user returns to this view as it was when the user left it, so I save the scroll position in viewWillDisappear(_:) and restore it in viewWillAppear(_:) — not viewDidAppear(_:), where the user might see the scroll position jump.

These methods are useful also when something must be true exactly so long as a view is in the interface. For example, a repeating Timer that must be running while a view is present can be started in the view controller’s viewDidAppear(_:) and stopped in its viewWillDisappear(_:). (This architecture also allows you to avoid the retain cycle that could result if you waited to invalidate the timer in a deinit that might otherwise never arrive.)

A view does not disappear if a presented view controller’s view merely covers it rather than supplanting it. For example, a view controller that presents another view controller using the .formSheet presentation style gets no lifetime events during presentation and dismissal.

A view does not disappear merely because the app is backgrounded and suspended. Once suspended, your app might be killed. So you cannot rely on viewWillDisappear(_:) or viewDidDisappear(_:) alone for saving data that the app will need the next time it launches. If you are to cover every case, you may need to ensure that your data-saving code also runs in response to an application lifetime event such as applicationWillResignActive or applicationDidEnterBackground (and see Appendix A for a discussion of the application lifetime events).

Event Forwarding to a Child View Controller

A custom container view controller, as I explained earlier, must effectively send willMove(toParentViewController:) and didMove(toParentViewController:) to its children manually.

It must also forward resizing events to its children. This will happen automatically if you call super in your implementation of the willTransition methods. Conversely, if you implement these methods, failure to call super may prevent them from being forwarded correctly to the child view controller.

The appear and disappear events are normally passed along automatically. However, you can take charge by overriding this property:

shouldAutomaticallyForwardAppearanceMethods

If you override this property to return false, you are responsible for seeing that the four appear and disappear methods are called on your view controller’s children. You do not do this by calling these methods directly. The reason is that you have no access to the correct moment for sending them. Instead, you call these two methods on your child view controller:

• beginAppearanceTransition(_:animated:); the first parameter is a Bool saying whether this view controller’s view is about to appear (true) or disappear (false)

• endAppearanceTransition

Here’s what to do if you’ve implemented shouldAutomaticallyForwardAppearanceMethods to return false. There are two main occasions on which your custom container view controller must forward appear and disappear events to a child.

First, what happens when your custom container view controller’s own view itself appears or disappears? If it has a child view controller’s view within its own view, it must implement and forward all four appear and disappear events to that child. You’ll need an implementation along these lines, for each of the four events:

override func viewWillAppear(_ animated: Bool) {
    super.viewWillAppear(animated)
    let child = // whatever
    if child.isViewLoaded && child.view.superview != nil {
        child.beginAppearanceTransition(true, animated: true)
    }
}
override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    let child = // whatever
    if child.isViewLoaded && child.view.superview != nil {
        child.endAppearanceTransition()
    }
}

(The implementations for viewDidAppear(_:) and viewDidDisappear(_:) are similar, except that the first argument for beginAppearanceTransition is false.)

Second, what happens when you swap one view controller’s child for another in your interface? Apple warns that you should not call the UIViewController method transition(from:...); instead, you perform the transition animation directly, calling beginAppearanceTransition(_:animated:) and endAppearanceTransition yourself.

A minimal correct implementation might involve the UIView transition class method (see Chapter 4). Here’s an example of a parent view controller swapping one child view controller and its view for another, while taking charge of notifying the child view controllers of the appearance and disappearance of their views. I’ve put asterisks to call attention to the additional method calls that forward the appear and disappear events to the children (fromvc and tovc):

self.addChildViewController(tovc) // "will" called for us
fromvc.willMove(toParentViewController: nil)
fromvc.beginAppearanceTransition(false, animated:true) // *
tovc.beginAppearanceTransition(true, animated:true) // *
UIView.transition(
    from:fromvc.view, to:tovc.view,
    duration:0.4, options:.transitionFlipFromLeft) {_ in
        tovc.endAppearanceTransition() // *
        fromvc.endAppearanceTransition() // *
        tovc.didMove(toParentViewController: self)
        fromvc.removeFromParentViewController()
}

How to Test State Restoration

To test whether your app is saving and restoring state as you expect:

1. Run the app from Xcode as usual, in the Simulator or on a device.

2. At some point, in the Simulator or on the device, click the Home button (Hardware → Home in the Simulator). This causes the app to be suspended in good order, and state is saved.

3. Now, back in Xcode, stop the running project (Product → Stop).

4. Run the project again. If there is saved state, it is restored.

(To test the app’s behavior from a truly cold start, delete it from the Simulator or device. You might need to do this after changing something about the underlying save-and-restore model.)

Apple also provides some debugging tools (look for “restorationArchiveTool for iOS” at https://developer.apple.com/download/more/):

restorationArchiveTool

A command-line tool letting you examine a saved state archive in textual format. The archive is in a folder called Saved Application State in your app’s sandboxed Library. See Chapter 22 for more about the app’s sandbox, and how to copy it to your computer from a device.

StateRestorationDebugLogging.mobileconfig

A configuration profile. When installed on a device, it causes the console to dump information as state saving and restoration proceeds.

StateRestorationDeveloperMode.mobileconfig

A configuration profile. When installed on a device, it prevents the state archive from being jettisoned after unexpected termination of the app (a crash, or manual termination through the app switcher interface). This can allow you to test state restoration a bit more conveniently.

To install a .mobileconfig file on a device, the simplest approach is to email it to yourself on the device and tap the file in the Mail message. You can subsequently delete the file, if desired, through the Settings app.

Participating in State Restoration

Built-in state restoration is an opt-in technology: it operates only if you explicitly tell the system that you want to participate in it. To do so, you take three basic steps:

Implement app delegate methods

The app delegate must implement these methods to return true:

• application(_:shouldSaveApplicationState:)

• application(_:shouldRestoreApplicationState:)

(Naturally, your code can instead return false to prevent state from being saved or restored on some particular occasion.)

Implement application(_:willFinishLaunchingWithOptions:)

Although it is very early, application(_:didFinishLaunchingWithOptions:) is too late for state restoration. Your app needs its basic interface before state restoration begins. The solution is to use a different app delegate method, application(_:willFinishLaunchingWithOptions:).

Typically, you can just change did to will in the name of this method, keeping your existing code unchanged. However, your implementation must call makeKeyAndVisible explicitly on the window! Otherwise, the interface doesn’t come into existence soon enough for restoration to happen during launch.

Provide restoration IDs

Both UIViewController and UIView have a restorationIdentifier property, which is a string. Setting this string to a non-nil value is your signal to the system that you want this view controller (or view) to participate in state restoration. If a view controller’s restorationIdentifier is nil, neither it nor any subsequent view controllers down the chain will be saved or restored. (A nice feature of this architecture is that it lets you participate partially in state restoration, omitting some view controllers by not assigning them a restoration identifier.)

You can set the restorationIdentifier manually, in code; typically you’ll do that early in a view controller’s lifetime. If a view controller or view is instantiated from a nib, you’ll want to set the restoration identifier in the nib editor; the Identity inspector has a Restoration ID field for this purpose. If you’re using a storyboard, it’s a good idea, in general, to make a view controller’s restoration ID in the storyboard the same as its storyboard ID; in fact, it’s such a good idea that the storyboard editor provides a checkbox, “Use Storyboard ID,” that makes the one value automatically the same as the other.

In the case of a simple storyboard-based app, where each needed view controller instance can be reconstructed directly from the storyboard, those steps alone can be sufficient to bring state restoration to life, operating correctly at the view controller level. Let’s test it! Start with a storyboard-based app with the following architecture (Figure 6-11):

• A navigation controller.

• Its root view controller, connected by a relationship from the navigation controller. Call its class RootViewController.

  • A presented view controller, connected by a modal segue from a Present button in RootViewController’s view. Call its class PresentedViewController. Its view contains a Dismiss button.

• A second view controller, connected by a push segue from a Push button in RootViewController’s view. Call its class SecondViewController.

  • The very same presented view controller (PresentedViewController), also connected by a modal segue from a Present button in the second view controller’s view.

Figure 6-11. Architecture of an app for testing state restoration

This storyboard-based app runs perfectly with just about no code at all; all we need is an empty implementation of an unwind method in RootViewController and SecondViewController so that we can create an unwind segue from the PresentedViewController’s Dismiss button.

We will now make this app implement state restoration:

1. In the app delegate, change the name of application(_:didFinishLaunchingWithOptions:) to application(_:willFinishLaunchingWithOptions:), and insert this line of code:

   self.window?.makeKeyAndVisible()

2. In the app delegate, implement these two methods to return true:

   • application(_:shouldSaveApplicationState:)

   • application(_:shouldRestoreApplicationState:)

3. In the storyboard, give restoration IDs to all four view controller instances: let’s call them "nav", "root", "second", and "presented".

That’s all! The app now saves and restores state. When we run the app, navigate to any view controller, quit, and later relaunch, the app appears in the same view controller it was in when we quit.

Restoration ID, Identifier Path, and Restoration Class

Having everything done for us by the storyboard reveals nothing about what’s really happening. To learn more, let’s rewrite the example without using the storyboard. Implement the same architecture using code alone:

// AppDelegate.swift:
func application(_ application: UIApplication,
    didFinishLaunchingWithOptions
    launchOptions: [UIApplicationLaunchOptionsKey : Any]?)
    -> Bool {
        self.window = self.window ?? UIWindow()
        let rvc = RootViewController()
        let nav = UINavigationController(rootViewController:rvc)
        self.window!.rootViewController = nav
        self.window!.backgroundColor = .white
        self.window!.makeKeyAndVisible()
        return true
}

// RootViewController.swift:
override func viewDidLoad() {
    super.viewDidLoad()
    // ... color view background, create buttons ...
}
func doPresent(_ sender: Any?) {
    let pvc = PresentedViewController()
    self.present(pvc, animated:true)
}
func doPush(_ sender: Any?) {
    let svc = SecondViewController()
    self.navigationController!.pushViewController(svc, animated:true)
}

// SecondViewController.swift:
override func viewDidLoad() {
    super.viewDidLoad()
    // ... color view background, create button ...
}
func doPresent(_ sender: Any?) {
    let pvc = PresentedViewController()
    self.present(pvc, animated:true)
}

// PresentedViewController.m:
override func viewDidLoad() {
    super.viewDidLoad()
    // ... color view background, create button ...
}
func doDismiss(_ sender: Any?) {
    self.presentingViewController!.dismiss(animated:true)
}

That’s a working app. Now let’s start adding state restoration, just as before:

1. In the app delegate, change the name of application(_:didFinishLaunchingWithOptions:) to application(_:willFinishLaunchingWithOptions:).

2. In the app delegate, implement these two methods to return true:

   • application(_:shouldSaveApplicationState:)

   • application(_:shouldRestoreApplicationState:)

3. Give all four view controller instances restoration IDs: let’s call them "nav", "root", "second", and "presented". We’ll have to do this in code. We’re creating each view controller instance manually, so we may as well assign its restorationIdentifier in the next line, like this:

   let rvc = RootViewController()
   rvc.restorationIdentifier = "root"
   let nav = UINavigationController(rootViewController:rvc)
   nav.restorationIdentifier = "nav"

   And so on.

Run the app. We are not getting state restoration. Why not?

The reason is that the restorationIdentifier alone is not sufficient to tell the state restoration mechanism what to do as the app launches. The restoration mechanism knows the chain of view controller classes that needs to be generated, but it is up to us to generate the instances of those classes. (Our storyboard-based example didn’t exhibit this problem, because the storyboard itself was the source of the instances.) To do that, we need to know about the identifier path and the restoration class.

func doPresent(_ sender: Any?) {
    let pvc = PresentedViewController()
    pvc.restorationIdentifier = "presented"
    pvc.restorationClass = type(of:self) // *
    self.present(pvc, animated:true)
}
class func viewController(withRestorationIdentifierPath ip: [Any],
    coder: NSCoder) -> UIViewController? {
        var vc : UIViewController? = nil
        let last = ip.last as! String
        switch last {
        case "presented":
            let pvc = PresentedViewController()
            pvc.restorationIdentifier = "presented"
            pvc.restorationClass = self
            vc = pvc
        default: break
        }
        return vc
}

class func makePresentedViewController () -> UIViewController {
    let pvc = PresentedViewController()
    pvc.restorationIdentifier = "presented"
    pvc.restorationClass = self
    return pvc
}
func doPresent(_ sender: Any?) {
    let pvc = type(of:self).makePresentedViewController()
    self.present(pvc, animated:true)
}
class func viewController(withRestorationIdentifierPath ip: [Any],
    coder: NSCoder) -> UIViewController? {
        var vc : UIViewController? = nil
        let last = ip.last as! String
        switch last {
        case "presented":
            vc = self.makePresentedViewController()
        default: break
        }
        return vc
}

Restoring View Controller State

I have explained how the state restoration mechanism creates a view controller and places it into the view controller hierarchy. But at that point, the work of restoration is only half done. What about the state of that view controller?

A newly restored view controller probably won’t have the data and property values it was holding at the time the app was terminated. The history of the configuration of this view controller throughout the time the app was previously running is not magically recapitulated during restoration. It is up to each view controller, therefore, to restore its own state when it itself is restored. And in order to do that, it must previously save its own state when the app is backgrounded. The state saving and restoration mechanism provides a way of helping your view controllers do this, through the use of a coder (an NSCoder object). Think of this coder as a box in which the view controller is invited to place its valuables for safekeeping, and from which it can retrieve them later. Each of these valuables needs to be identified, so it is tagged with a key (an arbitrary string) when it is placed into the box, and is then later retrieved by using the same key, much as in a dictionary.

Anyone who has anything to save at the time it is handed a coder can do so by calling encode(_:forKey:). If an object’s class doesn’t adopt the NSCoding protocol, you may have to archive it to a Data object before you can encode it. However, views and view controllers can be handled by the coder directly, because they are treated as references. Whatever was saved in the coder can later be extracted using the same key. You can call decodeObject(forKey:) and cast down as needed, or you can call a specialized method corresponding to the expected type, such as decodeFloat(forKey:).

The keys do not have to be unique across the entire app; they only need to be unique for a particular view controller. Each object that is handed a coder is handed its own personal coder. It is handed this coder at state saving time, and it is handed the same coder (that is, a coder with the same archived objects and keys) at state restoration time.

Here’s the sequence of events involving coders:

Saving state

When it’s time to save state (as the app is about to be backgrounded), the state saving mechanism provides coders as follows:

1. The app delegate is sent application(_:shouldSaveApplicationState:). The coder is the second parameter.

2. The app delegate is sent application(_:willEncodeRestorableStateWith:). The coder is the second parameter, and in fact it is the same coder as in the previous step, because this is the same object (the app delegate).

3. Each view controller down the chain, starting at the root view controller, is sent encodeRestorableState(with:). The coder is the parameter. The implementation should call super. Each view controller gets its own coder.

Restoring state

When it’s time to restore state (as the app is launched), the state restoration mechanism provides coders as follows:

1. The app delegate is sent application(_:shouldRestoreApplicationState:). The coder is the second parameter.

2. As each view controller down the chain is to be created, one of these methods is called (as I’ve already explained); the coder is the one appropriate to the view controller that’s to be created:

   • The restoration class’s viewController(withRestorationIdentifierPath:coder:), if the view controller has a restoration class.

   • Otherwise, the app delegate’s application(_:viewControllerWithRestorationIdentifierPath:coder:).

3. Each view controller down the chain, starting at the root view controller, is sent decodeRestorableState(with:). The coder is the parameter. The implementation should call super.

4. The app delegate is sent application(_:didDecodeRestorableStateWith:). The coder is the second parameter, and is the same one sent to application(_:shouldRestoreApplicationState:).

The UIStateRestoration.h header file describes five built-in keys that are available from every coder during restoration:

UIStateRestorationViewControllerStoryboardKey

A reference to the storyboard from which this view controller came, if any.

UIApplicationStateRestorationBundleVersionKey

Your Info.plist CFBundleVersion string at the time of state saving.

UIApplicationStateRestorationUserInterfaceIdiomKey

An NSNumber wrapping a UIUserInterfaceIdiom value, either .phone or .pad, telling what kind of device we were running on when state saving happened. You can extract this information as follows:

let key = UIApplicationStateRestorationUserInterfaceIdiomKey
if let idiomraw = coder.decodeObject(forKey: key) as? Int {
    if let idiom = UIUserInterfaceIdiom(rawValue:idiomraw) {
        if idiom == .phone {
            // ...
        }
    }
}

UIApplicationStateRestorationTimestampKey

A Date telling when state saving happened.

UIApplicationStateRestorationSystemVersionKey

A NSString telling the system version under which state saving happened.

One purpose of these keys is to allow your app to opt out of state restoration, wholly or in part, because the archive is too old, was saved on the wrong kind of device (and presumably migrated to this one by backup and restore), and so forth.

A typical implementation of encodeRestorableState(with:) and decodeRestorableState(with:) will concern itself with properties and interface views. decodeRestorableState(with:) is guaranteed to be called after viewDidLoad, so you know that viewDidLoad won’t overwrite any direct changes to the interface performed in decodeRestorableState(with:).

To illustrate, I’ll add state saving and restoration to my earlier UIPageViewController example, the one that displays a Pep Boy on each page. Recall how that example is architected. The project has no storyboard. The code defines just two classes, the app delegate and the Pep view controller. The app delegate creates a UIPageViewController and makes it the window’s root view controller, and makes itself the page view controller’s data source; its self.pep instance property holds the data model, which is just an array of string Pep Boy names. The page view controller’s data source methods create and supply an appropriate Pep instance whenever a page is needed for the page view controller, along these lines:

// ... work out index of new name ...
return Pep(pepBoy: self.pep[ix])

The challenge is to restore the Pep object displayed in the page view controller as the app launches. One solution involves recognizing that a Pep object is completely configured once created, and it is created just by handing it the name of a Pep Boy in its designated initializer, which becomes its boy property. Thus we can mediate between a Pep object and a mere string, and all we really need to save and restore is that string.

All the additional work, therefore, can be performed in the app delegate. We save and restore the current Pep Boy name in the app delegate’s encode and decode methods:

func application(_ application: UIApplication,
    willEncodeRestorableStateWith coder: NSCoder) {
        let pvc = self.window!.rootViewController as! UIPageViewController
        let boy = (pvc.viewControllers![0] as! Pep).boy
        coder.encode(boy, forKey:"boy")
}
func application(_ application: UIApplication,
    didDecodeRestorableStateWith coder: NSCoder) {
        let boyMaybe = coder.decodeObject(forKey:"boy")
        guard let boy = boyMaybe as? String else {return}
        let pvc = self.window!.rootViewController as! UIPageViewController
        let pep = Pep(pepBoy: boy)
        pvc.setViewControllers([pep], direction: .forward, animated: false)
}

A second, more general solution is to make our Pep view controller class itself capable of saving and restoration. This means that every view controller down the chain from the root view controller to our Pep view controller must have a restoration identifier. In our simple app, there’s just one such view controller, the UIPageViewController; the app delegate can assign it a restoration ID when it creates it:

let pvc = UIPageViewController(
    transitionStyle: .scroll, navigationOrientation: .horizontal)
pvc.restorationIdentifier = "pvc" // *

We’ll have a Pep object assign itself a restoration ID in its own designated initializer. The Pep object will also need a restoration class; as I mentioned earlier, this can perfectly well be the Pep class itself, and that seems most appropriate here:

required init(pepBoy boy:String) { // *
    self.boy = boy
    super.init(nibName: nil, bundle: nil)
    self.restorationIdentifier = "pep" // *
    self.restorationClass = type(of:self) // *
}

The only state that a Pep object needs to save is its boy string, so we implement encodeRestorableState to do that. We don’t need to implement decodeRestorableState, because the coder that will come back to us in viewController(withRestorationIdentifierPath:coder:) contains the boy string, and once we use it to create the Pep instance, the Pep instance is completely configured. This is a class method, and it can’t call an initializer on self unless that initializer is marked as required; we did mark it required (in the previous code):

override func encodeRestorableState(with coder: NSCoder) {
    super.encodeRestorableState(with:coder)
    coder.encode(self.boy, forKey:"boy")
}
class func viewController(withRestorationIdentifierPath ip: [Any],
    coder: NSCoder) -> UIViewController? {
        let boy = coder.decodeObject(forKey:"boy") as! String
        return self.init(pepBoy: boy)
}

Now comes a surprise. We run the app and test it, and we find that we’re not getting saving and restoration of our Pep object. It isn’t being archived; its encodeRestorableState(with:) isn’t even being called! The reason is that the state saving mechanism doesn’t work automatically for a UIPageViewController and its children (or for a custom container view controller and its children, for that matter). It is up to us to see to it that the current Pep object is archived.

To do so, we can archive and unarchive the current Pep object in an implementation of encodeRestorableState(with:) and decodeRestorableState(with:) that is being called. For our app, that would have to be in the app delegate. The code we’ve written so far has all been necessary to make the current Pep object archivable and restorable; now the app delegate will make sure that it is archived and restored:

func application(_ application: UIApplication,
    willEncodeRestorableStateWith coder: NSCoder) {
        let pvc = self.window!.rootViewController as! UIPageViewController
        let pep = pvc.viewControllers![0] as! Pep
        coder.encode(pep, forKey:"pep")
}
func application(_ application: UIApplication,
    didDecodeRestorableStateWith coder: NSCoder) {
        let pepMaybe = coder.decodeObject(forKey:"pep")
        guard let pep = pepMaybe as? Pep else {return}
        let pvc = self.window!.rootViewController as! UIPageViewController
        pvc.setViewControllers([pep], direction: .forward, animated: false)
}

This solution may seem rather heavyweight, but it isn’t. We’re not really archiving an entire Pep instance; it’s just a reference. The Pep instance that arrives in application(_:didDecodeRestorableStateWith:) was never in the archive; it is the instance created by Pep’s implementation of viewController(withRestorationIdentifierPath:coder:).

Restoration Order of Operations

When you implement state saving and restoration for a view controller, the view controller ends up with two different ways of being configured. One way involves the view controller lifetime events I discussed earlier (“View Controller Lifetime Events”). The other involves the state restoration events I’ve been discussing here. You want your view controller to be correctly configured no matter whether this view controller is undergoing state restoration or not.

Before state saving and restoration, you were probably configuring your view controller, at least in part, in viewWillAppear(_:) and viewDidAppear(_:). So you’d like to know when these will arrive during state restoration in relation to decodeRestorableState(with:). But you don’t know; it might be before or after decodeRestorableState(with:). In fact, you don’t even know whether viewDidAppear(_:) will arrive: it might well never arrive, even if viewWillAppear(_:) arrives. This is another of those view controller lifetime event incoherencies I complained about earlier in this chapter.

Fortunately, there’s another view controller event I haven’t mentioned yet: applicationFinishedRestoringState. If you implement this method in a view controller subclass, it will be called if and only if we’re doing state restoration, at a time when all view controllers have already been sent decodeRestorableState(with:).

Thus, the known order of events during state restoration is like this:

1. application(_:shouldRestoreApplicationState:)

2. application(_:viewControllerWithRestorationIdentifierPath:coder:)

3. viewController(withRestorationIdentifierPath:coder:), in order down the chain

4. viewDidLoad, in order down the chain; possibly interleaved with the foregoing

5. decodeRestorableState(with:), in order down the chain

6. application(_:didDecodeRestorableStateWith:)

7. applicationFinishedRestoringState, in order down the chain

You still don’t know when viewWillAppear(_:) and viewDidAppear(_:) will arrive, or whether viewDidAppear(_:) will arrive at all. But in applicationFinishedRestoringState you can reliably finish configuring your view controller and your interface.

A typical situation is that you will want to update your interface after all properties have been set. So you’ll factor out your interface-updating code into a single method. Now there are two possibilities, and they are both handled coherently:

We’re not restoring state

Properties will be set through initialization and configuration, and then viewWillAppear(_:) calls your interface-updating method.

We are restoring state

Properties will be set by decodeRestorableState(with:), and then applicationFinishedRestoringState calls your interface-updating method.

There is still some indeterminacy as to what’s going to happen, but the interface-updating method can mediate that indeterminacy by checking for two things that can go wrong:

It is called too soon

The interface-updating method should check to see that the properties have in fact been set; if not, it should just return. It will be called again when the properties have been set.

It is called unnecessarily

The interface-updating method might run twice in quick succession with the same set of properties. This is not a disaster, but if you don’t like it, you can prevent it by comparing the properties to the interface and return if the interface has already been configured with these properties.

Restoration of Other Objects

A view will participate in automatic saving and restoration of state if its view controller does, and if it itself has a restoration identifier. Some built-in UIView subclasses have built-in restoration abilities. For example, a scroll view that participates in state saving and restoration will automatically return to the point to which it was scrolled previously. You should consult the documentation on each UIView subclass to see whether it participates usefully in state saving and restoration, and I’ll mention a few significant cases when we come to discuss those views in later chapters.

In addition, an arbitrary object can be made to participate in automatic saving and restoration of state. There are three requirements for such an object:

• The object’s class must adopt the UIStateRestoring protocol. This declares three optional methods:

  • encodeRestorableState(with:)

  • decodeRestorableState(with:)

  • applicationFinishedRestoringState

• When the object is created, someone must register it with the runtime by calling this UIApplication class method:

  • registerObject(forStateRestoration:restorationIdentifier:)

• Someone who participates in state saving and restoration, such as a view controller, must make the archive aware of this object by storing a reference to it in the archive (typically in encodeRestorableState(with:)) — much as we did with the Pep object earlier.

So, for example, here’s an NSObject subclass Thing with a word property, that participates in state saving and restoration:

class Thing : NSObject, UIStateRestoring {
    var word = ""
    func encodeRestorableState(with coder: NSCoder) {
        coder.encode(self.word, forKey:"word")
    }
    func decodeRestorableState(with coder: NSCoder) {
        self.word = coder.decodeObject(forKey:"word") as! String
    }
    func applicationFinishedRestoringState() {
        // not used
    }
}

And here’s a view controller with an Optional Thing property (self.thing):

class func makeThing () -> Thing {
    let thing = Thing()
    UIApplication.registerObject(
        forStateRestoration: thing, restorationIdentifier: "thing")
    return thing
}
override func awakeFromNib() {
    super.awakeFromNib()
    self.thing = type(of:self).makeThing()
}
override func encodeRestorableState(with coder: NSCoder) {
    super.encodeRestorableState(with:coder)
    coder.encode(self.thing, forKey: "mything") // *
}

The starred line is crucial; it introduces our Thing object to the archive and brings its UIStateRestoring methods to life. The result is that if we background the app while an instance of this view controller exists, and if state restoration is performed on the next launch, the view controller’s Thing has the same word that it had before; the Thing has participated in state saving and restoration along with the view controller that owns it.

There is an optional objectRestorationClass property of the restorable object, and an object(withRestorationIdentifierPath:coder:) method that the designated class must implement. The class in question should formally adopt the UIObjectRestoration protocol. Its implementation of object(withRestorationIdentifierPath:coder:) should return the restorable object, by creating it or pointing to it; alternatively, it can return nil to prevent restoration. If you want to assign an objectRestorationClass, you’ll have to declare the property:

var objectRestorationClass: UIObjectRestoration.Type?

However, our Thing object was restorable even without an objectRestorationClass! Presumably, just calling registerObject sufficiently identifies this object to the runtime.

Another optional property of the restorable object is restorationParent. Again, if you want to assign to it, you’ll have to declare it:

var restorationParent: UIStateRestoring?

The purpose of the restoration parent is to give the restorable object an identifier path. For example, if we have a chain of view controllers with a path ["nav", "second"], then if that last view controller is the restorationParent of our Thing object, the Thing object’s identifier path in object(withRestorationIdentifierPath:coder:) will be ["nav", "second", "thing"], rather than simply ["thing"]. This is useful if we are worried that ["thing"] alone will not uniquely identify this object.

Snapshot Suppression

When your app is backgrounded, the system takes a snapshot of your interface. It is used in the app switcher interface, and as a launch image when your app is resumed. But what happens if your app is killed in the background and relaunched?

If your app isn’t participating in state restoration, then its default launch image is used. This makes sense, because your app is starting from scratch. But if your app is participating in state restoration, then the snapshot is used as a launch image. This makes sense, too, because the interface that was showing when the app was backgrounded is presumably the very interface your state restoration process is about to restore.

However, you might decide, while saving state, that there is reason not to use the system’s snapshot when relaunching. (Perhaps there is something in your interface that would be inappropriate to display when the app is subsequently launched.) In that case, you can call the UIApplication instance method ignoreSnapshotOnNextApplicationLaunch. When the app launches with state restoration, the user will see your app’s default launch image, followed by a change to the restored interface. They may not match, but at least there is a nice cross-dissolve between them.

By the same token, if the view controller whose view was showing at state saving time is not restorable (it has no restoration ID), then if the app is killed in the background and subsequently launches with state restoration, the restoration mechanism knows that the snapshot taken at background time doesn’t match the interface we’re about to restore to, so the user will initially see your app’s default launch image.