UIAlertView Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Companion guide
Declared in
UIAlertView.h
Related sample code

Overview

Use the UIAlertView class to display an alert message to the user. An alert view functions similar to but differs in appearance from an action sheet (an instance of UIActionSheet).

Use the properties and methods defined in this class to set the title, message, and delegate of an alert view and configure the buttons. You must set a delegate if you add custom buttons. The delegate should conform to the UIAlertViewDelegate protocol. Use the show method to display an alert view once it is configured.

Subclassing Notes

The UIAlertView class is intended to be used as-is and does not support subclassing. The view hierarchy for this class is private and must not be modified.

For more information about appearance and behavior configuration, see “Alert Views”.

Tasks

Creating Alert Views

Setting Properties

Configuring Buttons

Displaying

Dismissing

Properties

alertViewStyle

The kind of alert displayed to the user.

@property(nonatomic, assign) UIAlertViewStyle alertViewStyle
Availability
  • Available in iOS 5.0 and later.
Related Sample Code
Declared In
UIAlertView.h

cancelButtonIndex

The index number of the cancel button.

@property(nonatomic) NSInteger cancelButtonIndex
Discussion

The button indices start at 0. If -1, then the index is not set.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIAlertView.h

delegate

The receiver’s delegate or nil if it doesn’t have a delegate.

@property(nonatomic, assign) id delegate
Discussion

See UIAlertViewDelegate Protocol Reference for the methods this delegate should implement.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIAlertView.h

firstOtherButtonIndex

The index of the first other button. (read-only)

@property(nonatomic, readonly) NSInteger firstOtherButtonIndex
Discussion

The button indices start at 0. If -1, then the index is not set. This property is ignored if there are no other buttons. The default value is -1.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIAlertView.h

message

Descriptive text that provides more details than the title.

@property(nonatomic, copy) NSString *message
Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIAlertView.h

numberOfButtons

The number of buttons on the alert view. (read-only)

@property(nonatomic, readonly) NSInteger numberOfButtons
Availability
  • Available in iOS 2.0 and later.
Declared In
UIAlertView.h

title

The string that appears in the receiver’s title bar.

@property(nonatomic, copy) NSString *title
Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIAlertView.h

visible

A Boolean value that indicates whether the receiver is displayed. (read-only)

@property(nonatomic, readonly, getter=isVisible) BOOL visible
Discussion

If YES, the receiver is displayed; otherwise, NO.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIAlertView.h

Instance Methods

addButtonWithTitle:

Adds a button to the receiver with the given title.

- (NSInteger)addButtonWithTitle:(NSString *)title
Parameters
title

The title of the new button.

Return Value

The index of the new button. Button indices start at 0 and increase in the order they are added.

Discussion

Adding too many buttons can cause the alert view to scroll. For guidelines on the best ways to use an alert in an app, see “Temporary Views” in iOS Human Interface Guidelines.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIAlertView.h

buttonTitleAtIndex:

Returns the title of the button at the given index.

- (NSString *)buttonTitleAtIndex:(NSInteger)buttonIndex
Parameters
buttonIndex

The index of the button. The button indices start at 0.

Return Value

The title of the button specified by index buttonIndex.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIAlertView.h

dismissWithClickedButtonIndex:animated:

Dismisses the receiver, optionally with animation.

- (void)dismissWithClickedButtonIndex:(NSInteger)buttonIndex animated:(BOOL)animated
Parameters
buttonIndex

The index of the button that was clicked just before invoking this method. The button indices start at 0.

animated

YES if the receiver should be removed by animating it first; otherwise, NO if it should be removed immediately with no animation.

Discussion

In iOS 4.0, you may want to call this method whenever your application moves to the background. An alert view is not dismissed automatically when an application moves to the background. This behavior differs from previous versions of the operating system, where they were canceled automatically when the application was terminated. Dismissing the alert view gives your application a chance to save changes or abort the operation and perform any necessary cleanup in case your application is terminated later.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIAlertView.h

initWithTitle:message:delegate:cancelButtonTitle:otherButtonTitles:

Convenience method for initializing an alert view.

- (id)initWithTitle:(NSString *)title message:(NSString *)message delegate:(id)delegate cancelButtonTitle:(NSString *)cancelButtonTitle otherButtonTitles:(NSString *)otherButtonTitles, ...
Parameters
title

The string that appears in the receiver’s title bar.

message

Descriptive text that provides more details than the title.

delegate

The receiver’s delegate or nil if it doesn’t have a delegate.

cancelButtonTitle

The title of the cancel button or nil if there is no cancel button.

Using this argument is equivalent to setting the cancel button index to the value returned by invoking addButtonWithTitle: specifying this title.

otherButtonTitles,

The title of another button.

Using this argument is equivalent to invoking addButtonWithTitle: with this title to add more buttons.

Too many buttons can cause the alert view to scroll. For guidelines on the best ways to use an alert in an app, see “Temporary Views”.

...

Titles of additional buttons to add to the receiver, terminated with nil.

Return Value

Newly initialized alert view.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIAlertView.h

show

Displays the receiver using animation.

- (void)show
Availability
  • Available in iOS 2.0 and later.
Declared In
UIAlertView.h

textFieldAtIndex:

Returns the text field at the given index

- (UITextField *)textFieldAtIndex:(NSInteger)textFieldIndex
Parameters
textFieldIndex

The index of the text field. The text field indices start at 0.

Return Value

The text field specified by index textFieldIndex.

Discussion

The number of text fields present in an alert is dependent on the style of the alert.

Alert Style

Text Fields

UIAlertViewStyleDefault

No user-editable text fields.

UIAlertViewStyleSecureTextInput

A single text field at index 0.

UIAlertViewStylePlainTextInput

A single text field at index 0.

UIAlertViewStyleLoginAndPasswordInput

The login field is at index 0. The password field is at index 1.

If your application attempts to retrieve a text field with an index that is out of bounds, the alert raises an NSRangeException.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIAlertView.h

Constants

UIAlertViewStyle

The presentation style of the alert.

typedef enum {
   UIAlertViewStyleDefault = 0,
   UIAlertViewStyleSecureTextInput,
   UIAlertViewStylePlainTextInput,
   UIAlertViewStyleLoginAndPasswordInput
} UIAlertViewStyle;
Constants
UIAlertViewStyleDefault

A standard alert.

Available in iOS 5.0 and later.

Declared in UIAlertView.h.

UIAlertViewStyleSecureTextInput

An alert that allows the user to enter text. The text field is obscured.

Available in iOS 5.0 and later.

Declared in UIAlertView.h.

UIAlertViewStylePlainTextInput

An alert that allows the user to enter text.

Available in iOS 5.0 and later.

Declared in UIAlertView.h.

UIAlertViewStyleLoginAndPasswordInput

An alert that allows the user to enter a login identifier and password.

Available in iOS 5.0 and later.

Declared in UIAlertView.h.