Chapter 6. View Controllers

An iOS app’s interface is dynamic, and with good reason. On the desktop, an application’s windows can be big, and there can be more than one of them, so there’s room for lots of interface. With iOS, everything needs to fit on a single display consisting of a single window, which in the case of the iPhone is almost forbiddingly tiny. The iOS solution is to introduce, at will, completely new interface — a new view, possibly with an elaborate hierarchy of subviews — replacing or covering the previous interface.

For this to work, regions of interface material — often the entire contents of the screen — must come and go in an agile fashion that is understandable to the user. There will typically be a logical, structural, and functional relationship between the view that was present and the view that replaces or covers it, and this relationship will need to be maintained behind the scenes, in your code, as well as being indicated to the user: multiple views may be pure alternatives or siblings of one another, or one view may be a temporary replacement for another, or views may be like successive pages of a book. Animation is often used to emphasize and clarify these relationships as one view is superseded by another. Navigational interface and a vivid, suggestive gestural vocabulary give the user an ability to control what’s seen and an understanding of the possible options: a tab bar whose buttons summon alternate views, a back button or a swipe gesture for returning to a previously visited view, a tap on an interface element to dive deeper into a conceptual world, a Done or Cancel button to escape from a settings screen, and so forth.

In iOS, this management of the dynamic interface is performed through view controllers. A view controller is an instance of UIViewController. Actually, a view controller is most likely to be an instance of a UIViewController subclass; the UIViewController class is designed to be subclassed, and you are very unlikely to use a plain vanilla UIViewController object without subclassing it. You might write your own UIViewController subclass; you might use a built-in UIViewController subclass such as UINavigationController or UITabBarController; or you might subclass a built-in UIViewController subclass such as UITableViewController (Chapter 8).

A view controller manages a single view (which can, of course, have subviews); its view property points to the view it manages. This is the view controller’s main view, or simply its view. A view controller’s main view has no explicit pointer to the view controller that manages it, but a view controller is a UIResponder and is in the responder chain just above its view, so it is the view’s nextResponder.

View Controller Responsibilities

A view controller’s most important responsibility is its view. A view controller must have a view (it is useless without one). If that view is to be useful, it must somehow get into the interface, and hence onto the screen; a view controller is usually responsible for seeing to that, too, but typically not the view controller whose view this is; rather, it will be some view controller whose view is already in the interface. In most cases, this will be taken care of automatically for you by a built-in mechanism (I’ll talk more about this in the next section), but you can participate in the process, and for some view controllers you may have to do the work yourself. The reverse is also true: a view that comes may also eventually go, and the view controller responsible for putting a view into the interface will also be responsible for removing it.

A view controller will also typically provide animation of the interface as a view comes or goes. Built-in view controller subclasses and built-in ways of summoning or removing a view controller and its view come with built-in animations. We are all familiar, for example, with tapping something to make new interface slide in from the right, and then tapping a back button to make that interface slide back out to the right. In cases where you are responsible for getting a view controller’s view onto the screen, you are also responsible for providing the animation. And, new in iOS 7, you can take complete charge of the animation even for built-in view controllers.

View controllers, working together, can save and restore state automatically. This feature, introduced in iOS 6, helps you ensure that if your app is terminated in the background and subsequently relaunched, it will quickly resume displaying the same interface that was showing when the user last saw it.

The most powerful view controller is the root view controller. This is the view controller managing the view that sits at the top of the view hierarchy, as the one and only direct subview of the main window, acting as the superview for all other interface (the root view). I described in Chapter 1 how this view controller attains its lofty position: it is assigned to the window’s rootViewController property. The window then takes that view controller’s main view, gives it the correct frame (resizing it if necessary), and makes it its own subview.

Note

An app without a root view controller, while theoretically possible, is strongly discouraged by a warning from the runtime (“Applications are expected to have a root view controller at the end of application launch”). I don’t consider such an option in this book.

The root view controller is responsible for rotation of the interface. The user can rotate the device, and you might like the interface to rotate in response, to compensate. As I explained in Chapter 1, the window is effectively pinned to the physical display (window bounds are screen bounds and do not change), but a view can be given a transform so that its top moves to the current top of the display. The root view controller can respond to device rotation by applying this transform to the root view.

The root view controller also bears ultimate responsibility for manipulation of the status bar. The status bar is actually a secondary window belonging to the runtime, but the runtime consults the root view controller as to whether the status bar should be present and, if so, whether its text should be light or dark. (This view controller responsibility is new in iOS 7.)

Your participation in all these view controller responsibilities depends upon your customization of a view controller, through properties and methods provided for this purpose. View controllers do many things automatically, but the options that specify the details are up to you. The root view controller rotates the interface in response to the user’s rotation of the device; but should it do so on this particular occasion? A certain transition between views of built-in view controllers may come with a choice of built-in animations; which one would you like? (Or, in iOS 7, do you prefer to supply your own animation?) Similarly, some view controllers add navigation interface to their views; how should that interface look? You’ll determine all of this, and more, through your customization of view controllers.

View Controller Hierarchy

As I said in the previous section, there is always one root view controller, along with its view, the root view. There may also be other view controllers, each of which has its own main view. Such view controllers are subordinate to the root view controller. In iOS, there are two subordination relationships between view controllers:

Parentage (containment)

A view controller can contain another view controller. The containing view controller is the parent of the contained view controller; the contained view controller is a child of the containing view controller. This containment relationship of the view controllers is reflected in their views: the child view controller’s view is a subview of the parent view controller’s view. (“Subview” here means “subview at some depth.”)

Replacement of one view with another often involves a parent view controller managing its children and their views. The parent view controller is responsible for getting a child view controller’s view into the interface, by making it a subview of its own view, and (if necessary) for removing it later.

A familiar example is the navigation interface: the user taps something and new interface slides in from the right, replacing the current interface. Figure 6-1 shows the TidBITS News app displaying a typical iPhone interface, consisting of a list of story headlines and summaries. This interface is managed by a parent view controller (a UINavigationController) with a child view controller whose view is the list of headlines and summaries. If the user taps an entry in the list, the whole list will slide away to the left and the text of that story will slide in from the right; the parent view controller has added a new child view controller, and has manipulated the views of its two children to bring about this animated change of the interface. The parent view controller itself, meanwhile, stays put — and so does its own view. (In this example, the UINavigationController is the root view controller, and its view is the root view.)

The TidBITS News app
Figure 6-1. The TidBITS News app
Presentation (modal views)

A view controller can present another view controller. The first view controller is the presenting view controller (not the parent) of the second; the second view controller is the presented view controller (not a child) of the first. The second view controller’s view replaces or covers the first view controller’s view.

The name for this mechanism and relationship between view controllers has changed over time. In iOS 4 and before, the presented view controller was called a modal view controller, and its view was a modal view; there is an analogy here to the desktop, where a window is modal if it sits in front of, and denies the user access to, the rest of the interface until it is explicitly dismissed. The terms presented view controller and presented view are more recent and more general, but the term “modal” still appears in the documentation and in the API.

A presented view controller’s view does indeed sometimes look rather like a desktop modal view; for example, it might have a button such as Done or Save for dismissing the view, the implication being that this is a place where the user must make a decision and can do nothing else until the decision is made. However, as I’ll explain later, that isn’t the only use of a presented view controller.

There is thus a hierarchy of view controllers. In a properly constructed iOS app, there should be exactly one root view controller, and it is the only nonsubordinate view controller — it has neither a parent view controller nor a presenting view controller. Any other view controller, if its view is to appear in the interface, must be a child view controller (of some parent view controller) or a presented view controller (of some presenting view controller).

At the same time, at any given moment, the actual views of the interface form a hierarchy dictated by and parallel to some portion of the view controller hierarchy. Every view visible in the interface owes its presence to a view controller’s view: either it is a view controller’s view, or it’s a subview of a view controller’s view.

The place of a view controller’s view in the view hierarchy will most often be automatic. You might never need to put a UIViewController’s view into the view hierarchy manually. You’ll manipulate view controllers; their hierarchy and their built-in functionality will construct and manage the view hierarchy for you.

For example, in Figure 6-1, we see two interface elements:

  • The navigation bar, containing the TidBITS logo.
  • The list of stories, which is actually a UITableView.

I will describe how all of this comes to appear on the screen through the view controller hierarchy and the view hierarchy (Figure 6-2):

  • The app’s root view controller is a UINavigationController; the UINavigationController’s view, which is never seen in isolation, is the window’s sole immediate subview (the root view). The navigation bar is a subview of that view.
  • The UINavigationController contains a second UIViewController — a parent–child relationship. The child is a custom UIViewController subclass; its view is what occupies the rest of the window, as another subview of the UINavigationController’s view. That view is the UITableView. This architecture means that when the user taps a story listing in the UITableView, the whole table will slide out, to be replaced by the view of a different UIViewController, while the navigation bar stays.
The TidBITS News app’s initial view controller and view hierarchy
Figure 6-2. The TidBITS News app’s initial view controller and view hierarchy

In Figure 6-2, notice the word “automatic” in the two large right-pointing arrows associating a view controller with its view. This is intended to tell you how the view controller’s view became part of the view hierarchy. The UINavigationController’s view became the window’s subview automatically, by virtue of the UINavigationController being the window’s rootViewController. The custom UIViewController’s view became the UINavigationController’s view’s second subview automatically, by virtue of the UIViewController being the UINavigationController’s child.

Sometimes, you’ll write your own parent view controller class. In that case, you will be doing the kind of work that the UINavigationController was doing in that example, so you will need to put a child view controller’s view into the interface manually, as a subview (at some depth) of the parent view controller’s view.

I’ll illustrate with another app of mine (Figure 6-3). The interface displays a flashcard containing information about a Latin word, along with a toolbar (the dark area at the bottom) where the user can tap an icon to choose additional functionality.

A Latin flashcard app
Figure 6-3. A Latin flashcard app

Again, I will describe how the interface shown in Figure 6-3 comes to appear on the screen through the view controller hierarchy and the view hierarchy (Figure 6-4). The app actually contains over a thousand of these Latin words, and I want the user to be able to navigate between flashcards to see the next or previous word; there is an excellent built-in view controller for this purpose, the UIPageViewController. However, that’s just for the card; the toolbar at the bottom stays there, so it can’t be inside the UIPageViewController’s view. Therefore:

The Latin flashcard app’s initial view controller and view hierarchy
Figure 6-4. The Latin flashcard app’s initial view controller and view hierarchy

Finally, here’s an example of a presented view controller. My Latin flashcard app has a second mode, where the user is drilled on a subset of the cards in random order; the interface looks very much like the first mode’s interface (Figure 6-5), but it behaves completely differently.

The Latin flashcard app, in drill mode
Figure 6-5. The Latin flashcard app, in drill mode

To implement this, I have another UIViewController subclass, DrillViewController; it is structured very much like RootViewController. When the user is in drill mode, a DrillViewController is being presented by the RootViewController, meaning that the DrillViewController’s interface takes over the screen automatically: the DrillViewController’s view, with its whole subview hierarchy, replaces the RootViewController’s view and its whole subview hierarchy (Figure 6-6). The RootViewController and its hierarchy of child view controllers remains in place, but the corresponding view hierarchy is not in the interface; it will be returned to the interface automatically when we leave drill mode (because the presented DrillViewController is dismissed), and the situation will look like Figure 6-4 once again.

The Latin flashcard app’s drill mode view controller and view hierarchy
Figure 6-6. The Latin flashcard app’s drill mode view controller and view hierarchy

For any app that you write, you should be able to construct a diagram showing the hierarchy of view controllers and charting how each view controller’s view fits into the view hierarchy. The diagram should be similar to mine! The view hierarchy should run neatly parallel with the view controller hierarchy; there should be no crossed wires or orphan views. And every view controller’s view should be placed automatically into the view hierarchy, unless you have written your own parent view controller.

Warning

Do not put a view controller’s view into the interface manually, unless one of the following is the case:

View Controller Creation

A view controller is an instance like any other instance, and it is created like any other instance — by instantiating its class. You might perform this instantiation in code; in that case, you will of course have to initialize the instance properly as you create it. Here’s an example from one of my own apps: 

LessonListController* llc =
    [[LessonListController alloc] initWithTerms: self.data];
UINavigationController* nav =
    [[UINavigationController alloc] initWithRootViewController:llc];

In that example, LessonListController is my own UIViewController subclass, so I have called its designated initializer, which I myself have defined; UINavigationController is a built-in UIViewController subclass, and I have used one of its convenience initializers.

Alternatively, a view controller instance might come into existence through the loading of a nib. To make it possible to get a view controller into the nib in the first place, view controllers are included among the object types available through the Object library in the nib editor.

It is legal, though in practice not common, for a .xib file to contain a view controller. A .storyboard file, on the other hand, is chock full of view controllers; view controllers are the basis of a storyboard’s structure, with each scene consisting of one top-level view controller object. A view controller in a storyboard will go into a nib file in the built app, and that nib file will be loaded when the view controller instance is needed.

A nib file that comes from a storyboard is typically loaded automatically. If the nib file contains a view controller, this will happen under two primary circumstances:

Nevertheless, despite this automatic behavior of the storyboard mechanism, a view controller in a storyboard is an ordinary nib object and, if it is to be used in the running app, will be instantiated through the loading of the nib just like any other nib object. I’ll give full details on how a view controller is instantiated from a storyboard later in this chapter.

Once a view controller comes into existence, it must be retained so that it will persist. This will happen automatically when the view controller is assigned a place in the view controller hierarchy that I described in the previous section. A view controller assigned as a window’s rootViewController is retained by the window. A view controller assigned as another view controller’s child is retained by that other view controller (the parent). A presented view controller is retained by the presenting view controller. The parent view controller or presenting view controller then takes ownership, and will release the other view controller in good order when it is no longer needed.

Here’s an example, from one of my apps, of view controllers being instantiated and then being retained by being placed into the view controller hierarchy:

LessonListController* llc =
    [[LessonListController alloc] initWithTerms: self.data];
UINavigationController* nav =
    [[UINavigationController alloc] initWithRootViewController:llc];
[self presentViewController:nav animated:YES completion:nil];

That’s the same code I showed a moment ago, extended by one line. It comes from a view controller class called RootViewController. In the first line, I instantiate LessonListController. In the second line, I instantiate UINavigationController, and I assign the LessonListController instance to the UINavigationController instance as its child; the UINavigationController retains and takes ownership of the LessonListController instance. In the third line, I present the UINavigationController instance on self, a RootViewController instance; the RootViewController instance is the presenting view controller, and it retains and takes ownership of the UINavigationController instance. The RootViewController instance itself is the window’s rootViewController, and so the view controller hierarchy is safely established.

View controllers can be used in other ways, and you must take care to perform correct memory management in those situations as well. For example, passing a view controller as the argument to UIPopoverController’s initWithContentViewController: causes the UIPopoverController instance to retain the view controller instance, but there is then the problem of who will retain the UIPopoverController — this will cause much gnashing of teeth in Chapter 9.

All of this sounds straightforward, but it is worth dwelling on, because things can go wrong. It is quite possible, if things are mismanaged, for a view controller’s view to get into the interface while the view controller itself is allowed to go out of existence. This must not be permitted. If it does, at the very least the view will apparently misbehave, failing to perform its intended functionality, because that functionality is embodied by the view controller, which no longer exists. (I’ve made this mistake, so I speak from experience here.) If you instantiate a view controller in code, you should immediately ask yourself who will be retaining this view controller.

If a view controller is instantiated automatically from a storyboard, on the other hand, it will be retained automatically. That isn’t magic, however; it’s done in exactly the same ways I just listed — by assigning it as the window’s rootViewController, or by making it another view controller’s child view controller or presented view controller.

How a View Controller Gets Its View

Initially, when it first comes into existence, a view controller has no view. A view controller is a small, lightweight object; a view is a relatively heavyweight object, involving interface elements that occupy memory. Therefore, a view controller postpones obtaining its view until it has to do so, namely, when it is asked for the value of its view property. At that moment, if its view property is nil, the view controller sets about obtaining its view. (We say that a view controller loads its view lazily.) Typically, this happens because it is time to put the view controller’s view into the interface.

In working with a newly instantiated view controller, be careful not to refer to its view property if you don’t need to, since this will trigger the view controller’s obtaining its view prematurely. To learn whether a view controller has a view without causing it to load its view, call isViewLoaded. (As usual, I speak from experience here. I once made the mistake of mentioning a UIViewController’s view in its awakeFromNib and caused the view to be loaded twice.)

As soon as a view controller has its view, its viewDidLoad method is called. If this view controller is an instance of your own UIViewController subclass, viewDidLoad is your opportunity to modify the contents of this view — to populate it with subviews, to tweak the subviews it already has, and so forth — as well as to perform other initializations of the view controller consonant with its acquisition of a view. The view property is now pointing to the view, so it is safe to refer to self.view. Bear in mind, however, that the view may not yet be part of the interface! In fact, it almost certainly is not; self.view.window will be nil. Thus, for example, you cannot rely on the dimensions of the view at this point to be the dimensions that the view will assume when it becomes visible in the interface. Performing certain customizations prematurely in viewDidLoad is a common beginner mistake. I’ll have more to say about this later in the chapter.

Before viewDidLoad will be called, however, the view controller must obtain its view. The question of where and how the view controller will get its view is often crucial. In some cases, to be sure, you won’t care about this; in particular, when a view controller is an instance of a built-in UIViewController subclass such as UINavigationController or UITabBarController, its view is out of your hands — you might never even have cause to refer to it over the entire course of your app’s lifetime — and you simply trust that the view controller will somehow generate its view. But when the view controller is of your own subclass of UIViewController, and when you yourself will design or modify its view, it becomes essential to understand the process whereby a view controller gets its view.

This process is not difficult to understand, but it is rather elaborate, because there are multiple possibilities. Most important, this process is not magic. Yet it quite possibly causes more confusion to beginners than any other matter connected with iOS programming. Therefore, I will explain it in detail. The more you know about the details of how a view controller gets its view, the deeper and clearer will be your understanding of the entire workings of your app, its view controllers, its .storyboard and .xib files, and so on.

The alternatives are as follows:

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

Warning

Do not confuse loadView with viewDidLoad. Yes, I’ve made this mistake myself. I confess! loadView creates the view; viewDidLoad is called afterward.

Let’s try it. Start with a project made (with Use Core Data unchecked, of course) from the Empty Application project template (not the Single View Application template; our purpose here is to generate the entire interface in code, ourselves):

  1. We need a UIViewController subclass, so choose File → New → File; specify an iOS Cocoa Touch Objective-C class. Click Next.
  2. Name the class RootViewController, and specify that it is to be a UIViewController subclass. Uncheck the XIB checkbox. Click Next.
  3. Confirm that we’re saving into the appropriate folder and group, and that these files will be part of the app target. Click Create.

We now have a RootViewController class, and we proceed to edit its code. In RootViewController.m, 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:

- (void) loadView {
    UIView* v = [UIView new];
    v.backgroundColor = [UIColor greenColor];
    self.view = v;
    UILabel* label = [UILabel new];
    [v addSubview:label];
    label.text = @"Hello, World!";
    label.autoresizingMask = (
                              UIViewAutoresizingFlexibleTopMargin |
                              UIViewAutoresizingFlexibleLeftMargin |
                              UIViewAutoresizingFlexibleBottomMargin |
                              UIViewAutoresizingFlexibleRightMargin
                              );
    [label sizeToFit];
    label.center = CGPointMake(CGRectGetMidX(v.bounds),
                               CGRectGetMidY(v.bounds));
    label.frame = CGRectIntegral(label.frame);
}

We have not yet given a RootViewController instance a place in our view controller hierarchy — in fact, we have no RootViewController instance (and no view controller hierarchy). Let’s make one. To do so, we turn to AppDelegate.m. (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.m, add the line #import "RootViewController.h" at the start, so that our code can speak of the RootViewController class. Then modify the implementation of application:didFinishLaunchingWithOptions: (Appendix A) to create a RootViewController instance and make it the window’s rootViewController. Observe that we must do this after our window property actually has a UIWindow as its value! That’s why the template’s comment, “Override point for customization after application launch,” comes after the line that creates the UIWindow:

self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
// Override point for customization after application launch.
RootViewController* theRVC = [RootViewController new];
self.window.rootViewController = theRVC;
// ... and the rest is as in the template

Build and run the app. Sure enough, there’s our green background and our “Hello, world” label!

We have proved that we can create a view controller and get its view into the interface. But perhaps you’re not persuaded that the view controller is managing that view in an interesting way. To prove this, let’s rotate our interface. While our app is running in the simulator, choose Hardware → Rotate Left or Hardware → Rotate Right. Observe that both the app, as indicated by the orientation of the status bar, and the view, as indicated by the orientation of the “Hello, World” label, automatically rotate to compensate; that’s the work of the view controller. We were careful to give the label an appropriate autoresizingMask, to keep it centered in the view even when the view’s bounds are changed to fit the rotated window.

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. 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, the possibility that this will happen.

Generic Automatic View

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

UIView* v = [UIView new];
self.view = v;

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

- (void) loadView {
    UIView* v = [UIView new];
    self.view = v;
}
- (void)viewDidLoad {
    [super viewDidLoad];
    UIView* v = self.view;
    v.backgroundColor = [UIColor greenColor];
    UILabel* label = [UILabel new];
    [v addSubview:label];
    label.text = @"Hello, World!";
    label.autoresizingMask = (
                              UIViewAutoresizingFlexibleTopMargin |
                              UIViewAutoresizingFlexibleLeftMargin |
                              UIViewAutoresizingFlexibleBottomMargin |
                              UIViewAutoresizingFlexibleRightMargin
                              );
    [label sizeToFit];
    label.center = CGPointMake(CGRectGetMidX(v.bounds),
                               CGRectGetMidY(v.bounds));
    label.frame = CGRectIntegral(label.frame);
}

But if we’re going to do that, we can go even further and remove our implementation of loadView altogether! If you don’t implement loadView, and if no view is supplied in any other way, then UIViewController’s 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 has a view property; the view controller’s representative in the nib has a view outlet, which must point 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 owner’s representative is the File’s Owner proxy object. Therefore, a .xib file that is to serve as the source of a view controller’s view must be a .xib file in which the following two things are 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.m, because we want the view to come from a nib and we’re going to populate it in the nib. Then:

  1. Choose File → New → File and specify an iOS User Interface View document. This will be a .xib file containing a UIView object. Click Next.
  2. In the Device Family pop-up menu, choose iPhone. Click Next.
  3. Name the file MyNib (or MyNib.xib). Confirm the appropriate folder and group, and make very sure that the file will be part of the app target. Click Create.

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

    1. Set the File’s Owner class to RootViewController (in the Identity inspector).
    2. Connect the File’s Owner view outlet to the View object.
  5. Design the view. To make it clear that this is not the same view we were creating previously, perhaps you should give the view a red background color (in the Attributes inspector). Drag a UILabel into the middle of the view and give it some text, such as “Hello, World!”

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

RootViewController* theRVC = [RootViewController new];
self.window.rootViewController = theRVC;

We need 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 directly (it is read-only). Instead, as we instantiate the view controller, we must use the designated initializer, initWithNibName:bundle:, like this:

RootViewController* theRVC =
    [[RootViewController alloc] initWithNibName:@"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 show you a shortcut based on the name of the nib. It turns out that if the nib name passed to initWithNibName:bundle: is nil, a nib will be sought automatically with the same name as the view controller’s class. Moreover, UIViewController’s init calls initWithNibName:bundle:, passing nil for both arguments. This means, in effect, that we can return to using new (or 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:

RootViewController* theRVC = [RootViewController new];
self.window.rootViewController = theRVC;

Build and run. The project still 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. (This feature is undocumented, but it works reliably and I can’t believe it would ever be retracted.) Thus, we can name our nib file RootView.xib instead of RootViewController.xib, and it will still be properly associated with our RootViewController instance when we initialize that instance using init (or new).

When you create the files for a UIViewController subclass, the Xcode dialog has a XIB 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. I mentioned in Chapter 2 that when an image file is sought by calling imageNamed: or pathForResource:ofType:, an image file with the specified name but extended by the suffix ~ipad will be used, if there is one, when the app runs on an iPad. The same rule applies to nib files. So, for example, a nib file named RootViewController~ipad.xib will be loaded on an iPad when a nib named @"RootViewController" is sought, regardless of whether it is specified explicitly (as the first argument to initWithNibName:bundle:) or implicitly (because the view controller class is RootViewController, and the first argument to initWithNibName:bundle: is nil). This principle can greatly simplify your life when you’re writing a universal app.

Finally, let’s be specific about the place of this way of obtaining a view controller’s view among the other of ways of obtaining it:

  1. When the view controller first decides that it needs its view, loadView is always called.
  2. If we override loadView, we supply and set the view in code, and we do not call super. Therefore the process of seeking a view comes to an end.

  3. If we don’t override loadView, UIViewController’s built-in default implementation of loadView is used. It is this default implementation of loadView that loads the view controller’s associated nib (the one specified by its nibName, or, if that’s nil, the one whose name matches the name of the view controller’s class).

    That, indeed, is why, if we do override loadView, we must not call super — that would cause us to get both behaviors!

  4. If the previous steps all fail — we don’t override loadView, and there is no associated nib — UIViewController’s default implementation of loadView proceeds to create a generic UIView as discussed in the previous section.

Warning

It follows from what I’ve just said if a view controller’s view is to come from a nib, you should not implement loadView. Once again, I’ve made this mistake. The results were not pretty.

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 nib. This is the standard way of creating a scene in a .storyboard file; it can also be used with a .xib file, but this is rarely done.

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.

If you’d like to try it, start over with a new project from the Empty Application template, and give it a .xib file containing a view controller, as follows:

  1. Choose File → New → File and ask for an iOS User Interface Empty document. Press Next.
  2. Set the device family to iPhone. Press Next.
  3. Name the new file Main.xib, make sure it’s being saved into the right place and that it is part of the app target, and click Create.
  4. Edit Main.xib. Drag a plain vanilla View Controller object into the canvas.

In AppDelegate.m, 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:

NSArray* arr =
    [[UINib nibWithNibName:@"Main" bundle:nil]
        instantiateWithOwner:nil options:nil];
self.window.rootViewController = arr[0];

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:

  1. Give the project a RootViewController class (a UIViewController subclass).
  2. In Main.xib, select the view controller object and use its Identity inspector to set its class to RootViewController.

Now you can implement loadView in RootViewController, or implement viewDidLoad but not loadView. Alternatively, you can add another nib called RootViewController.xib (or RootView.xib) and configure it properly, and sure enough, the view controller instantiated from Main.xib will find that nib, load it, and get its view from it. There is also a way to specify in the nib editor the name of the nib that this view controller should use to find its nib: 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 initWithNibName:bundle:).

When a nib contains a view controller, there is an additional way for it to obtain its view: provide the view in the same nib as the view controller. In fact, using the nib editor we can design the interface in the view controller itself. You’ve probably noticed that the view controller, as portrayed in the canvas in the nib editor, is represented by a rectangle the size of an iPhone screen, even though a view controller is not a view. This is intended to accommodate the view controller’s view!

Let’s try it:

  1. If you’ve been experimenting with the code in RootViewController.m, remove any implementation of loadView or viewDidLoad from it.
  2. In Main.xib, find the plain vanilla View object in the Object library and drag it into the view controller object in the canvas. This view object automatically becomes this view controller’s view, and is drawn inside it in the canvas. Thus, you can now add further interface objects to this view.

Build and run. The interface you designed inside the view object inside the view controller object in Main.xib appears in the running app. (This way of supplying a view controller’s view takes priority over looking for the view in another nib, so if you also created a RootViewController.xib or RootView.xib as the source of this view controller’s view, it is ignored.)

Note

Like any other nib object, when a view controller is instantiated from a nib, its designated initializer in your code (initWithNibName:bundle:) is not called. If your UIViewController subclass code needs access to the view controller instance very early in its lifetime, it can override initWithCoder: or awakeFromNib.

If you’ve ever used a storyboard, it will not have escaped your attention that what we constructed in Main.xib, in the previous section — 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.

Each scene in a .storyboard file is rather like a .xib file containing a view controller nib object. Each scene’s view controller is instantiated only when needed; the underlying mechanism is that each scene’s view controller (or the view controllers of multiple scenes with a parent–child relationship) 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 is loaded from its own nib in the running app, on demand, when needed, 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 of your being able to see and edit a lot of your app’s interface simultaneously in one place.

Furthermore, 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 it. 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 a nib file that comes from a .xib with the same name as this view controller’s class, or even (if all of that fails) by creating a generic UIView.

(However, there’s no way in a .storyboard file to specify as the source of a view controller’s view a .xib file with a different name from the view controller’s class. The nib editor lacks the NIB Name field in a view controller’s Attributes inspector when you’re working in a storyboard.)

The Xcode 5 app templates (with the exception of the Empty Application template) 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 storyboardWithName:bundle:), instantiates its initial view controller (by calling instantiateInitialViewController), and makes that instance the window’s rootViewController. If you edit the storyboard to contain segues, 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’s convenient for beginners, but it can also be restrictive. You might have a feeling that your app must have a main storyboard, and that every view controller must be instantiated from it automatically. That’s not the case. It is possible to use storyboards in a much more agile, intentional way, much as one would use .xib files. For example, your app can have multiple storyboards. Why might that be useful? Well, since autolayout is configured at the file level — either an entire .storyboard file uses autolayout or none of it does — multiple storyboards constitute a very good way to use autolayout selectively in only certain areas of your interface. Or you might use an ancillary storyboard as a source of just one view controller, a more convenient and memory-efficient way to do what we did with a view controller in a .xib file earlier.

I’ll summarize the ways in which a view controller can be instantiated from a storyboard. You can get a reference to a storyboard either by calling the UIStoryboard class method storyboardWithName: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.

View Resizing and the Status Bar

As I’ve already mentioned, a view controller’s main view may be resized as it is placed into the interface, in order to fit into that interface correctly. You will want to design your main view so as to accommodate such resizing. The same view may end up at different sizes under different circumstances:

In the nib editor, the size at which a view controller’s main view is shown may not be the size it will end up at when the app runs and the view is placed into the interface. On the other hand, the nib editor gives you tools to simulate a variety of specific sizes that your view may assume:

These, however, are merely ways of experimenting with possible ultimate sizes that your view may assume. The size at which a view controller’s main view is portrayed in the nib has no effect on the size it will assume at runtime. The only way to discover the view’s true size at runtime is to run the app.

In iOS 7, the rules have changed, in comparison to earlier systems, for how a view controller’s view is resized to fit the screen as a whole (when, for example, it is the root view controller’s view) or to fit into a navigation controller’s view or a tab bar controller’s view:

The status bar is transparent

The iOS 7 status bar is transparent, so that the region of a view behind it is visible through it. The root view, and any other fullscreen view such as a presented view controller’s view, occupies the entire window, including the status bar area, the top 20 pixels of the view being visible behind the transparent status bar. You’ll want to design your view so that its top doesn’t contain any interface objects that will be overlapped by the status bar.

(In iOS 6 and before, the status bar was usually opaque, and a view was usually sized smaller than the screen, so that the status bar would not overlap it, by setting its frame to [UIScreen mainScreen].applicationFrame. Alternatively, a view controller’s view could be fullscreen, and this was desirable in cases where the status bar was translucent or hidden, but you had to take explicit steps to achieve this result, such as setting the view controller’s wantsFullScreenLayout to YES. In iOS 7, wantsFullScreenLayout is deprecated, and all apps are fullscreen apps.)

Top and bottom bars may be underlapped

In iOS 7, top and bottom bars (navigation bar, tab bar, toolbar) can be translucent. When they are, the main view displayed within the view of a navigation controller or tab bar controller, by default, is extended behind the translucent bar, underlapping it. (In iOS 6, this never happened; the top of the view was the bottom of the top bar, and bottom of the view was the top of the bottom bar.)

You can change this behavior for your UIViewController whose parent is a navigation controller or tab bar controller using two UIViewController properties:

edgesForExtendedLayout

A UIRectEdge. The default is UIRectEdgeAll, meaning that this view controller’s view will underlap a translucent top bar or a translucent bottom bar. The other extreme is UIRectEdgeNone, meaning that this view controller’s view won’t underlap top and bottom bars, just as on iOS 6 and before. Other possibilities are UIRectEdgeTop (underlap top bars only) and UIRectEdgeBottom (underlap bottom bars only).

Note that edgesForExtendedLayout has nothing to do with the status bar. On iOS 7, the status bar is transparent, all apps are fullscreen apps, and that’s that; you can’t change this behavior.

extendedLayoutIncludesOpaqueBars
If YES, then if edgesForExtendedLayout permits underlapping of bars, those bars will be underlapped even if they are opaque. The default is NO, meaning that only translucent bars are underlapped.

Warning

It is possible to set these two extendedLayout properties using the three Extend Edges checkboxes in a view controller’s Attributes inspector. However, if there are already subviews in this view controller’s main view, changing the checkboxes may cause those subviews to be repositioned unpredictably. I recommend changing these properties in code instead; a view controller’s viewDidLoad is a good place.

If you’re using autolayout, a view controller can help you position subviews within its main view in a way that compensates for changes in the size of the view. The view controller supplies two properties, its topLayoutGuide and its bottomLayoutGuide, to which you can form constraints. Typically, you’ll pin a view by its top to the topLayoutGuide, or you’ll pin a view by its bottom to the bottomLayoutGuide. The position of these guide objects moves automatically at runtime to reflect the view’s environment:

topLayoutGuide

The topLayoutGuide is positioned as follows:

bottomLayoutGuide

The bottomLayoutGuide is positioned as follows:

Thus, by pinning your subviews to the guides, you can achieve consistent results, regardless of whether or not the main view underlaps a bar (and regardless of whether or not the status bar is present).

You can create constraints involving the topLayoutGuide and the bottomLayoutGuide in the nib editor or in code:

A layout guide’s distance 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 (see on rotation and layout events, in the next section).

Consistent Layout Across Systems

This book concentrates on iOS 7 and isn’t concerned with backward compatibility, but the changes in how views are resized is the cause of much confusion. So here are some hints on how to lay out the subviews of a view controller’s main view so as to achieve consistent results between iOS 6 and iOS 7.

If you’re using autolayout and creating constraints in the nib editor, pin the top of a subview to the top layout guide (and possibly the bottom of a subview to the bottom layout guide) and lay everything else out in relation to those. If you create these constraints in the nib, they will work on iOS 6, even though iOS 6 has no top layout guide or bottom layout guide: on iOS 6, the guides are expressed as views with zero height at the top and bottom of the main view, so the outcome is the same as if you had pinned your subviews to the top or bottom of the main view — which, given the way the main view is resized on iOS 6, gives exactly the same result as the guides will give in iOS 7.

If you’re using autolayout and creating constraints in code, use conditional code to pin to a layout guide in iOS 7 and to the top or bottom of the main view in iOS 6.

If you’re not using autolayout and you’re laying out subviews in the nib editor, use the iOS 6/7 Deltas settings to compensate for the difference in the resizing behavior of the earlier and later systems. Typically, this will mean setting a ΔY of -20, as I suggested in Chapter 1, to compensate for the fact that iOS 7 adds 20 pixels of height to the main view in order to underlap the status bar.

If you’re not using autolayout and you’re laying out subviews in code, you’ll have to use conditional code to perform that same compensation.

Also, if you’re not using autolayout, you can use conditional code on iOS 7 to set your view controller’s edgesForExtendedLayout to UIRectEdgeNone, to make the resizing behavior of the view controller’s view inside a navigation controller or tab bar controller’s view the same on iOS 7 as on iOS 6 — namely, the view doesn’t underlap top bars and bottom bars. (If you do this, though, you sacrifice the cool look of your view underlapping a transparent bar.)

The job of determining the look of the status bar is also vested, by default, in view controllers — in the root view controller in the first instance. A view controller can override these methods:

preferredStatusBarStyle
Your choices are UIStatusBarStyleDefault and UIStatusBarStyleLightContent, meaning dark text and light text, respectively. Use light text for legibility if the view content underlapping the status bar is dark.
prefersStatusBarHidden
Return YES to make the status bar invisible.
childViewControllerForStatusBarStyle
childViewControllerForStatusBarHidden
Used to delegate the decision on the status bar style or visibility to a child view controller’s preferredStatusBarStyle or prefersStatusBarHidden instead of this view controller. For example, a navigation controller implements these methods to allow your view controller to decide the status bar style and visibility when its view becomes visible in the navigation controller’s view.

You never call any of those methods yourself; they are called automatically when the view controller situation changes. If you want them to be called immediately, because they are not being called when you need them to be, or because the situation has changed and a call to one of them would now give a different answer, call the view controller instance method setNeedsStatusBarAppearanceUpdate on your view controller. If this call is inside an animation block, the animation of the change in the look of the status bar will have the specified duration, thus matching the other animations that are also taking place. The character of the animation from a visible to an invisible status bar (and vice versa) is set by your view controller’s implementation of preferredStatusBarUpdateAnimation; you can return one of these values:

This entire view controller–based mechanism for determining the look of the status bar is new in iOS 7. Previously, the status bar was controlled by calls to various UIApplication methods. If your app is to be backward-compatible with iOS 6 or before, you may want to opt out of the new mechanism and use the old UIApplication calls instead. To do so, set the Info.plist key “View controller–based status bar appearance” (UIViewControllerBasedStatusBarAppearance) to NO. In that case, you can also hide the status bar initially by setting the Info.plist key “Status bar is initially hidden” (UIStatusBarHidden) to YES.

Warning

When you toggle the visibility of the status bar, the top layout guide will move up or down by 20 points. If your main view has subviews with constraints to the top layout guide, those subviews will move. If this happens when the main view is visible, the user will see the subviews move (as a jump). This is probably not what you want.

The resizing of the view as it is placed into the interface takes place after viewDidLoad. For this reason, you should not use viewDidLoad to make any changes whose validity depends upon the final dimensions of the view. A better location for such changes is viewWillAppear: or viewDidAppear:; even better, perhaps (because they have to do with layout) are viewWillLayoutSubviews and viewDidLayoutSubviews. However, viewDidLoad has the advantage of being called only once during the lifetime of a view controller; the others can be called any number of times, so if you need to perform one-time initializations in any of them, use a BOOL instance variable flag to ensure that your code runs only the first time:

-(void) viewWillLayoutSubviews {
    if (!self.didSetup) {
        self.didSetup = YES;
        // ... perform one-time setup here ...
    }
}

Warning

If you have older app code in which you were manually setting the frame of a view controller’s view, in code, to [[UIScreen mainScreen] applicationFrame] in iOS 6 or before, do not do that in iOS 7. Delete that line, or use conditional code. In iOS 7, allow the runtime to resize your view controller’s view automatically.

Rotation

A major part of a view controller’s job is to know how to rotate the view. The user will experience this as rotation of the app itself: the top of the app shifts so that it is oriented against a different side of the device’s display. There are two complementary uses for rotation:

Compensatory rotation
The app rotates to compensate for the orientation of the device, so that the app appears right way up with respect to how the user is holding the device. The challenge of compensatory rotation stems, quite simply, from the fact that the screen is not square. This means that if the app rotates 90 degrees, the interface no longer fits the screen, and must be changed to compensate.
Forced rotation
The app rotates when a particular view appears in the interface, or when the app launches, to indicate that the user needs to rotate the device in order to view the app the right way up. This is typically because the interface has been specifically designed, in the face of the fact that the screen is not square, to appear in one particular mode (portrait or landscape).

In the case of the iPhone, no law says that your app has to perform compensatory rotation. Most of my iPhone apps do not do so; indeed, I have no compunction about doing just the opposite, forcing the user to rotate the device differently depending on what view is being displayed. 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 swapped — 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 mode, the master pane and the detail pane appear side by side, but in portrait mode, the master pane is removed and must be summoned as a temporary overlay on top of the detail pane.

In iOS 7 (and iOS 6), an app is free, by default, to perform compensatory rotation in response to the user’s rotation of the device. For an iPhone app, this means that the app can appear with its top at the top of the device or either of the two sides of the device; having the app’s top appear at the bottom of the device (because the device is held upside-down) is generally frowned on. For an iPad app, this means that the app can assume any orientation.

If this isn’t what you want, it is up to you to prevent it, as follows:

A UIViewController class method attemptRotationToDeviceOrientation prompts the runtime to do immediately what it would do if the user were to rotate the device, namely to walk the three levels I’ve just described and, if the results permit rotation of the interface to match the current device orientation, to rotate the interface. This would be useful if, say, your view controller had returned NO from shouldAutorotate, so that the interface does not match the current device orientation, but is now for some reason prepared to return YES and wants to be asked again, immediately.

The bitmask you return from application:supportedInterfaceOrientationsForWindow: or supportedInterfaceOrientations may be one of these values, or multiple values combined with bitwise-or:

If your code needs to know the current orientation of the device, it can ask the device, by calling [UIDevice currentDevice].orientation. Possible results are UIDeviceOrientationUnknown, UIDeviceOrientationPortrait, and so on. Convenience macros UIDeviceOrientationIsPortrait and UIDeviceOrientationIsLandscape let you test a given orientation for whether it falls into that category. By the time you get a rotation-related query event, the device’s orientation has already changed.

The current orientation of the interface is available as a view controller’s interfaceOrientation property. Never ask for this value if the device’s orientation is UIDeviceOrientationUnknown.

Warning

The interface orientation mask values (UIInterfaceOrientationMask...) that you return from application:supportedInterfaceOrientationsForWindow: or supportedInterfaceOrientations are not the same as the device orientation values used by UIDevice to report the current device orientation, or the interface orientation values used by UIViewController to report the current interface orientation. Do not return a device orientation or interface orientation value where an interface orientation mask value is expected!

What Rotates?

We say that your app rotates, and you’ll think of it as rotating, but what really rotates is the status bar’s position. When the device rotates, a UIDeviceOrientationDidChangeNotification is emitted by the UIDevice, and if the app’s interface is to rotate to match, the UIApplication instance is sent the setStatusBarOrientation:animated: message. A transform is applied so that the window’s root view appears “right way up,” and in a 90-degree rotation, the window’s root view has its width and height dimensions swapped. Moreover, this is all accompanied by animation, so it really looks to the user as if the app is rotating. But the window itself doesn’t budge; it remains pinned to the screen (window bounds are screen bounds). It is taller than it is wide, and its top is at the top of the device (away from the home button). As for the root view, its bounds are wider than tall in a landscape orientation, but its frame remains taller than wide (though you really shouldn’t be referring to the root view’s frame in this situation, because it has a transform applied; see Chapter 1).

Rotation and Layout Events

The resizing of your view controller’s view when the app rotates 90 degrees is even more dramatic than the resizing that took place when it was inserted into the interface to begin with (discussed in the previous section). The view doesn’t merely become taller or shorter in height; rather, its height and width bounds dimensions are effectively swapped. You will want to implement layout (Chapter 1) that can adapt to such a change. Autoresizing or autolayout can change the size and position of your view’s subviews in response to the change in bounds size.

In some cases, however, this won’t be sufficient; you may have to perform manual layout, perhaps even adding or removing views entirely. For example, as I’ve already mentioned, Apple’s Mail app on the iPad eliminates the entire master view (the list of messages) when the app assumes a portrait orientation. The question is then when to perform this manual layout. I will demonstrate two possible approaches.

Your UIViewController subclass can override any of the following methods (which are called in the order shown) to be alerted in connection with interface rotation:

willRotateToInterfaceOrientation:duration:
The first parameter is the new orientation; self.interfaceOrientation is the old orientation, and the view’s bounds are the old bounds.
willAnimateRotationToInterfaceOrientation:duration:
The first parameter is the new orientation; self.interfaceOrientation is the new orientation, and the view’s bounds are the new bounds. The call is wrapped by an animation block, so changes to animatable view properties are animated.
didRotateFromInterfaceOrientation:
The parameter is the old orientation; self.interfaceOrientation is the new orientation, and the view’s bounds are the new bounds.

You might take advantage of these events to perform manual layout in response to interface rotation. Imagine, for example, that our app displays a black rectangle at the left side of the screen if the device is in landscape orientation, but not if the device is in portrait orientation. We could implement that as follows:

- (UIView*) blackRect { // property getter
    if (!self->_blackRect) {
        if (UIInterfaceOrientationIsPortrait(self.interfaceOrientation))
            return nil;
        CGRect f = self.view.bounds;
        f.size.width /= 3.0;
        f.origin.x = -f.size.width;
        UIView* br = [[UIView alloc] initWithFrame:f];
        br.backgroundColor = [UIColor blackColor];
        self.blackRect = br;
    }
    return self->_blackRect;
}
-(void)willAnimateRotationToInterfaceOrientation:(UIInterfaceOrientation)io
                                        duration:(NSTimeInterval)duration {
    UIView* v = self.blackRect;
    if (UIInterfaceOrientationIsLandscape(io)) {
        if (!v.superview) {
            [self.view addSubview:v];
            CGRect f = v.frame;
            f.origin.x = 0;
            v.frame = f;
        }
    } else {
        if (v.superview) {
            CGRect f = v.frame;
            f.origin.x -= f.size.width;
            v.frame = f;
        }
    }
}
- (void) didRotateFromInterfaceOrientation:(UIInterfaceOrientation)io {
    if (UIInterfaceOrientationIsPortrait(self.interfaceOrientation))
        [self.blackRect removeFromSuperview];
}

We have a UIView property, blackRect, to retain the black rectangle; we implement its getter to create the black rectangle if it hasn’t been created already, but only if we are in landscape orientation, since otherwise we cannot set the rectangle’s dimensions properly. The implementation of willAnimateRotationToInterfaceOrientation:​duration: slides the black rectangle in from the left as part of the rotation animation if we have ended up in a landscape orientation, but only if it isn’t in the interface already; after all, the user might rotate the device 180 degrees, from one landscape orientation to the other. Similarly, it slides the black rectangle out to the left if we have ended up in a portrait orientation, but only if it is in the interface already. Finally, didRotateFromInterfaceOrientation:, called after the rotation animation is over, makes sure the rectangle is removed from its superview if we have ended up in a portrait orientation.

However, there’s another way that I think is better. Recall from Chapter 1 that when a view’s bounds change, it is asked to update its constraints (if necessary) with a call to updateConstraints, and then to perform layout with a call to layoutSubviews. It turns out that if this is a view controller’s view, the view controller is notified just before the view’s constraints are updated, with updateViewConstraints; it is also notified before and after view layout, with viewWillLayoutSubviews and viewDidLayoutSubviews. Here’s the full sequence during rotation:

  • willRotateToInterfaceOrientation:duration:
  • updateViewConstraints (and you must call super!)
  • updateConstraints (to the view)
  • viewWillLayoutSubviews
  • layoutSubviews (to the view)
  • viewDidLayoutSubviews
  • willAnimateRotationToInterfaceOrientation:duration:
  • didRotateFromInterfaceOrientation:

These UIViewController events allow your view controller to participate in its view’s layout, without your having to subclass UIView so as to implement updateConstraints and layoutSubviews directly. Our problem is a layout problem, so it seems more elegant to implement it through layout events.

Here’s a two-part solution involving constraints. I won’t bother to remove the black rectangle from the interface; I’ll add it once and for all as I configure the view initially, and just slide it onscreen and offscreen as needed. In viewDidLoad, then, we add the black rectangle to our interface, and then we prepare two sets of constraints, one describing the black rectangle’s position onscreen (within our view bounds) and one describing its position offscreen (to the left of our view bounds):

-(void)viewDidLoad {
    UIView* br = [UIView new];
    br.translatesAutoresizingMaskIntoConstraints = NO;
    br.backgroundColor = [UIColor blackColor];
    [self.view addSubview:br];
    // b.r. is pinned to top and bottom of superview
    [self.view addConstraints:
     [NSLayoutConstraint
      constraintsWithVisualFormat:@"V:|[br]|"
      options:0 metrics:nil views:@{@"br":br}]];
    // b.r. is 1/3 the width of superview
    [self.view addConstraint:
     [NSLayoutConstraint
      constraintWithItem:br attribute:NSLayoutAttributeWidth
      relatedBy:0
      toItem:self.view attribute:NSLayoutAttributeWidth
      multiplier:1.0/3.0 constant:0]];
    // onscreen, b.r.'s left is pinned to superview's left
    NSArray* marrOn =
     [NSLayoutConstraint
      constraintsWithVisualFormat:@"H:|[br]"
      options:0 metrics:nil views:@{@"br":br}];
    // offscreen, b.r.'s right is pinned to superview's left
    NSArray* marrOff = @[
     [NSLayoutConstraint
      constraintWithItem:br attribute:NSLayoutAttributeRight
      relatedBy:NSLayoutRelationEqual
      toItem:self.view attribute:NSLayoutAttributeLeft
      multiplier:1 constant:0]
    ];
    // store constraints in instance variables
    self.blackRectConstraintsOnscreen = marrOn;
    self.blackRectConstraintsOffscreen = marrOff;
}

That’s a lot of preparation, but the payoff is that responding to a request for layout is simple and clear; we simply swap in the constraints appropriate to the new interface orientation (self.interfaceOrientation at layout time):

-(void)updateViewConstraints {
    [self.view removeConstraints:self.blackRectConstraintsOnscreen];
    [self.view removeConstraints:self.blackRectConstraintsOffscreen];
    if (UIInterfaceOrientationIsLandscape(self.interfaceOrientation))
        [self.view addConstraints:self.blackRectConstraintsOnscreen];
    else
        [self.view addConstraints:self.blackRectConstraintsOffscreen];
    [super updateViewConstraints];
}

Moreover, the movement of the black rectangle is animated as the interface rotates, because any constraint-based layout performed as the interface rotates is animated.

Initial Orientation

The basic way to dictate your app’s initial orientation, as the user will see it when launching, is to use your app’s Info.plist settings. The reason is that the system can consult those settings during launch, before any of your code runs:

On the iPhone

The app will launch, preferentially, into the first orientation listed in the Info.plist in the “Supported interface orientations” array (UISupportedInterfaceOrientations). In Xcode, edit the Info.plist; the editor lets you drag the elements of the array to reorder them.

If the root view controller limits the supported interface orientations, you should arrange the order of the “Supported interface orientations” entries to agree with it. For example, suppose your app as a whole supports portrait, landscape left, and landscape right, but your initial root view controller supports only landscape left and landscape right. Then you should put “Landscape (right home button)” and “Landscape (left home button)” before “Portrait” in the Info.plist “Supported interface orientations” array. Otherwise, if “Portrait” comes first, the app will try to launch into portrait orientation, only to discover, as your code finally starts running and your root view controller’s supportedInterfaceOrientations is called, that this was wrong.

On the iPad
iPad apps are supposed to be more or less orientation-agnostic, so the order of orientations listed in the Info.plist in the “Supported interface orientations” array (UISupportedInterfaceOrientations) or “Supported interface orientations (iPad)” (UISupportedInterfaceOrientations~ipad) is ignored. Instead, the app will launch into whatever permitted orientation is closest to the device’s current orientation.

Nevertheless, all apps launch into portrait mode initially. This is because the window goes only one way, with its top at the top of the device (away from the home button) — window bounds are screen bounds (see What Rotates?). If the app’s initial visible orientation is not portrait, then there must be an initial rotation to that initial visible orientation, even if the user never sees it. Thus, an app whose initial orientation is landscape mode must be configured to rotate from portrait to landscape even if it doesn’t support rotation after that.

A common beginner mistake, in this situation, is to try to work with the interface dimensions in your code too soon, before the rotation has taken place, in viewDidLoad. At the time viewDidLoad is called, the view controller has loaded its view — there is now something called self.view — but this view has not yet been put into the interface. It has not yet been resized to fit the interface (as I described in the previous section), and if the app needs to rotate on launch, that rotation has not yet taken place. If you try to work with the view’s dimensions in viewDidLoad in an app that launches into a non-portrait orientation, it will appear that the width and height values of your interface bounds are the reverse of what you expect.

For example, let’s say that our iPhone app’s Info.plist has its “Supported interface orientations” ordered with “Landscape (right home button)” first, and our root view controller’s viewDidLoad code places a small black square at the top center of the interface, like this:

- (void) viewDidLoad {
    [super viewDidLoad];
    UIView* square =
        [[UIView alloc] initWithFrame:CGRectMake(0,0,10,10)];
    square.backgroundColor = [UIColor blackColor];
    square.center =
        CGPointMake(CGRectGetMidX(self.view.bounds),5); // top center?
    [self.view addSubview:square];
}

The app launches into landscape orientation; the user must hold the device with the home button at the right to see it correctly. That’s good. But where’s the little black square? Not at the top center of the screen! The square appears at the top of the screen, but only about a third of the way across. The trouble is that in determining the x-coordinate of the square’s center we examined the view’s bounds too soon, at a time when the view’s x-dimension (its width dimension) was still its shorter dimension.

So when is it safe to work with our view’s initial dimensions? In iOS 5 and before, a possible solution was to override one of the rotation events discussed in the previous section, such as didRotateFromInterfaceOrientation:, and complete the configuration of your view there. In iOS 6 and iOS 7, however, that won’t work, because rotation events are not sent in conjunction with the initial rotation of your app’s interface.

The earliest event we receive at launch time after self.view has assumed its initial size in the interface is viewWillLayoutSubviews. This seems a perfectly appropriate place to configure our additional subview, since layout is exactly what we’re doing. This event can be received multiple times over the lifetime of the view controller, but we want to perform our initial configuration only once, so we’ll use a BOOL instance variable as a flag:

- (void) viewWillLayoutSubviews {
    if (!self->_viewInitializationDone) {
        self->_viewInitializationDone = YES;
        UIView* square =
            [[UIView alloc] initWithFrame:CGRectMake(0,0,10,10)];
        square.backgroundColor = [UIColor blackColor];
        square.center = CGPointMake(CGRectGetMidX(self.view.bounds),5);
        [self.view addSubview:square];
    }
}

The best solution of all, I think, is to use autolayout if at all possible, positioning our black square through constraints instead of its frame. The beauty of constraints is that you describe your layout conceptually rather than numerically; those concepts continue to apply through any future rotation. We don’t need a BOOL instance variable, and we can even put our code back into viewDidLoad, because our constraints will continue to position the subview correctly whenever the view assumes its ultimate size: 

- (void) viewDidLoad {
    [super viewDidLoad];
    UIView* square = [UIView new];
    square.backgroundColor = [UIColor blackColor];
    [self.view addSubview:square];
    square.translatesAutoresizingMaskIntoConstraints = NO;
    CGFloat side = 10;
    [square addConstraint:
     [NSLayoutConstraint
      constraintWithItem:square attribute:NSLayoutAttributeWidth
      relatedBy:0
      toItem:nil attribute:0
      multiplier:1 constant:side]];
    [self.view addConstraints:
     [NSLayoutConstraint
      constraintsWithVisualFormat:@"V:|[square(side)]"
      options:0 metrics:@{@"side":@(side)}
      views:@{@"square":square}]];
    [self.view addConstraint:
     [NSLayoutConstraint
      constraintWithItem:square attribute:NSLayoutAttributeCenterX
      relatedBy:0
      toItem:self.view attribute:NSLayoutAttributeCenterX
      multiplier:1 constant:0]];
}

Presented View Controller

Back when the only iOS device was an iPhone, a presented view controller was called a modal view controller. The root view controller remained in place, but its view was taken out of the interface and the modal view controller’s view was used instead. Thus, this was the simplest way to replace the entire interface with a different interface.

You can see why this configuration was characterized as “modal”. The presented view controller’s view has, in a sense, blocked access to the “real” view, the root view controller’s view. The user is thus forced to work in the presented view controller’s view, until that view is “dismissed” and the “real” view is visible again. These notions are analogous to a modal dialog in a desktop application, where the user can’t do anything else but work in the dialog as long as it is present. A presented view controller’s view often reinforces this analogy with obvious dismissal buttons with titles like Save, Done, or Cancel.

The color picker view in my own Zotz! app is a good example (Figure 6-7); this is an interface that says, “You are now configuring a color, and that’s all you can do; change the color or cancel, or you’ll be stuck here forever.” The user can’t get out of this view without tapping Cancel or Done, and the view that the user was previously using is visible as a blur behind this view, waiting for the user to return to it.

A modal view
Figure 6-7. A modal view

Figure 6-5, from my Latin flashcard app, is another example of a presented view. It has a Cancel button, and the user is in a special “mode”, performing a drill exercise rather than scrolling through flashcards.

Nevertheless, the “modal” characterization is not always apt. A presented view controller might be no more than a device that you, the programmer, have used to alter the interface; the user needn’t be conscious of this. A presented view controller’s view may have a complex interface; it may have child view controllers; it may present yet another view controller; it may take over the interface permanently, with the user never returning to the interface that it replaced.

With the coming of the iPad, the range of what a presented view controller’s view could do was extended. A presented view on the iPad, instead of replacing the entire interface, can replace a subview within the existing interface. Alternatively, a presented view controller’s view on the iPad may cover the existing interface only partially; the existing interface is never removed. And iOS 7 gives you a way to accomplish the same thing on the iPhone.

Presenting a View

To make a view controller present another view controller, you send the first view controller presentViewController:animated:completion:, handing it the second view controller, which you will probably instantiate for this very purpose. (The first view controller is very typically self.) We now have two view controllers that stand in the relationship of presentingViewController and presentedViewController, and the latter is retained. The presented view controller’s view effectively replaces (or covers) the presenting view controller’s view in the interface.

This state of affairs persists until the presenting view controller is sent dismissViewControllerAnimated:completion:. The presented view controller’s view is then removed from the interface, and the presented view controller is released; it will thereupon typically go out of existence, together with its view, its child view controllers and their views, and so on.

As the view of the presented view controller appears, and again when it is dismissed, there’s an option for animation as the transition takes place (the animated: argument). 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 determine 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:

Presented view controller
The view controller specified as the first argument to presentViewController:animated:completion:.
Original presenter

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

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

Presenting view controller

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

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

The receiver of 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.

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

Conversely, you can test for a nil presentedViewController or presentingViewController 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.

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:

  1. Choose File → New → File and make a new iOS Cocoa Touch Objective-C class. Click Next.
  2. Name the class SecondViewController, make sure it is a subclass of UIViewController, and check the XIB checkbox so that we can design this view controller’s view quickly and easily in a nib. Click Next.
  3. Confirm the folder, group, and app target membership, and click Create.
  4. Edit SecondViewController.xib, and do something there to make the view distinctive, so that you’ll recognize it when it appears; for example, give it a red background color.
  5. We need a way to trigger the presentation of SecondViewController. Edit Main.storyboard and add a button to the ViewController’s view’s interface. Connect that button to an action method in ViewController.m; let’s call it doPresent:.

  6. Import "SecondViewController.h" at the top of ViewController.m, so that we can speak of SecondViewController, and write the code for doPresent:, as follows: 

    - (IBAction)doPresent:(id)sender {
    [self presentViewController:[SecondViewController new]
                       animated:YES completion:nil];
}

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, put a button into SecondViewController’s view and connect it to an action method in SecondViewController.m:

- (IBAction)doDismiss:(id)sender {
    [self.presentingViewController
        dismissViewControllerAnimated:YES completion:nil];
}

Run the project. You can now alternate between ViewController’s view and SecondViewController’s view.

In real life, it is quite probable that both presentation and dismissal will be a little more involved; in particular, it is likely 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:

SecondViewController* svc = [SecondViewController new];
svc.data = @"This is very important data!";
[self presentViewController: svc
                   animated: YES completion:nil];

Indeed, if you’re calling presentViewController:animated:completion: explicitly like this, you might even give SecondViewController a designated initializer that accepts the required data. In my Latin vocabulary app, the transition that engenders Figure 6-6 looks like this:

DrillViewController* dvc =
    [[DrillViewController alloc] initWithData:drillTerms];
[self presentViewController:dvc animated:YES completion:nil];

I’ve given DrillViewController a designated initializer initWithData: precisely so that whoever creates it can 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, so that it can call that method and hand over the information — and this needs to work regardless of the original presenter’s class.

The standard solution is to use delegation. The presented view controller defines a protocol declaring a method that the presented view controller wants to call before it is dismissed. The original presenter conforms to this protocol, and hands the presented view controller a reference to itself as it creates and configures the presented view controller; we can call this the presented view controller’s delegate. The delegate reference is declared as an id adopting the presented view controller’s protocol, so the presented view controller now not only has the required reference to the original presenter, but it also knows the signature of a method that the original presenter implements.

Let’s modify our example to embody this architecture. First, modify SecondViewController to look like this:

// SecondViewController.h:
@protocol SecondViewControllerDelegate
- (void) dismissWithData: (id) data;
@end
@interface SecondViewController : UIViewController
@property (nonatomic, weak) id <SecondViewControllerDelegate> delegate;
@property (nonatomic, strong) id data;
@end

// SecondViewController.m:
- (IBAction)doDismiss:(id)sender {
    [self.delegate dismissWithData: @"Even more important data!"];
}

ViewController will need to declare itself as adopting SecondViewControllerDelegate; I like to do this in a class extension in the implementation file (ViewController.m):

@interface ViewController () <SecondViewControllerDelegate>
@end

ViewController could then present and dismiss SecondViewController like this:

- (IBAction)doPresent:(id)sender {
    SecondViewController* svc = [SecondViewController new];
    svc.data = @"This is very important data!";
    svc.delegate = self;
    [self presentViewController: svc
                       animated: YES completion:nil];
}
- (void) dismissWithData:(id)data {
    // do something with the data here
    [self dismissViewControllerAnimated:YES completion:nil];
}

In that example, the original presenter is sent the data and told to dismiss the presented view controller, in a single method. It might be wiser to separate these two functionalities. Here, I’ll rename dismissWithData: as acceptData:, and its job is just to receive the data; ViewController will no longer dismiss SecondViewController. Rather, SecondViewController will dismiss itself, and will then hear about that dismissal in a lifetime event, viewWillDisappear:, which calls acceptData: to ensure that the data is handed across. There is more than one reason why viewWillDisappear: might be called; we can test that this is the moment of our own dismissal by calling isBeingDismissed. Here is what SecondViewController looks like now:

// SecondViewController.h:
@protocol SecondViewControllerDelegate
- (void) acceptData: (id) data;
@end
@interface SecondViewController : UIViewController
@property (nonatomic, weak) id <SecondViewControllerDelegate> delegate;
@property (nonatomic, strong) id data;
@end

// SecondViewController.m:
- (IBAction)doDismiss:(id)sender {
    [self.presentingViewController
        dismissViewControllerAnimated:YES completion:nil];
}
- (void) viewWillDisappear:(BOOL)animated {
    [super viewWillDisappear: animated];
    if ([self isBeingDismissed])
        [self.delegate acceptData: @"Even more important data!"];
}

Configuring this architecture involves considerable work, and I know from experience that there is a strong temptation to be lazy and avoid it. It may indeed be possible to get by with a simplified solution; for example, SecondViewController could post a notification for which ViewController has supposedly registered. Nevertheless, delegation is the most reliable way for a presented view controller to communicate back to its original presenter.

When a view is presented and later when it is dismissed, an animation can be performed, according to whether the animated: parameter of the corresponding method is YES.

There are several built-in animation styles, whose names preserve the legacy “modal” designation:

UIModalTransitionStyleCoverVertical (the default)
The presented view slides up from the bottom to cover the presenting view on presentation and down to reveal the presenting view on dismissal. “Bottom” is defined differently depending on the orientation of the device and the orientations the view controllers support.
UIModalTransitionStyleFlipHorizontal

The view flips on the vertical axis as if the two views were the front and back of a piece of paper. The “vertical axis” is the device’s long axis, regardless of the app’s orientation.

This animation style provides one of those rare occasions where the user may glimpse the window behind the transitioning views. You may want to set the window’s background color appropriately.

UIModalTransitionStyleCrossDissolve
The views remain stationary, and one fades into the other.
UIModalTransitionStylePartialCurl

The first view curls up like a page in a notepad to expose most of the second view, but remains covering the top-left region of the second view. Thus there must not be any important interface in that region, as the user will not be able to see it.

If the user clicks on the curl, dismissViewControllerAnimated:completion: is called on the original presenter. That’s convenient, but make sure it doesn’t disrupt communication between your view controllers; this is another reason for factoring out any final handing back of information from the presented view controller into its viewWillDisappear:, as I did in the previous section.

You do not pass the animation style as a parameter when presenting or dismissing a view controller; rather, it is attached beforehand to a view controller as its modalTransitionStyle property. (It is legal, but not common, for the modalTransitionStyle value to differ at the time of dismissal from its value at the time of presentation. Reversing on dismissal with the same animation style that was used on presentation is a subtle cue to the user that we’re returning to a previous state.) The view controller that should have this modalTransitionStyle property set will generally be the presented view controller (I’ll talk about the exception to this rule later). There are three typical ways in which this happens:

New in iOS 7, you can supply your own animation instead of using one of the built-in modal transition styles. Moreover, if you do this, you are able, for the first time in iOS history, to have the presented view controller’s view cover the original presenter’s view only partially, even on the iPhone. I’ll discuss this topic later in the chapter.

On the iPad, additional options for how the presented view controller’s view should cover the screen, and for what view controller should be the presenting view controller, are expressed through the presented view controller’s modalPresentationStyle property. Your choices (which display more legacy “modal” names) are:

UIModalPresentationFullScreen
The default. As on the iPhone, the presenting view controller is the root view controller or a fullscreen presented view controller, and its view — meaning the entire interface — is replaced. (This is the only mode in which UIModalTransitionStylePartialCurl is legal.)
UIModalPresentationPageSheet
Similar to UIModalPresentationFullScreen, but in a landscape orientation, the presented view has the width of the portrait-oriented screen, so the presenting view controller’s view remains partially visible behind the presented view controller’s view, dimmed so that the user can’t interact with it.
UIModalPresentationFormSheet
Similar to UIModalPresentationPageSheet, but the presented view controller’s view is smaller, allowing the user to see more of the presenting view controller’s view behind it. As the name implies, this is intended to allow the user to fill out a form (Apple describes this as “gathering structured information from the user”).
UIModalPresentationCurrentContext
The presenting view controller is not necessarily the root view controller or a fullscreen presented view controller; it can be any view controller, such as a child view controller or a popover’s view controller. The presented view controller’s view replaces the presenting view controller’s view, both of which may occupy only a portion of the screen.

When the presented view controller’s modalPresentationStyle is UIModalPresentationCurrentContext, 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 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:

  1. Starting with the original presenter (the view controller to which presentViewController:animated:completion: was sent), we walk up the chain of parent view controllers, looking for one whose definesPresentationContext property is YES. If we find one, that’s the one; it will be the presentingViewController, and its view will be replaced by the presented view controller’s view.

    (If we don’t find one, things work as if the presented view controller’s modalPresentationStyle had been UIModalPresentationFullScreen.)

  2. If, during the search just described, we find a view controller whose definesPresentationContext property is YES, we also look to see if that view controller’s providesPresentationContextTransitionStyle property is also YES. If so, that view controller’s modalTransitionStyle is used for this transition animation, instead of using the presented view controller’s modalTransitionStyle.

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 a universal version of 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 iPad storyboard, put a button in the First View Controller view, and connect it to an action method in FirstViewController.m that summons the new view controller as a presented view controller:

- (IBAction)doPresent:(id)sender {
    UIViewController* vc = [ExtraViewController new];
    [self presentViewController:vc animated:YES completion:nil];
}

(You’ll also need to import "ExtraViewController.h" at the top of that file, obviously.) Run the project in the iPad Simulator, 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.

Now change the code to look like this:

- (IBAction)doPresent:(id)sender {
    UIViewController* vc = [ExtraViewController new];
    self.definesPresentationContext = YES;
    vc.modalPresentationStyle = UIModalPresentationCurrentContext;
    [self presentViewController:vc animated:YES completion:nil];
}

Run the project in the iPad Simulator, 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 (while the first view remains covered by the presented view). That’s because the presented view controller’s modalPresentationStyle is UIModalPresentationCurrentContext, and the original presenter’s definesPresentationContext is YES. Thus the search for a context stops in FirstViewController (the original presenter), which thus also becomes the presenting view controller — and 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)doPresent:(id)sender {
    UIViewController* vc = [ExtraViewController new];
    self.definesPresentationContext = YES;
    self.providesPresentationContextTransitionStyle = YES;
    self.modalTransitionStyle = UIModalTransitionStyleFlipHorizontal;
    vc.modalPresentationStyle = UIModalPresentationCurrentContext;
    vc.modalTransitionStyle = UIModalTransitionStyleCoverVertical;
    [self presentViewController:vc animated:YES completion:nil];
}

The transition uses the flip horizontal animation belonging to the presenting view controller, rather than the cover vertical animation of the presented view controller.

It’s helpful to experiment with the above code, commenting out individual lines to see what effect they have on the overall result. Note too that all the properties discussed in this section can be set by way of the nib editor.

Finally, put the same button with the same action in the iPhone storyboard, and observe that none of this works; the UIModalPresentationCurrentContext, and all that follows from it, is an iPad-only feature.

There is, however, one more presentation style (other than UIModalPresentationFullScreen) that works on the iPhone — UIModalPresentationCustom. Its use has to do with custom transition animations, which I’ll discuss later in this chapter.

When a view controller is presented, and its presentation style is not UIModalPresentationFullScreen, 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 becoming the top-level view controller, supplanting the root view controller. To make the answer be yes, set this view controller’s modalPresentationCapturesStatusBarAppearance to YES.

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 be forced to rotate as the presented view appears — and the same thing will be true in reverse when the presented view controller is dismissed. This 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.

Note

In iOS 6 and iOS 7, a presented view controller is the only officially sanctioned way to force the interface to rotate. In iOS 5 and before, the interface could be forced to rotate by other kinds of view controller transition, such as pushing a view controller onto a navigation controller’s stack, but this is no longer the case; attempts to circumvent this change and restore the iOS 5 behavior are generally futile (and unnecessary).

For example, in my Latin flashcard app (Figure 6-3), the individual flashcards are viewed only in landscape orientation. But there is also an option to display a list (a UITableView) of all vocabulary, which is permitted to assume portrait orientation only. Therefore the interface rotates when the vocabulary list appears (to portrait orientation), and again when it disappears (back to landscape orientation); the user is expected to respond by rotating the device. Here’s how this is achieved:

  • The app as a whole, as dictated by its Info.plist, supports three orientations, in this order: “Landscape (right home button),” “Landscape (left home button),” and “Portrait” — the set of all orientations the app will ever be permitted to assume.
  • The RootViewController class implements supportedInterfaceOrientations to return UIInterfaceOrientationMaskLandscape.
  • The AllTermsListController class, whose view contains the total vocabulary list, implements supportedInterfaceOrientations to return UIInterfaceOrientationMaskPortrait — and an AllTermsListController instance is used only as a presented view controller.

In addition, a presented view controller whose supportedInterfaceOrientations: is a mask permitting multiple possible orientations is able to specify which of those orientations it would like to appear in initially. To do so, override preferredInterfaceOrientationForPresentation; this method is called before supportedInterfaceOrientations:, and should return a single interface orientation (not a mask). For example:

-(UIInterfaceOrientation)preferredInterfaceOrientationForPresentation {
    return UIInterfaceOrientationPortrait;
}
-(NSUInteger)supportedInterfaceOrientations {
    return UIInterfaceOrientationMaskAll;
}

That says, “When I am summoned initially as a presented view controller, the app should be rotated to portrait orientation. After that, while my view is being presented, the app can rotate to compensate for any orientation of the device.”

The presented view controller’s supportedInterfaceOrientations (preceded by its preferredInterfaceOrientationForPresentation if implemented) is consulted when the presented view controller is first summoned. Subsequently, both the presenting and presented view controllers’ supportedInterfaceOrientations are called on each rotation of the device, and the presenting view controller’s supportedInterfaceOrientations is called when the presented view controller is dismissed. Both view controllers may get layout events both when the presented view controller is summoned and when it is dismissed.

Presenting a View in Response to Rotation

An interesting alternative to performing complex layout on rotation, as in Rotation and Layout Events, might be to summon a presented view controller instead. We detect the rotation of the device directly. If the device passes into a landscape orientation, we present a view controller whose view is suited to landscape orientation; if the device passes out of landscape orientation, we dismiss that view controller.

Call the two view controllers ViewController and SecondViewController. SecondViewController is landscape-only:

-(NSUInteger)supportedInterfaceOrientations {
    return UIInterfaceOrientationMaskLandscape;
}

ViewController sets itself up to receive notifications when the device orientation changes. When such a notification arrives, it presents or dismisses SecondViewController as appropriate:

- (void) viewDidLoad {
    [super viewDidLoad];
    [[UIDevice currentDevice] beginGeneratingDeviceOrientationNotifications];
    [[NSNotificationCenter defaultCenter]
        addObserver:self selector:@selector(screenRotated:)
        name:UIDeviceOrientationDidChangeNotification object:nil];
}
- (void)screenRotated:(NSNotification *)n {
    UIDeviceOrientation r = [UIDevice currentDevice].orientation;
    if (UIDeviceOrientationIsLandscape(r) & !self.presentedViewController) {
        UIViewController* vc = [SecondViewController new];
        vc.modalTransitionStyle = UIModalTransitionStyleCrossDissolve;
        [self presentViewController:vc animated:YES completion:nil];
    } else if (UIDeviceOrientationPortrait == rot) {
        [self dismissViewControllerAnimated:YES completion:nil];
    }
}

This works, but it lacks the animated rotation of the status bar as we transition from portrait to landscape or from landscape to portrait. Adding the status bar rotation is tricky, because setStatusBarOrientation:animated:, the UIApplication instance method we want to call, doesn’t actually perform any animation unless supportedInterfaceOrientations returns 0 — which the documentation says is forbidden. Nevertheless, I’ll demonstrate a way to do it.

In SecondViewController, supportedInterfaceOrientations now allows the interface to rotate automatically if the user switches from one landscape orientation to the other, but returns 0 if we’re rotating back to portrait:

-(NSUInteger)supportedInterfaceOrientations {
    if ([UIDevice currentDevice].orientation == UIDeviceOrientationPortrait)
        return 0;
    return UIInterfaceOrientationMaskLandscape;
}

And here’s ViewController:

-(NSUInteger)supportedInterfaceOrientations {
    return 0;
}
- (void) viewDidLoad {
    [super viewDidLoad];
    [[UIDevice currentDevice] beginGeneratingDeviceOrientationNotifications];
    [[NSNotificationCenter defaultCenter]
        addObserver:self selector:@selector(screenRotated:)
        name:UIDeviceOrientationDidChangeNotification object:nil];
}
- (void)screenRotated:(NSNotification *)n {
    UIDeviceOrientation r = [UIDevice currentDevice].orientation;
    UIInterfaceOrientation r2 = (UIInterfaceOrientation)r;
    if (UIDeviceOrientationIsLandscape(r) & !self.presentedViewController) {
        [[UIApplication sharedApplication]
            setStatusBarOrientation:r2 animated:YES];
        UIViewController* vc = [SecondViewController new];
        vc.modalTransitionStyle = UIModalTransitionStyleCrossDissolve;
        [self presentViewController:vc animated:YES completion:nil];
    } else if (UIDeviceOrientationPortrait == r) {
        [[UIApplication sharedApplication]
            setStatusBarOrientation:r2 animated:YES];
        [self dismissViewControllerAnimated:YES completion:nil];
    }
}

Tab Bar Controllers

A tab bar (UITabBar, see also Chapter 12) is a horizontal bar containing items. Each item is a UITabBarItem; it displays, by default, an image and a title. At all times, exactly one of these items is selected (highlighted); when the user taps an item, it becomes the selected item.

If there are too many items to fit on a tab bar, the excess items are automatically subsumed into a final More item. When the user taps the More item, a list of the excess items appears, and the user can select one; the user can also be permitted to edit the tab bar, determining which items appear in the tab bar itself and which ones spill over into the More list.

A tab bar is an independent interface object, but it is most commonly used in conjunction with a tab bar controller (UITabBarController, a subclass of UIViewController) to form a tab bar interface. The tab bar controller displays the tab bar at the bottom of its own view. From the user’s standpoint, the tab bar items correspond to views; when the user selects a tab bar item, the corresponding view appears. The user is thus employing the tab bar to choose an entire area of your app’s functionality. In reality, the UITabBarController is a parent view controller; you give it child view controllers, which the tab bar controller then contains, and the views summoned by tapping the tab bar items are the views of those child view controllers.

Familiar examples of a tab bar interface on the iPhone are Apple’s Clock app, which has four tab bar items, and Apple’s Music app, which has four tab bar items plus a More item that reveals a list of five more.

You can get a reference to the tab bar controller’s tab bar through its tabBar property. In general, you won’t need this. When using a tab bar interface by way of a UITabBarController, you do not interact (as a programmer) with the tab bar itself; you don’t create it or set its delegate. You provide the UITabBarController with children, and it does the rest; when the UITabBarController’s view is displayed, there’s the tab bar along with the view of the selected item. You can, however, customize the look of the tab bar (see Chapter 12 for details).

As discussed earlier in this chapter, your app’s automatic rotation in response to user rotation of the device depends on the interplay between the app (represented by the Info.plist and the app delegate) and the top-level view controller. If a UITabBarController is the top-level view controller, it will help determine your app’s automatic rotation, through its implementation of supportedInterfaceOrientations. By default, a UITabBarController does not implement supportedInterfaceOrientations, so your interface will be free to rotate to any orientation permitted by the app as a whole.

In iOS 6, the only way around this was to subclass UITabBarController for the sole purpose of implementing supportedInterfaceOrientations, like this:

@implementation MyTabBarController : UITabBarController
-(NSUInteger)supportedInterfaceOrientations {
    return UIInterfaceOrientationMaskPortrait;
}
@end

It seems silly, however, to be compelled to subclass UITabBarController merely to take control of its rotation behavior, and in iOS 7 there’s a better way: you can govern the tab bar controller’s rotation behavior in its delegate instead, by implementing tabBarControllerSupportedInterfaceOrientations:. In this example, the tab bar controller’s first child view controller makes itself the tab bar controller’s delegate, and prevents the app from rotating:

-(void)viewDidLoad {
    [super viewDidLoad];
    self.tabBarController.delegate = self;
}
-(NSUInteger)tabBarControllerSupportedInterfaceOrientations:
        (UITabBarController *) tabBarController {
    return UIInterfaceOrientationMaskPortrait;
}

Another tab bar controller delegate method that’s new in iOS 7, tabBarControllerPreferredInterfaceOrientationForPresentation:, comes into play when the tab bar controller is a presented view controller. It dictates the orientation to which the app will rotate when the tab bar controller’s view initially appears as a presented view.

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:

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

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

New in iOS 7, you can add a separate selectedImage (possibly by initializing with initWithTitle:image:selectedImage:). The selectedImage will be displayed in place of the normal image when this tab bar item is selected in the tab bar.

The image (and selectedImage) for a tab bar item should be a 30×30 PNG; if it is larger, it will be scaled down as needed. By default, it will be treated as a transparency mask (a template): the hue of its pixels will be ignored, and the transparency of its pixels will be combined with the tab bar’s tintColor, which may be inherited from higher up the view hierarchy. However, new in iOS 7, you can instead display the image as is, and not as a transparency mask. Send your image the imageWithRenderingMode: message, with an argument of UIImageRenderingModeAlwaysOriginal (see Chapter 2), and use the resulting image in your tab bar item.

(The finishedSelectedImage and finishedUnselectedImage of iOS 5 and 6 are thus no longer necessary, and are deprecated in iOS 7.)

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

Configuring a Tab Bar Controller

As I’ve already said, you configure a tab bar controller by handing 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 excerpted from the app delegate’s application:didFinishLaunchingWithOptions: of one of my apps, in which I construct and display a tab bar interface in code:

UITabBarController* tbc = [UITabBarController new];
UIViewController* b = [GameBoardController new];
UIViewController* s = [SettingsController new]
UINavigationController* n =
    [[UINavigationController alloc] initWithRootViewController:s];
tbc.viewControllers = @[b, n];
self.window.rootViewController = tbc;

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, 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 override initWithNibName:bundle: (or initWithCoder: or awakeFromNib, if appropriate) for this purpose. For example, in the same app as the previous code:

// GameBoardController.m:
- (id) initWithNibName:(NSString *)nib bundle:(NSBundle *)bundle {
    self = [super initWithNibName:nib bundle:bundle];
    // we will be embedded in a tab view, configure
    if (self) {
        UIImage* im = [UIImage imageNamed:@"game.png"];
        self.tabBarItem.image = im;
        self.title = @"Game";
    }
    return self;
}

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 tell the tab bar controller which tab bar item should be selected, you can couch your choice in terms of the contained view controller (selectedViewController) or by index number in the array (selectedIndex). The same properties also tell you what view controller’s view the user has displayed by tapping in the tab bar.

New in iOS 7, you can supply an animation when a tab bar controller’s selected tab item changes and one child view controller’s view is replaced by another. I’ll discuss this topic later in the chapter.

You can also set the UITabBarController’s delegate; the delegate should adopt the UITabBarControllerDelegate protocol. 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 also 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 directly in the nib, such as its system item or its title, image (but not its 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.

Note

See the discussion earlier in this chapter of how a view controller’s view is resized to fit the interface. You will want to prepare your view for this resizing. In iOS 7, a tab bar controller’s child controller’s view by default will underlap the tab bar if the tab bar is translucent.

Navigation Controllers

A navigation bar (UINavigationBar, see also Chapter 12) is a horizontal bar displaying a center title and a right button. When the user taps the right button, the navigation bar animates, sliding its interface out to the left and replacing it with a new interface that enters from the right. The new interface displays a back button at the left side, and a new center title — and possibly a new right button. The user can tap the back button to go back to the first interface, which slides in from the left; or, if there’s a right button in the second interface, the user can tap it to go further forward to a third interface, which slides in from the right.

The successive interfaces of a navigation bar thus behave like a stack. In fact, a navigation bar does represent an actual stack — an internal stack of navigation items (UINavigationItem). It starts out with one navigation item: the root or bottom item of the stack. Since there is just one navigation item, this is also the top item of the stack (the navigation bar’s topItem). It is the top item whose interface is always reflected in the navigation bar. When the user taps a right button, a new navigation item is pushed onto the stack; it becomes the top item, and its interface is seen. When the user taps a back button, the top item is popped off the stack, and what was previously the next item beneath it in the stack — the back item (the navigation bar’s backItem) — becomes the top item, and its interface is seen.

The state of the stack is thus reflected in the navigation bar’s interface. The navigation bar’s center title comes automatically from the top item, and its back button comes from the back item. (See Chapter 12 for a complete description.) Thus, the title tells the user what item is current, and the left side is a button telling the user what item we would return to if the user were to tap that button. The animations reinforce this notion of directionality, giving the user a sense of position within a chain of items.

A navigation bar is an independent interface object, but it is most commonly used in conjunction with a navigation controller (UINavigationController, a subclass of UIViewController) to form a navigation interface. Just as there is a stack of navigation items in the navigation bar, there is a stack of view controllers in the navigation controller. These view controllers are the navigation controller’s children, and each navigation item belongs to a view controller — it is a view controller’s navigationItem.

The navigation controller performs automatic coordination of the navigation bar and the overall interface. Whenever a view controller comes to the top of the navigation controller’s stack, its view is displayed in the interface. At the same time, its navigationItem is automatically pushed onto the top of the navigation bar’s stack — and thus is automatically displayed in the navigation bar. Moreover, the animation in the navigation bar is reinforced by animation of the interface as a whole: by default, a view controller’s view slides into the main interface from the left or right just as its navigation item slides into the navigation bar from the left or right. (New in iOS 7, the animation of the view controller’s view can be changed; I’ll discuss that later in the chapter.)

Your code can control the overall navigation, so in real life, the user may well navigate to the right, not by tapping the right button in the navigation bar, but by tapping something inside the main interface, such as a listing in a table view. (Figure 6-1 is a navigation interface that works this way.) In this situation, your code is deciding in real time what the next view should be; typically, you won’t even create the next view controller until the user asks to navigate to it. The navigation interface thus becomes a master–detail interface.

Conversely, you might put a view controller inside a navigation controller just to get the convenience of the navigation bar, with its title and buttons, even when no actual push-and-pop navigation is going to take place.

You can get a reference to the navigation controller’s navigation bar through its navigationBar property. In general, you won’t need this. When using a navigation interface by way of a UINavigationController, you do not interact (as a programmer) with the navigation bar itself; you don’t create it or set its delegate. You provide the UINavigationController with children, and it does the rest, handing each child view controller’s navigationItem to the navigation bar for display and showing the child view controller’s view each time navigation occurs. You can, however, customize the look of the navigation bar (see Chapter 12 for details).

A navigation interface may also optionally display a toolbar at the bottom. A toolbar (UIToolbar) is a horizontal view displaying a row of items, any of which the user can tap. Typically, the tapped item may highlight momentarily, but it is not selected; it represents the initiation of an action, like a button. You can get a reference to a UINavigationController’s toolbar through its toolbar property. The look of the toolbar can be customized (Chapter 12). In a navigation interface, however, the contents of the toolbar are determined automatically by the view controller that is currently the top item in the stack: they are its toolbarItems.

Note

A UIToolbar can also be used independently, and often is. It then typically appears at the bottom on an iPhone — Figure 6-3 has a toolbar at the bottom — but often appears at the top on an iPad, where it plays something of the role that the menu bar plays on the desktop. When a toolbar is displayed by a navigation controller, though, it always appears at the bottom.

A familiar example of a navigation interface is Apple’s Settings app on the iPhone. The Mail app on the iPhone is a navigation interface that includes a toolbar.

As discussed earlier in this chapter, your app’s automatic rotation in response to user rotation of the device depends on the interplay between the app (represented by the Info.plist and the app delegate) and the top-level view controller. If a UINavigationController is the top-level view controller, it will help determine your app’s automatic rotation, through its implementation of supportedInterfaceOrientations. By default, a UINavigationController does not implement supportedInterfaceOrientations, so your interface will be free to rotate to any orientation permitted by the app as a whole.

In iOS 6, the only way around this was to subclass UINavigationController for the sole purpose of implementing supportedInterfaceOrientations, like this:

@implementation MyNavigationController : UINavigationController
-(NSUInteger)supportedInterfaceOrientations {
    return UIInterfaceOrientationMaskPortrait;
}
@end

It seems silly, however, to be compelled to subclass UINavigationController merely to take control of its rotation behavior, and in iOS 7 there’s a better way: you can govern the navigation controller’s rotation in its delegate instead, by implementing navigationControllerSupportedInterfaceOrientations:.

Another navigation controller delegate method that’s new in iOS 7, navigationControllerPreferredInterfaceOrientationForPresentation:, comes into play when a navigation controller is a presented view controller. It dictates the orientation to which the app will rotate when the navigation controller’s view initially appears as a presented view.

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:

Basic bar button item
The bar button item behaves like a simple button.
Custom view
The bar button item has no inherent behavior, but has (and displays) a customView.

UIBarItem is not a UIView subclass. A basic bar button item is button-like, but it has no frame, no UIView touch handling, and so forth. A UIBarButtonItem’s customView, however, is a UIView — indeed, it can be any kind of UIView. Thus, a bar button item with a customView can display any sort of view in a toolbar or navigation bar, and that view can implement touch handling 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, the image 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, new in iOS 7, you can instead display the image as is, and not as a transparency mask. Send your image the imageWithRenderingMode: message, with an argument of UIImageRenderingModeAlwaysOriginal (see Chapter 2), and use the resulting image in your bar button item.

A basic bar button item has a style property; this will usually be UIBarButtonItemStylePlain. The alternative, UIBarButtonItemStyleDone, 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.

Warning

A bar button item looks quite different in iOS 7 from iOS 6 and before. In iOS 6, a bar button item could display both an image and a title (in a toolbar), and there was usually a border around the item (though this could be prevented in a toolbar by using UIBarButtonItemStylePlain). In iOS 7, the bar button item never draws its own border, and the UIBarButtonItemStyleBordered style is irrelevant. And the use and effect of the tintColor is completely changed in iOS 7. Adapting your iOS 6 app to look good when compiled for iOS 7 can be quite a chore.

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

There are three ways to make a bar button item:

By borrowing it from the system
Instantiate UIBarButtonItem using initWithBarButtonSystemItem:target:​action:. Consult the documentation for the list of available system items; they are not the same as for a tab bar item. You can’t assign a title or change the image. (But you can change the tint color or assign a background image.)
By making your own basic bar button item

Instantiate UIBarButtonItem using initWithTitle:style:target:action: or initWithImage:style:target:action:.

An additional method, initWithImage:landscapeImagePhone:style:target:​action:, lets you supply two images, one for portrait orientation, the other for landscape orientation; this is because by default, the bar’s height might change when the interface is rotated.

By making a custom view bar button item
Instantiate UIBarButtonItem using initWithCustomView:, supplying a UIView that the bar button item is to display. The bar button item has no action and target; the UIView itself must somehow implement button behavior if that’s what you want. For example, the customView might be a UISegmentedButton, but then it is the UISegmentedButton’s target and action that give it button behavior.

Bar button items in a toolbar are horizontally positioned automatically by the system. You can provide hints to help with this positioning. If you know that you’ll be changing an item’s title dynamically, you’ll probably want its width to accommodate the longest possible title right from the start; to arrange that, set the possibleTitles property to an NSSet 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 initWithBarButtonSystemItem:target:action:, but they have no visible appearance, and cannot be tapped. The UIBarButtonSystemItemFlexibleSpace is the one most frequently used; place these between the visible items to distribute the visible items equally across the width of the toolbar. There is also a UIBarButtonSystemItemFixedSpace whose width lets you insert a space of defined size.

Navigation Items and Toolbar Items

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

title or titleView

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

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

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

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

A segmented control in the center of a navigation bar
Figure 6-8. A segmented control in the center of a navigation bar
prompt
An optional string to appear centered above everything else in the navigation bar. The navigation bar’s height will be increased to accommodate it.
rightBarButtonItem or rightBarButtonItems

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

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

backBarButtonItem

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

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

UIBarButtonItem* b =
    [[UIBarButtonItem alloc] initWithTitle:@"Go Back"
      style:UIBarButtonItemStylePlain target:nil action:nil];
self.navigationItem.backBarButtonItem = b;

A BOOL property, hidesBackButton, allows the top navigation item to suppress display of the back item’s back bar button item. Obviously, if you set this to YES, you’ll probably ensure some other means of letting the user navigate back.

In iOS 7, the visible indication that the back button is a back button is a left-pointing chevron (the back indicator) that’s separate from the button itself. (This contrasts with iOS 6 and before, where the button itself had a left-pointing shape.) This chevron can also be customized, but it’s a feature of the navigation bar, not the bar button item: set the navigation bar’s backIndicatorImage and backIndicatorTransitionMask (I’ll give an example in Chapter 12). Alternatively, if the back button is assigned a background image, the back indicator is removed; it is up to the background image to point left, if desired.

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

A view controller’s navigation item can have its properties set at any time while being displayed in the navigation bar. This (and not direct manipulation of the navigation bar) is the way to change the navigation bar’s contents dynamically. For example, in one of my apps, 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:

// change the progress view
if (self->_nowPlayingItem) {
    MPMediaItem* item = self->_nowPlayingItem;
    NSTimeInterval current = self.mp.currentPlaybackTime;
    NSTimeInterval total =
        [[item valueForProperty:MPMediaItemPropertyPlaybackDuration]
            doubleValue];
    self.prog.progress = current / total;
} else {
    self.prog.progress = 0;
}
// change the bar button
int whichButton = -1;
if ([self.mp playbackState] == MPMusicPlaybackStatePlaying)
    whichButton = UIBarButtonSystemItemPause;
else if ([self.mp playbackState] == MPMusicPlaybackStatePaused ||
         [self.mp playbackState] == MPMusicPlaybackStateStopped)
    whichButton = UIBarButtonSystemItemPlay;
if (whichButton == -1)
    self.navigationItem.rightBarButtonItem = nil;
else {
    UIBarButtonItem* bb =
        [[UIBarButtonItem alloc]
            initWithBarButtonSystemItem:whichButton
            target:self action:@selector(doPlayPause:)];
    self.navigationItem.rightBarButtonItem = bb;
}

Each view controller to be pushed onto the navigation controller’s stack is responsible 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.

A view controller 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 YES. 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. For more flexibility, you can send setToolbarHidden:animated: to the UINavigationController at any time.

You configure a navigation controller by manipulating its stack of view controllers. This stack is the navigation controller’s viewControllers array property, though, as I’ll explain in a moment, 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 initWithRootViewController:; 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:

FirstViewController* fvc = [FirstViewController new];
UINavigationController* nav =
    [[UINavigationController alloc] initWithRootViewController:fvc];
self.window.rootViewController = nav;

Instead of initWithRootViewController:, you might choose to create the navigation controller with initWithNavigationBarClass:toolbarClass:, in which case you’ll have to set its root view controller in a subsequent line of code. The reason for wanting to set the navigation bar and toolbar class has to do with customization of 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.

You can also set the UINavigationController’s delegate; the delegate should adopt the UINavigationControllerDelegate protocol. 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 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:

// FirstViewController.m:
SecondViewController* svc = [SecondViewController new];
[self.navigationController pushViewController:svc animated:YES];

Typically, that’s all there is to it! 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.

New in iOS 7, the user can alternatively go back by dragging a pushed view controller’s view from the left edge of the screen. This too is 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: yourself; 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 view controller, 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.

The navigation controller’s navigation bar will automatically display the navigationItem of the topViewController (and the back button of the navigationItem of the back view controller). Thus, a child view controller will probably want to configure its navigationItem early in its lifetime, so that the navigationItem is ready 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; however, Apple’s own code examples, including the Master–Detail Application template, violate this warning. It is probably best to override initWithNibName:bundle: (or initWithCoder: 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:.

You can also 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 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 button and right button of its navigationItem. Moreover, the Navigation Item has outlets, one of which permits you to set its titleView. (However, you can’t assign a navigation item multiple rightBarButtonItems or leftBarButtonItems in the nib editor.) 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: 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.

Note

See the discussion earlier in this chapter of how a view controller’s view is resized to fit the interface. You will want to prepare your view for this resizing. In iOS 7, a navigation controller’s child controller’s view by default will underlap a navigation bar or toolbar if the bar is translucent; if it underlaps a navigation bar, it will also underlap the status bar. If the view does not underlap a bar and you hide or show that bar dynamically, the view will be resized then and there. If you show or hide the status bar dynamically, the navigation bar’s height will expand or contract accordingly; this too may cause the view’s size to change. Showing or hiding the navigation bar or status bar will cause your view controller’s topLayoutGuide to move; showing or hiding the toolbar will cause your view controller’s bottomLayoutGuide to move.

Custom Transition Animations

New in iOS 7, you can supply your own custom transition animation for a tab bar controller as its selected view controller changes, for a navigation controller as its child view controller is pushed or popped, or for a presented view controller as it is presented or dismissed.

Given the extensive animation resources of iOS 7 (see Chapter 4), this is an excellent chance for you to provide your app with variety, interest, and distinctiveness. The view of a child view controller pushed onto a navigation controller’s stack needn’t arrive sliding from the right; it can expand by zooming from the middle of the screen, drop from above and fall into place with a bounce, snap into place like a spring, or whatever else you can dream up.

In your custom transition animation, you have control of both the outgoing view controller’s view and the incoming view controller’s view. Moreover, you are free to add further temporary views during the course of the animation. For example, as the outgoing view departs and the incoming view arrives, a third view can move across from the outgoing view to the incoming view. This might be a way for you to suggest or emphasize the significance of the transition that is now taking place. In a master–detail navigation interface, for instance, where the master view is a list of story titles, when the user taps a title and the detail view arrives to reveal the full story, the tapped title might simultaneously fly from its place within the list to its new place at the top of the full story, to clarify that these are the same story.

As you contemplate what might be possible and how it might be achieved, don’t forget about view snapshotting (see Chapter 2). This is exactly why snapshotting was invented for iOS 7. Instead of moving a view, which could upset the arrangement of things, you can take a snapshot of that view and move the snapshot.

In addition, a custom animation can be interactively gesture-driven (similar to the way a navigation controller’s view can be popped, in iOS 7, by dragging from the left edge of the screen). The user does not merely tap and cause an animation to take place; the user performs an extended gesture and gradually summons the new view to supersede the old one. The user can thus participate in the progress of the transition.

Noninteractive Custom Transition Animation

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

  1. The view controller in charge of the transition must have a delegate.
  2. As the transition begins, the delegate will be asked for an animation controller. This can be any object adopting the UIViewControllerAnimatedTransitioning protocol. Return nil to specify that the default animation (if any) should be used.

  3. The animation controller will be sent two messages:

    transitionDuration:
    The duration of the custom animation.
    animateTransition:
    The animation controller should perform the animation.

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

To illustrate, I’ll start by animating the transition between two child view controllers of a tab bar controller. The most obvious custom animation is that the new view controller’s view should slide in from the 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.

The first step is to configure a delegate for the tab bar controller. Let’s assume that the tab bar controller is our app’s root view controller. For simplicity, I’ll set its delegate in the app delegate’s application:didFinishLaunchingWithOptions:, and I’ll make that delegate be the app delegate itself:

UITabBarController* tbc = (UITabBarController*)self.window.rootViewController;
tbc.delegate = self;

The result is that when the user taps a tab bar item to change view controllers, the corresponding delegate method is called, asking for an animation controller. This is what that delegate method looks like for a tab bar controller:

- (id<UIViewControllerAnimatedTransitioning>)
        tabBarController:
            (UITabBarController *)tabBarController
        animationControllerForTransitionFromViewController:
            (UIViewController *)fromVC
        toViewController:
            (UIViewController *)toVC {
    return self;
}

There is no particular reason why the animation controller should be self; indeed, the animation code can be rather elaborate, and it might make for cleaner code to move it off into a class of its own. The animation controller can be any object implementing the UIViewControllerAnimatedTransitioning protocol, and thus may be extremely lightweight; it can be a simple NSObject.

There is also no reason why the animation controller should be the same object every time this method is called. We are provided with plenty of information about what’s about to happen: we know the tab bar controller and both child view controllers. Thus we could readily decide in real time to provide a different animation controller under different circumstances, or we could return nil to use the default transition (which, for a tab bar controller, means no animation).

One way or another, then, here we are in the animation controller. Our first job is to reveal in advance the duration of our animation:

-(NSTimeInterval)transitionDuration:
        (id<UIViewControllerContextTransitioning>)transitionContext {
    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:

-(void)animateTransition:
        (id<UIViewControllerContextTransitioning>)transitionContext {
    // ...
}

There are certain standard tasks to perform in animateTransition:, so its structure will be roughly the same in every case:

  1. Query the transition context (the transitionContext parameter) to get the view controllers, the frames of their views, and the container view.
  2. Put the second view controller’s view into the container view.
  3. Perform the animation, ending with completeTransition:.

First, query the transition context. This code is practically boilerplate for any custom view controller transition animation:

UIViewController* vc1 =
    [transitionContext viewControllerForKey:
        UITransitionContextFromViewControllerKey];
UIViewController* vc2 =
    [transitionContext viewControllerForKey:
        UITransitionContextToViewControllerKey];
UIView* con = [transitionContext containerView];
CGRect r1start = [transitionContext initialFrameForViewController:vc1];
CGRect r2end = [transitionContext finalFrameForViewController:vc2];
UIView* v1 = vc1.view;
UIView* v2 = vc2.view;

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, for our intended animation, we want to calculate the converse, 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:

UITabBarController* tbc = (UITabBarController*)self.window.rootViewController;
int ix1 = [tbc.viewControllers indexOfObject:vc1];
int ix2 = [tbc.viewControllers indexOfObject:vc2];
int dir = ix1 < ix2 ? 1 : -1;
CGRect r = r1start;
r.origin.x -= r.size.width * dir;
CGRect r1end = r;
r = r2end;
r.origin.x += r.size.width * dir;
CGRect r2start = r;

We now put the second view controller’s view into the container view at its initial frame, and perform the animation. We must not forget to call completeTransition: after the animation ends:

v2.frame = r2start;
[con addSubview:v2];
[UIView animateWithDuration:0.4 animations:^{
    v1.frame = r1end;
    v2.frame = r2end;
} completion:^(BOOL finished) {
    [transitionContext completeTransition:YES];
}];

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 a custom transition animation:

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 using 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. We’re going to need an interactive 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:

Create a UIPercentDrivenInteractiveTransition object
We supply a UIPercentDrivenInteractiveTransition object (let’s call this the percent driver). This percent driver object performs the frames of the animation for us by calling our animateTransition: and “freezing” the animation block. All we have to do is track the interaction and call the percent driver’s updateInteractiveTransition:, telling it how far the interaction has proceeded; the percent driver updates the interface, performing our animation partially to match the extent of the gesture. At the end of the gesture, we decide whether to finish or cancel the transition; accordingly, we call the percent driver’s finishInteractiveTransition or cancelInteractiveTransition. Finally, we call the transition context’s completeTransition:
Adopt UIViewControllerInteractiveTransitioning
We supply our own object with our own code. This object, conforming to the UIViewControllerInteractiveTransitioning protocol, will need to respond to startInteractiveTransition:, whose parameter will be the transitionContext object supplied by the system, adopting the UIViewControllerContextTransitioning protocol. Once we are told that the transition has started, we will set up the initial conditions for the animation and then constantly track the interaction, changing the interface and calling the transition context’s updateInteractiveTransition:. When the interaction ends, we decide whether to finish or cancel the transition; accordingly, we animate into the final or initial conditions, and call the transition context’s finishInteractiveTransition or cancelInteractiveTransition. Finally, we call the transition context’s completeTransition:.

As an example, I’ll describe how to make an interactive version of the tab bar controller transition animation that we’ve just developed. We’ll attach a UIScreenEdgePanGestureRecognizer to the interface so that the user can drag the tab bar controller’s adjacent view controller in from the right or from the left.

Since we have already written a noninteractive version of our transition animation, using the percent driver is going to be the simpler approach, because it lets us keep our existing animateTransition: code. So let’s do that first. The steps build upon those of a noninteractive transition animation; in fact, all the code we’ve already written can be left more or less as is (which is one of the main reasons for using a percent driver):

  1. The view controller in charge of the transition must have a delegate.
  2. We observe that the user is interacting in a way that should trigger a change of view controller. We respond by triggering that change.
  3. As the transition begins, the delegate will be asked for an animation controller, as before. We return an object adopting the UIViewControllerAnimatedTransitioning protocol, as before.
  4. The delegate is also asked for an interactive controller. (This happened before, but we didn’t supply one, which is why our transition animation wasn’t interactive.) We have elected to use a UIPercentDrivenInteractiveTransition object. So we return that object.

  5. The animation controller is sent the same two messages as before:

    transitionDuration:
    The duration of the custom animation.
    animateTransition:
    The animation controller should perform the animation. But the animation will not in fact take place at this moment; its “frames” will be produced as the interaction proceeds.
  6. We continue tracking the interaction, calling our percent driver’s updateInteractiveTransition: to tell it how far the interaction has proceeded. The percent driver performs that much of our animation for us.
  7. Sooner or later the interaction will end. At this point, we must decide whether to declare the transition completed or cancelled. The usual approach is to say that if the user performed more than half the full interactive gesture, that constitutes completion; otherwise, it constitutes cancellation. We call the percent driver’s finishInteractiveTransition or cancelInteractiveTransition accordingly. The percent driver either completes the animation or (if we cancelled) reverses the animation.
  8. The animation is now completed, and its completion block is called. We call completeTransition:, with the argument stating whether the transition was finished or cancelled.

Now I’ll write the code performing the additional steps. To track the user’s gesture, I’ll put a pair of UIScreenEdgePanGestureRecognizers into the interface, and keep references to them so they can be identified later. The gesture recognizers are attached to the tab view controller’s view (tbc.view), as this will remain constant while the views of its view controllers are sliding across the screen:

UIScreenEdgePanGestureRecognizer* sep =
    [[UIScreenEdgePanGestureRecognizer alloc]
        initWithTarget:self action:@selector(pan:)];
sep.edges = UIRectEdgeRight;
[tbc.view addGestureRecognizer:sep];
sep.delegate = self;
self.rightEdger = sep;
sep =
    [[UIScreenEdgePanGestureRecognizer alloc]
        initWithTarget:self action:@selector(pan:)];
sep.edges = UIRectEdgeLeft;
[tbc.view addGestureRecognizer:sep];
sep.delegate = self;
self.leftEdger = sep;

The delegate of the two gesture recognizers prevents the pan gesture from operating unless there is another child of the tab view controller available on that side of the current child:

-(BOOL)gestureRecognizerShouldBegin:(UIScreenEdgePanGestureRecognizer *)g {
    UITabBarController* tbc =
        (UITabBarController*)self.window.rootViewController;
    BOOL result = NO;
    if (g == self.rightEdger)
        result = (tbc.selectedIndex < tbc.viewControllers.count - 1);
    else
        result = (tbc.selectedIndex > 0);
    return result;
}

So much for preparation. If the gesture recognizer action handler pan: is called, we now know that this means our interactive transition animation is to take place. I’ll break down the discussion to examine each of the gesture recognizer’s stages separately:

- (void) pan: (UIScreenEdgePanGestureRecognizer *) g {
    UIView* v = g.view;
    if (g.state == UIGestureRecognizerStateBegan) {
        self.inter = [UIPercentDrivenInteractiveTransition new];
        UITabBarController* tbc =
            (UITabBarController*)self.window.rootViewController;
        if (g == self.rightEdger)
            tbc.selectedIndex = tbc.selectedIndex + 1;
        else
            tbc.selectedIndex = tbc.selectedIndex - 1;
    }
    // ... more to come ...
}

As the gesture begins, we create the UIPercentDrivenInteractiveTransition object and store it in an instance variable (self.inter). We then set the tab bar controller’s selectedIndex. This triggers the animation! As before, the runtime turns to the tab bar controller’s delegate to see whether there is a transition animation; as before, we make ourselves the animation controller:

- (id<UIViewControllerAnimatedTransitioning>)
        tabBarController:
            (UITabBarController *)tabBarController
        animationControllerForTransitionFromViewController:
            (UIViewController *)fromVC
        toViewController:
            (UIViewController *)toVC {
    return self;
}

The runtime now asks if there is also an interactive controller. There wasn’t one in our previous example, but now there is — the percent driver:

-(id<UIViewControllerInteractiveTransitioning>)
    tabBarController:
        (UITabBarController *)tabBarController
    interactionControllerForAnimationController:
        (id<UIViewControllerAnimatedTransitioning>)animationController {
    return self.inter;
}

The runtime now calls our percent driver’s startInteractiveTransition:, handing it a reference to the transition context. This is where the magic happens. The percent driver immediately turns around and calls our animateTransition: method. Yet the animation does not happen! The percent driver has “frozen” the animation described in the animation block. Our job now is to keep calling the percent driver, telling it what “frame” of the animation to display at every moment; the percent driver will move the views to correspond to that “frame” of the animation as the interaction proceeds, and will call the transition context on our behalf.

(I suppose you’re wondering how this magic is performed. The percent driver takes advantage of the fact that a CALayer conforms to the CAMediaTiming protocol, as I mentioned in Chapter 4. It asks the transition context for the container view, obtains that view’s layer, and sets the layer’s speed to 0. This freezes the animation. Then, as we call the percent driver’s updateInteractiveTransition:, it adjusts that layer’s timeOffset accordingly, thus displaying a different “frame” of the animation.)

We are now back in the gesture recognizer’s action handler, as the gesture proceeds; we keep sending updateInteractiveTransition: to the percent driver:

- (void) pan: (UIScreenEdgePanGestureRecognizer *) g {
    UIView* v = g.view;
    // ...
    else if (g.state == UIGestureRecognizerStateChanged) {
        CGPoint delta = [g translationInView: v];
        CGFloat percent = fabs(delta.x/v.bounds.size.width);
        [self.inter updateInteractiveTransition:percent];
    }
    // ...
}

When the gesture ends, we decide whether this counts as finishing or canceling, and we report to the percent driver accordingly:

- (void) pan: (UIScreenEdgePanGestureRecognizer *) g {
    UIView* v = g.view;
    // ...
    else if (g.state == UIGestureRecognizerStateEnded) {
        CGPoint delta = [g translationInView: v];
        CGFloat percent = fabs(delta.x/v.bounds.size.width);
        if (percent > 0.5)
            [self.inter finishInteractiveTransition];
        else
            [self.inter cancelInteractiveTransition];
    }
    // ...
}

If we call finishInteractiveTransition, the percent driver plays the rest of the animation forward to completion. If we call cancelInteractiveTransition, the percent driver plays the animation backward to its beginning!

Finally, we find ourselves back inside animateTransition:, in the animation completion: handler. This is the only place where a change is needed in our previously existing code. As I’ve just said, the transition can complete in one of two ways. We must still call completeTransition: ourselves, but we must tell the transition context which way things turned out, so that the transition context can restore the previous state of things if the transition was cancelled. Luckily, the transition context already knows whether the transition was cancelled. So we ask it:

BOOL cancelled = [transitionContext transitionWasCancelled];
[transitionContext completeTransition:!cancelled];

The amazing thing is that, with only a tiny bit of further modification (not shown), the very same code will now serve us both for an interactive and a noninteractive version of the transition animation. That is the point of using a percent driver.

If we don’t use a percent driver, then the entire interactive transition animation is up to us. We ourselves must repeatedly reposition the views at every stage of the gesture, and when the gesture ends, we ourselves must animate them either into their final position or back into their initial position. We will no longer need an animateTransition: method (it must be present, to satisfy the protocol requirements, but it can be empty); all the logic of initializing, positioning, and finalizing the moving views must be effectively deconstructed and folded into the various stages of our gesture recognizer action handler. There is no percent driver; at every stage, we must keep talking to the transition context itself.

The resulting code is verbose, and can be difficult to express in a compact or object-oriented way. However, it is more powerful, more flexible, and possibly more reliable than using a percent driver. I’ll just sketch the structure. We have our gesture recognizer(s) as before. When the gesture begins, the UIGestureRecognizerStateBegan section of the action handler triggers the transition as before. The delegate is asked for an animation controller and an interaction controller; the interaction controller is now not a percent driver, but some object that we will supply — let’s say it’s self:

-(id<UIViewControllerInteractiveTransitioning>)
    tabBarController:
        (UITabBarController *)tabBarController
    interactionControllerForAnimationController:
        (id<UIViewControllerAnimatedTransitioning>)animationController {
    return self;
}

The result is that, in our role as adopter of the UIViewControllerInteractiveTransitioning protocol, our startInteractiveTransition: is called; here, we set up the initial conditions of the transition, putting the view controllers’ views into place, and storing a reference to the transitionContext in an instance variable where our gesture recognizer action handler can access it:

-(void)startInteractiveTransition:
        (id<UIViewControllerContextTransitioning>)transitionContext {
    // store transition context so the gesture recognizer can get at it
    self.context = transitionContext;
    // ... set up initial conditions ...
    // ... store any additional instance variables ...
}

Now our gesture recognizer action handler is called again, repeatedly, at the UIGestureRecognizerStateChanged stage. We keep repositioning our views (not animating them) in accordance with the progress of the interactive gesture. At the same time, we keep informing the transition context of that progress:

else if (g.state == UIGestureRecognizerStateChanged) {
    // calculate progress
    CGPoint delta = [g translationInView: v];
    CGFloat percent = fabs(delta.x/v.bounds.size.width);
    // ... put views into position corresponding to current "frame" ...
    // ... and finally, notify the transition context
    v1.frame = // whatever
    v2.frame = // whatever
    [self.context updateInteractiveTransition:percent];
}

Finally, our gesture recognizer action handler is called one last time, at the UIGestureRecognizerStateEnded stage. We now animate our views the rest of the way, or else back to the start, and call either finishInteractiveTransition or cancelInteractiveTransition followed by completeTransition: with the appropriate argument:

if (percent > 0.5) {
    [UIView animateWithDuration:0.2 animations:^{
        v1.frame = r1end;
        v2.frame = r2end;
    } completion:^(BOOL finished) {
        [transitionContext finishInteractiveTransition];
        [transitionContext completeTransition:YES];
    }];
}
else {
    [UIView animateWithDuration:0.2 animations:^{
        v1.frame = r1start;
        v2.frame = r2start;
    } completion:^(BOOL finished) {
        [transitionContext cancelInteractiveTransition];
        [transitionContext completeTransition:NO];
    }];
}

Why must we call updateInteractiveTransition: throughout the progress of the interactive gesture? For a tab bar controller’s transition, this call has little or no significance. But in the case, say, of a navigation controller, the animation has a component separate from what you’re doing — the change in the appearance of the navigation bar (as the old title departs and the new title arrives, and so forth). The transition context needs to coordinate that animation with the interactive gesture and with your animation. So you need to keep telling it where things are in the course of the interaction.

Custom Presented View Controller Transition

A new iOS 7 view controller property, transitioningDelegate, allows you to set a delegate (on the presented view controller) that will be asked for an animation controller and an interactive controller separately for both the presentation and the dismissal:

  • animationControllerForPresentedController:presentingController:sourceController:
  • interactionControllerForPresentation:
  • animationControllerForDismissedController:
  • interactionControllerForDismissal:

If you return the same object as the animation controller for both presentation and dismissal, your implementation of animateTransition: will need to distinguish which is happening. During presentation, the “from” view controller’s view is the old interface, and the “to” view controller is the presented view controller. But during dismissal, it’s the other way round: the “from” view controller is the presented view controller.

A presented view controller transition has a problem that a tab bar controller or navigation controller transition doesn’t have — there’s no existing view to serve as the container view. Therefore, as the transition begins, the runtime has to pull some serious hanky-panky (that’s a technical programming term): it creates an extra container view and inserts it into the view hierarchy, and removes it after the transition is over.

When the modal presentation style is UIModalPresentationFullScreen or UIModalPresentationCurrentContext, the effect from your point of view is similar to a tab bar controller or navigation controller animation. By the time you have a transition context, the runtime has already ripped the “from” view out of its superview, created the container view, put it into the “from” view’s old superview, and put the “from” view into the container view. You put the “to” view into the container view and do the animation, and afterward the runtime rips the “to” view out of the container view, puts it into the container view’s superview, removes the “from” view from the interface, and throws away the container view.

Other modal presentation styles, however, leave both view controllers’ views in place: the presented view controller’s view appears only partially covering the already existing view. You may have to make allowance for the special conditions of this arrangement.

Let’s consider, for example, the iPad’s UIModalPresentationFormSheet presentation style. The presented view controller’s view appears smaller than the screen, leaving the presenting view controller’s view in place, visible only “through a glass darkly”. That darkness is in fact due to an extra view, a “dimming view”; in front of the dimming view is a “drop shadow view”, and the presented view controller’s view is inside that. Moreover, at the time the custom animation begins, neither view is in the transition context’s containerView; both are already in their final places in the real interface.

This is a complicated arrangement, and we mustn’t do anything to upset it. Nevertheless, I am quite willing to pluck the presented view controller’s view from its place in the interface, stick it into the containerView, animate it, and return it to its original place. Let’s say, for instance, that we want the presented view controller’s view to appear to grow from the center of the screen. I pull the second view (v2) out of its superview, preserve its frame, animate it, restore its frame, and put it back in its old superview. The transition context has nothing useful to say about v2’s frame relative to the containerView, so I copy its superview’s frame:

-(void)animateTransition:
        (id<UIViewControllerContextTransitioning>)transitionContext {
    UIViewController* vc2 =
        [transitionContext viewControllerForKey:
            UITransitionContextToViewControllerKey];
    UIView* con = [transitionContext containerView];
    UIView* v2 = vc2.view;
    UIView* drop = v2.superview;
    CGRect oldv2frame = v2.frame;
    [con addSubview: v2];
    v2.frame = drop.frame;
    v2.transform = CGAffineTransformMakeScale(0.1, 0.1);
    [UIView animateWithDuration:0.4 animations:^{
        v2.transform = CGAffineTransformIdentity;
    } completion:^(BOOL finished) {
        [drop addSubview: v2];
        v2.frame = oldv2frame;
        [transitionContext completeTransition:YES];
    }];
}

If that seems extreme, we might prefer to leave v2 in place and animate a snapshot instead. But it is not easy to do this, because at the time animateTransition: is called, v2 has not been rendered; there is nothing to take a snapshot of. I don’t know any way to force v2 to be rendered immediately, short of calling its layer’s renderInContext:. So I do that, rendering it into an image context, and end up animating an image view:

-(void)animateTransition:
        (id<UIViewControllerContextTransitioning>)transitionContext {
    UIViewController* vc2 =
        [transitionContext viewControllerForKey:
            UITransitionContextToViewControllerKey];
    UIView* con = [transitionContext containerView];
    UIView* v2 = vc2.view;
    // force rendering and snapshot now
    UIGraphicsBeginImageContextWithOptions(v2.bounds.size, YES, 0);
    [v2.layer renderInContext:UIGraphicsGetCurrentContext()];
    UIImage* im = UIGraphicsGetImageFromCurrentImageContext();
    UIGraphicsEndImageContext();
    UIView* snap = [[UIImageView alloc] initWithImage:im];
    snap.frame = v2.superview.frame;
    snap.transform = CGAffineTransformMakeScale(0.1, 0.1);
    [con addSubview: snap];
    // animate the snapshot
    [UIView animateWithDuration:0.4 animations:^{
        snap.transform = CGAffineTransformIdentity;
    } completion:^(BOOL finished) {
        [transitionContext completeTransition:YES];
    }];
}

When the modal presentation style is UIModalPresentationCustom (new in iOS 7), the runtime leaves the final position of the presented view controller’s view entirely up to you — possibly only partially covering the existing view, even on an iPhone. This is possible because the transition context’s container view is not taken away when the presentation transition ends; it remains in place until after the dismissal transition. Therefore, you can also put extra views into the container view, and they will stay there together with the presented view controller’s view.

To illustrate, I’ll write a presented view controller that imitates a UIAlertView — a small view that floats over the existing interface, which is behind a darkened glass. This is something that developers have longed for since the earliest days of iOS. A UIAlertView is convenient and small, but you can’t (legally) customize its content very much. A presented view controller’s view, on the other hand, is completely up to you. In the past, a presented view controller’s view on the iPhone had to cover the entire screen. Now that restriction is lifted.

Our view controller, then, has a small view — let’s say about 260×150 — and we aren’t going to resize it. We will cause this view to shrink into place in the middle of the screen when it is presented, and to shrink further when it is dismissed, just as an alert view does. While our view is present, the surrounding screen behind it will be darkened slightly.

Our view controller’s modalPresentationStyle is UIModalPresentationCustom, and its transitioningDelegate is self. When the transitioning delegate methods are called, the view controller returns self as the animation controller. When animateTransition: is called, we start by gathering up the relevant information from the transition context, as usual:

UIViewController* vc1 =
    [transitionContext
        viewControllerForKey:UITransitionContextFromViewControllerKey];
UIViewController* vc2 =
    [transitionContext
        viewControllerForKey:UITransitionContextToViewControllerKey];
UIView* con = [transitionContext containerView];
UIView* v1 = vc1.view;
UIView* v2 = vc2.view;

We can distinguish presentation from dismissal easily: if this is presentation, the “to” view controller’s view is our own view:

if (v2 == self.view) {
    // ... presentation ...
}

The “to” view is not yet in the containerView. The “from” view, on the other hand, is in the containerView, where it will remain until after dismissal. We start by adding a shadow view that fills the container view, covering the “to” view and creating the “through a glass darkly” effect:

UIView* shadow = [[UIView alloc] initWithFrame:con.bounds];
shadow.backgroundColor = [UIColor colorWithWhite:0.4 alpha:0.2];
shadow.alpha = 0;
shadow.tag = 987;
[con addSubview: shadow];

Now we position the incoming view in the center of the container view, in front of the shadow view. We must be careful in our treatment of this view, because of the possibility that the interface will be rotated. If the interface has already been rotated when presentation occurs, the incoming view has a transform; we mustn’t accidentally remove that transform. If the interface is rotated while our view is present, our view mustn’t be resized as its superview’s bounds dimensions are swapped; I’ll use an autoresizing mask to ensure that:

v2.center =
    CGPointMake(CGRectGetMidX(con.bounds), CGRectGetMidY(con.bounds));
v2.autoresizingMask =
    UIViewAutoresizingFlexibleTopMargin |
    UIViewAutoresizingFlexibleBottomMargin |
    UIViewAutoresizingFlexibleRightMargin |
    UIViewAutoresizingFlexibleLeftMargin;
CGAffineTransform scale = CGAffineTransformMakeScale(1.6,1.6);
v2.transform = CGAffineTransformConcat(scale, v2.transform);
v2.alpha = 0;
[con addSubview: v2];

Both the shadow view and our view are initially invisible. We animate them into visibility, shrinking our view’s scale transform to its proper size at the same time. As we do so, we set the existing view’s tintAdjustmentMode to its dimmed appearance, just as a UIAlertView does, to add to the sense that the user can work only within our view (see Chapter 12 for more about the tintAdjustmentMode):

v1.tintAdjustmentMode = UIViewTintAdjustmentModeDimmed;
[UIView animateWithDuration:0.25 animations:^{
    v2.alpha = 1;
    v2.transform =
        CGAffineTransformConcat(CGAffineTransformInvert(scale), v2.transform);
    shadow.alpha = 1;
} completion:^(BOOL finished) {
    [transitionContext completeTransition:YES];
}];

At dismissal time, both views and our extra shadow view are still in the containerView. We animate away the shadow view — we cleverly gave it a tag earlier so as to be able to identify it now — while at the same time we animate away the presented view (the “from” view); at the end, we restore the tint color of the background view (the “to” view):

} else {
    UIView* shadow = [con viewWithTag:987];
    [UIView animateWithDuration:0.25 animations:^{
        shadow.alpha = 0;
        v1.transform = CGAffineTransformScale(v1.transform,0.5,0.5);
        v1.alpha = 0;
    } completion:^(BOOL finished) {
        v2.tintAdjustmentMode = UIViewTintAdjustmentModeAutomatic;
        [transitionContext completeTransition:YES];
    }];
}

I’ll conclude by describing an elaborate real-life presentation animation from one of my own apps. Figure 6-9 shows the existing view and the presented view. The presented view appears to cover the existing view, which is visible through it in a blurred way.

A view and a presented view that covers it
Figure 6-9. A view and a presented view that covers it

The modal presentation style of the second view controller is UIModalPresentationCustom. The second view rises from the bottom of the screen, in imitation of a UIModalTransitionStyleCoverVertical animation. At the same time, the color swatch that was tapped in the first view, which summons the presented view controller, rises to become the color swatch in the second view; this serves as an almost subconscious indication that the user is editing this swatch.

We thus have to manage three things simultaneously: the blurred background, the rising presented view, and the moving swatch.

To create the blurred background, the first view is snapshotted into an image context:

[vc1.view drawViewHierarchyInRect: v1.bounds afterScreenUpdates: NO];

The image is then blurred and put into a UIImageView. This image view cannot simply be the background of the second view, because the second view is going to rise from the bottom of the screen: we don’t want the blurred image to rise with it, as this would break the illusion that the second view itself is blurring the first view behind it. So the image view is a separate view placed into the container view, with a contentMode of UIViewContentModeBottom and an initial height of zero. The second view, meanwhile, has a transparent background. As the second view rises from the bottom of the screen, we simultaneously increase the height of the image view behind it, also from the bottom of the screen! Thus the blur is stationary behind the second view.

Figure 6-10 is a freeze frame in the middle of the animation, as the second view rises from the bottom of the screen; as you can see, the part of the first view that’s behind the second view appears blurred, but the part of the first view that isn’t yet covered by the second view is still sharp.

An elaborate transition animation
Figure 6-10. An elaborate transition animation

At the same time, in Figure 6-10, the blue swatch, which the user tapped, is rising from its place in the first view to its place in the second view. It is currently higher than the black rectangle in the second view that it will eventually occupy, but they are both heading toward the same spot, and will meet there precisely at the end of the animation. The swatch is not really moving from one view to the other; what the user sees during the transition is actually just a snapshot view, taken by snapshotting the colored rectangle that the user originally tapped:

UIView* swatch = [self.tappedColor snapshotViewAfterScreenUpdates:NO];

The swatch in the second view has been hidden; when the transition ends, the snapshot of the swatch will be removed and the swatch in the second view will be made visible. The really tricky part is getting the initial and final frame of the snapshot view and translating those into containerView coordinates. The solution is to start by putting the “to” view into its final position and then requesting immediate layout:

v2.frame = v1.bounds;
[con addSubview: v2];
[con layoutIfNeeded];

This causes everything in v2 to assume its ultimate position, and now we can work out the initial and final frames of the moving swatch snapshot view:

CGRect r1 = self.tappedColor.frame;
r1 = [self.tappedColor.superview convertRect:r1 toView:vc1.view];
CGRect r2 = cpc.swatch.frame;
r2 = [vc2.view convertRect:r2 fromView:cpc.swatch.superview];

Then and only then do we move v2 to its position below the bottom of the screen, ready to begin the animation.

Transition Coordinator

While a view controller is involved in a transition, its transitionCoordinator property is set by the runtime to an object implementing the UIViewControllerTransitionCoordinator protocol. This object, the transition coordinator, is a kind of wrapper around the 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.

Warning

Unfortunately, exactly when the transition coordinator is available seems to differ depending on the type of transition. Take, for example, an interactive transition instigated through a pan gesture from the right edge of the screen, such as I described earlier. If the view controllers involved in this transition are children of a UINavigationController, then the transition coordinator is available in the second view controller’s viewWillAppear:; but if their parent is a UITabBarController, it isn’t. I regard this inconsistency as a bug. You’ll have to experiment for your particular situation.

One use of the transition coordinator is to ascertain whether we are in an interactive transition and, if so, whether it has been cancelled. It may well be that what your view controller wants to do will differ in this situation. You can send the transition coordinator the notifyWhenInteractionEndsUsingBlock: message to run a block at the moment the user abandons the interactive gesture and the transition is about to be either completed or cancelled. Here’s code from a view controller that might be pushed interactively onto a UINavigationController:

-(void)viewWillAppear:(BOOL)animated {
    [super viewWillAppear:animated];
    id<UIViewControllerTransitionCoordinator> tc = self.transitionCoordinator;
    if (tc && [tc initiallyInteractive]) {
        [tc notifyWhenInteractionEndsUsingBlock:
         ^(id<UIViewControllerTransitionCoordinatorContext> context) {
             if ([context isCancelled]) {
                 // ...
             }
        }];
    }
}

If the view controller’s parent is a UITabBarController, it can ask whether its view is disappearing because an interactive gesture was abandoned and the transition was cancelled, like this:

- (void) viewWillDisappear:(BOOL)animated {
    [super viewWillDisappear:animated];
    id<UIViewControllerTransitionCoordinator> tc = self.transitionCoordinator;
    if (tc && [tc initiallyInteractive] && [tc isCancelled]) {
        // ...
    }
}

You can also use the transition coordinator to be notified when the transition ends. This works even if this is not a custom transition; for example, you can run code in response to the default push transition ending. Call the transition coordinator’s animateAlongsideTransition:completion: with a completion: block. This code is from the top view controller of a UINavigationController as another view controller is pushed on top of it:

-(void)viewWillDisappear:(BOOL)animated {
    [super viewWillDisappear:animated];
    id<UIViewControllerTransitionCoordinator> tc = self.transitionCoordinator;
    if (tc) {
        [tc animateAlongsideTransition:nil completion:
         ^(id<UIViewControllerTransitionCoordinatorContext> context) {
             // ...
        }];
    }
}

Another use of animateAlongsideTransition:completion: is, as the name suggests, to supply an additional animation. This works even if the transition is interactive. If the view affected by this additional animation is outside the transition context’s container view, call animateAlongsideTransitionInView:animation:completion: instead. (But this secondary animation is not reliable; sometimes, the affected view property is changed immediately, without animation.)

Page View Controller

A page view controller (UIPageViewController) displays a view controller’s view. The user, by a gesture, can navigate in one direction or the other to see the next or the previous view controller’s view, successively — like turning the pages of a book.

To create a UIPageViewController, initialize it with initWithTransitionStyle:navigationOrientation:options:. Here’s what the parameters mean:

transitionStyle:

The animation style during navigation. Your choices are:

navigationOrientation:

The direction of navigation. Your choices are:

options:

A dictionary. Possible keys are:

UIPageViewControllerOptionSpineLocationKey

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

UIPageViewControllerOptionInterPageSpacingKey
If you’re using the scroll transition, this is the spacing between successive pages, visible as a gap during the transition. The value is an NSNumber wrapping a float.

You then assign the page view controller a dataSource, which should conform to the UIPageViewControllerDataSource protocol, and configure the page view controller’s initial content by handing it its initial child view controller(s). You do that by calling setViewControllers:direction:animated:completion:. Here’s what the parameters mean:

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

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

animated:, completion:
A BOOL and a completion handler.

Here’s a minimal example. First I need to explain where my pages come from. I’ve got a UIViewController subclass called Pep and a data model consisting of an array (self.pep) of the names of the Pep Boys, along with eponymous image files in my app bundle portraying each Pep Boy. I initialize a Pep object by calling initWithPepBoy:nib:bundle:, supplying the name of a Pep Boy from the array; Pep’s viewDidLoad then fetches the corresponding image and assigns it as the image of a UIImageView within its own view:

self.pic.image = [UIImage imageNamed: self.boy];

Thus, each page in the page view controller portrays an image of a named Pep Boy. Here’s how I create the page view controller:

// make a page view controller
UIPageViewController* pvc =
    [[UIPageViewController alloc]
        initWithTransitionStyle:
            UIPageViewControllerTransitionStylePageCurl
        navigationOrientation:
            UIPageViewControllerNavigationOrientationHorizontal
        options: nil];
// give it an initial page
Pep* page = [[Pep alloc] initWithPepBoy:self.pep[0] nib:nil bundle:nil];
[pvc setViewControllers: @[page]
              direction: UIPageViewControllerNavigationDirectionForward
               animated: NO completion: nil];
// give it a data source
pvc.dataSource = self;

As for the page view controller’s view, 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, you can make it a presented view controller, or 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 some other view controller’s view, you must turn that other view controller into a custom container view controller (as I’ll describe in the next section). At the same time, you must retain the page view controller itself; that will happen in the natural course of things if you get its view into the interface correctly.

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. We have three pages, because we have three Pep Boys and their images — but only potentially. 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:

-(UIViewController *)pageViewController:(UIPageViewController *)pvc
        viewControllerAfterViewController:(UIViewController *)viewController {
    NSString* boy = [(Pep*)viewController boy]; // string name of this Pep Boy
    NSUInteger ix = [self.pep indexOfObject:boy]; // find it in the data model
    ix++;
    if (ix >= [self.pep count])
        return nil; // there is no next page
    return [[Pep alloc] initWithPepBoy: self.pep[ix] nib: nil bundle: nil];
}

You can also, at any time, call setViewControllers:... to change programmatically what page is being displayed, possibly with animation. I do that in my Latin flashcard app during drill mode (Figure 6-5), to advance to the next term in the current drill:

[self.terms shuffle];
Term* whichTerm = self.terms[0];
CardController* cdc = [[CardController alloc] initWithTerm:whichTerm];
[self.pvc setViewControllers:@[cdc]
                   direction:UIPageViewControllerNavigationDirectionForward
                    animated:YES completion:nil];

If you refer, in the completion block of setViewControllers:..., to the page view controller to which the message was sent, ARC will warn of a possible retain cycle. I don’t know why there would be a retain cycle, but I take no chances: I do the weak–strong dance to prevent it.

A page view controller with the scroll transition style has a long-standing bug that you might need to watch out for. In order to be ready with the next or previous page as the user starts to scroll, the page view controller caches the next or previous view controller in the sequence. If you navigate manually with setViewControllers:... to a view controller that isn’t the next or previous in the sequence, and if animated: is YES, this cache is not refreshed; if the user now navigates with a scroll gesture, the wrong view controller is shown. I have developed a gut-wrenchingly horrible workaround: in the completion: handler, perform the same navigation again without animation. This requires doing the weak–strong dance and using delayed performance:

__weak UIPageViewController* pvcw = pvc;
[pvc setViewControllers:@[page]
    direction:UIPageViewControllerNavigationDirectionForward
    animated:YES completion:^(BOOL finished) {
        UIPageViewController* pvcs = pvcw;
        if (!pvcs) return;
        dispatch_async(dispatch_get_main_queue(), ^{
            [pvcs setViewControllers:@[page]
                direction:UIPageViewControllerNavigationDirectionForward
                animated:NO completion:nil];
        });
    }];

If you’re using the scroll style, the page view controller will optionally display a page indicator (a UIPageControl, see Chapter 12). The user can look at this to get a sense of what page we’re on, and can tap to the left or right of it to navigate. To get the page indicator, you must implement two more data source methods; they are consulted in response to setViewControllers:.... We called that method initially to configure the page view controller, and if we never call it again, these data source methods won’t be called again either, as the page view controller can keep track of the current index on its own. Here’s my implementation for the Pep Boy example:

-(NSInteger)presentationCountForPageViewController:(UIPageViewController*)pvc {
    return [self.pep count];
}
-(NSInteger)presentationIndexForPageViewController:(UIPageViewController*)pvc {
    Pep* page = [pvc viewControllers][0];
    NSString* boy = page.boy;
    return [self.pep indexOfObject:boy];
}

In iOS 7, the page view controller’s page indicator by default has white dots and a clear background, so it is invisible in front of a white background. Moreover, there is no direct access to it. Use the appearance proxy (Chapter 12) to customize it. For example:

UIPageControl* proxy =
    [UIPageControl appearanceWhenContainedIn:
        [UIPageViewController class], nil];
[proxy setPageIndicatorTintColor:
    [[UIColor redColor] colorWithAlphaComponent:0.6]];
[proxy setCurrentPageIndicatorTintColor:[UIColor redColor]];
[proxy setBackgroundColor:[UIColor yellowColor]];

It is also possible to assign a page view controller a delegate, which adopts the UIPageViewControllerDelegate protocol. You get an event when the user starts turning the page and when the user finishes turning the page, and you get a chance to 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 in iOS 7 also gets messages allowing it to specify the page view controller’s rotation policy, so that you don’t have to subclass UIPageViewController solely for that purpose.

If you’ve assigned the page view controller the page curl transition, the user can ask for navigation by tapping at either edge of the view or by dragging across the view. These gestures are detected through two gesture recognizers, which you can access through the page view controller’s gestureRecognizers property. The documentation suggests that you might change where the user can tap or drag by attaching them to a different view, and other customizations are possible as well. In this code, I change the page view controller’s behavior so that the user must double tap to request navigation:

for (UIGestureRecognizer* g in pvc.gestureRecognizers)
    if ([g isKindOfClass: [UITapGestureRecognizer class]])
        ((UITapGestureRecognizer*)g).numberOfTapsRequired = 2;

Of course you are also free to add to the user’s stock of gestures for requesting navigation. You can supply any controls or gesture recognizers that make sense for your app, and respond by calling setViewControllers:.... For example, if you’re using the scroll transition style, there’s no tap gesture recognizer, so the user can’t tap at either edge of the page view controller’s view to request navigation. Let’s change that. I’ve added invisible views at either edge of my Pep view controller’s view, with tap gesture recognizers attached. When the user taps, the tap gesture recognizer fires, and the action handler posts a notification whose object is the tap gesture recognizer. I receive this notification and use the tap gesture recognizer’s view’s tag to learn which view it is; I then navigate accordingly (n is the notification, pvc is the page view controller):

UIGestureRecognizer* g = n.object;
int which = g.view.tag;
UIViewController* vc =
    which == 0 ?
        [self pageViewController:pvc
            viewControllerBeforeViewController:pvc.viewControllers[0]] :
        [self pageViewController:pvc
            viewControllerAfterViewController:pvc.viewControllers[0]];
if (!vc) return;
UIPageViewControllerNavigationDirection dir =
    which == 0 ?
    UIPageViewControllerNavigationDirectionReverse :
    UIPageViewControllerNavigationDirectionForward;
[pvc setViewControllers:@[vc] direction:dir animated:YES completion:nil];

One further bit of configuration, if you’re using the page curl transition, is performed through the doubleSided property. If it is YES, the next page occupies the back of the previous page. The default is NO, unless the spine is in the middle, in which case it’s YES and can’t be changed. Your only option here, therefore, is to set it to YES 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, and spine location. It also has delegate and data source outlets, though you’re not allowed to connect them to other view controllers (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.

Container View Controllers

UITabBarController, UINavigationController, and UIPageViewController are built-in parent view controllers: you hand them a child view controller and they put that child view controller’s view into the interface for you, inside their own view. What if you want your own view controller to do the same thing?

In iOS 3 and 4, that was illegal; the only way a view controller’s view could get into the interface was if a built-in parent view controller put it there. You could put a view into the interface, of course — but not a view controller’s view. Naturally, developers ignored this restriction, and got themselves into all kinds of difficulties. In iOS 5, Apple relented, and created a coherent way for you to create your own parent view controllers, which can legally manage child view controllers and put their views into the interface. A custom parent view controller of this sort is called a container view controller.

Your view controller has a childViewControllers array. You must not, however, just wantonly populate this array however you like. A child view controller needs to receive certain events as it becomes a child view controller, as it ceases to be a child view controller, and as its view is added to and removed from the interface. Therefore, to act as a parent view controller, your UIViewController subclass must fulfill certain responsibilities:

Adding a child

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

  1. Send addChildViewController: to itself, with the child as argument. The child is automatically added to your childViewControllers array and is retained.
  2. Get the child view controller’s view into the interface (as a subview of your view controller’s view), if that’s what adding a child view controller means.
  3. Send didMoveToParentViewController: to the child with your view controller as its argument.
Removing a child

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

  1. Send willMoveToParentViewController: to the child with a nil argument.
  2. Remove the child view controller’s view from your interface.
  3. Send removeFromParentViewController to the child. The child is automatically removed from your childViewControllers array and is released.

This is a clumsy and rather confusing dance. The underlying reason for it is that a child view controller must always receive willMoveToParentViewController: followed by didMoveToParentViewController: (and your own child view controllers can take advantage of these events however you like). But it turns out that addChildViewController: sends willMoveToParentViewController: for you, and that removeFromParentViewController sends didMoveToParentViewController: for you; so 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.

I’ll illustrate two versions of the dance. First, we’ll simply obtain a new child view controller and put its view into the interface, where no child view controller’s view was previously:

UIViewController* vc = // whatever; this the initial child view controller
[self addChildViewController:vc]; // "will" is called for us
[self.view addSubview: vc.view];
// when we call "add", we must call "did" afterward
[vc didMoveToParentViewController:self];
vc.view.frame = // whatever, or use constraints

This could very well be all you need to do. For example, consider Figure 6-3 and Figure 6-4. My view controller’s view contains a UIPageViewController’s view as one of its subviews. The only to achieve this legally and coherently is for my view controller — in this case, it’s the app’s root view controller — to act as the UIPageViewController’s parent view controller. Here’s the actual code as the root view controller configures its interface:

// create the page view controller
UIPageViewController* pvc =
 [[UIPageViewController alloc]
  initWithTransitionStyle:UIPageViewControllerTransitionStylePageCurl
  navigationOrientation:UIPageViewControllerNavigationOrientationHorizontal
  options: @{UIPageViewControllerOptionSpineLocationKey:
            @(UIPageViewControllerSpineLocationMin)}
];
pvc.delegate = self;
pvc.dataSource = self;
// add its view to the interface
[self addChildViewController:pvc];
[self.view addSubview:pvc.view];
[pvc didMoveToParentViewController:self];
// configure the view
pvc.view.translatesAutoresizingMaskIntoConstraints = NO;
[self.view addConstraints:
 [NSLayoutConstraint
  constraintsWithVisualFormat:@"|[pvc]|"
  options:0 metrics:nil views:@{@"pvc":pvc.view}]];
[self.view addConstraints:
 [NSLayoutConstraint
  constraintsWithVisualFormat:@"V:|[pvc]|"
  options:0 metrics:nil views:@{@"pvc":pvc.view}]];

(A storyboard makes it simpler to configure a custom container view controller’s initial child view controller and its view, as I’ll explain in the next section.)

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:

  • transitionFromViewController:toViewController:duration:options:​animations:​completion:

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:

options:
A bitmask comprising the same possible options that apply to any block-based view transition (see Transitions; these are the options whose names start with UIViewAnimationOption...).
animations:
A block that may be used for additional view animations, besides the transition animation specified in the options: argument. Alternatively, if none of the built-in transition animations is suitable, you can animate the views yourself here; they are both in the interface during this block.
completion:
This block will be important if the transition is part of removing or adding a child view controller. At the time transitionFromViewController:... is called, both view controllers involved must be children of the parent view controller; so if you’re going to remove one of the view controllers as a child, you’ll do it in the completion: block. Similarly, if you owe a new child view controller a didMoveToParentViewController: call, you’ll use the completion: block to fulfill that debt.

Here’s an example. To keep things simple, suppose that our view controller has just one child view controller at a time, and displays the view of that child view controller within its own view. So let’s say that when our view controller is handed a new child view controller, it substitutes that new child view controller for the old child view controller and replaces the old child view controller’s view with the new child view controller’s view. Here’s code that does that correctly; the two view controllers are called 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" is called for us
// when we call "remove", we must call "will" (with nil) beforehand
[fromvc willMoveToParentViewController:nil];
[self transitionFromViewController:fromvc
    toViewController:tovc
    duration:0.4
    options:UIViewAnimationOptionTransitionFlipFromLeft
    animations:nil
    completion:^(BOOL done){
        // we called "add"; we must call "did" afterward
        [tovc didMoveToParentViewController:self];
        [fromvc removeFromParentViewController];
        // "did" is 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:

tovc.view.translatesAutoresizingMaskIntoConstraints = NO;
// must have both as children before we can transition between them
[self addChildViewController:tovc]; // "will" called for us
// when we call remove, we must call "will" (with nil) beforehand
[fromvc willMoveToParentViewController:nil];
[self transitionFromViewController:fromvc
    toViewController:tovc
    duration:0.4
    options:UIViewAnimationOptionTransitionFlipFromLeft
    animations:^{
       [self.panel addConstraints:
        [NSLayoutConstraint
         constraintsWithVisualFormat:@"H:|[v]|"
         options:0 metrics:nil views:@{@"v":tovc.view}]];
       [self.panel addConstraints:
        [NSLayoutConstraint
         constraintsWithVisualFormat:@"V:|[v]|"
         options:0 metrics:nil views:@{@"v":tovc.view}]];
    }
    completion:^(BOOL done){
        // when we call add, we must call "did" afterward
        [tovc didMoveToParentViewController:self];
        [fromvc removeFromParentViewController];
        // "did" is called for us
    }];

As I mentioned earlier, if the built-in transition animations are unsuitable, you can set the options: argument to UIViewAnimationOptionTransitionNone and provide your own animation in the animations: block, at which time both views are in the interface:

[self addChildViewController:tovc];
[fromvc willMoveToParentViewController:nil];
tovc.view.transform = CGAffineTransformMakeScale(0.1,0.1);
[self transitionFromViewController:fromvc
    toViewController:tovc
    duration:0.4
    options:UIViewAnimationOptionTransitionNone
    animations:^{
        tovc.view.transform = CGAffineTransformIdentity;
    }
    completion:^(BOOL done){
        [tovc didMoveToParentViewController:self];
        [fromvc removeFromParentViewController];
    }];

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:

  • childViewControllerForStatusBarStyle
  • childViewControllerForStatusBarHidden

Storyboards

Throughout this chapter, I’ve been describing how to create a view controller and present it or make it another view controller’s child manually, entirely in code. But if you’re using a storyboard, you will often (or always) allow the storyboard to do those things for you automatically. A storyboard can be helpful and convenient in this regard, though not, perhaps, for the reasons one might expect. It doesn’t necessarily reduce the amount of code you’ll have to write; indeed, in some cases using a storyboard may compel you to write more code, and in a less readable and maintainable way, than if you were creating your view controllers manually. But a storyboard does clarify the relationships between your view controllers over the course of your app’s lifetime. Instead of having to hunt around in each of your classes to see which class creates which view controller and when, you can view and manage the chain of view controller creation graphically in the nib editor (Figure 6-11).

The storyboard of an actual app
Figure 6-11. The storyboard of an actual app

A storyboard, as I’ve already explained, is basically a collection of view controller nibs (scenes) and view nibs. Each view controller is instantiated from its own nib, as needed, and will then obtain its view, as needed — typically from a view nib that you’ve configured by editing the view controller’s view, within the view controller itself, in the same storyboard. I described this process in detail, and listed the ways in which a view controller in a storyboard can be instantiated, in Storyboard-Instantiated View Controller. One of those ways is manual (calling instantiateViewControllerWithIdentifier:); the other three are, or can be, automatic:

Initial view controller
If your app has a main storyboard, as specified by its Info.plist, that storyboard’s initial view controller will be instantiated and assigned as the window’s rootViewController automatically as the app launches. To specify that a view controller is a storyboard’s initial view controller, check the “Is Initial View Controller” checkbox in its Attributes inspector. This will cause any existing initial view controller to lose its initial view controller status. The initial view controller is distinguished graphically in the canvas by an arrow pointing to it from the left. If a view controller is added to an empty canvas, it is made the initial view controller automatically.
Relationship

Two built-in parent view controllers can specify their children directly in the storyboard, setting their viewControllers array:

To add a view controller as a viewControllers child to a parent view controller, Control-drag from the parent view controller to the child view controller; in the little HUD that appears, choose “view controllers” for a UITabBarController, or “root view controller” for a UINavigationController. The result is a relationship whose source is the parent and whose destination is the child. The destination view controller will be instantiated automatically when the source view controller is instantiated, and will be assigned into its viewControllers array, thus making it a child and retaining it.

Segue

A segue configures a future situation, when the segue will be triggered. At that time, one view controller that already exists will cause the instantiation of another, bringing the latter into existence. The two chief types of segue are:

Push
The future view controller will be pushed onto the stack of the navigation controller of which the existing view controller is already a child.
Modal
The future view controller will be a presented view controller (and the existing view controller will be its original presenter).

Unlike a relationship, a segue does not have to emanate from a view controller; it can emanate from certain kinds of gesture recognizer, or from an appropriate view (such as a button or a table view cell) in the first view controller’s view. This is a graphical shorthand signifying that the segue should be triggered, bringing the second view controller into existence, when a tap or other gesture occurs.

To create a segue, Control-drag from the view in the first view controller, or from the first view controller itself, to the second view controller. In the little HUD that appears, choose the type of segue you want.

(The arrows to the left of the four view controllers in Figure 6-11 are, sequentially, the initial view controller indicator, a relationship, a push segue, and a modal segue.)

Segues

A segue is a full-fledged object, an instance of UIStoryboardSegue (or your custom subclass thereof). 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 initWithIdentifier:source:destination:. It can, however, be configured in the nib editor, through the Attributes inspector.

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 at the time the segue is triggered; the destination view controller is the one that the segue itself will be responsible for instantiating.

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.

In the case of a push segue, the identifier is the only thing you can customize in the Attributes inspector. The segue is going to call pushViewController:animated: for you, and you can’t change anything about that.

In the case of a modal segue, the Attributes inspector lets you specify a Transition; if this is not Default, you’re telling the segue to assign the destination view controller this transition style (animation), which may be different from (and will therefore override) the modalTransitionStyle that the destination view controller already has. This is effectively the same as the code I showed earlier, where a view controller creates another view controller and sets its modalTransitionStyle before presenting it:

UIViewController* vc = [ExtraViewController new];
vc.modalTransitionStyle = UIModalTransitionStyleCoverVertical;
[self presentViewController:vc animated:YES completion:nil];

A modal segue’s Attributes inspector also has an Animates checkbox. This is effectively the same as the second argument in presentViewController:animated:completion:.

If neither of these behaviors is what you want, you can configure the segue as a Custom segue. The Attributes inspector lets you specify a custom class, which must be a UIStoryboardSegue subclass. In that subclass, you must override perform, which will be called after the segue is triggered and instantiated. Your perform implementation can access the segue’s identifier, sourceViewController, and destinationViewController properties. The destinationViewController has already been instantiated, but that’s all; doing something with this view controller so as to make it a child view controller or presented view controller, retaining it and causing its view to appear in the interface, is entirely up to your code.

You do not, however, need a custom segue just in order to implement a custom transition animation in iOS 7. A built-in segue is calling pushViewController:animated: or presentViewController:animated:completion: just as you would do in code, so if the relevant view controller has a delegate which returns an animation controller, your custom transition animation will be performed as usual. Remember, though, to configure the view controller early enough; viewDidLoad will not do as a place for a view controller to assign itself, say, a transitioningDelegate. This view controller is being instantiated from a nib, so awakeFromNib or initWithCoder: is appropriate.

Now let’s talk about how a segue will be triggered:

When a segue is triggered, the destination view controller is instantiated automatically. This is nice in the sense that automatic behavior is convenient, but how are you going to communicate between the source view controller and the destination view controller? This, you’ll remember, was the subject of an earlier section of this chapter (Communication With a Presented View Controller), where I used this code as an example:

SecondViewController* svc = [SecondViewController new];
svc.data = @"This is very important data!";
[self presentViewController: svc
                   animated:YES completion:nil];

In that code, the first view controller created the second view controller, and therefore had an opportunity of passing along some data to it before presenting it. With a push segue, however, the second view controller is instantiated for you, and the segue itself is going to call presentViewController:animated:completion:. So when and how will you be able to set svc.data?

The answer is that, after the segue has instantiated the second view controller but before it is performed, the source view controller is sent prepareForSegue:sender:. (For a custom segue, this happens before the segue’s own perform is called.) This is the moment when the source view controller and the destination view controller meet; the source view controller can thus perform configurations on the destination view controller, hand it data, and so forth. The source view controller can work out which segue is being triggered by examining the segue’s identifier and destinationViewController properties, and the sender is the interface object that was tapped to trigger the segue (or, if performSegueWithIdentifier:sender: was called in code, whatever object was supplied as the sender: argument).

This solves the communication problem, though in a clumsy way; prepareForSegue:sender: feels like a blunt instrument. The destinationViewController arrives typed as a generic id, and it is up to your code to know its actual type, cast it, and configure it. Moreover, if more than one segue emanates from a view controller, they are all bottlenecked through the same prepareForSegue:sender: implementation, which thus devolves into an ugly collection of conditions to distinguish them.

You can configure a UITabViewController’s child view controllers or a UINavigationController’s root view controller in a storyboard, because these are built-in parent view controllers and the nib editor understands how they work. But 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. Nevertheless, if you’re able to conform to some basic assumptions that the nib editor makes, you can perform some initial parent–child configuration of your container view controller in a storyboard.

Those assumptions are:

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; 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, locate the Container View object in the Object library and drag it into the parent view controller’s view in the canvas. The result is a view, together with a segue from it to an additional child view controller. You can then assign the child view controller its correct class in its Identity inspector.

The segue here is an embed segue. When it 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.

By default, an embed segue is triggered automatically, and the child view controller is instantiated, when the parent view controller is instantiated. If that isn’t what you want, override shouldPerformSegueWithIdentifier:sender: in the parent view controller to return NO for this segue, and call performSegueWithIdentifier:sender: later when you do want the child view controller instantiated.

Since this is a segue, 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 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 by using a custom segue and a UIStoryboardSegue subclass.

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 modal segue that says presentViewController:animated:completion: but no modal segue that says dismissViewControllerAnimated:completion:.

In a nutshell, you can’t use push and modal segues to mean “go back”. A segue’s destination is a class; triggering the segue instantiates that class. 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.

Warning

A common mistake among beginners is to make a modal segue from view controller A to view controller B, and then try to express the notion “go back” by making another modal segue from view controller B to view controller A. The result, of course, is not presentation and subsequent dismissal, but presentation piled on presentation, one view controller instantiated on top of another on top of another. Do not construct a cycle of segues. (Unfortunately, the nib editor doesn’t alert you to this mistake.)

Thus, when storyboards were introduced in iOS 5, the way to call popViewControllerAnimated: was to call it, in code (or let a back button call it for you), just as if there were no such thing as a storyboard. The way to call dismissViewControllerAnimated:completion: was to call it, in code, just as if there were no such thing as a storyboard.

To deal with this shortcoming, iOS 6 introduced the unwind segue. An unwind segue does let you express the notion “go back” in a storyboard. It works in an ingenious and rather elaborate way. It has to, because (as I’ve just shown) it can’t possibly work like a normal segue! There are two chief problems to be solved: exactly what does “go back” mean, and exactly where should we “go back” to?

The answer to both questions depends upon the notion of a view controller chain. This is similar to, though not quite the same as, the view controller hierarchy; it refers to the chain of view controller instantiations, making each new view controller instance a child view controller or a presented view controller, that got us to the current view controller situation. To “go back” means to walk this chain in reverse: every view controller has either a parentViewController or a presentingViewController, so the next view controller up the chain is that view controller.

(Observe that this chain is well-defined even if it takes us out of the storyboard. The app’s entire view controller hierarchy might not come from a single storyboard, and some parts of it might not come from a storyboard at all. Even so, there is a well-defined chain and it still leads all the way back up to the root view controller.)

Before you can create an unwind segue, you implement an unwind method in the class of any view controller represented in the storyboard. This should be a method returning an IBAction (as a hint to the storyboard editor) and taking a single parameter, a UIStoryboardSegue.

Once you’ve done that, 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, connecting it to the Exit proxy object in the same scene. 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.

Even so, the name of the unwind method to which the unwind segue is bound is only a name. The unwind segue’s source view controller is the view controller that contains it. But its destination view controller is unknown; it will not be determined until the app runs and the segue is triggered.

At runtime, when the unwind segue is triggered, the runtime conducts a search among the existing view controllers for a destination view controller. Put simply, the first view controller it finds that implements the unwind method will be the destination view controller. (I’ll describe the actual details of this search in a moment.)

Once the destination view controller is found, the following steps are performed:

  1. The source view controller’s shouldPerformSegueWithIdentifier:sender: is called. It can stop the whole process dead at this point by returning NO.
  2. The source view controller’s prepareForSegue:identifier: is called. The two view controllers are now in contact (because the other view controller is the segue’s destinationViewController). This is an opportunity for the source view controller to hand information to the destination view controller before being destroyed.
  3. The destination view controller’s unwind method is called. Its parameter is the segue; this segue can be identified through its identifier property. The two view controllers are now in contact again (because the other view controller is the segue’s sourceViewController). It is perfectly reasonable, however, for the unwind method body to be empty; the unwind method’s real purpose is to mark this view controller as the destination view controller.
  4. The segue is performed, destroying the source controller and any intervening view controllers up to (but not including) the destination view controller, in good order.

Now I’ll go back and explain in detail how the destination view controller is found and used to construct the actual segue. This is partly out of sheer interest (it’s a devilishly clever procedure), and partly in case you need to customize the process.

When an unwind segue is triggered, the runtime starts walking back along the view controller chain from the source view controller instance toward the root view controller, asking each view controller for the destination view controller, by calling viewControllerForUnwindSegueAction:fromViewController:withSender:. There are two possible responses:

The default UIViewController implementation of viewControllerForUnwindSegueAction:... is for a view controller to send itself canPerformUnwindSegueAction:fromViewController:withSender:. Thus:

The default implementation of canPerformUnwindSegueAction:..., in turn, is for a view controller to send itself respondsToSelector: for the unwind method! Thus, the normal outcome is that if a view controller implements the unwind method, it will end up as the destination view controller, and otherwise, the search will continue on up the chain. You can, however, override canPerformUnwindSegueAction:... to return NO, to force the runtime search to continue on up the view controller chain past this view controller.

What I have said so far does not explain how a push is reversible. After all, the next view controller up the chain from a pushed view controller is the UINavigationController itself; nevertheless, a push can unwind by popping, which means that we end up at one of the pushed view controller’s siblings, further down the navigation stack, as the unwind segue’s destination view controller. How is that possible?

The answer is that UINavigationController implements viewControllerForUnwindSegueAction:... differently from UIViewController. It doesn’t consider itself as a possible destination. Instead, it consults its children, starting at the top of the stack and polling them in reverse order, looking for the first one that returns YES from canPerformUnwindSegueAction:...; if it finds one, it returns it (and otherwise it returns nil). By default, canPerformUnwindSegueAction:... returns NO if the fromViewController: is self, so if a pushed view controller is the source view controller of an unwind segue, this constitutes an attempt to find a view controller to pop to.

Your own custom container view controller class, too, can override viewControllerForUnwindSegueAction:fromViewController:withSender: to intervene in the process of choosing a destination view controller. The unwind method will be called on the destination view controller that you return, so do not return a view controller that doesn’t implement the unwind method, as you’ll be setting the app up to crash.

Presume that the search is now over, and the runtime has found a destination view controller. The segue is now constructed by sending segueForUnwindingToViewController:fromViewController:identifier: to the destination view controller — or, if the destination view controller has a parent, to the parent. That view controller then returns a segue whose perform method is tailor-made for the current situation, dictating the entire “go back” sequence that will release the source view controller and all intervening view controllers in good order, and performing an appropriate transition animation.

This segue’s identifier is the identifier, if any, that you specified in the storyboard; its sourceViewController is the source view controller from the storyboard (the fromViewController:); and its destinationViewController is the destination view controller we have at last settled on (the toViewController:).

Your view controller, typically a custom container view controller, can override segueForUnwindingToViewController:fromViewController:identifier:. The simplest implementation is to call the UIStoryboardSegue class method segueWithIdentifier:source:destination:performHandler:, which lets you create on the fly a segue complete with a perform implementation supplied as a block.

For example, consider this chain: a navigation controller, its root view controller, a pushed view controller, and a presented view controller. By default, if we unwind directly from the presented view controller to the root view controller, we get only the reverse of the presented view controller’s original animation. That’s not very clear to the user, since in fact we’re going back two steps. To improve things, our UINavigationController subclass can substitute a segue that performs two successive animations: 

-(UIStoryboardSegue*)segueForUnwindingToViewController:
        (UIViewController *)toViewController
        fromViewController:(UIViewController *)fromViewController
        identifier:(NSString *)identifier {
    return [UIStoryboardSegue segueWithIdentifier:identifier
        source:fromViewController
        destination:toViewController performHandler:^{
            [fromViewController.presentingViewController
                dismissViewControllerAnimated:YES completion:^{
                [self popToViewController:toViewController animated:YES];
            }];
        }];
}

View Controller Lifetime Events

As views come and go, driven by view controllers and the actions of the user, events arrive that give your view controller the opportunity to respond to the various stages of its own existence and the management of its view. By overriding these methods, your UIViewController subclass can perform appropriate tasks at appropriate moments. Here’s a list:

viewDidLoad
The view controller has obtained its view. See the discussion earlier in this chapter of how a view controller gets its view.
willRotateToInterfaceOrientation:duration:
willAnimateRotationToInterfaceOrientation:duration:
didRotateFromInterfaceOrientation:
The view controller is undergoing rotation. See the discussion of rotation earlier in this chapter. When an app launches into an orientation other than portrait, these events are not sent even though rotation takes place.
updateViewConstraints
viewWillLayoutSubviews
viewDidLayoutSubviews
The view is receiving updateConstraints and layoutSubviews events. See Chapter 1, and the discussion of rotation earlier in this chapter. Your implementation of updateViewConstraints must call super.
willMoveToParentViewController:
didMoveToParentViewController:
The view controller is being added or removed as a child of another view controller. See the discussion of container view controllers earlier in this chapter.
viewWillAppear:
viewDidAppear:
viewWillDisappear:
viewDidDisappear:

The view is being added to or removed from the interface. This includes being supplanted by another view controller’s view or being restored by the removal of another view controller’s view. A view that has appeared (or has not yet disappeared) is in the window; it is part of your app’s active view hierarchy. A view that has disappeared (or has not yet appeared) is not in the window; its window is nil. You must call super in your override of any of these four methods; if you forget to do so, things may go wrong in subtle ways.

To distinguish more precisely why your view is appearing or disappearing, call any of these methods on self:

A good way to get a sense for when these events are useful is to track the sequence in which they normally occur. Take, for example, a UIViewController being pushed onto the stack of a navigation controller. It receives, in this order, the following messages:

When this same UIViewController is popped off the stack of the navigation controller, it receives, in this order, the following messages:

Disappearance, as I mentioned a moment ago, can happen because another view controller’s view supplants this view controller’s view. For example, consider a UIViewController functioning as the top (and visible) view controller of a navigation controller. When another view controller is pushed on top of it, the first view controller gets these messages:

The converse is also true. For example, when a view controller is popped from a navigation controller, the view controller that was below it in the stack (the back view controller) receives these events:

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

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.

The appear/disappear methods 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).

Similarly, they are useful when something must be true exactly while a view is visible. For example, a timer that must be running while a view is visible can be started in its 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 dealloc that might 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 UIModalPresentationFormSheet presentation style gets no lifetime events during presentation and dismissal.

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

Manual Event Forwarding to a Child View Controller

A custom container (parent) view controller, as I explained earlier, must effectively send willMoveToParentViewController: and didMoveToParentViewController: to its children manually. But other lifetime events, such as the appear events and rotation events, are normally passed along automatically. However, you can take charge of calling these events manually, by implementing these methods:

shouldAutomaticallyForwardRotationMethods

If you override this method to return NO, you are responsible for calling these methods on your view controller’s children:

  • willRotateToInterfaceOrientation:duration:
  • willAnimateRotationToInterfaceOrientation:duration:
  • didRotateFromInterfaceOrientation:

I have no idea how common it is to take charge of sending these events manually; I’ve never done it.

shouldAutomaticallyForwardAppearanceMethods

If you override this method to return YES, you are responsible for seeing that these methods on your view controller’s children are called:

  • viewWillAppear:
  • viewDidAppear:
  • viewWillDisappear:
  • viewDidDisappear:

In iOS 6 and iOS 7, however, you do not do this by calling these methods directly. The reason is that you have no access to the correct moment for sending them. Instead, you call these two methods on your child view controller:

  • beginAppearanceTransition:animated:; the first parameter is a BOOL saying whether this view controller’s view is about to appear (YES) or disappear (NO)
  • endAppearanceTransition

There are two main occasions on which your custom container controller must forward appear events to a child. First, what happens when your custom container 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 events to that child. You’ll need an implementation along these lines, for each of the four appear events:

- (void) viewWillAppear:(BOOL)animated {
    [super viewWillAppear:animated];
    UIViewController* child = // child whose view might be in our interface;
    if (child.isViewLoaded && child.view.superview)
        [child beginAppearanceTransition:YES animated:YES];
}
- (void) viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    UIViewController* child = // child whose view might be in our interface;
    if (child.isViewLoaded && child.view.superview)
        [child endAppearanceTransition];
}

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

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 appear calls 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 method transitionFromView:toView:.... 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 events to the children:

[self addChildViewController:tovc];
[fromvc willMoveToParentViewController:nil];
[fromvc beginAppearanceTransition:NO animated:YES]; // *
[tovc beginAppearanceTransition:YES animated:YES]; // *
[UIView transitionFromView:fromvc.view
    toView:tovc.view
    duration:0.4
    options:UIViewAnimationOptionTransitionFlipFromLeft
    completion:^(BOOL finished) {
        [tovc endAppearanceTransition]; // *
        [fromvc endAppearanceTransition]; // *
        [tovc didMoveToParentViewController:self];
        [fromvc removeFromParentViewController];
    }];

View Controller Memory Management

Memory is at a premium on a mobile device. Thus you want to minimize your app’s use of memory — especially when the memory-hogging objects you’re retaining are not needed at this moment. Because a view controller is the basis of so much of your application’s architecture, it is likely to be a place where you’ll concern yourself with releasing unneeded memory.

The object of releasing memory, in the multitasking world, is partly altruistic and partly selfish. You want to keep your memory usage as low as possible so that other apps can be launched and the user can switch between suspended apps. You also want to prevent your own app from being terminated! If your app is backgrounded and suspended while using a lot of memory, it may be terminated in the background when memory runs short. If your app uses an inordinate amount of memory while in the foreground, it may be summarily killed before the user’s very eyes.

One of your view controller’s most memory-intensive objects is its view. Fortunately, the iOS runtime manages a view controller’s view’s memory for you. If a view controller has never received viewDidAppear:, or if it has received viewDidDisappear: without subsequently receiving viewWillAppear:, its view is not in the interface, and can be temporarily dispensed with. In such a situation, if memory is getting tight, then even though the view controller itself persists, the runtime may release its view’s backing store (the cached bitmap representing the view’s drawn contents). The view will then be redrawn when and if it is to be shown again later.

In addition, if memory runs low, your view controller may be sent didReceiveMemoryWarning (preceded by a call to the app delegate’s applicationDidReceiveMemoryWarning:, together with a UIApplicationDidReceiveMemoryWarningNotification posted to any registered objects). You are invited to respond by releasing any data that you can do without. Do not release data that you can’t readily and quickly recreate! The documentation advises that you should call super.

If you’re going to release data in didReceiveMemoryWarning, you must concern yourself with how you’re going to get it back. A simple and reliable mechanism is lazy loading — a getter that reconstructs or fetches the data if it is nil.

In this example, we have a property myBigData which might be a big piece of data. In didReceiveMemoryWarning we write myBigData out as a file to disk (Chapter 23) and release it from memory. We have also overridden the synthesized accessors for myBigData to implement lazy loading: if we try to get myBigData and it’s nil, we attempt to fetch it from disk — and if we succeed, we delete it from disk (to prevent stale data):

@interface ViewController ()
@property (strong) NSData* myBigDataAlias;
@property (nonatomic, strong) NSData* myBigData;
@end
@implementation ViewController
@synthesize myBigDataAlias = _myBigData;
- (void) setMyBigData: (NSData*) data {
    self.myBigDataAlias = data;
}
- (NSData*) myBigData { // lazy loading
    if (!self.myBigDataAlias) {
        NSFileManager* fm = [NSFileManager new];
        NSString* f =
            [NSTemporaryDirectory()
                stringByAppendingPathComponent:@"myBigData"];
        if ([fm fileExistsAtPath:f]) {
            self.myBigDataAlias = [NSData dataWithContentsOfFile:f];
            NSError* err = nil;
            BOOL ok = [fm removeItemAtPath:f error:&err];
            NSAssert(ok, @"Couldn't remove temp file");
        }
    }
    return self.myBigDataAlias;
}
- (void)saveAndReleaseMyBigData {
    if (self.myBigData) {
        NSString* f =
            [NSTemporaryDirectory()
                stringByAppendingPathComponent:@"myBigData"];
        [self.myBigData writeToFile:f atomically:NO];
        self.myBigData = nil;
    }
}
- (void)didReceiveMemoryWarning {
    [super didReceiveMemoryWarning];
    [self saveAndReleaseMyBigData];
}
@end

To test low-memory circumstances artificially, run your app in the Simulator and choose Hardware → Simulate Memory Warning. I don’t believe this has any actual effect on memory, but a memory warning of sufficient severity is sent to your app, so you can see the results of triggering your low-memory response code, including the app delegate’s applicationDidReceiveMemoryWarning: and your view controller’s didReceiveMemoryWarning.

On the device, the equivalent is to call an undocumented method:

[[UIApplication sharedApplication]
    performSelector:@selector(_performMemoryWarning)];

(Be sure to remove this code when it is no longer needed for testing, as the App Store won’t accept it.)

You will also wish to concern yourself with releasing memory when your app is about to be suspended. If your app has been backgrounded and suspended and the system later discovers it is running short of memory, it will go hunting through the suspended apps, looking for memory hogs that it can kill in order to free up that memory. If the system decides that your suspended app is a memory hog, it isn’t politely going to wake your app and send it a memory warning; it’s just going to terminate your app in its sleep. The time to be concerned about releasing memory, therefore, is before the app is suspended. You’ll probably want your view controller to be registered with the shared application to receive UIApplicationDidEnterBackgroundNotification. The arrival of this notification is an opportunity to release any easily restored memory-hogging objects, such as myBigData in the previous example:

-(void)backgrounding:(NSNotification*)n {
    // got UIApplicationDidEnterBackgroundNotification
    [self saveAndReleaseMyBigData];
}

Testing how your app’s memory behaves in the background isn’t easy. In a WWDC 2011 video, an interesting technique is demonstrated. The app is run under Instruments on the device, using the virtual memory instrument, and is then backgrounded by pressing the Home button, thus revealing how much memory it voluntarily relinquishes at that time. Then a special memory-hogging app is launched on the device: its interface loads and displays a very large image in a UIImageView. Even though your app is backgrounded and suspended, the virtual memory instrument continues to track its memory usage, and you can see whether further memory is reclaimed under pressure from the demands of the memory-hogging app in the foreground.

State Restoration

In the multitasking world, when the user leaves your app and then later returns to it, one of two things might have happened in the meantime:

Your app was suspended
Your app was suspended in the background, and remained suspended while the user did something else. When the user returns to your app, the system simply unfreezes your app, and there it is, looking just as it did when the user left it.
Your app was terminated
Your app was suspended in the background, and then, as the user worked with other apps, a moment came where the system decided it needed the resources (such as memory) being held by your suspended app. Therefore it terminated your app. When the user returns to your app, the app launches from scratch.

For most apps, a general goal should be to make those two situations more or less indistinguishable to the user. The user, after all, doesn’t know the difference between those two things, so why should the app behave differently some of the time? It should always feel to the user as if the app is being resumed from where it left off the last time it was in the foreground, even if in fact the app was terminated while suspended in the background. Otherwise, as the WWDC 2013 video on this topic puts it, the user will feel that the app has mysteriously and annoyingly “lost my place.”

This goal is state restoration. Your app has a state at every moment: some view controller’s view is occupying the screen, and views within it are displaying certain values (for example, a certain switch is set to On, or a certain table view is scrolled to a certain position). The idea of state restoration is to save that information when the app goes into the background, and use it to make all those things true again if the app is subsequently launched from scratch.

iOS provides a general solution to the problem of state restoration (introduced originally in iOS 6). This solution is centered around view controllers, which makes sense, since view controllers are the heart of the problem. What is the user’s “place” in the app, which we don’t want to “lose”? It’s the chain of view controllers that got us to where we were when the app was backgrounded, along with the configuration of each one. The goal of state restoration must therefore be to reconstruct all existing view controllers, initializing each one into the state it previously had.

Note that state, in this sense, is neither user defaults nor data. If something is a preference, make it a preference and store it in NSUserDefaults. If something is data (for example, the underlying model on which your app’s functionality is based), keep it in a file (Chapter 23). Don’t misuse the state saving and restoration mechanism for such things. The reason for this is not only conceptual; it’s also because saved state can be lost. You don’t want to commit anything to the state restoration mechanism if it would be a disaster to have lost it the next time the app launches.

For example, suppose the user kills your app outright by double-clicking the Home button to show the app switcher interface and flicking your app’s snapshot upward; the system will throw away its state. Similarly, if your app crashes, the system will throw away its state. In both cases, the system assumes that something went wrong, and doesn’t want to launch your app into what might be a troublesome saved state. Instead, your app will launch cleanly, from the beginning. There’s no problem for the user, barring a mild inconvenience — as long as the only thing that gets thrown away is state.

How to Test State Restoration

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

  1. Run the app as usual, in the Simulator or on a device.
  2. At some point, in the Simulator or on the device, click the Home button. This causes the app to be suspended in good order, and state is saved.
  3. Now, back in Xcode, stop the running project (Product → Stop).
  4. Run the project again. If there is saved state, it is restored.

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

Apple also provides a number of debugging tools (find them at http://developer.apple.com/downloads):

restorationArchiveTool
A command-line tool for reading a saved state archive in textual format. The archive is in a folder called Saved Application State in your app’s sandboxed Library. See Chapter 23 for more about the app’s sandbox, and how to copy it to your computer from a device.
StateRestorationDebugLogging.mobileconfig
A configuration profile. When installed on a device (through the iPhone Configuration Utility, or by emailing it to yourself and opening it on the device), it causes the console to dump information as state saving and restoration proceeds.
StateRestorationDeveloperMode.mobileconfig
A configuration profile. When installed on a device, it prevents the state archive from being jettisoned after unexpected termination of the app (a crash, or manual termination through the app switcher interface). This can allow you to test state restoration a bit more conveniently.

Participating in State Restoration

Built-in state restoration operates more or less automatically. All you have to do is tell the system that you want to participate in it. To do so, you take three basic steps:

Implement app delegate methods
The app delegate must implement application:shouldSaveApplicationState: and application:shouldRestoreApplicationState: to return YES. (Naturally, your code can instead return NO to prevent state from being saved or restored on some particular occasion.)
Implement application:willFinishLaunchingWithOptions:
Although it is very early, application:didFinishLaunchingWithOptions: is too late for state restoration. Your app needs its basic interface before state restoration begins. The solution is to use a different app delegate method, application:willFinishLaunchingWithOptions:. Typically, you can just change “did” to “will” in the name of this method, keeping your existing code unchanged.
Provide restoration IDs

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

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

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

  • A navigation controller.

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

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

  • A second view controller, connected by a push segue from a Push bar button item in the root view controller’s navigation item. Call its class SecondViewController.

    • The very same presented view controller (PresentedViewController), also connected by a modal segue from a Present button in the second view controller’s view.
Architecture of an app for testing state restoration
Figure 6-12. 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 Pop button.

We will now make this app implement state restoration:

  1. Change the name of application:didFinishLaunchingWithOptions: in the app delegate to application:willFinishLaunchingWithOptions:.
  2. Implement application:shouldSaveApplicationState: and application:​shouldRestoreApplicationState: to return YES.
  3. Give all four view controller instances in the storyboard restoration IDs: let’s call them @"nav", @"root", @"second", and @"presented".

That’s all! The app now saves and restores state.

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.m:
- (BOOL)application:(UIApplication *)application
        didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    self.window =
        [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
    // Override point for customization after application launch.
    RootViewController* rvc = [RootViewController new];
    UINavigationController* nav =
        [[UINavigationController alloc] initWithRootViewController:rvc];
    self.window.rootViewController = nav;
    self.window.backgroundColor = [UIColor whiteColor];
    [self.window makeKeyAndVisible];
    return YES;
}

// RootViewController.m:
-(void)viewDidLoad {
    [super viewDidLoad];
    // ... color view background, create buttons ...
}
-(void)doPresent:(id)sender {
    PresentedViewController* pvc = [PresentedViewController new];
    [self presentViewController:pvc animated:YES completion:nil];
}
-(void)doPush:(id)sender {
    SecondViewController* svc = [SecondViewController new];
    [self.navigationController pushViewController:svc animated:YES];
}

// SecondViewController.m:
-(void)viewDidLoad {
    [super viewDidLoad];
    // ... color view background, create button ...
}
-(void)doPresent:(id)sender {
    PresentedViewController* pvc = [PresentedViewController new];
    [self presentViewController:pvc animated:YES completion:nil];
}

// PresentedViewController.m:
-(void)viewDidLoad {
    [super viewDidLoad];
    // ... color view background, create button ...
}
-(void)doDismiss:(id)sender {
    [self dismissViewControllerAnimated:YES completion:nil];
}

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

  1. Change the name of application:didFinishLaunchingWithOptions: in the app delegate to application:willFinishLaunchingWithOptions:.
  2. Implement application:shouldSaveApplicationState: and application:​shouldRestoreApplicationState: to return YES.

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

    RootViewController* rvc = [RootViewController new];
rvc.restorationIdentifier = @"root";
UINavigationController* nav =
    [[UINavigationController alloc] initWithRootViewController:rvc];
nav.restorationIdentifier = @"nav";

    And so on.

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

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

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 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 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 in application:willFinishLaunchingWithOptions:. Here’s how you do that:

  1. Give the view controller a restorationClass. Typically, this will be the view controller’s own class, or the class of the view controller responsible for creating this view controller instance.
  2. Implement the class method viewControllerWithRestorationIdentifierPath:coder: on the class named by each view controller’s restorationClass property, returning a view controller instance as specified by the identifier path. Very often, viewControllerWithRestorationIdentifierPath:coder: will itself instantiate the view controller and return it.
  3. Specify formally that each class named as a restorationClass implements the UIViewControllerRestoration protocol.

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:

+ (UIViewController*) viewControllerWithRestorationIdentifierPath:
            (NSArray*)ip
        coder: (NSCoder*)coder {
    UIViewController* vc = nil;
    if ([[ip lastObject] isEqualToString:@"presented"]) {
        PresentedViewController* pvc = [PresentedViewController new];
        pvc.restorationIdentifier = @"presented";
        pvc.restorationClass = [self class];
        vc = pvc;
    }
    return vc;
}
-(void)doPresent:(id)sender {
    PresentedViewController* pvc = [PresentedViewController new];
    pvc.restorationIdentifier = @"presented";
    pvc.restorationClass = [self class];
    [self presentViewController:pvc animated:YES completion:nil];
}

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:

+ (UIViewController*) makePresentedViewController {
    PresentedViewController* pvc = [PresentedViewController new];
    pvc.restorationIdentifier = @"presented";
    pvc.restorationClass = [self class];
    return pvc;
}
+ (UIViewController*) viewControllerWithRestorationIdentifierPath:
            (NSArray*)ip
        coder:(NSCoder*)coder {
    UIViewController* vc = nil;
    if ([[ip lastObject] isEqualToString:@"presented"]) {
        vc = [self makePresentedViewController];
    }
    return vc;
}
-(void)doPresent:(id)sender {
    UIViewController* pvc = [[self class] makePresentedViewController];
    [self presentViewController:pvc animated:YES completion:nil];
}

Continuing in the same vein, we expand RootViewController still further to make it also the restoration class for SecondViewController:

+ (UIViewController*) makePresentedViewController {
    PresentedViewController* pvc = [PresentedViewController new];
    pvc.restorationIdentifier = @"presented";
    pvc.restorationClass = [self class];
    return pvc;
}
+ (UIViewController*) makeSecondViewController {
    SecondViewController* svc = [SecondViewController new];
    svc.restorationIdentifier = @"second";
    svc.restorationClass = [self class];
    return svc;
}
+ (UIViewController*) viewControllerWithRestorationIdentifierPath:
            (NSArray*)ip
        coder:(NSCoder*)coder {
    UIViewController* vc = nil;
    if ([[ip lastObject] isEqualToString:@"presented"]) {
        vc = [self makePresentedViewController];
    }
    else if ([[ip lastObject] isEqualToString:@"second"]) {
        vc = [self makeSecondViewController];
    }
    return vc;
}
-(void)doPresent:(id)sender {
    UIViewController* pvc = [[self class] makePresentedViewController];
    [self presentViewController:pvc animated:YES completion:nil];
}
-(void)doPush:(id)sender {
    UIViewController* svc = [[self class] makeSecondViewController];
    [self.navigationController pushViewController:svc animated:YES];
}

Finally, SecondViewController can make itself the restoration class for the PresentedViewController instance that it creates. (I won’t bother showing the code, which just repeats what we’ve already done for RootViewController.) There’s no conflict in the notion that both RootViewController and SecondViewController can fulfill this role, as we’re talking about two different PresentedViewController instances.

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.

viewControllerWithRestorationIdentifierPath:coder: 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.”

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 your app delegate’s application:viewControllerWithRestorationIdentifierPath:coder:. If you do, 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).

If you do implement this method, be prepared to receive identifier paths for existing view controllers! 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 (in application:willFinishLaunchingWithOptions:), and we must return pointers to those instances.

Here’s an implementation of application:viewControllerWithRestorationIdentifierPath:coder: that works correctly with the storyboard-based version of our example app. For the two view controllers that have already been created, it returns pointers to them. For the other two, it instantiates them from the storyboard by treating their restoration IDs as their storyboard IDs (I told you it was a good idea for these to be the same!). The result is that there is no result: state restoration just keeps working as it did before. The point, however, is that we could now, on some occasion, return nil instead, in order to prevent restoration of a particular view controller:

-(UIViewController *)application:(UIApplication *)app
        viewControllerWithRestorationIdentifierPath:(NSArray *)ip
        coder:(NSCoder *)coder {
    if ([[ip lastObject] isEqualToString:@"nav"]) {
        return self.window.rootViewController;
    }
    if ([[ip lastObject] isEqualToString:@"root"]) {
        return [(UINavigationController*)self.window.rootViewController
                viewControllers][0];
    }
    UIStoryboard* board =
        [coder decodeObjectForKey:
            UIStateRestorationViewControllerStoryboardKey];
    return [board instantiateViewControllerWithIdentifier:[ip lastObject]];
}

The very simple example of four view controllers that I’ve been using in the preceding couple of sections (diagrammed in Figure 6-12) is so simple that it ignores half the problem. The truth is that when the state restoration mechanism creates a view controller and places it into the view controller hierarchy, the work of restoration is only half done.

A newly restored view controller probably won’t yet have the data and instance variable values it was holding at the time the app was terminated. The history of the creation and configuration of this view controller are not repeated 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 calling viewControllerWithRestorationIdentifierPath:coder:, 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 repeated, 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:

When state is saved

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

  1. The app delegate is sent application:shouldSaveApplicationState:. The coder is the second parameter.
  2. The app delegate is sent application:willEncodeRestorableStateWithCoder:. This is the same coder as in the previous step, because this is the same object (the app delegate).
  3. Each view controller down the chain, starting at the root view controller, is sent encodeRestorableStateWithCoder: if it implements it. The implementation should call super. Each view controller gets its own coder.
When state is restored

When the app is launched, if state is to be restored, the state restoration mechanism provides coders as follows:

  1. The app delegate is sent application:shouldRestoreApplicationState:. The coder (the one belonging to the app delegate) is the second parameter.
  2. As each view controller down the chain is to be created, either the app delegate’s application:viewControllerWithRestorationIdentifierPath:coder: (if implemented) or the restoration class’s viewControllerWithRestorationIdentifierPath:coder: (if the view controller has a restoration class) is called. The coder is the one appropriate to the view controller that’s to be created.
  3. Each view controller down the chain, starting at the root view controller, is sent decodeRestorableStateWithCoder: if it implements it. The implementation should call super. The coder is the one appropriate to this view controller.
  4. The app delegate is sent application:didDecodeRestorableStateWithCoder:. The coder is the same one sent to application:shouldRestoreApplicationState: (the one belonging to the app delegate).

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

UIStateRestorationViewControllerStoryboardKey
A reference to the storyboard from which this view controller came, if any. (I took advantage of this key in the example at the end of preceding section.)
UIApplicationStateRestorationBundleVersionKey
Your Info.plist CFBundleVersion string when state saving happened.
UIApplicationStateRestorationUserInterfaceIdiomKey
An NSNumber wrapping either UIUserInterfaceIdiomPhone or UIUserInterfaceIdiomPad, telling what kind of device we were running on when state saving happened.
UIApplicationStateRestorationTimestampKey
An NSDate telling when state saving happened.
UIApplicationStateRestorationSystemVersionKey
A NSString telling the system version from when state saving happened.

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

A typical implementation of encodeRestorableStateWithCoder: and decodeRestorableStateWithCoder: will concern itself with instance variables 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:.

Here’s an example from the TidBITS News app. Note that decodeRestorableStateWithCoder: uses nil tests, and that it updates the interface directly:

-(void)encodeRestorableStateWithCoder:(NSCoder *)coder {
    if (self.parsedData)
        [coder encodeObject: self.parsedData forKey:@"parsedData"];
    [coder encodeObject: self.refreshControl.attributedTitle.string
                 forKey: @"lastPubDate"];
    [super encodeRestorableStateWithCoder:coder];
}
-(void)decodeRestorableStateWithCoder:(NSCoder *)coder {
    NSData* parsedData = [coder decodeObjectForKey:@"parsedData"];
    if (parsedData)
        self.parsedData = parsedData;
    NSString* s = [coder decodeObjectForKey:@"lastPubDate"];
    if (s)
        [self setRefreshControlTitle:s];
    [super decodeRestorableStateWithCoder:coder];
}

As a more complete demonstration, I’ll add state saving and restoration to my earlier UIPageViewController example, the one that displays a Pep Boy on each page. The project has no storyboard. There are 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 creates and supplies an appropriate Pep instance whenever a page is needed for the page view controller, along these lines:

Pep* page = [[Pep alloc] initWithPepBoy:self.pep[ix] nib: nil bundle: nil];

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 it happens that we can mediate between a Pep object and a mere string, so 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 YES. Now we save and restore the current Pep Boy name in the app delegate’s encode and decode methods:

-(void)application:(UIApplication *)application
        willEncodeRestorableStateWithCoder:(NSCoder *)coder {
    UIPageViewController* pvc =
        (UIPageViewController*)self.window.rootViewController;
    NSString* boy = [(Pep*)pvc.viewControllers[0] boy];
    [coder encodeObject:boy forKey:@"boy"];
}
-(void)application:(UIApplication *)application
        didDecodeRestorableStateWithCoder:(NSCoder *)coder {
    NSString* boy = [coder decodeObjectForKey:@"boy"];
    if (boy) {
        UIPageViewController* pvc =
            (UIPageViewController*)self.window.rootViewController;
        Pep* pep = [[Pep alloc] initWithPepBoy:boy nib:nil bundle:nil];
        [pvc setViewControllers:@[pep]
            direction:UIPageViewControllerNavigationDirectionForward
            animated:NO completion:nil];
    }
}

A second solution, which is more realistic, assumes that we want our Pep view controller class to be 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:

UIPageViewController* pvc =
    [[UIPageViewController alloc]
        initWithTransitionStyle:
            UIPageViewControllerTransitionStyleScroll
        navigationOrientation:
            UIPageViewControllerNavigationOrientationHorizontal
        options:nil];
pvc.restorationIdentifier = @"pvc";

The app delegate is also the data source, and thus ends up creating Pep objects many times. To prevent duplication of code, 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:

- (id) initWithPepBoy: (NSString*) inputboy
                  nib: (NSString*) nib bundle: (NSBundle*) bundle {
    self = [self initWithNibName:nib bundle:bundle];
    if (self) {
        self->_boy = [inputboy copy];
        self.restorationIdentifier = @"pep";
        self.restorationClass = [self class];
    }
    return self;
}

Let’s be clever and efficient. The most important 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:

-(void)encodeRestorableStateWithCoder:(NSCoder *)coder {
    [coder encodeObject:self->_boy forKey:@"boy"];
}
+(UIViewController *)viewControllerWithRestorationIdentifierPath:(NSArray*)ip
        coder:(NSCoder *)coder {
    NSString* boy = [coder decodeObjectForKey:@"boy"];
    return [[Pep alloc] initWithPepBoy: boy nib: nil bundle: nil];
}

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:

-(void)application:(UIApplication *)application
        willEncodeRestorableStateWithCoder:(NSCoder *)coder {
    UIPageViewController* pvc =
        (UIPageViewController*)self.window.rootViewController;
    Pep* pep = (Pep*)pvc.viewControllers[0];
    [coder encodeObject:pep forKey:@"pep"];
}
-(void)application:(UIApplication *)application
        didDecodeRestorableStateWithCoder:(NSCoder *)coder {
    Pep* pep = [coder decodeObjectForKey:@"pep"];
    if (pep) {
        UIPageViewController* pvc =
            (UIPageViewController*)self.window.rootViewController;
        [pvc setViewControllers:@[pep]
            direction:UIPageViewControllerNavigationDirectionForward
            animated:NO 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 lifetime events I discussed earlier in this chapter (View Controller Lifetime Events). The other involves the events I’ve been discussing in this section. 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.

In iOS 6, this indeterminacy made adoption of state saving and restoration difficult and frustrating. In iOS 7, a new UIViewController event is available, applicationFinishedRestoringState. If you implement this method, 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:

  • application:shouldRestoreApplicationState:
  • application:viewControllerWithRestorationIdentifierPath:coder:
  • viewControllerWithRestorationIdentifierPath:coder:, in order down the chain
  • viewDidLoad, in order down the chain; possibly interleaved with the foregoing
  • decodeRestorableStateWithCoder:, in order down the chain
  • application:didDecodeRestorableStateWithCoder:
  • applicationFinishedRestoringState, in order down the chain

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

Here’s an example from one of my own apps. My configureView method relies on self.detailItem. If state restoration is not happening, then detailItem was set by another view controller, and viewWillAppear: will call configureView based on it; if state restoration is happening, then detailItem was set by decodeRestorableStateWithCoder:, and applicationFinishedRestoringState will call configureView based on it:

-(void)decodeRestorableStateWithCoder:(NSCoder *)coder {
    FPItem* detailItem = [coder decodeObjectForKey:@"detailItem"];
    if (detailItem)
        self->_detailItem = detailItem;
    [super decodeRestorableStateWithCoder:coder];
}
-(void)applicationFinishedRestoringState {
    [self configureView];
}
- (void) viewWillAppear:(BOOL)animated {
    [super viewWillAppear:animated];
    [self configureView];
}
- (void)configureView {
    if (self.detailItem) {
        // ...
    }
}

The worst that can happen is that configureView will be called twice in quick succession with the same detailItem. If I don’t like that, I can prevent it — but not by trying to mediate between viewWillAppear: and applicationFinishedRestoringState! That’s a hopeless task; their order is undefined and unreliable. Instead, configureView can use another instance variable as a flag. For example:

if (self.detailItem == self.lastDetailItem)
    return; // pointless to configure interface again
self.lastDetailItem = self.detailItem;
// ... configure ...

Note

If your app has additional state restoration work to do on a background thread (Chapter 25), the documentation says you should call UIApplication’s extendStateRestoration as you begin and completeStateRestoration when you’ve finished. The idea is that if you don’t call completeStateRestoration, the system can assume that something has gone very wrong (like, your app has crashed) and will throw away the saved state information, which may be faulty.

Restoration of Other Objects

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

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

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

    • encodeRestorableStateWithCoder:
    • decodeRestorableStateWithCoder:
    • applicationFinishedRestoringState

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

    • registerObjectForStateRestoration:restorationIdentifier:
  • Some other object that participates in saving and restoration, such as a view controller, must make the archive aware of this object by storing it in the archive (typically in encodeRestorableStateWithCoder:).

So, for example, here’s an NSObject subclass Thing that participates in saving and restoration:

// Thing.h:
@interface Thing : NSObject  <UIStateRestoring>
@end

// Thing.m:
@implementation Thing
-(void)encodeRestorableStateWithCoder:(NSCoder *)coder {
    // ...
}
-(void)decodeRestorableStateWithCoder:(NSCoder *)coder {
    // ...
}
-(void)applicationFinishedRestoringState {
    // ...
}
@end

Here’s a view controller with a Thing instance variable:

+(Thing*)makeThing {
    Thing* thing = [Thing new];
    [UIApplication registerObjectForStateRestoration:thing
        restorationIdentifier:@"thing"];
    return thing;
}
-(void)awakeFromNib {
    [super awakeFromNib];
    self.thing = [[self class] makeThing];
}
-(void)encodeRestorableStateWithCoder:(NSCoder *)coder {
    [super encodeRestorableStateWithCoder:coder];
    [coder encodeObject:self.thing forKey:@"mything"];
}

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

There is an 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! I presume that this is because registerObjectForStateRestoration:restorationIdentifier: sufficiently identifies this object to the runtime. If you do want to assign an objectRestorationClass, you’ll have to redeclare the property, as it is read-only by default:

@property (strong, nonatomic)
    Class<UIObjectRestoration> objectRestorationClass;

As the declaration shows, the class in question must 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 redeclare it, as it is read-only by default:

@property (strong, nonatomic) id<UIStateRestoring> restorationParent;

The parent must adopt the UIStateRestoring protocol, as the declaration shows. 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.

Snapshot Suppression

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

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

However, you might decide, while saving state, that there is reason not to use the system’s snapshot when relaunching. (Perhaps there is something in your interface that it 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.