UIAlertView Class (1)

UIAlertView Class Reference

Contents

UIAlertView Class Reference 3Overview 3

Subclassing Notes 4Tasks 4

Creating Alert Views 4Setting Properties 4Configuring Buttons 5Displaying 5Dismissing 5

Properties 5alertViewStyle 5cancelButtonIndex 6delegate 6firstOtherButtonIndex 6message 7numberOfButtons 7title 7visible 8

Instance Methods 8addButtonWithTitle: 8buttonTitleAtIndex: 9dismissWithClickedButtonIndex:animated: 9initWithTitle:message:delegate:cancelButtonTitle:otherButtonTitles: 10show 11textFieldAtIndex: 12

Constants 13UIAlertViewStyle 13

Document Revision History 14

2011-10-12 | © 2011 Apple Inc. All Rights Reserved.

2

Inherits from UIView : UIResponder : NSObject

Conforms to NSCoding (UIView)

UIAppearance (UIView)

UIAppearanceContainer (UIView)

NSObject (NSObject)

Framework /System/Library/Frameworks/UIKit.framework

Availability Available in iOS 2.0 and later.

Declared in UIAlertView.h

Related sample code AdvancedURLConnections

GeocoderDemo

GKTank

LaunchMe

UICatalog

OverviewUse the UIAlertView class to display an alert message to the user. An alert view functions similar to butdiffers 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 viewand configure the buttons. You must set a delegate if you add custom buttons. The delegate should conformto the UIAlertViewDelegate protocol. Use the show (page 11) method to display an alert view once it isconfigured.


3

UIAlertView Class Reference

Important: In iOS 4.0 and later, alert views are not dismissed automatically when an application moves tothe background. This behavior differs from earlier versions of the operating system, where alert views wereautomatically cancelled (and their cancellation handler executed) as part of the termination sequence forthe application. Now, it is up to you to decide whether to dismiss the alert view (and execute its cancellationhandler) or leave it visible for when your application moves back to the foreground. Remember that yourapplication can still be terminated while in the background, so some type of action may be necessary ineither case.

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

Tasks

Creating Alert Views

– initWithTitle:message:delegate:cancelButtonTitle:otherButtonTitles: (page 10)Convenience method for initializing an alert view.

Setting Properties

delegate (page 6) propertyThe receiver’s delegate or nil if it doesn’t have a delegate.

alertViewStyle (page 5) propertyThe kind of alert displayed to the user.

title (page 7) propertyThe string that appears in the receiver’s title bar.

message (page 7) propertyDescriptive text that provides more details than the title.

visible (page 8) propertyA Boolean value that indicates whether the receiver is displayed. (read-only)

UIAlertView Class ReferenceTasks


4

Configuring Buttons

– addButtonWithTitle: (page 8)Adds a button to the receiver with the given title.

numberOfButtons (page 7) propertyThe number of buttons on the alert view. (read-only)

– buttonTitleAtIndex: (page 9)Returns the title of the button at the given index.

– textFieldAtIndex: (page 12)Returns the text field at the given index

cancelButtonIndex (page 6) propertyThe index number of the cancel button.

firstOtherButtonIndex (page 6) propertyThe index of the first other button. (read-only)

Displaying

– show (page 11)Displays the receiver using animation.

Dismissing

– dismissWithClickedButtonIndex:animated: (page 9)Dismisses the receiver, optionally with animation.

Properties

alertViewStyle

The kind of alert displayed to the user.

@property(nonatomic, assign) UIAlertViewStyle alertViewStyle

AvailabilityAvailable in iOS 5.0 and later.

UIAlertView Class ReferenceProperties


5

Related Sample CodeUICatalog

Declared inUIAlertView.h

cancelButtonIndex

The index number of the cancel button.

@property(nonatomic) NSInteger cancelButtonIndex

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


Related Sample CodeMVCNetworking


delegate

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

@property(nonatomic, assign) id delegate

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



firstOtherButtonIndex

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



6

@property(nonatomic, readonly) NSInteger firstOtherButtonIndex

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



message

Descriptive text that provides more details than the title.

@property(nonatomic, copy) NSString *message


Related Sample CodeGeocoderDemo


numberOfButtons

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

@property(nonatomic, readonly) NSInteger numberOfButtons



title

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



7

@property(nonatomic, copy) NSString *title


Related Sample CodeGeocoderDemo


visible

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

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

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


Related Sample CodeGKRocketGKTank


Instance Methods

addButtonWithTitle:

Adds a button to the receiver with the given title.

- (NSInteger)addButtonWithTitle:(NSString *)title

Parameterstitle

The title of the new button.

UIAlertView Class ReferenceInstance Methods


8

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


See Also@property message (page 7)

Related Sample CodeGeocoderDemoGKRocket


buttonTitleAtIndex:

Returns the title of the button at the given index.

- (NSString *)buttonTitleAtIndex:(NSInteger)buttonIndex

ParametersbuttonIndex

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

Return ValueThe title of the button specified by index buttonIndex.


See Also“Displaying” (page 5)


dismissWithClickedButtonIndex:animated:

Dismisses the receiver, optionally with animation.

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



9

ParametersbuttonIndex

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

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

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


Related Sample CodeGKRocket


initWithTitle:message:delegate:cancelButtonTitle:otherButtonTitles:

Convenience method for initializing an alert view.

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

Parameterstitle

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

messageDescriptive text that provides more details than the title.

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



10

cancelButtonTitleThe 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 invokingaddButtonWithTitle: (page 8) specifying this title.

otherButtonTitles,The title of another button.

Using this argument is equivalent to invoking addButtonWithTitle: (page 8) with this title to add morebuttons.

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

Return ValueNewly initialized alert view.


See Also– addButtonWithTitle: (page 8)

Related Sample CodeAdvancedURLConnectionsMVCNetworkingUICatalogURLCacheWiTap


show

Displays the receiver using animation.

- (void)show


Related Sample CodeAdvancedURLConnectionsGeocoderDemo



11

SquareCamUICatalogWiTap


textFieldAtIndex:

Returns the text field at the given index

- (UITextField *)textFieldAtIndex:(NSInteger)textFieldIndex

ParameterstextFieldIndex

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

Return ValueThe text field specified by index textFieldIndex.

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

Text FieldsAlert Style

No user-editable text fields.UIAlertViewStyleDefault

A single text field at index 0.UIAlertViewStyleSecureTextInput

A single text field at index 0.UIAlertViewStylePlainTextInput

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

UIAlertViewStyleLoginAndPasswordInput

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





12

Constants

UIAlertViewStyle

The presentation style of the alert.

typedef enum {UIAlertViewStyleDefault = 0,UIAlertViewStyleSecureTextInput,UIAlertViewStylePlainTextInput,UIAlertViewStyleLoginAndPasswordInput

} UIAlertViewStyle;

ConstantsUIAlertViewStyleDefault

A standard alert.

Available in iOS 5.0 and later.

Declared in UIAlertView.h.

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



UIAlertViewStylePlainTextInputAn alert that allows the user to enter text.



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



UIAlertView Class ReferenceConstants


13

This table describes the changes to UIAlertView Class Reference .

NotesDate

Updated for iOS 5.2011-10-12

Added guidance on what to do when an application displaying an alertview moves to the background.

2010-05-14

Corrected the description of the initialization routine when addingadditional buttons.

2009-04-30

Made minor corrections.2008-09-09

New document that describes the class used to present an alert messageto the user.

2008-04-18


14

Document Revision History

Apple Inc.© 2011 Apple Inc.All rights reserved.

No part of this publication may be reproduced,stored in a retrieval system, or transmitted, in anyform or by any means, mechanical, electronic,photocopying, recording, or otherwise, withoutprior written permission of Apple Inc., with thefollowing exceptions: Any person is herebyauthorized to store documentation on a singlecomputer for personal use only and to printcopies of documentation for personal useprovided that the documentation containsApple’s copyright notice.

No licenses, express or implied, are granted withrespect to any of the technology described in thisdocument. Apple retains all intellectual propertyrights associated with the technology describedin this document. This document is intended toassist application developers to developapplications only for Apple-labeled computers.

Apple Inc.1 Infinite LoopCupertino, CA 95014408-996-1010

Apple and the Apple logo are trademarks ofApple Inc., registered in the U.S. and othercountries.

iOS is a trademark or registered trademark ofCisco in the U.S. and other countries and is usedunder license.

Even though Apple has reviewed this document,APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THISDOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED“AS IS,” AND YOU, THE READER, ARE ASSUMING THEENTIRE RISK AS TO ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIALDAMAGES RESULTING FROM ANY DEFECT ORINACCURACY IN THIS DOCUMENT, even if advised ofthe possibility of such damages.

THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,agent, or employee is authorized to make anymodification, extension, or addition to this warranty.

Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation orexclusion may not apply to you. This warranty givesyou specific legal rights, and you may also have otherrights which vary from state to state.

UIAlertView Class (1)

Documents

Transcript of UIAlertView Class (1)