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

Chapter 3. Alerting the User

At times, you need to grab your user’s attention. New data might arrive or some status might change. You might want to tell your user that there’s going to be a wait before anything more happens—or that the wait is over and it’s time to come back and pay attention. iOS offers many ways to provide such a heads-up to the user: from alerts and progress bars to audio pings. In this chapter, you’ll discover how to build these indications into your applications and expand your user-alert vocabulary. You’ll see real-life examples that showcase these classes and discover how to make sure your user pays attention at the right time.

Talking Directly to Your User through Alerts

Alerts speak to your user. Members of the UIAlertView and UIActionSheet classes pop up or scroll in above other views to deliver their messages. These lightweight classes add two-way dialog to your apps. Alerts visually “speak” to users and can prompt them to reply. You present your alert, get user acknowledgment, and then dismiss the alert to move on with other tasks.

If you think that an alert is nothing more than a message with an attached OK button, think again. Alert objects provide incredible versatility. You can build progress indicators, allow for text input, make queries, and more. In this chapter’s recipes, you’ll see how to create a wide range of useful alerts that you can use in your own programs, using the system-supplied alerts as well as some custom ones.

Building Simple Alerts

To create alerts, allocate a UIAlertView object. Initialize it with a title and an array of button titles. The title is an NSString, as are the button titles. In the button array, each string represents a single button that should be shown.

The method snippet shown here creates and displays the simplest alert scenario. It shows a message with a single OK button. The alert doesn’t bother with delegates or callbacks, so its lifetime ends when the user taps a button:

- (void)showAlert:(NSString *)theMessage
{
UIAlertView *av = [[UIAlertView alloc] initWithTitle:@"Title"
message:theMessage
delegate:nil
cancelButtonTitle:@"OK"
otherButtonTitles:nil];
[av show];
}

Add buttons by introducing them as parameters to otherButtonTitles:. Make sure you end your arbitrary list of buttons with nil. Adding nil tells the method where your list finishes. The following snippet creates an alert with three buttons (Cancel, Option, and OK). Because this code does not declare a delegate, there’s no way to recover the alert and determine which of these three buttons was tapped. The alert displays until a user taps, and then it automatically dismisses without any further effect:

- (void)showAlert:(NSString *)theMessage
{
UIAlertView *av = [[UIAlertView alloc] initWithTitle:@"Title"
message:theMessage
delegate:nil
cancelButtonTitle:@"Cancel"
otherButtonTitles:@"Option", @"OK", nil];
[av show];
}

When working with alerts, space is at a premium. Adding more than two buttons causes the alert to display in multiline mode. Figure 3-1 shows a pair of alerts depicting both two-button (side-by-side display) and three-button (line-by-line display) presentations. Limit the number of alert buttons you add at any time to no more than three or four. Having fewer buttons works better; one or two is ideal. If you need to use more buttons, consider using action sheet objects, which are discussed later in this chapter, rather than alert views.

Figure 3-1 Alerts work best with one or two buttons (left). Alerts with more than two buttons stack the buttons as a list, producing a less elegant presentation (right).

UIAlertView objects provide simple “default” button highlights. These are based on the number of buttons, as shown in Figure 3-1. Two-button alerts highlight the rightmost button. This is defined by the single otherButtonTitles in the alert initialization. On alerts with more than two buttons, the bottom button is highlighted. This is usually represented by cancelButtonTitle. If you don’t supply one, the last button item acts as the default instead. As a rule, Cancel buttons appear at the bottom or left of alerts.

Alert Delegates

Need to know if a user tapped OK or Cancel? Alerts use delegates to recover user choices after they’ve been made, using a simple callback. Delegates should declare the UIAlertViewDelegate protocol. In normal use, you often set the delegate to your primary (active) view controller object.

Delegate methods enable you to react as different buttons are pressed. As you’ve already seen, you can omit that delegate support if all you need to do is show some message with an OK button.

After the user has seen and interacted with your alert, the delegate receives an alertView:clickedButtonAtIndex: callback. The second parameter passed to this method indicates which button was pressed. Button numbering begins with zero. The Cancel button defaults to button 0. Even though it appears at the left in some views and the bottom in others, its button numbering remains the same unless you adjust the Cancel button index (retrievable via the cancelButtonIndex property). This is not true for action sheet objects, which are discussed later in this chapter.

Here is a simple example of an alert presentation and callback, which prints out the selected button number to the debugging console:

@interface TestBedViewController : UIViewController
<UIAlertViewDelegate>
@end

@implementation TestBedViewController
- (void)alertView:(UIAlertView *)alertView
clickedButtonAtIndex:(int)index
{
NSLog(@"User selected button %d\n", index);
}

- (void)showAlert
{
UIAlertView *av = [[UIAlertView alloc]
initWithTitle:@"Alert View Sample"
message:@"Select a Button"
delegate:self
cancelButtonTitle:@"Cancel"
otherButtonTitles:@"One", @"Two", @"Three", nil];

// Tag your UIAlertView so it can be distinguished
// from others in your delegate callbacks.
av.tag = MAIN_ALERT;
[av show];
}
@end

If your controller works with multiple alerts, tags help identify which alert produced a given callback. Unlike controls that use target-action pairs, all alerts trigger the same methods. Adding an alert-tag-based switch statement lets you differentiate your responses to each alert.

Displaying the Alert

The show instance method tells your alert to appear. When shown, the alert works in a modal fashion. That is, it dims the screen behind it and blocks user interaction with your application outside the alert. This modal interaction continues until your user acknowledges the alert through a button tap, typically by selecting OK or Cancel. When the user does so, control passes to the alert delegate, allowing that delegate to finish working with the alert and respond to the selected button.

The alert properties remain modifiable after creation. You may customize an alert by updating its title or message properties. The message is the optional text that appears below the alert title and above its buttons. You can add more buttons via addButtonWithTitle:.

Kinds of Alerts

The alertViewStyle property allows you to create several alert styles. The default style (UIAlertViewStyleDefault) creates a standard alert, with a title and message text, followed by buttons, as shown in Figure 3-1. It is the bread and butter of the alert world, allowing you to query for button presses such as Yes/No, Cancel/OK, and other simple choices.

iOS offers three more styles, specifically for entering text:

UIAlertViewStylePlainTextInput—This alert style enables users to enter text.

UIAlertViewStyleSecureTextInput—When security is an issue, this alert style allows users to enter text that is automatically obscured as they type it. The text appears as a series of large dots, but the input can be read programmatically by the delegate callback.

UIAlertViewStyleLoginAndPasswordInput—This alert style offers two entry fields, including a plain-text user account login field and an obscured text password field.

When working with text entry alerts, keep your button choices simple. Use no more than two side-by-side buttons—usually OK and Cancel. Too many buttons create improper visuals, with text fields floating off above or to the sides of the alert.

You can recover the text entered in each text field of the alert view. The textFieldAtIndex: method takes one argument, an integer index starting at 0, and returns the text field at that index. In real use, the only text field that is not at index 0 is the password field, which uses index 1. After you’ve retrieved a text field, you can query its contents by using its text property, as follows:

NSLog(@"%@", [myAlert textFieldAtIndex:0].text);

Recipe: Using Blocks with Alerts

Using an alert’s delegate callbacks can produce unnecessarily complex code. All your code handling ends up in a common routine. You must implement tagging to differentiate which alert your method must handle. You must vigilantly track which button corresponds to the functionality you wish to execute, such as the alert in Figure 3-2.

Figure 3-2 This alert processes responses in blocks passed at UIAlert button creation instead of in traditional delegate callbacks.

A much simpler solution is to assign the intended implementation when declaring the buttons themselves. Blocks were built just for this task.

Blocks

Blocks are an extension to the C language that were first supported in iOS 4. They are similar in concept to a method or function that can be stored in a variable. C provides a similar mechanism for storing functions: function pointers. Blocks go beyond function pointers by storing a copy of the enclosing scope in addition to the block of executable code.

When a block is defined, a copy of the local stack is created and attached to the block. When the block is finally executed, it has access to this copy of the stack. This is very powerful, allowing a block of code and its surrounding state to be passed to a method. This code can be executed at a future point or within a certain context, such as on another thread or in a certain order.

Block syntax can be a bit perplexing. It inherits much from C function pointers, which for those not familiar can seem a bit unnatural. The caret symbol (^) denotes a block. The general syntax includes a return type, argument list, and the code block itself:

^(return type)(argument list) { // code block }

The return type can be omitted if void. The argument list can be omitted completely if there are no arguments. The simplest block could then be defined as follows:

^{ // your code here }

The typedef syntax referring to a block is slightly modified from the above:

typedef (return type)(^typeName)(argument list);

Once a block has been defined, it can then be executed, like this:

typedef void (^SomeBlock)(BOOL);
SomeBlock myBlock = ^(BOOL success)
{
if (success)
NSLog(@"Successful!");
else
NSLog(@"FAILED!");
};
myBlock(YES);

This code does very little that could not be done in a standard method call. However, passing blocks as parameters to methods opens up numerous opportunities, such as calling a block while iterating through an array. The unique feature of blocks is the ability to access variables from the enclosing scope. The following example accesses the captured myBaseNumber:

NSInteger myBaseNumber = 7;
NSArray *numbers = @[@2, @3, @5, @8, @9, @11];
[numbers enumerateObjectsUsingBlock:^(id obj, NSUInteger idx, BOOL *stop)
{
NSInteger current = [obj integerValue];
NSLog(@"%d * %d = %d", myBaseNumber, current, myBaseNumber * current);
}];

Blocks can access their captured context even if they have left the scope of that variable.

The ability of blocks to capture their enclosing scope does come with a couple caveats. The stack stored with a block is a copy. Any modifications made to captured variables after the block is declared but before it is run will not be reflected in the block. Any modifications to captured variables in the block will be lost outside the block.

To modify a captured variable from within a block, the variable must be declared with the __block storage type modifier. The variable will reside in storage that is shared between both the enclosing scope of the original code as well as the block. Any changes in one will impact the other.

The second concern with blocks and captured scope is retain cycles.

Retain Cycles and Blocks

When using blocks, be wary of the creation of retain cycles. It is very easy to unintentionally retain self inside a block. This occurs by referencing self directly or by using an ivar, which captures self indirectly.

To avoid the retain cycle, capture a weak variant of self and then assign the weak reference to a strong reference prior to use within the block. Adding the strong reference at the very start of the block ensures that if a strong reference is possible, it endures throughout the entire block scope. Don’t forget to check that the strong reference to self is not nil. The following listing avoids issues with retain cycles and nil references:

__weak TestBedViewController *weakSelf = self;
[blockAlertView addButtonWithTitle:@"OK" actionBlock:^{
TestBedViewController *strongSelf = weakSelf;
if (strongSelf)
{
NSString *name = [strongSelf->blockAlertView
textFieldAtIndex:0].text;
NSLog(@"Tapped OK after entering: %@", name);
}
}];

Blocks enable clearer APIs and greatly simplified multithreaded programming. This section has only scratched the surface of the capabilities of and uses for blocks. The Apple documentation has a trove of information on blocks and Grand Central Dispatch that are worth exploring.