UIActionSheet API referrence

 

Next

UIActionSheet Class Reference

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	UIActionSheet.h
Related sample code	EADemo GenericKeychain SeismicXML

Overview

Use the UIActionSheet class to present the user with a set of alternatives for how to proceed with a given task. You can also use action sheets to prompt the user to confirm a potentially dangerous action. The action sheet contains an optional title and one or more buttons, each of which corresponds to an action to take.

Use the properties and methods of this class to configure the action sheet’s message, style, and buttons before presenting it. You should also assign a delegate to your action sheet. Your delegate object is responsible for performing the action associated with any buttons when they are tapped and should conform to the UIActionSheetDelegate protocol. For more information about implementing the methods of the delegate, see UIActionSheetDelegate Protocol Reference.

You can present an action sheet from a toolbar, tab bar, button bar item, or from a view. This class takes the starting view and current platform into account when determining how to present the action sheet. For applications running on iPhone and iPod touch devices, the action sheet typically slides up from the bottom of the window that owns the view. For applications running on iPad devices, the action sheet is typically displayed in a popover that is anchored to the starting view in an appropriate way. Taps outside of the popover automatically dismiss the action sheet, as do taps within any custom buttons. You can also dismiss it programmatically.

When presenting an action sheet on an iPad, there are times when you should not include a cancel button. If you are presenting just the action sheet, the system displays the action sheet inside a popover without using an animation. Because taps outside the popover dismiss the action sheet without selecting an item, this results in a default way to cancel the sheet. Including a cancel button would therefore only cause confusion. However, if you have an existing popover and are displaying an action sheet on top of other content using an animation, a cancel button is still appropriate. For more information see iOS Human Interface Guidelines.

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

Tasks

Creating Action Sheets

• – initWithTitle:delegate:cancelButtonTitle:destructiveButtonTitle:otherButtonTitles:

Setting Properties

•   delegate  property
•   title  property
•   visible  property
•   actionSheetStyle  property

Configuring Buttons

• – addButtonWithTitle:
•   numberOfButtons  property
• – buttonTitleAtIndex:
•   cancelButtonIndex  property
•   destructiveButtonIndex  property
•   firstOtherButtonIndex  property

Presenting the Action Sheet

• – showFromTabBar:
• – showFromToolbar:
• – showInView:
• – showFromBarButtonItem:animated:
• – showFromRect:inView:animated:

Dismissing the Action Sheet

• – dismissWithClickedButtonIndex:animated:

Properties

For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.

actionSheetStyle

The receiver’s presentation style.

@property(nonatomic) UIActionSheetStyle actionSheetStyle

Discussion

This property determines how the action sheet looks when it is presented. For a list of possible values, see the UIActionSheetStyle constants.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• GenericKeychain

Declared In

UIActionSheet.h

cancelButtonIndex

The index number of the cancel button.

@property(nonatomic) NSInteger cancelButtonIndex

Discussion

Button indices start at 0. The default value of this property is normally -1, which indicates that no cancel button has been set. However, a cancel button may be created and set automatically by the initWithTitle:delegate:cancelButtonTitle:destructiveButtonTitle:otherButtonTitles: method. If you use that method to create a cancel button, you should not change the value of this property.

When presenting an action sheet on an iPad, there are times when you should not include a cancel button. For more information on when you should include a cancel button, see the class overview or iOS Human Interface Guidelines.

Availability

• Available in iOS 2.0 and later.

Declared In

UIActionSheet.h

delegate

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

@property(nonatomic, assign) id<UIActionSheetDelegate> delegate

Discussion

For a list of methods your delegate object can implement, see UIActionSheetDelegate Protocol Reference.

Availability

• Available in iOS 2.0 and later.

Declared In

UIActionSheet.h

destructiveButtonIndex

The index number of the destructive button.

@property(nonatomic) NSInteger destructiveButtonIndex

Discussion

Button indices start at 0. The default value of this property is normally -1, which indicates that no destructive button has been set. However, a destructive button may be created and set automatically by the initWithTitle:delegate:cancelButtonTitle:destructiveButtonTitle:otherButtonTitles: method. If you use that method to create a destructive button, you should not change the value of this property.

Availability

• Available in iOS 2.0 and later.

Declared In

UIActionSheet.h

firstOtherButtonIndex

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

@property(nonatomic, readonly) NSInteger firstOtherButtonIndex

Discussion

Button indices start at 0. The default value of this property is -1, which indicates that there are no other custom buttons.

Availability

• Available in iOS 2.0 and later.

Declared In

UIActionSheet.h

numberOfButtons

The number of buttons on the action sheet. (read-only)

@property(nonatomic, readonly) NSInteger numberOfButtons

Availability

• Available in iOS 2.0 and later.

Declared In

UIActionSheet.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.

Declared In

UIActionSheet.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

UIActionSheet.h

Instance Methods

addButtonWithTitle:

Adds a custom button to the action sheet.

- (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.

Availability

• Available in iOS 2.0 and later.

See Also

• UIActionSheet

Declared In

UIActionSheet.h

buttonTitleAtIndex:

Returns the title of the button at the specified 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.

See Also

• – showInView:

Declared In

UIActionSheet.h

dismissWithClickedButtonIndex:animated:

Dismisses the action sheet immediately using an optional animation.

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

Parameters

buttonIndex

The index of the button that was clicked. Button indices start at 0.

animated

Specify YES to animate the dismissal of the action sheet or NO to remove the action sheet without an animation.

Discussion

You can use this method to dismiss the action sheet programmatically as needed. The action sheet also calls this method itself in response to the user tapping one of the buttons in the action sheet.

In iOS 4.0, you may want to call this method whenever your application moves to the background. An action sheet 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 action sheet 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

UIActionSheet.h

initWithTitle:delegate:cancelButtonTitle:destructiveButtonTitle:otherButtonTitles:

Initializes the action sheet using the specified starting parameters.

- (id)initWithTitle:(NSString *) title delegate:(id < UIActionSheetDelegate >) delegate cancelButtonTitle:(NSString *) cancelButtonTitle destructiveButtonTitle:(NSString *) destructiveButtonTitle otherButtonTitles:(NSString *) otherButtonTitles, ...

Parameters

title

A string to display in the title area of the action sheet. Pass nil if you do not want to display any text in the title area.

delegate

The receiver’s delegate object. Although this parameter may be nil, the delegate is used to respond to taps in the action sheet and should usually be provided.

cancelButtonTitle

The title of the cancel button. This button is added to the action sheet automatically and assigned an appropriate index, which is available from the cancelButtonIndex property. This button is displayed in black to indicate that it represents the cancel action. Specify nil if you do not want a cancel button or are presenting the action sheet on an iPad.

destructiveButtonTitle

The title of the destructive button. This button is added to the action sheet automatically and assigned an appropriate index, which is available from the destructiveButtonIndex property. This button is displayed in red to indicate that it represents a destructive behavior. Specify nil if you do not want a destructive button.

otherButtonTitles, ...

The titles of any additional buttons you want to add. This parameter consists of a nil-terminated, comma-separated list of strings. For example, to specify two additional buttons, you could specify the value @"Button 1", @"Button 2", nil.

Return Value

A newly initialized action sheet.

Discussion

The action sheet automatically sets the appearance of the destructive and cancel buttons. If the action sheet contains only one button, it does not apply the custom colors associated with the destructive and cancel buttons.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• EADemo
• GenericKeychain
• SeismicXML

Declared In

UIActionSheet.h

showFromBarButtonItem:animated:

Displays an action sheet that originates from the specified bar button item.

- (void)showFromBarButtonItem:(UIBarButtonItem *) item animated:(BOOL) animated

Parameters

item

The bar button item from which the action sheet originates.

animated

Specify YES to animate the presentation of the action sheet or NO to present it immediately without any animation effects.

Discussion

On iPad, this method presents the action sheet in a popover and adds the toolbar that owns the button to the popover’s list of passthrough views. Thus, taps in the toolbar result in the action methods of the corresponding toolbar items being called. If you want the popover to be dismissed when a different toolbar item is tapped, you must implement that behavior in your action handler methods.

Availability

• Available in iOS 3.2 and later.

Declared In

UIActionSheet.h

showFromRect:inView:animated:

Displays an action sheet that originates from the specified view.

- (void)showFromRect:(CGRect) rect inView:(UIView *) view animated:(BOOL) animated

Parameters

rect

The portion of view from which to originate the action sheet.

view

The view from which to originate the action sheet.

animated

Specify YES to animate the presentation of the action sheet or NO to present it immediately without any animation effects.

Discussion

On iPad, this method displays the action sheet in a popover whose arrow points to the specified rectangle of the view. The popover does not overlap the specified rectangle.

Availability

• Available in iOS 3.2 and later.

Declared In

UIActionSheet.h

showFromTabBar:

Displays an action sheet that originates from the specified tab bar.

- (void)showFromTabBar:(UITabBar *) view

Parameters

view

The tab bar from which the action sheet originates.

Discussion

The appearance of the action sheet is animated.

On iPad, this method centers the action sheet in the middle of the screen. Generally, if you want to present an action sheet relative to a tab bar in an iPad application, you should use the showFromRect:inView:animated: method instead.

Availability

• Available in iOS 2.0 and later.

See Also

• – showFromToolbar:

Declared In

UIActionSheet.h

showFromToolbar:

Displays an action sheet that originates from the specified toolbar.

- (void)showFromToolbar:(UIToolbar *) view

Parameters

view

The toolbar from which the action sheet originates.

Discussion

The appearance of the action sheet is animated.

On iPad, this method centers the action sheet in the middle of the screen. Generally, if you want to present an action sheet relative to a toolbar in an iPad application, you should use the showFromBarButtonItem:animated: method instead.

Availability

• Available in iOS 2.0 and later.

See Also

• – showFromTabBar:

Declared In

UIActionSheet.h

showInView:

Displays an action sheet that originates from the specified view.

- (void)showInView:(UIView *) view

Parameters

view

The view from which the action sheet originates.

Discussion

The appearance of the action sheet is animated.

On iPad, this method centers the action sheet in the middle of the screen. Generally, if you want to present an action sheet in an iPad application, you should use the showFromRect:inView:animated: method to display the action sheet instead.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• GenericKeychain
• SeismicXML

Declared In

UIActionSheet.h

Constants

UIActionSheetStyle

Specifies the style of an action sheet.

typedef enum {
    UIActionSheetStyleAutomatic        = -1,
    UIActionSheetStyleDefault          = UIBarStyleDefault,
    UIActionSheetStyleBlackTranslucent = UIBarStyleBlackTranslucent,
    UIActionSheetStyleBlackOpaque      = UIBarStyleBlackOpaque,
} UIActionSheetStyle;

Constants

UIActionSheetStyleAutomatic

Takes the appearance of the bottom bar if specified; otherwise, same as UIActionSheetStyleDefault.

Available in iOS 2.0 and later.

Declared in UIActionSheet.h.

UIActionSheetStyleDefault

The default style.

Available in iOS 2.0 and later.

Declared in UIActionSheet.h.

UIActionSheetStyleBlackTranslucent

A black translucent style.

Available in iOS 2.0 and later.

Declared in UIActionSheet.h.

UIActionSheetStyleBlackOpaque

A black opaque style.

Available in iOS 2.0 and later.

Declared in UIActionSheet.h.

Availability

• Available in iOS 2.0 and later.

Declared In

UIActionSheet.h

Next

© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-05-14)

Did this document help you? Yes It's good, but... Not helpful...

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

• Mailing Lists
• RSS Feeds

Copyright © 2010 Apple Inc. All rights reserved.

• Terms of Use
• Privacy Policy