The Core iOS Developer’s Cookbook, Fifth Edition (2014)

---

Developing with Navigation Controllers and Split Views

The UINavigationController class offers one of the most important ways of managing interfaces on a device that has limited screen space. It creates a way for users to navigate up and down a hierarchy of interface presentations to create a virtual GUI that’s far larger than the device. Navigation controllers fold their GUIs into a neat tree-based scheme. Users travel through that scheme using buttons and choices that transport them around the tree. You see navigation controllers in the Contacts application and in Settings, where selections lead to new screens and Back buttons move to previous ones.

Several standard GUI elements reveal the use of navigation controllers in applications, as shown in Figure 7-1 (left). These include their large navigation bars that appear at the top of each screen, the backward-pointing button at the top left that appears when the user drills into hierarchies, and option buttons at the top right that offer other application functionality such as editing. Many navigation controller applications are built around scrolling lists, where elements in a list lead to new screens, indicated by the disclosure indicator (gray chevron) and the detail disclosure button (encircled i) found on the right side of each table cell.

Figure 7-1 The iPhone’s navigation controller (left) uses gray chevrons to indicate that detail views will be pushed onscreen when their parents are selected. On the iPad (right), split view controllers use the entire screen, separating navigation elements from detail presentations.

The iPad, with its large screen size, doesn’t require the kind of space-saving shortcuts that navigation controllers leverage on iPhone-family devices. Tablet applications can use navigation controllers directly, but the UISplitViewController shown in Figure 7-1 (right) offers a presentation that’s better suited for the more expansive device.

Notice the differences between the iPhone implementation on the left and the iPad implementation on the right of Figure 7-1. The iPad’s split view controller contains no chevrons. When items are tapped, their data appears on the same screen, using the large right-side detail area. The iPhone, lacking this space, presents chevrons which indicate that new views will be pushed onscreen. Each approach takes device-specific design into account in its presentation.

Both the iPhone-family and iPad Inbox views use similar navigation controller elements. These include the Back button (< iCloud), an options button (Edit), and the description in the title bar (the current folder, Core iOS). Each element is created using the navigation controller API to present a hierarchy of e-mail accounts and mailboxes.

The difference lies at the bottom of the navigation tree, at the level of individual messages that form the leaves of the data structure. The iPhone-family standard uses chevrons to indicate leaves. When selected, these leaf view controllers are pushed onto the navigation stack. They join the other view’s controllers that trace a user’s progress through the interface. The iPad doesn’t push its leaves. It presents them in a separate view and omits chevrons that otherwise indicate that users have reached the extent of the hierarchy traversal.

iPhone-style navigation controllers play roles as well on the iPad. When iPad applications use standard (iPhone-style) navigation controllers, they usually do so in narrow contexts such as transient popover presentations, where the controller is presented onscreen in a small view with a limited lifetime. Otherwise, iPad applications are encouraged to use the split view approach that occupies the entire screen.

Using Navigation Controllers and Stacks

Every navigation controller owns a root view controller. This controller forms the base of its stack. You can programmatically push other controllers onto the stack as the user makes choices while navigating through the model’s tree. Although the tree itself may be multidimensional, the user’s path (essentially his history) is always a straight line representing the choices already made to date. Moving to a new choice extends the navigation breadcrumb trail and automatically builds a Back button each time a new view controller gets pushed onto the stack.

Users can tap a Back button to pop controllers off the stack. The name of each button is the title of the most recent view controller. As you return through the stack of previous view controllers, each Back button indicates the view controller that can be returned to. Users can pop back until they reach the root. Then they can go no further. The root is the base of the tree, and you cannot pop beyond that root.

This stack-based design lingers even when you plan to use just one view controller. You might want to leverage the UINavigationController’s built-in navigation bar to build a simple utility that uses a two-button menu, for example. This would disregard any navigational advantage of the stack. You still need to set that one controller as the root via initWithRootViewController:.

Pushing and Popping View Controllers

Add new items onto the navigation stack by pushing a new controller with pushViewController:animated:. Each view controller provides a navigationController property. This property points to the navigation controller that this controller is participating in. The property isnil if the controller is not pushed onto a navigation stack.

Use the navigationController property to push a new view controller onto the navigation stack and call the push method on the navigation controller. When pushed, the new controller slides onscreen from the right (assuming that you set animated to YES). A left-pointing Back button appears, leading you one step back on the stack. The Back button uses a chevron along with the title of the previous view controller on the navigation stack. Replace the chevron with a custom image by setting the backIndicatorImage property. Always use caution when overriding Apple standard elements. Be sure to maintain the spirit of the Apple Human Interface Guidelines (HIG).

You might push a new view for many reasons. Typically, these involve navigating to specialty views such as detail views or drilling down a file structure or preferences hierarchy. You can push controllers onto the navigation controller stack after your user taps a button, a table item, or a disclosure accessory.

There’s little reason to ever subclass UINavigationController. Perform push requests and navigation bar customization (such as setting up a bar’s title or buttons) inside UIViewController subclasses. Customization gets passed up to the navigation controller from the child controllers.

For the most part, you don’t access the navigation controller directly. The exceptions to this rule include managing the navigation bar’s buttons, changing the bar’s look, and initializing with a custom navigation bar class. You might change a bar style or its tint color by accessing thenavigationBar property directly, as follows:

self.navigationController.navigationBar.barStyle =
UIBarStyleBlack;

Be aware that in iOS 7, Apple added barTintColor to tint the bar background instead of tintColor. The tintColor property is repurposed to tint bar button items.

Bar Buttons

To add new buttons, you modify your navigationItem, which provides a representational class that describes the content shown on the navigation bar, including its left and right bar button items and its title view. Here’s how you can assign a button to the bar:

self.navigationItem.rightBarButtonItem = [[UIBarButtonItem alloc]
initWithTitle:@"Action" style:UIBarButtonItemStylePlain target:self
action:@selector(performAction:)];

To remove a button, assign the item to nil. Bar button items are not views. They are classes that contain titles, styles, and callback information that navigation items and toolbars use to build actual buttons in to interfaces. iOS does not provide you with access to the button views built by bar button items and their navigation items.

Starting in iOS 5, you can add multiple bar button items to the left and right. Assign an array to the rightBarButtonItems (notice the s) or leftBarButtonItems properties for the navigation item:

self.navigationItem.rightBarButtonItems = barButtonArray;

Edge-to-Edge Layout

The design focus of iOS 7 is your application’s content—more specifically, your user’s content. Borders and shadows have been removed and transparency has been added in navigation bars and other UI elements. This change significantly impacts the layout of your views, especially when you’re using a navigation bar.

Beginning with iOS 7, all view controllers use full-screen layout. The wantsFullScreenLayout property on UIViewController has been deprecated, and setting it to NO will likely lead to very unexpected layout. With full-screen layout, the view controller will size its view to fill the entire screen, passing fully under the translucent system status bar. In addition, by default, all bars in iOS 7 are now translucent to further reveal the underlying content.

The flowing of content under bars will shift your content in ways that are foreign in previous versions. You must actively include the area underneath the status bar and your own bars in your layout.

To provide more control over placement, UIViewController now provides a number of new layout properties. Manage status bar visibility at the view controller level by implementing prefersStatusBarHidden in your subclasses and returning an appropriate Boolean. Many of the new properties allow the positioning or sizing of views based on the currently displayed bars.

For view controllers, you can now specify which edges of the view should be extended under translucent bars by setting edgesForExtendedLayout. By default, this property is UIRectEdgeAll—which means all your edges will extend through the translucent elements as shown inFigure 7-2 (left). You can also specify any specific edge(s) or UIRectEdgeNone, stopping the content view edge when it reaches the bar, as shown in Figure 7-2 (right). By default, edgesForExtendedLayout also includes opaque bars. SetextendedLayoutIncludesOpaqueBars to NO to alter this behavior.

Figure 7-2 In iOS 7, edgesForExtendedLayout on UIViewController controls the edge of the view used for layout. UIRectEdgeAll, the default, extends the edge through the translucent bars (left). UIRectEdgeNone stops the edge at the extent of the bars (right).

Scroll views are also impacted by the system status bar and developer-implemented bars (navigation bar, toolbar, and tab bar). By default, UIScrollViews automatically adjust their content insets to handle these bar elements. To turn off this behavior and manually manage the scroll view insets, set automaticallyAdjustsScrollViewInsets to NO.

Finally, to assist in laying out content within your views, iOS 7 provides the topLayoutGuide and bottomLayoutGuide properties. These properties indicate the top and bottom bar edges in your view controller’s view. The location represented depends on the visible bars.

For topLayoutGuide:

Status bar but no navigation bar visible—bottom of the status bar.

Navigation bar visible—bottom of the navigation bar.

No status or navigation bar visible—top of the screen.

For bottomLayoutGuide:

Toolbar or tab bar visible—top of the toolbar or tab bar.

No toolbar or tab bar visible—bottom of the screen.

Use these properties to create relative constraints, positioning your subviews relative to the bar edges regardless of the frame location or foreknowledge of bar visibility. Use them with Auto Layout constraints both in Interface Builder (IB) or in your layout code. Outside of Auto Layout, use guides in frame-based positioning. Reference the offset value in the guide’s length property.

Recipe: The Navigation Item Class

The objects that populate the navigation bar are put into place using the UINavigationItem class, which is a class that stores information about those objects. Navigation item properties include the left and right bar button items, the title shown on the bar, the view used to show the title, and any Back button used to navigate back from the current view.

This class enables you to attach buttons, text, and other UI objects in three key locations: the left, the center, and the right of the navigation bar. Typically, this works out to be a regular button on the right, some text (usually the UIViewController’s title) in the middle, and a Back-style button on the left. But you’re not limited to this layout. You can add custom controls to any of three locations: the left, the center (title area), and the right. You might build navigation bars with search fields in the middle instead, or segment controls, toolbars, pictures, and more. Further, you can add multiple items to the left and right button arrays. It’s all easy to modify.

Titles and Back Buttons

The central title area is especially customizable. You can assign a title to the navigation item like this:

self.navigationItem.title = @"My Title"

This is equivalent to setting the view controller’s title property directly. The simplest way to customize the actual title is to use the title property of the child view controller rather than the navigation item:

self.title = @"Hello";

When assigned, the navigation controller uses the title to establish the Back button’s “go back” text. If you push a new controller on top of a controller titled "Hello", the Back button indicates that it links to "Hello".

You could also replace the text-based title with a custom view such as a control. This code adds a custom segmented control, but this could be an image view, a stepper, or anything else:

self.navigationItem.titleView =
[[UISegmentedControl alloc] initWithItems:items];

Macros

Macros simplify your work when building bar buttons because the creation task is so repetitive. The following macro creates a basic button item:

#define BARBUTTON(TITLE, SELECTOR) [[UIBarButtonItem alloc] \
initWithTitle:TITLE style:UIBarButtonItemStylePlain \
target:self action:SELECTOR]

You supply it with a title and a selector to call. Each call to this macro specifies only the title and selector, tightening up the code’s readability:

self.navigationItem.rightBarButtonItem =
BARBUTTON(@"Push", @selector(push:));

This version of the macro assumes that the target is "self", which is quite common, although you could easily adapt this. The following macro adds a target that you specify:

#define BARBUTTON_TARGET(TITLE, TARGET, SELECTOR) \
[[UIBarButtonItem alloc] initWithTitle:TITLE \
style:UIBarButtonItemStylePlain target:TARGET action:SELECTOR]

The vocabulary of bar buttons you use varies by your particular application demands. It’s easy to create macros for system items provided by Apple, image items created from picture resources, and custom view items, which can embed controls and other non-bar button elements.

Recipe 7-1 combines these features to demonstrate how controller titles and navigation items build together during drilling. It offers a super-simple interface: You select the title for the next item you want to push onto the navigation stack, and then you push it on. This allows you to see how the navigation controller stack grows using default behavior.

Recipe 7-1 Basic Navigation Drilling