To supply a UIViewController’s view manually, in code, implement 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. We are going to do everything manually, so we don’t need or want a storyboard; therefore, start with an app without a main storyboard (I explained how to make such an app at the start of Chapter 1), and modify it as follows:

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 an identifiable color, and we’ll put some interface inside it, namely a “Hello, World” label:

override func loadView() {
    let v = UIView()
    v.backgroundColor = UIColor.greenColor()
    self.view = v
    let label = UILabel()
    v.addSubview(label)
    label.text = "Hello, World!"
    label.autoresizingMask = [
        .FlexibleTopMargin,
        .FlexibleLeftMargin,
        .FlexibleBottomMargin,
        .FlexibleRightMargin]
    label.sizeToFit()
    label.center = CGPointMake(v.bounds.midX, v.bounds.midY)
    label.frame.makeIntegralInPlace()
}

We have not yet given a RootViewController instance a place in our view controller hierarchy — in fact, we have no view controller hierarchy. Let’s make one. To do so, we turn to AppDelegate.swift. (It’s a little frustrating having to set things up in two different places before our labors can bear any visible fruit, but such is life.)

In AppDelegate.swift, modify the implementation of application:didFinishLaunchingWithOptions: to create a RootViewController instance and make it the window’s rootViewController (see Example 1-1):

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

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.)

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 = UIColor.greenColor()
    let label = UILabel()
    v.addSubview(label)
    label.text = "Hello, World!"
    label.translatesAutoresizingMaskIntoConstraints = false
    NSLayoutConstraint.activateConstraints([
        label.centerXAnchor.constraintEqualToAnchor(v.centerXAnchor),
        label.centerYAnchor.constraintEqualToAnchor(v.centerYAnchor),
    ])
}

But if we’re going to do that, we can go even further and remove our implementation of loadView altogether! 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 already doing in code: 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!

A view controller’s view can be supplied from a nib file. This approach gives you the convenience of configuring and populating the view by designing it graphically in the nib editor interface.

When the nib loads, the view controller instance will already have been created, and it will serve as the nib’s owner. The view controller’s proxy in the nib has the same class as the view controller, and its view outlet points to the view object in the nib. Thus, when the nib loads, the view controller obtains its view through the nib-loading mechanism!

I’ll illustrate by modifying the preceding example to use a .xib file. (I’ll deal later with the use of a .storyboard file; knowing first how the process works for a .xib file will greatly enhance your understanding of how it works for a .storyboard file.)

In a .xib file, the nib owner is represented by 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:

Let’s try it. We begin with the example we’ve already developed, with our RootViewController class. Delete the implementation of loadView 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:

We have designed the nib, but we have done nothing as yet to associate this nib with our RootViewController instance. To do so, let’s once again return to AppDelegate.swift, where we create our RootViewController instance:

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

We’re going to modify this code so that our RootViewController instance, theRVC, is aware of this nib file, MyNib.xib, as its own nib file. That way, when theRVC needs to acquire its view, it will load that nib file with itself as owner, thus ending up with the correct view as its own view property. A UIViewController has a nibName property for this purpose. However, we are not allowed to set its nibName property (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() 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 has a name that 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, like this:

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 you create a UIViewController subclass, the Xcode dialog has a checkbox (which we unchecked earlier) offering to create an eponymous .xib file at the same time. If you accept that option, the nib is created with the File’s Owner’s class already set to the view controller’s class and with its view outlet already hooked up to the view. This automatically created .xib file does not have “Controller” stripped off the end of its name; you can rename it manually later (I generally do) if the default name bothers you.

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 (though conditional constraints, described in Chapter 1, may permit you to design an interface differing on iPad and iPhone in a single nib).

We are now in a position to summarize the sequence whereby a view controller’s view is obtained:

As I mentioned earlier, a view controller can be a nib object, to be instantiated through the loading of the nib. In the nib editor, the Object library contains a View Controller (UIViewController) as well as several built-in UIViewController subclasses. Any of these can be dragged into the canvas. This is the standard way of creating a scene in a .storyboard file; doing the same with a .xib file is rare but perfectly possible.

When a view controller has been instantiated from a nib, and when it comes eventually to obtain its view, all the ways I’ve already described whereby a view controller can obtain its view still apply. (There’s also an additional way, which I’ll discuss in a moment.)

To try this with a .xib file, start over with an empty project without a storyboard:

In AppDelegate.swift, we must now arrange to load Main.xib and extract the view controller instance created from the nib object we just put into the nib, making that view controller our app’s root view controller. Here’s one very simple way to do that:

let arr = UINib(nibName: "Main", bundle: nil)
    .instantiateWithOwner(nil, options: nil)
self.window!.rootViewController = arr[0] as? UIViewController

You can now proceed, if you like, to experiment with various ways of helping this view controller get its view. At the moment it is a plain UIViewController instance. Let’s make it a class of our own:

Now you can help RootViewController get its view, in any of the ways we’ve already explored:

If this nib-instantiated view controller is to get its view from another nib, there’s a way to specify the name of that nib in the nib editor: select the view controller in its nib, and enter the name of the view’s nib in the NIB Name field in its Attributes inspector. This is the equivalent of specifying a nib name when you call init(nibName:bundle:).

When a nib contains a view controller, there is, as I hinted a moment ago, an additional way for it to obtain its view — and you’ve probably already guessed what it is. When you first drag a View Controller object into the canvas in the nib editor, it already contains a view, hooked up and ready to act as its main view! The view controller, in fact, is portrayed in the canvas more or less as if it were this view. Thus, using the nib editor we can design the view controller’s main view’s interface in the view controller itself. Let’s try it:

Build and run. The interface you designed inside the view object inside the view controller object in Main.xib appears in the running app.

If you’ve ever used a storyboard, it will not have escaped your attention that the .xib file we constructed in the previous section, consisting of a view controller directly containing its view, looks a lot like a scene in a storyboard. That’s because, by default, this is the structure of a scene in a storyboard. Indeed, we are now ready to appreciate and understand how a storyboard works.

Each scene in a .storyboard file is rather like a .xib file containing a view controller nib object. A scene’s view controller is instantiated only when needed; the underlying mechanism is that the scene’s view controller is stored in a nib file in the built app, inside the .storyboardc bundle, and this nib file is loaded on demand and the view controller is instantiated from it, as we did in the previous section.

Moreover, by default, the view controller in a scene in a .storyboard file comes equipped with a view, which appears inside it in the canvas. You design the view and its subviews in the nib editor. When the app is built, each view controller’s view goes into a separate nib file, inside the .storyboardc bundle, and the view controller, once instantiated, loads its view from that nib file lazily, exactly as we did earlier.

In this way, a storyboard embodies the very same mechanisms we’ve already explored through .xib files. Even though a storyboard may appear, in the nib editor, to contain many view controllers and their main views, each view controller and each main view constitutes an individual nib, which is loaded on demand, when needed by the running app, just as if we had configured the project with multiple .xib files. Thus a storyboard combines the memory management advantages of .xib files, which are not loaded until they’re needed, and can be loaded multiple times to give additional instances of the same nib objects, with the convenience to you 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 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, or even (if all of that fails) by creating a generic UIView.

The Xcode app templates start with a single main storyboard called Main.storyboard, which is designated the app’s main storyboard by the Info.plist key “Main storyboard file base name” (UIMainStoryboardFile). Therefore, 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.

If you add segues to your storyboard, then when one of those segues is performed — which can be configured to happen automatically in response to the user tapping an interface object — the destination view controller is automatically instantiated. In this way it is perfectly possible for a single storyboard to be the source of every view controller that your app will ever instantiate, and for all of that instantiation to take place automatically.

That doesn’t mean, however, that an app’s interface must be configured as a single monolithic main storyboard. It is perfectly possible to use a main storyboard for some view controllers and to instantiate other view controllers in code (perhaps getting their views from corresponding .xib files). You can also have different storyboards containing different view controllers. In Xcode 7, using multiple storyboards is easier than ever — you no longer have to load your ancillary storyboards manually, because a segue in one storyboard can lead through a storyboard reference to a view controller in another storyboard, which will be loaded automatically. (I’ll discuss storyboard references later in this chapter.)

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. With a storyboard instance in hand, a view controller can be instantiated from that storyboard in one of four ways:

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

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: for a storyboard, select the view controller (for a .xib file, select the top-level view) and choose a specific device from the Size pop-up menu under Simulated Metrics at the top of the Attributes inspector. You can also specify an orientation, as well as the presence or absence of interface elements that can affect layout (status bar, top bar, bottom bar).

But don’t forget that the specific size you see in the nib still may not reflect runtime reality. Suppose you design the interface for a view controller’s view sized like an iPhone 4s; then when the app loads on an iPhone 5, or one of the two iPhone 6 models, the view is a different size, and the interface as designed isn’t the interface you actually see. The Interface Builder Preview feature can be a big help here, allowing you to view your interface laid out for multiple devices simultaneously.

From this point of view, Xcode’s “Use Size Classes” option is a boon (see Chapter 1). By default, it shows a view controller’s main view as a square — a neutral shape that will never be encountered in real life. This serves as a reminder that the interface you are designing must adapt to a variety of real sizes when the app runs.

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 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 position of these guide objects moves automatically at runtime to reflect the view’s environment:

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 moves. Such constraints are easy to form in the nib editor — they are the default. When you’re using the new iOS 9 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. Note that viewDidLoad is too early to obtain a meaningful value; the earliest coherent opportunity is probably viewWillLayoutSubviews (I’ll discuss this event later). New in iOS 9, if you are constructing a constraint relative to the height of a layout guide, you can use its heightAnchor property.

var hide = false
override func prefersStatusBarHidden() -> Bool {
    return self.hide
}
@IBAction func doButton(sender: AnyObject) {
    self.hide = !self.hide
    UIView.animateWithDuration(0.4, animations: {
        self.setNeedsStatusBarAppearanceUpdate()
        self.view.layoutIfNeeded()
    })
}

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; new in iOS 9, they are associated also with iPad multitasking (Chapter 9):

(I’ll describe the use of the transitionCoordinator: parameter later in this chapter.)

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

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

There is no guarantee that any of these events, if sent, will be sent exactly once.

Your app can rotate, moving its top to correspond to a different edge of the device’s screen. In iOS 7 and before, this rotation was something of an illusion: the window remained pinned to the screen, and rotation was a matter of applying a transform to the root view and changing the bounds size to match the new orientation. In iOS 8 and later, however, the app really does rotate. Rotation expresses itself in two ways:

There are two complementary uses for rotation:

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. My view controller views often look best in just one orientation (or one pair of opposed orientations, 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, especially because it’s a phone. (The iPod touch isn’t a phone, but the same argument works by analogy.)

On the other hand, Apple would prefer iPad apps to rotate to at least two opposed orientations (such as landscape with the button on the right and landscape with the button on the left), and preferably to all four possible orientations, so that the user isn’t restricted in how the device is held.

It’s fairly 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 func supportedInterfaceOrientations()
    -> UIInterfaceOrientationMask {
        return .Portrait
}

let orientation = UIDevice.currentDevice().orientation

override func viewDidLoad() {
    super.viewDidLoad()
    let square = UIView(frame:CGRectMake(0,0,10,10))
    square.backgroundColor = UIColor.blackColor()
    square.center = CGPointMake(self.view.bounds.midX,5) // top center?
    self.view.addSubview(square)
}

override func viewDidLoad() {
    super.viewDidLoad()
    let square = UIView(frame:CGRectMake(0,0,10,10))
    square.backgroundColor = UIColor.blackColor()
    square.center = CGPointMake(self.view.bounds.midX,5)
    square.autoresizingMask =
        [.FlexibleLeftMargin, .FlexibleRightMargin, .FlexibleBottomMargin]
    self.view.addSubview(square)
}

override func viewDidLoad() {
    super.viewDidLoad()
    let square = UIView()
    square.backgroundColor = UIColor.blackColor()
    self.view.addSubview(square)
    square.translatesAutoresizingMaskIntoConstraints = false
    let side : CGFloat = 10
    var con = [NSLayoutConstraint]()
    con.appendContentsOf([
        square.widthAnchor.constraintEqualToConstant(side),
        square.centerXAnchor.constraintEqualToAnchor(self.view.centerXAnchor)
    ])
    con.appendContentsOf(
        NSLayoutConstraint.constraintsWithVisualFormat("V:|[square(side)]",
            options:[], metrics:["side":side],
            views:["square":square]))
    NSLayoutConstraint.activateConstraints(con)
}

var viewInitializationDone = false
override func viewWillLayoutSubviews() {
    if !self.viewInitializationDone {
        self.viewInitializationDone = true // ensure we do this just once
        // perform initializations here
    }
}

lazy var greenRect : UIView = self.makeGreenRect()
func makeGreenRect() -> UIView {
    var f = self.view.bounds
    if self.traitCollection.verticalSizeClass != .Compact {
        (f.size.width, f.size.height) = (f.size.height, f.size.width)
    }
    f.size.width /= 3.0
    f.origin.x = -f.size.width
    let gr = UIView(frame:f)
    gr.backgroundColor = UIColor.greenColor()
    return gr
}
override func willTransitionToTraitCollection(
    newCollection: UITraitCollection,
    withTransitionCoordinator coordinator:
    UIViewControllerTransitionCoordinator) {
        super.willTransitionToTraitCollection(newCollection,
            withTransitionCoordinator: coordinator)
        let v = self.greenRect
        var newFrameOriginX = v.frame.origin.x
        if newCollection.verticalSizeClass == .Compact { // landscape
            if v.superview == nil {
                self.view.addSubview(v)
                newFrameOriginX = 0
            }
        } else { // portrait
            if v.superview != nil {
                newFrameOriginX = -v.frame.size.width
            }
        }
        coordinator.animateAlongsideTransition({
            _ in
            v.frame.origin.x = newFrameOriginX // animate!
            }, completion: {
                _ in
                if newCollection.verticalSizeClass != .Compact {
                    self.greenRect.removeFromSuperview()
                }
            })
}

var greenRectConstraintsOnscreen : [NSLayoutConstraint]!
var greenRectConstraintsOffscreen : [NSLayoutConstraint]!
override func viewDidLoad() {
    super.viewDidLoad()
    let gr = UIView()
    gr.translatesAutoresizingMaskIntoConstraints = false
    gr.backgroundColor = UIColor.greenColor()
    self.view.addSubview(gr)
    var c = [NSLayoutConstraint]()
    // "g.r. is pinned to top and bottom of superview"
    c.appendContentsOf(
        NSLayoutConstraint.constraintsWithVisualFormat("V:|[gr]|",
            options:[], metrics:nil, views:["gr":gr]))
    // "g.r. is 1/3 the width of superview"
    c.append(
        gr.widthAnchor.constraintEqualToAnchor(self.view.widthAnchor,
            multiplier: 1.0/3.0))
    // "onscreen, g.r.'s left is pinned to superview's left"
    let marrOn =
        NSLayoutConstraint.constraintsWithVisualFormat("H:|[gr]",
            options:[], metrics:nil, views:["gr":gr])
    // "offscreen, g.r.'s right is pinned to superview's left"
    let marrOff = [
        gr.trailingAnchor.constraintEqualToAnchor(self.view.leadingAnchor)!
    ]
    self.greenRectConstraintsOnscreen = marrOn
    self.greenRectConstraintsOffscreen = marrOff
    // start out offscreen!
    c.appendContentsOf(marrOff)
    NSLayoutConstraint.activateConstraints(c)
}
override func willTransitionToTraitCollection(
    newCollection: UITraitCollection,
    withTransitionCoordinator coordinator:
    UIViewControllerTransitionCoordinator) {
        super.willTransitionToTraitCollection(newCollection,
            withTransitionCoordinator: coordinator)
        NSLayoutConstraint.deactivateConstraints(
            self.greenRectConstraintsOnscreen)
        NSLayoutConstraint.deactivateConstraints(
            self.greenRectConstraintsOffscreen)
        if newCollection.verticalSizeClass == .Compact {
            NSLayoutConstraint.activateConstraints(
                self.greenRectConstraintsOnscreen)
        } else {
            NSLayoutConstraint.activateConstraints(
                self.greenRectConstraintsOffscreen)
        }
    }

override func viewDidLoad() {
    super.viewDidLoad()
    let gr = UIView()
    // ... create constraints as before ...
    self.adjustInterfaceForSize(self.view.bounds.size)
}
override func viewWillTransitionToSize(size: CGSize,
    withTransitionCoordinator coordinator:
    UIViewControllerTransitionCoordinator) {
        super.viewWillTransitionToSize(size,
            withTransitionCoordinator: coordinator)
        if size != self.view.bounds.size {
            self.adjustInterfaceForSize(size)
        }
}
func adjustInterfaceForSize(size: CGSize) {
    NSLayoutConstraint.deactivateConstraints(
        self.greenRectConstraintsOnscreen)
    NSLayoutConstraint.deactivateConstraints(
        self.greenRectConstraintsOffscreen)
    if size.width > size.height {
        NSLayoutConstraint.activateConstraints(
            self.greenRectConstraintsOnscreen)
    } else {
        NSLayoutConstraint.activateConstraints(
            self.greenRectConstraintsOffscreen)
    }
}

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

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 block of code 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 presentViewController:animated:completion:. It will help if we distinguish three roles that view controllers can play in presenting a view controller:

The receiver of dismissViewControllerAnimated: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 view 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 presentViewController:animated:completion: to a view controller whose presentedViewController isn’t nil, nothing will happen and the completion handler 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 dismissViewControllerAnimated: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 dismissViewControllerAnimated: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: handler 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 presentViewController:animated:completion: for you, whereas I want you to call it yourself.

So start with an iPhone project made from the Single View Application 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:

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:AnyObject?) {
    self.presentingViewController!.dismissViewControllerAnimated(
        true, completion: nil)
}

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.

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:

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

Indeed, if you’re calling presentViewController:animated:completion: explicitly like this, you might even give your SecondViewController 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:

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 example to embody this architecture. First, edit SecondViewController.swift to look like this:

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

It is now ViewController’s job to adopt the SecondViewControllerDelegate protocol, and to set itself as the SecondViewController’s delegate. 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:AnyObject?) {
        let svc = SecondViewController(
            nibName: "SecondViewController", bundle: nil)
        svc.data = "This is very important data!"
        svc.delegate = self // *
        self.presentViewController(svc, animated:true, completion:nil)
    }
    func acceptData(data:AnyObject!) {
        // do something with data here
        self.dismissViewControllerAnimated(true, completion: nil)
    }
}

That is a perfectly satisfactory implementation, and we could stop at this point. For completeness, I’ll just show a possible variation. You 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. Surely the presented view controller should hand back any data and should then dismiss itself (as in the preceding section). 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. First, edit ViewController’s acceptData: so that it accepts the data and no more (it no longer performs the dismissal). Second, 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 acceptData: 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 calling isBeingDismissed. Here is what SecondViewController looks like now:

protocol SecondViewControllerDelegate : class {
    func acceptData(data:AnyObject!)
}
class SecondViewController : UIViewController {
    var data : AnyObject?
    weak var delegate : SecondViewControllerDelegate?
    @IBAction func doDismiss(sender:AnyObject?) {
        self.presentingViewController!.dismissViewControllerAnimated(
            true, completion: nil)
    }
    override func viewWillDisappear(animated: Bool) {
        super.viewWillDisappear(animated)
        if self.isBeingDismissed() {
            self.delegate?.acceptData("Even more important data!")
        }
    }
}

If you’re using a storyboard, 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 prepareForSegue: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 prepareForSegue:sender:. I’ll give more details later in this chapter.

When a view is presented and later when it is dismissed, a simple animation can be performed, according to whether the animated: parameter of the corresponding method is true. There are a few different built-in animation styles (modal transition styles) to choose from.

Your choice of built-in animation style is not passed as a parameter when presenting or dismissing a view controller; rather, it is attached beforehand to a presented view controller as its modalTransitionStyle property. This value can be set in code or in the nib editor. Your choices (UIModalTransitionStyle) are:

By default, the presented view controller’s view occupies the entire screen, completely replacing that of the presenting view controller. But you can choose from a few other built-in options expressing how the presented view controller’s view should cover the screen (modal presentation styles).

To choose a presentation style, set the presented view controller’s modalPresentationStyle property. This value can be set in code or in the nib editor. Your choices (UIModalPresentationStyle) are:

When the presented view controller’s modalPresentationStyle is .CurrentContext or .OverCurrentContext, a decision has to be made by the runtime as to what view controller should be the presenting view controller. This will determine what view will be replaced or covered by the presented view controller’s view. The decision involves another UIViewController property, definesPresentationContext (a Bool), and possibly still another UIViewController property, providesPresentationContextTransitionStyle. Here’s how the decision operates:

To illustrate, I need a parent–child view controller arrangement to work with. This chapter hasn’t yet discussed any parent view controllers in detail, but the simplest is UITabBarController, which I discuss in the next section, and it’s easy to create a working app with a UITabBarController-based interface, so that’s the example I’ll use.

Start with the Tabbed Application project template. As in the previous example, I want us to create and present the presented view controller manually, rather than letting the storyboard do it automatically; so make a new view controller class with an accompanying .xib file, to use as a presented view controller — call it ExtraViewController. In ExtraViewController.xib, give the view a distinctive background color, so you’ll recognize it when it appears.

In the storyboard, put a button in the First View Controller view, and connect it to an action method in FirstViewController.swift that summons the new view controller as a presented view controller:

@IBAction func doPresent(sender:AnyObject?) {
    let vc = ExtraViewController(nibName: "ExtraViewController", bundle: nil)
    self.presentViewController(vc, animated: true, completion: nil)
}

Run the project and tap the button. Observe that the presented view controller’s view occupies the entire interface, covering even the tab bar; it replaces the root view, because the presentation style is .FullScreen. The presenting view controller is the root view controller, which is the UITabBarController.

Now change the code to look like this:

@IBAction func doPresent(sender:AnyObject?) {
    let vc = ExtraViewController(nibName: "ExtraViewController", bundle: nil)
    self.definesPresentationContext = true // *
    vc.modalPresentationStyle = .CurrentContext // *
    self.presentViewController(vc, animated: true, completion: nil)
}

Run the project and tap the button. The presented view controller’s view replaces only the first view controller’s view; the tab bar remains, and you can switch back and forth between the tab bar’s first and second views even while the first view remains covered by the presented view. That’s because the presented view controller’s modalPresentationStyle is .CurrentContext, and definesPresentationContext is true in FirstViewController, which is the original presenter. Thus the search for a context stops in FirstViewController, which thus becomes the presenting view controller — meaning that the presented view replaces FirstViewController’s view instead of the root view.

We can also override the presented view controller’s transition animation through the modalTransitionStyle property of the presenting view controller:

@IBAction func doPresent(sender:AnyObject?) {
    let vc = ExtraViewController(nibName: "ExtraViewController", bundle: nil)
    self.definesPresentationContext = true
    self.providesPresentationContextTransitionStyle = true // *
    self.modalTransitionStyle = .CoverVertical // *
    vc.modalPresentationStyle = .CurrentContext
    vc.modalTransitionStyle = .FlipHorizontal // this will be overridden
    self.presentViewController(vc, animated: true, completion: nil)
}

Because the presenting view controller’s providesPresentationContextTransitionStyle is true, the transition uses the .CoverVertical animation belonging to the presenting view controller, rather than the .FlipHorizontal animation of the presented view controller.

When a view controller is presented, if its presentation style is not .FullScreen, a question arises of whether its status bar methods (prefersStatusBarHidden and preferredStatusBarStyle) should be consulted. By default, the answer is no, because this view controller is not the top-level view controller. To make the answer be yes, set this view controller’s modalPresentationCapturesStatusBarAppearance to true.

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:

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:

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:AnyObject?) {
        let svc = SecondViewController(
            nibName: "SecondViewController", bundle: nil)
        svc.modalPresentationStyle = .FormSheet
        svc.presentationController!.delegate = self // *
        self.presentViewController(svc, animated:true, completion:nil)
    }
    func adaptivePresentationStyleForPresentationController(
        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:

extension ViewController : UIAdaptivePresentationControllerDelegate {
    // ... same as before ...
    func presentationController(controller: UIPresentationController,
        viewControllerForAdaptivePresentationStyle
        style: UIModalPresentationStyle) -> UIViewController? {
            let newvc = ThirdViewController(
                nibName: "ThirdViewController", 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.

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 method is called before supportedInterfaceOrientations, and should return a single UIInterfaceOrientation (not a bitmask). For example:

override func preferredInterfaceOrientationForPresentation()
    -> UIInterfaceOrientation {
        return .LandscapeLeft
}

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 enabled.

There are two ways to make a tab bar item:

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.

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 parentViewController 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:

var tabBarController = UITabBarController()
func application(application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [NSObject:AnyObject]?)
    -> Bool {
        self.window = UIWindow()
        let viewController1 = GameBoardController()
        let viewController2 = UINavigationController(
            rootViewController:SettingsController())
        self.tabBarController.viewControllers =
            [viewController1, viewController2]
        self.tabBarController.selectedIndex = 0
        self.tabBarController.delegate = self
        self.window!.rootViewController = self.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.png")
    self.title = "Game"
}

In the tab bar, the image "game.png" is displayed as is, not as a template. I don’t have to call imageWithRenderingMode: because the rendering mode is set directly in the asset catalog that holds the image.

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 hidden to true and take charge of switching between children yourself — though if that’s your desired architecture, a UIPageViewController without animation or gesture response 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 NSUserDefaults 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 Application template.

The buttons 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:

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 however it likes.

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 enabled 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:

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.

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):

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

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, the titleView is a progress view (UIProgressView, Chapter 12) that needs updating every second, and the right bar button should be either the system Play button or the system Pause button, depending on whether music from the library is playing, paused, or stopped. 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 as! UIProgressView
if let item = self.nowPlayingItem {
    let current = self.mp.currentPlaybackTime
    let total = item.valueForProperty(
        MPMediaItemPropertyPlaybackDuration) as! Double
    prog.progress = Float(current / total)
} else {
    prog.progress = 0
}
// change the bar button
let whichButton : UIBarButtonSystemItem?
switch self.mp.currentPlaybackRate {
case 0..<0.1:
    whichButton = .Play
case 0.1...1.0:
    whichButton = .Pause
default:
    whichButton = nil
}
if let which = whichButton {
    let bb = UIBarButtonItem(barButtonSystemItem: which,
        target: self, action: "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.

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 parentViewController 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()
self.navigationController!.pushViewController(svc, animated: true)

There is usually no need to worry about going back; when the user taps the back button to navigate back, the runtime will call popViewControllerAnimated: 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: showViewController:sender:. This 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 generates a presented view controller 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 popViewControllerAnimated:, 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 popViewControllerAnimated: 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 popToRootViewControllerAnimated:. 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 init(nibName:bundle:) — or init(coder:) or awakeFromNib, if appropriate — 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:

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.

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 Application template. Alternatively, start with the Single View Application 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 Application 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.

Let’s start with the base case, where the custom animation is not interactive. Configuring your custom animation requires three steps:

The implementation of animateTransition: works, in general, as follows:

To illustrate, consider the transition between two child view controllers of a tab bar controller. By default, this transition isn’t animated; one view just replaces the other. Let’s animate the transition.

One obvious 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.

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 now be sent a message whenever the tab bar controller is about to change view controllers. That message is:

We must implement this method to return an animation controller, namely, some object implementing UIViewControllerAnimatedTransitioning. In this case, to keep things simple, I’ll return self. Here we go:

func tabBarController(tabBarController: UITabBarController,
    animationControllerForTransitionFromViewController
    fromVC: UIViewController,
    toViewController toVC: UIViewController)
    -> UIViewControllerAnimatedTransitioning? {
        return self
}

(There is no particular reason why the animation controller should be self; it 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. We know, in real time, what’s about to happen, because we receive the tab bar controller and both child view controllers as parameters. Thus we could readily provide a different animation controller under different circumstances, 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(
    transitionContext: UIViewControllerContextTransitioning?)
    -> NSTimeInterval {
        return 0.4
}

(Again, the value returned needn’t be the same every time this method is called. The transition context has arrived as parameter, and we could query it to identify the two view controllers involved and make a decision based on that. But make sure that the value you return here is indeed the duration of the animation you’ll perform in animateTransition:.)

Finally, we come to animateTransition: itself:

func animateTransition(
    transitionContext: UIViewControllerContextTransitioning) {
        // ...
}

Once more, simply perform the steps in order. First, query the transition context. This code is practically boilerplate for any custom view controller transition animation:

let vc1 = transitionContext.viewControllerForKey(
    UITransitionContextFromViewControllerKey)!
let vc2 = transitionContext.viewControllerForKey(
    UITransitionContextToViewControllerKey)!
let con = transitionContext.containerView()!
let r1start = transitionContext.initialFrameForViewController(vc1)
let r2end = transitionContext.finalFrameForViewController(vc2)
let v1 = transitionContext.viewForKey(UITransitionContextFromViewKey)!
let v2 = transitionContext.viewForKey(UITransitionContextToViewKey)!

We have the view controllers and their views, and the initial frame of the outgoing view and the destination frame of the incoming view. Now, to prepare for our intended animation, we want to calculate the converse, namely 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 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!.indexOf(vc1)!
let ix2 = tbc.viewControllers!.indexOf(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

We are now ready for the second step: put the second view controller’s view into the container view at its initial frame, and perform the animation. The end of the animation is also the moment to perform the all-important third step, namely to call completeTransition: to signal that our part has been played and our hands are off the views:

v2.frame = r2start
con.addSubview(v2)
UIView.animateWithDuration(0.4, animations: {
    v1.frame = r1end
    v2.frame = r2end
    }, completion: {
        _ in
        transitionContext.completeTransition(true)
    })

That’s all there is to it. Of course, that wasn’t a very complex animation; but an animation needn’t be complex to be interesting, significant, and helpful to the user. 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 handler.

A custom transition for a navigation controller is similar to a custom transition for a tab bar controller, so I don’t need to give a separate example. The only slight difference lies in the name of the navigation controller delegate method that will be called to discover whether there’s an animation controller:

The operation: parameter allows you to distinguish a push from a pop.

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 two ways to write an interactive custom transition animation. In both cases, we’re going to need an interaction controller, namely an object that conforms to the UIViewControllerInteractiveTransitioning protocol. The two ways of writing the code correspond to the two ways of supplying this object:

let sep = UIScreenEdgePanGestureRecognizer(target:self, action:"pan:")
sep.edges = UIRectEdge.Right
tbc.view.addGestureRecognizer(sep)
sep.delegate = self
self.rightEdger = sep
let sep2 = UIScreenEdgePanGestureRecognizer(target:self, action:"pan:")
sep2.edges = UIRectEdge.Left
tbc.view.addGestureRecognizer(sep2)
sep2.delegate = self
self.leftEdger = sep2

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

func pan(g:UIScreenEdgePanGestureRecognizer) {
    let v = g.view!
    let tbc = self.window!.rootViewController as! UITabBarController
    let delta = g.translationInView(v)
    let percent = fabs(delta.x/v.bounds.size.width)
    switch g.state {
        // ... to be continued ...
    }
}

case .Began:
    self.inter = UIPercentDrivenInteractiveTransition()
    self.interacting = true
    if g == self.rightEdger {
        tbc.selectedIndex = tbc.selectedIndex + 1
    } else {
        tbc.selectedIndex = tbc.selectedIndex - 1
    }

func tabBarController(tabBarController: UITabBarController,
    animationControllerForTransitionFromViewController
    fromVC: UIViewController,
    toViewController toVC: UIViewController)
    -> UIViewControllerAnimatedTransitioning? {
        return self
}

func tabBarController(tabBarController: UITabBarController,
    interactionControllerForAnimationController
    animationController: UIViewControllerAnimatedTransitioning)
    -> UIViewControllerInteractiveTransitioning? {
        let result : UIViewControllerInteractiveTransitioning? =
            self.interacting ? self.inter : nil
        return result
}

case .Changed:
    self.inter.updateInteractiveTransition(percent)

case .Ended:
    if percent > 0.5 {
        self.inter.finishInteractiveTransition()
    } else {
        self.inter.cancelInteractiveTransition()
    }
    self.interacting = false

UIView.animateWithDuration(0.4, delay:0, options:opts, animations: {
    v1.frame = r1end
    v2.frame = r2end
    }, completion: {
        _ in
        let cancelled = transitionContext.transitionWasCancelled()
        transitionContext.completeTransition(!cancelled)
    })

func startInteractiveTransition(
    transitionContext: UIViewControllerContextTransitioning){
    // store transition context so the gesture recognizer can get at it
    self.context = transitionContext
    // ... set up initial conditions ...
    // ... store any additional instance variables ...
    self.r1end = r1end
    self.r2start = r2start
}

case .Changed:
    // ... calculate progress (percent)
    // ... put views into position corresponding to current "frame" ...
    // ... and finally, notify the transition context
    v1.frame = // whatever
    v2.frame = // whatever
    tc.updateInteractiveTransition(percent)

case .Ended:
    if percent > 0.5 {
        UIView.animateWithDuration(0.2, animations:{
            v1.frame = self.r1end
            v2.frame = r2end
            }, completion: { _ in
                tc.finishInteractiveTransition()
                tc.completeTransition(true)
        })
    }
    else {
        UIView.animateWithDuration(0.2, animations:{
            v1.frame = r1start
            v2.frame = self.r2start
            }, completion: { _ in
                tc.cancelInteractiveTransition()
                tc.completeTransition(false)
        })
    }

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 until dismissal; 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 may require some extra effort on your part, but in fact it also simplifies considerably the task of customizing the animation itself.

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

func animationControllerForPresentedController(
    presented: UIViewController,
    presentingController presenting: UIViewController,
    sourceController source: UIViewController)
    -> UIViewControllerAnimatedTransitioning? {
        return self
}

func transitionDuration(
    transitionContext: UIViewControllerContextTransitioning?)
     -> NSTimeInterval {
        return 0.4
}
func animateTransition(
    transitionContext: UIViewControllerContextTransitioning) {
        let vc2 = transitionContext.viewControllerForKey(
            UITransitionContextToViewControllerKey)
        let con = transitionContext.containerView()!
        let r2end = transitionContext.finalFrameForViewController(vc2!)
        let v2 = transitionContext.viewForKey(UITransitionContextToViewKey)!
        v2.frame = r2end
        v2.transform = CGAffineTransformMakeScale(0.1, 0.1)
        v2.alpha = 0
        con.addSubview(v2)
        UIView.animateWithDuration(0.4, animations: {
            v2.alpha = 1
            v2.transform = CGAffineTransformIdentity
            }, completion: {
                _ in
                transitionContext.completeTransition(true)
            })
}

let v1 = transitionContext.viewForKey(UITransitionContextFromViewKey)
let v2 = transitionContext.viewForKey(UITransitionContextToViewKey)
if let v2 = v2 { // presenting
    // ...
} else if let v1 = v1 {
    // ...
}

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

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

override func 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, atIndex: 0)
    shadow.autoresizingMask = [.FlexibleWidth, .FlexibleHeight]
}

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

override func 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
}

A UIViewController, as I mentioned in the previous section, has a transitionCoordinator method, which yields an object adopting the UIViewControllerTransitionCoordinator protocol. This object, the transition coordinator, is a kind of wrapper around the current transition context, and also adopts the UIViewControllerTransitionCoordinatorContext protocol, just like 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:

To create a UIPageViewController, use its designated initializer:

Here’s what the parameters mean:

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:

Here’s what the parameters mean:

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, along with three eponymous image files in my app bundle 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 the 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: "Pep", 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.lowercaseString).jpg")
}

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, options: nil)
// give it an initial page
let page = Pep(pepBoy: self.pep[0])
pvc.setViewControllers(
    [page], direction: .Forward, animated: false, completion: nil)
// give it a data source
pvc.dataSource = self
// puts 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.

We now have a page view controller’s view in our interface, itself containing and displaying the view of a Pep view controller that is its child. In theory, we also 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:

The job of those methods is to return the requested successive view controller. You’ll need a strategy for doing that; the strategy you devise 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(pageViewController: UIPageViewController,
    viewControllerAfterViewController viewController: UIViewController)
    -> UIViewController? {
        let boy = (viewController as! Pep).boy
        let ix = self.pep.indexOf(boy)! + 1
        if ix >= self.pep.count {
            return nil
        }
        return Pep(pepBoy: self.pep[ix])
}

You can also, at any time, call setViewControllers:... to change programmatically what page is being displayed, possibly with animation.

func presentationCountForPageViewController(
    pageViewController: UIPageViewController) -> Int {
        return self.pep.count
}
func presentationIndexForPageViewController(
    pvc: UIPageViewController) -> Int {
        let page = pvc.viewControllers![0] as! Pep
        let boy = page.boy
        return self.pep.indexOf(boy)!
}

let proxy = UIPageControl.appearance()
proxy.pageIndicatorTintColor = UIColor.redColor().colorWithAlphaComponent(0.6)
proxy.currentPageIndicatorTintColor = UIColor.redColor()
proxy.backgroundColor = UIColor.yellowColor()

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

@IBAction func tap (sender: UIGestureRecognizer?) {
    NSNotificationCenter.defaultCenter().postNotificationName(
        "tap", object: sender)
}

let g = n.object as! UIGestureRecognizer
let which = g.view!.tag
let vc0 = pvc.viewControllers![0]
let vc = (which == 0 ?
    self.pageViewController(pvc, viewControllerBeforeViewController: vc0) :
    self.pageViewController(pvc, viewControllerAfterViewController: vc0))
if vc == nil {
    return
}
let dir : UIPageViewControllerNavigationDirection =
    which == 0 ? .Reverse : .Forward
UIApplication.sharedApplication().beginIgnoringInteractionEvents()
pvc.setViewControllers([vc!], direction: dir, animated: true, completion: {
    _ in
    UIApplication.sharedApplication().endIgnoringInteractionEvents()
})

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 doubleSided 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 doubleSided 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.

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:

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

This is a clumsy and rather confusing dance. The underlying reason for it is that a child view controller must always receive willMoveToParentViewController: followed by didMoveToParentViewController: (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:

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.

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
vc.view.frame = // whatever, or use constraints
// insert view into interface between "will" and "did"
self.view.addSubview(vc.view)
// when we call add, we must call "did" afterwards
vc.didMoveToParentViewController(self)

The next question is how 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 is for the parent view controller to send itself this message:

That method manages the stages in good order, adding one child view controller’s view to the interface before the transition and removing the other child view controller’s view 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:

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
// note: when we call remove, we must call "will" (with nil) beforehand
fromvc.willMoveToParentViewController(nil)
// then perform the transition
self.transitionFromViewController(fromvc,
    toViewController:tovc,
    duration:0.4,
    options:.TransitionFlipFromLeft,
    animations:nil,
    completion:{
        _ in
        // finally, finish up
        // note: when we call add, we must call "did" afterwards
        tovc.didMoveToParentViewController(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 transitionFromViewController:... is too soon, as the new child view controller’s view is not yet in the interface. The completion: block 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: block 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
// note: when we call remove, we must call "will" (with nil) beforehand
fromvc.willMoveToParentViewController(nil)
// then perform the transition
self.transitionFromViewController(fromvc,
    toViewController:tovc,
    duration:0.4,
    options:.TransitionFlipFromLeft,
    animations: {
        tovc.view.translatesAutoresizingMaskIntoConstraints = false
        // ... configure tovc.view constraints here ...
    },
    completion:{
        _ in
        // finally, finish up
        // note: when we call add, we must call "did" afterwards
        tovc.didMoveToParentViewController(self)
        fromvc.removeFromParentViewController() // "did" called for us
    })

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

If the built-in transition animations are unsuitable, you can set the options: argument to .None and provide your own animation in the animations: block, 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
UIGraphicsBeginImageContextWithOptions(tovc.view.bounds.size, true, 0)
tovc.view.layer.renderInContext(UIGraphicsGetCurrentContext()!)
let im = UIGraphicsGetImageFromCurrentImageContext()
UIGraphicsEndImageContext()
let iv = UIImageView(image:im)
iv.frame = CGRectZero
self.view.addSubview(iv)
tovc.view.alpha = 0
// must have both as children before we can transition between them
self.addChildViewController(tovc) // "will" called for us
// note: when we call remove, we must call "will" (with nil) beforehand
fromvc.willMoveToParentViewController(nil)
// then perform the transition
self.transitionFromViewController(fromvc,
    toViewController:tovc,
    duration:0.4,
    options:.TransitionNone,
    animations: {
        iv.frame = tovc.view.frame // animate bounds change
        // ... configure tovc.view constraints here ...
    },
    completion:{
        _ in
        tovc.view.alpha = 1
        iv.removeFromSuperview()
        // finally, finish up
        // note: when we call add, we must call "did" afterwards
        tovc.didMoveToParentViewController(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 implementing these methods (just as a UITabBarController does):

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:

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)
let tc = UITraitCollection(horizontalSizeClass: .Compact)
self.setOverrideTraitCollection(tc, forChildViewController: vc) // heh heh
vc.view.frame = // whatever
self.view.addSubview(vc.view)
vc.didMoveToParentViewController(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:

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:

If your parent view controller implements viewWillTransitionToSize:withTransitionCoordinator:, 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 sizeForChildContentContainer:withParentContainerSize: to return the new size.

A triggered segue (or simply segue), such as a push segue (show) or a modal segue (present modally), is a full-fledged object, an instance of UIStoryboardSegue (or your custom subclass thereof), 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.destinationViewController
        dest.modalPresentationStyle = .Custom
        dest.transitioningDelegate = self
        super.perform()
    }
}

extension MyCoolSegue: UIViewControllerTransitioningDelegate {
    func animationControllerForPresentedController(
        presented: UIViewController,
        presentingController presenting: UIViewController,
        sourceController source: UIViewController)
        -> UIViewControllerAnimatedTransitioning? {
            return self
    }
    func animationControllerForDismissedController(
        dismissed: UIViewController)
        -> UIViewControllerAnimatedTransitioning? {
            return self
    }
}

extension MyCoolSegue: UIViewControllerAnimatedTransitioning {
    func transitionDuration(
        transitionContext: UIViewControllerContextTransitioning?)
        -> NSTimeInterval {
            return 0.8
    }
    func animateTransition(transitionContext: UIViewControllerContextTransitioning) {
        let vc1 = transitionContext.viewControllerForKey(
            UITransitionContextFromViewControllerKey)!
        let vc2 = transitionContext.viewControllerForKey(
            UITransitionContextToViewControllerKey)!
        let con = transitionContext.containerView()!
        let r1start = transitionContext.initialFrameForViewController(vc1)
        let r2end = transitionContext.finalFrameForViewController(vc2)
        if let v2 = transitionContext.viewForKey(
            UITransitionContextToViewKey) {
                // ... provide presenting animation ...
        } else if let v1 = transitionContext.viewForKey(
            UITransitionContextFromViewKey) {
                // ... provide dismissing animation ...
        }
    }
}

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

As I mentioned earlier, 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:

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 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 didMoveToParentViewController: is called.

Despite its superficial resemblance to a relationship segue, 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. Nevertheless, 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 shouldPerformSegueWithIdentifier:sender: in the parent view controller to return false for this segue, and call performSegueWithIdentifier:sender: later when you do want the child view controller instantiated.

The parent view controller is sent prepareForSegue: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 been called, the child has been added to the parent’s childViewControllers, and the child’s view is inside the parent’s view.

Subsequently replacing one child view controller’s view with another in the interface will require that you call transitionFromViewController:... just as you would have done if a storyboard weren’t involved (as I described earlier in this chapter). Still, you can configure this through a storyboard as well, by using a custom segue and a UIStoryboardSegue subclass.

New in Xcode 7 and iOS 9, when you create a triggered segue in the storyboard, 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 view controller.

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

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 different storyboard. This allows you to organize your app’s interface into multiple storyboards. This 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.

This is a welcome and long-anticipated feature, which should make storyboards much more convenient to use.

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.

In a nutshell, you can’t 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 unwind methods known to this storyboard (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

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. The previous section contains a number of cases in point, and there are others. For example:

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. For example, if you do something in viewWillAppear: that needs to be cancelled or reversed in viewDidAppear:, you should also cancel or reverse it in viewWillDisappear:.

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 NSTimer 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: and 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).

A custom container (parent) view controller, as I explained earlier, must effectively send willMoveToParentViewController: and didMoveToParentViewController: 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 willTransitionToTraitCollection:... and viewWillTransitionToSize:.... By the same token, 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 implementing this method:

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? You must not call the UIViewController method transitionFromViewController:toViewController:...! It takes charge of sending the four events to the children itself, and it isn’t going to do so correctly in this situation. Instead, you must perform the transition animation directly. A minimal correct implementation might involve the UIView class method transitionFromView:toView:... (see Chapter 4). Here, you can and should call beginAppearanceTransition: and endAppearanceTransition yourself.

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)
fromvc.willMoveToParentViewController(nil)
fromvc.beginAppearanceTransition(false, animated:true) // *
tovc.beginAppearanceTransition(true, animated:true) // *
UIView.transitionFromView(fromvc.view,
    toView:tovc.view,
    duration:0.4,
    options:.TransitionFlipFromLeft,
    completion:{
        _ in
        tovc.endAppearanceTransition() // *
        fromvc.endAppearanceTransition() // *
        tovc.didMoveToParentViewController(self)
        fromvc.removeFromParentViewController()
})

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

(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 (at http://developer.apple.com/downloads) some debugging tools:

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.

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:

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):

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 Dismiss button.

We will now make this app implement state restoration:

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

Having everything done for us by the storyboard reveals nothing about what’s really happening. To learn more, let’s rewrite the example without a storyboard. Throw away the storyboard (and delete the Main Storyboard entry from the Info.plist) and implement the same architecture using code alone:

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

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

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

// PresentedViewController.m:
override func viewDidLoad() {
    super.viewDidLoad()
    // ... color view background, create button ...
}
func doDismiss(sender:AnyObject?) {
    self.dismissViewControllerAnimated(true, completion: nil)
}

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

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.

The restorationIdentifier serves as a guide during restoration as to what view controller is needed at each point in the view controller hierarchy. Any particular view controller instance, given its position in the view controller hierarchy, is uniquely identified by the sequence of restorationIdentifier values of all the view controllers (including itself) in the chain that leads to it. Those restorationIdentifier values, taken together and in sequence, constitute the identifier path for any given view controller instance.

Each identifier path is, in fact, merely an array of strings. In effect, the identifier paths are like a trail of breadcrumbs that you left behind as you created each view controller while the app was running, and that will now be used to identify each view controller again as the app launches.

For example, if we launch the app and press the Push button and then the Present button, then all four view controllers have been instantiated; those instances are identified as:

Observe that a view controller’s identifier path is not a record of the full story of how we got here. It’s just an identifier! The state-saving mechanism also saves a relational tree of identifiers. For example, if the app is suspended in the current situation, then the state-saving mechanism will record the true state of affairs, namely that the root view controller has two children and a presented view controller, along with their identifiers.

Now consider what the state restoration mechanism needs to do when the app has been suspended and killed, and comes back to life, from the situation I just described. We need to restore four view controllers; we know their identifiers and mutual relationships. State restoration doesn’t start until after application:willFinishLaunchingWithOptions:. So when the state restoration mechanism starts examining the situation, it discovers that the ["nav"] and ["nav", "root"] view controller instances have already been created! However, the view controller instances for ["nav", "second"] and ["nav", "presented"] must also be created now. The state restoration mechanism doesn’t know how to do that — so it’s going to ask your code for the instances.

But what code should it ask? One way of specifying this is for you to provide a restoration class for each view controller instance that is not restored by the time application:willFinishLaunchingWithOptions: returns. Here’s how you do that:

Let’s make our PresentedViewController and SecondViewController instances restorable. I’ll start with PresentedViewController. Our app can have two PresentedViewController instances (though not simultaneously) — the one created by RootViewController, and the one created by SecondViewController. Let’s start with the one created by RootViewController.

Since RootViewController creates and configures a PresentedViewController instance, it can reasonably act also as the restoration class for that instance. In its implementation of viewControllerWithRestorationIdentifierPath:coder:, RootViewController should then create and configure a PresentedViewController instance exactly as it was doing before we added state restoration to our app — except for putting it into the view controller hierarchy! The state restoration mechanism itself, remember, is responsible for assembling the view controller hierarchy; our job is merely to supply any needed view controller instances.

So RootViewController now must adopt UIViewControllerRestoration, and will contain this code:

func doPresent(sender:AnyObject?) {
    let pvc = PresentedViewController()
    pvc.restorationIdentifier = "presented"
    pvc.restorationClass = self.dynamicType // *
    self.presentViewController(pvc, animated:true, completion:nil)
}
class func viewControllerWithRestorationIdentifierPath(ip: [AnyObject],
    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
}

You can see what I mean when I say that the restoration class must do exactly what it was doing before state restoration was added. Clearly this situation has led to some annoying code duplication, so let’s factor out the common code. In doing so, we must bear in mind that doPresent: is an instance method, whereas viewControllerWithRestorationIdentifierPath:coder: is a class method; our factored-out code must therefore be a class method, so that they can both call it:

class func makePresentedViewController () -> UIViewController {
    let pvc = PresentedViewController()
    pvc.restorationIdentifier = "presented"
    pvc.restorationClass = self
    return pvc
}
func doPresent(sender:AnyObject?) {
    let pvc = self.dynamicType.makePresentedViewController()
    self.presentViewController(pvc, animated:true, completion:nil)
}
class func viewControllerWithRestorationIdentifierPath(ip: [AnyObject],
    coder: NSCoder) -> UIViewController? {
        var vc : UIViewController? = nil
        let last = ip.last as! String
        switch last {
        case "presented":
            vc = self.makePresentedViewController()
        default: break
        }
        return vc
}

The structure of our viewControllerWithRestorationIdentifierPath:coder: is typical. We test the identifier path — usually, it’s sufficient to examine its last element — and return the corresponding view controller; ultimately, we are also prepared to return nil, in case we are called with an identifier path we can’t interpret. We can also return nil deliberately, to tell the restoration mechanism, “Go no further; don’t restore the view controller you’re asking for here, or any view controller further down the same path.”

Continuing in the same vein, we expand RootViewController still further to make it also the restoration class for SecondViewController, and SecondViewController can make itself the restoration class for the PresentedViewController instance that it creates. There’s no conflict in the notion that both RootViewController and SecondViewController can fulfill the role of PresentedViewController restoration class, as we’re talking about two different PresentedViewController instances. The app now performs state saving and restoration correctly! (The details are left as an exercise for the reader.)

I said earlier that the state restoration mechanism can ask your code for needed instances in two ways. The second way is that you implement this method in your app delegate:

If you implement this method, it will be called for every view controller that doesn’t have a restoration class. This works in a storyboard-based app, and thus is a chance for you to intervene and prevent the restoration of a particular view controller on a particular occasion (by returning nil). Be prepared to receive identifier paths for an existing view controller! If that happens, return the existing view controller — don’t make a new one.

For example, if we were to implement application:viewControllerWithRestorationIdentifierPath:coder: in the example app I’ve been describing, it would be called for ["nav"] and for ["nav", "root"], because those view controllers have no restoration class. But we needn’t, and we mustn’t, create a new view controller; those view controller instances have already been created, and we must return those existing instances.

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 yet have the data and property values it was holding at the time the app was terminated. The history of the creation and configuration of this view controller is not magically recapitulated during restoration. If the view controller comes from a storyboard, then any settings in its Attributes inspector are obeyed, but the segue that generated the view controller in the first place is never run, so the previous view controller’s prepareForSegue:sender: is never called, and the previous view controller never gets to hand this view controller any data. If the view controller is created by a restoration class, it may have been given some initial configuration, but this very likely falls short of the full state that the view controller was holding when the app was terminated. Any additional communication between one view controller and another to hand it data will be missing from the process. Indeed, since the history of the app during its previous run is not recapitulated, there will be no data to hand over in the first place.

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 sending the coder an appropriate encode message with a key, such as encodeFloat:forKey: or encodeObject:forKey:. If an object’s class doesn’t adopt the NSCoding protocol, you may have to archive it to an NSData 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 by sending the coder the reverse operation using the same key, such as decodeFloatForKey: or decodeObjectForKey:.

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:

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

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 encodeRestorableStateWithCoder: and decodeRestorableStateWithCoder: will concern itself with properties and interface views. decodeRestorableStateWithCoder: is guaranteed to be called after viewDidLoad, so you know that viewDidLoad won’t overwrite any direct changes to the interface performed in decodeRestorableStateWithCoder:.

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. 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. As usual, we change “did” to “will” so that we are now implementing application:willFinishLaunchingWithOptions:, and we implement application:shouldSaveApplicationState: and application:shouldRestoreApplicationState: to return true. Now we save and restore the current Pep Boy name in the app delegate’s Encode and Decode methods:

func application(application: UIApplication,
    willEncodeRestorableStateWithCoder coder: NSCoder) {
        let pvc = self.window!.rootViewController as! UIPageViewController
        let boy = (pvc.viewControllers![0] as! Pep).boy
        coder.encodeObject(boy, forKey:"boy")
}
func application(application: UIApplication,
    didDecodeRestorableStateWithCoder coder: NSCoder) {
        let boy: AnyObject? = coder.decodeObjectForKey("boy")
        if let boy = boy as? String {
            let pvc = self.window!.rootViewController as! UIPageViewController
            let pep = Pep(pepBoy: boy)
            pvc.setViewControllers(
                [pep], direction: .Forward, animated: false, completion: nil)
        }
}

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, options: nil)
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: "Pep", bundle: nil)
    self.restorationIdentifier = "pep" // *
    self.restorationClass = self.dynamicType // *
}

The only state that a Pep object needs to save is its boy string. The coder in which that boy value is saved will come back to us in Pep’s viewControllerWithRestorationIdentifierPath:coder:, so we can use it to create the new Pep object by calling the designated initializer, thus avoiding code duplication:

override func encodeRestorableStateWithCoder(coder: NSCoder) {
    super.encodeRestorableStateWithCoder(coder)
    coder.encodeObject(self.boy, forKey:"boy")
}
class func viewControllerWithRestorationIdentifierPath(
    ip: [AnyObject], coder: NSCoder) -> UIViewController? {
        let boy = coder.decodeObjectForKey("boy") as! String
        return self.init(pepBoy: boy)
}

(Swift won’t permit a class to instantiate itself through an initializer on self unless we guarantee that any subclass implements that initializer; our marking of init(pepBoy:) as required constitutes just such a guarantee.)

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 encodeRestorableStateWithCoder: 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 encodeRestorableStateWithCoder: and decodeRestorableStateWithCoder: 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,
    willEncodeRestorableStateWithCoder coder: NSCoder) {
        let pvc = self.window!.rootViewController as! UIPageViewController
        let pep = pvc.viewControllers![0] as! Pep
        coder.encodeObject(pep, forKey:"pep")
}
func application(application: UIApplication,
    didDecodeRestorableStateWithCoder coder: NSCoder) {
        let pep : AnyObject? = coder.decodeObjectForKey("pep")
        if let pep = pep as? Pep {
            let pvc = self.window!.rootViewController as! UIPageViewController
            pvc.setViewControllers(
                [pep], direction: .Forward, animated: false, completion: nil)
        }
}

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 actual Pep instance is the one created by viewControllerWithRestorationIdentifierPath:coder:.

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:. With state saving and restoration added to the picture, you may also be receiving decodeRestorableStateWithCoder:. If you configure your view controller here, will you be overriding what happens in viewWillAppear: and viewDidAppear:, or will they come along later and override what you do in decodeRestorableStateWithCoder:?

The unfortunate fact is that you don’t know. For viewWillAppear: and viewDidAppear:, in particular, the only thing you do know during state restoration is that you’ll get both of them for the top view controller (the one whose view actually appears). You don’t know when they will arrive; it might be before or after decodeRestorableStateWithCoder:. For other view controllers, 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.

However, 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 decodeRestorableStateWithCoder:.

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

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:

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:

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 also 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:

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 encodeRestorableStateWithCoder(coder: NSCoder) {
        coder.encodeObject(self.word, forKey:"word")
    }
    func decodeRestorableStateWithCoder(coder: NSCoder) {
        self.word = coder.decodeObjectForKey("word") as! String
    }
    func applicationFinishedRestoringState() {
        // not used
    }
}

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

class func makeThing () -> Thing {
    let thing = Thing()
    UIApplication.registerObjectForStateRestoration(
        thing, restorationIdentifier: "thing")
    return thing
}
override func awakeFromNib() {
    super.awakeFromNib()
    self.thing = self.dynamicType.makeThing()
}
override func encodeRestorableStateWithCoder(coder: NSCoder) {
    super.encodeRestorableStateWithCoder(coder)
    coder.encodeObject(self.thing, forKey: "mything") // important!
}

That last line is crucial; it introduces our Thing object to the archive and brings its UIStateRestoring methods to life.

There is an optional objectRestorationClass property of the restorable object, and an objectWithRestorationIdentifierPath:coder: method that the designated class must implement. But our object is restorable even without an objectRestorationClass! Presumably, just calling registerObjectForStateRestoration:restorationIdentifier: sufficiently identifies this object to the runtime. If you do want to assign an objectRestorationClass, you’ll have to declare it:

var objectRestorationClass: UIObjectRestoration.Type?

The class in question should adopt the UIObjectRestoration protocol; its objectWithRestorationIdentifierPath:coder: will then be called, and can return the restorable object, by creating it or pointing to it. Alternatively, it can return nil to prevent restoration.

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 parent should adopt the UIStateRestoring protocol. The purpose of the 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 objectWithRestorationIdentifierPath: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.

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.