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

Chapter 8. Common Controllers

The iOS SDK provides a wealth of system-supplied controllers that you can use in your day-to-day development tasks. This chapter introduces some of the most popular ones. You’ll read about selecting images from your device library, snapping photos, and recording and editing videos. You’ll discover how to allow users to compose e-mails and text messages, and how to post updates to social services like Twitter and Facebook. Each controller offers a way to leverage prepackaged iOS system functionality. Here’s the know-how you need to get started using them.

Image Picker Controller

The UIImagePickerController class enables users to select images from a device’s media library and to snap pictures with its camera. It is somewhat of a living fossil; its system-supplied interface was created back in the early days of iPhone OS. Over time, as Apple rolled out devices with video recording (iOS 3.1) and front and rear cameras (iOS 4), the class evolved. It introduced photo and video editing, customizable camera view overlays, and more.

Image Sources

The image picker works with three sources:

UIImagePickerControllerSourceTypePhotoLibrary—This source contains all images synced to iOS. Material in this source includes images snapped by the user (Camera Roll), from photo streams, from albums synced from computers, copied via the camera connection kit, and so on.

UIImagePickerControllerSourceTypeSavedPhotosAlbum—This source refers only to the Camera Roll, which consists of pictures and videos captured by the user on units with cameras or to the Saved Photos album for noncamera units. Photo stream items captured on other devices also sync into the Camera Roll.

UIImagePickerControllerSourceTypeCamera—This source enables users to shoot pictures with a built-in iPhone camera. The source provides support for front and back camera selection and both still and video capture.

Although you might want more nuanced access to iCloud and to shared and individual photo streams, for now you can access your entire library, just the Camera Roll, or just the Camera. Submit your enhancement suggestions to http://bugreport.apple.com.

Presenting the Picker on iPhone and iPad

Figure 8-1 shows the image picker presented on an iPhone and iPad, using a library source. The UIImagePickerController class is designed to operate in a modal presentation on iPhone-like devices (left) or a popover on tablets (right).

Figure 8-1 The core image picker allows users to select images from pictures stored in the media library.

On iPhone-like devices, present the picker modally. On the iPad, embed pickers into popovers instead. Never push image pickers onto an existing navigation stack. On older versions of iOS, doing so would create a second navigation bar under the primary one. On modern versions of iOS, it throws a nasty exception: "Pushing a navigation controller is not supported by the image picker".

Recipe: Selecting Images

In its simplest role, the image picker enables users to browse their library and select a stored photo. Recipe 8-1 demonstrates how to create and present a picker and retrieve an image selected by the user. Before proceeding with general how-to, you need to know about two key how-to’s.

How To: Adding Photos to the Simulator

Before running this recipe on a Mac, you might want to populate the simulator’s photo collection. You can do this in two ways. First, you can drop images onto the simulator from Finder. Each image opens in Mobile Safari, where you can then tap-and-hold and choose Save Image to copy the image to your photo library.

Once you set up your test photo collection as you like, navigate to the Application Support folder in your home library on your Mac. Open the iPhone Simulator folder and then the folder for the iOS version you’re currently using (for example, 7.0). Inside, you’ll find a Media folder. The path to the Media folder will look something like this: /Users/(Your Account)/Library/Application Support/iPhone Simulator/(OS Version)/Media.

Back up the newly populated Media folder to a convenient location. Creating a backup enables you to restore it in the future without having to re-add each photo individually. Each time you reset the simulator’s contents and settings, this material gets deleted. Having a folder on hand that’s ready to drop in and test with can be a huge time saver.

Alternatively, purchase a copy of Ecamm’s PhoneView (http://ecamm.com). PhoneView offers access to a device’s Media folder through the Apple File Connection (AFC) service. Connect an iPhone or iPad, launch the application, and then drag and drop folders from PhoneView to your Mac. Make sure you check Show Entire Disk in PhoneView preferences to see all the relevant folders.

Using PhoneView, copy the DCIM, PhotoData, and Photos folders from a device to a folder on your Macintosh. Once copied, quit the simulator and add the copied folders into the ~/Library/Application Support/iPhone Simulator/(OS Version)/Media destination. When you next launch the simulator, your new media will be waiting for you in the Photos app.

The Assets Library Module

This recipe uses the assets library module. Be sure to add it to your source file with @import AssetsLibrary.

Using the assets library may sound complicated, but there are strong underlying reasons why this is a best practice for working with image pickers. An image picker may return an asset URL without providing a direct image to use. Recipe 8-1 assumes that this is a possibility and offers a method to load an image from the assets library (loadImageFromAssetURL:into:). A typical URL looks something like this:

assets-library://asset/asset.JPG?id=553F6592-43C9-45A0-B851-28A726727436&ext=JPG

This URL provides direct access to media.

Fortunately, Apple has now moved past an extremely annoying assets library issue. Historically, iOS queried the user for permission to use his or her location—permissions that users would often deny. Apps would get stuck because you cannot force the system to ask again. Beginning with iOS 6, the message properly states that the app would like to access a user’s photos rather than location, hopefully leading users to grant access. Determine your authorization situation by querying the class’s authorizationStatus. You can reset these granted privileges by opening Settings > Privacy and updating service-based permissions (like location and photo access) on an app-by-app basis.

Unfortunately, as of the initial release of iOS 7, Apple added a nasty bug related to asset library authorization on the iPad. A crash occurs when returning from the permission request if you display a picker in a popover. Restarting the app resolves the issue but provides a poor first-run experience. A workaround is to request asset library access prior to displaying the popover:

// Force authorization for asset library
[assetsLibrary enumerateGroupsWithTypes:ALAssetsGroupAll
usingBlock:^(ALAssetsGroup *group, BOOL *stop) {
// If authorized, catch the final iteration and display popover
if (group == nil)
{
dispatch_async(dispatch_get_main_queue(), ^{
popover = [[UIPopoverController alloc]
initWithContentViewController:
viewControllerToPresent];
popover.delegate = self;
[popover presentPopoverFromBarButtonItem:
self.navigationItem.rightBarButtonItem
permittedArrowDirections:
UIPopoverArrowDirectionAny
animated:YES];
});
}
*stop = YES;
} failureBlock:nil];

With the procedural details addressed, the next section introduces the image picker itself.

Presenting a Picker

Create an image picker by allocating and initializing it. Next, set its source type to the library (all images) or Camera Roll (captured images). Recipe 8-1 sets the photo library source type, allowing users to browse through all library images.

UIImagePickerController *picker = [[UIImagePickerController alloc] init];
picker.sourceType = UIImagePickerControllerSourceTypePhotoLibrary;

An optional editing property (allowsEditing) adds a step to the interactive selection process. When enabled, it allows users to scale and frame the image they picked before finishing their selection. When it is disabled, any media selection immediately redirects control to the next phase of the picker’s life cycle.

Be sure to set the picker’s delegate property. The delegate property conforms to the UINavigationControllerDelegate and UIImagePickerControllerDelegate protocols; it receives callbacks after a user has selected an image or cancelled selection. When using an image picker controller with popovers, declare the UIPopoverControllerDelegate protocol as well.

When working on iPhone-like devices, always present the picker modally; check for the active device at runtime. The following test (iOS 3.2 and later) returns true when run on an iPhone and false on an iPad:

#define IS_IPHONE (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPhone)

The following snippet shows the typical presentation patterns for image pickers:

if (IS_IPHONE)
{
[self presentViewController:picker animated:YES completion:nil];
}
else
{
if (popover) [popover dismissPopoverAnimated:NO];
popover = [[UIPopoverController alloc]
initWithContentViewController:picker];
popover.delegate = self;
[popover presentPopoverFromBarButtonItem:
self.navigationItem.rightBarButtonItem
permittedArrowDirections:UIPopoverArrowDirectionAny
animated:YES];
}

Handling Delegate Callbacks

Recipe 8-1 considers the following three possible image picker callback scenarios:

The user has successfully selected an image.

The user has tapped Cancel (only available on modal presentations).

The user has dismissed the popover that embeds the picker by tapping outside it.

The last two cases are simple. For a modal presentation, dismiss the controller. For a popover, remove any local references holding onto the instance. Processing a selection takes a little more work.

Pickers finish their lives by returning a custom information dictionary to their assigned delegate. This info dictionary contains key/value pairs related to the user’s selection. Depending on the way the image picker has been set up and the kind of media the user selects, the dictionary may contain few or many of these keys.

For example, when working with images on the simulator dropped in via Safari, expect to see nothing more than a media type and a reference URL. Images shot on a device and then edited through the picker may contain all six keys listed here:

UIImagePickerControllerMediaType—Defines the kind of media selected by the user—normally public.image for images or public.movie for movies. Media types are defined in the Mobile Core Services framework. Media types are primarily used in this context for adding items to the system pasteboard.

UIImagePickerControllerCropRect—Returns the portion of the image selected by the user as an NSValue that stores a CGRect.

UIImagePickerControllerOriginalImage—Offers a UIImage instance with the original (unedited) image contents.

UIImagePickerControllerEditedImage—Provides the edited version of the image, containing the portion of the picture selected by the user. The UIImage returned is small, sized to fit the device screen.

UIImagePickerControllerReferenceURL—Specifies a file system URL for the selected asset. This URL always points to the original version of an item, regardless of whether a user has cropped or trimmed an asset.

UIImagePickerControllerMediaMetadata—Offers metadata for a photograph taken within the image picker.

Recipe 8-1 uses several steps to move from the info dictionary contents to produce a recovered image. First, it checks whether the dictionary contains an edited version. If it does not find this, it accesses the original image. If that fails, it retrieves the reference URL and tries to load it through the assets library. Normally, at the end of these steps, the application has a valid image instance to work with. If it does not, it logs an error and returns.

Finally, don’t forget to dismiss modally presented controllers before wrapping up work in the delegate callback.