iOS Developer Library

Developer

UIKit Framework Reference UIActionSheet Class Reference

Options
Deployment Target:

On This Page
Language:

UIActionSheet

Inheritance


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 2.0 and later.

Important: UIActionSheet is deprecated in iOS 8. (Note that UIActionSheetDelegate is also deprecated.) To create and manage action sheets in iOS 8 and later, instead use UIAlertController with a preferredStyle of UIAlertControllerStyleActionSheet.

In apps that target versions of iOS prior to iOS 8, 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.

For more information about appearance and behavior configuration, see Action Sheets.

Subclassing Notes

UIActionSheet is not designed to be subclassed, nor should you add views to its hierarchy. If you need to present a sheet with more customization than provided by the UIActionSheet API, you can create your own and present it modally with presentViewController:animated:completion:.

  • Initializes the action sheet using the specified starting parameters.

    Declaration

    Swift

    init(title title: String?, delegate delegate: UIActionSheetDelegate?, cancelButtonTitle cancelButtonTitle: String?, destructiveButtonTitle destructiveButtonTitle: String?)

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    Not available in app extensions.

  • delegate delegate Property

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

    Declaration

    Swift

    unowned(unsafe) var delegate: UIActionSheetDelegate?

    Objective-C

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

    Discussion

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • title title Property

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

    Declaration

    Swift

    var title: String

    Objective-C

    @property(nonatomic, copy) NSString *title

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • visible visible Property

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

    Declaration

    Swift

    var visible: Bool { get }

    Objective-C

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

    Discussion

    If YEStrue, the receiver is displayed; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The receiver’s presentation style.

    Declaration

    Swift

    var actionSheetStyle: UIActionSheetStyle

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Adds a custom button to the action sheet.

    Declaration

    Swift

    func addButtonWithTitle(_ title: String) -> Int

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    UIActionSheet

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

    Declaration

    Swift

    var numberOfButtons: Int { get }

    Objective-C

    @property(nonatomic, readonly) NSInteger numberOfButtons

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Returns the title of the button at the specified index.

    Declaration

    Swift

    func buttonTitleAtIndex(_ buttonIndex: Int) -> String

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    – showInView:

  • The index number of the cancel button.

    Declaration

    Swift

    var cancelButtonIndex: Int

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The index number of the destructive button.

    Declaration

    Swift

    var destructiveButtonIndex: Int

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var firstOtherButtonIndex: Int { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func showFromTabBar(_ view: UITabBar!)

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Displays an action sheet that originates from the specified toolbar.

    Declaration

    Swift

    func showFromToolbar(_ view: UIToolbar!)

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Displays an action sheet that originates from the specified view.

    Declaration

    Swift

    func showInView(_ view: UIView!)

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func showFromBarButtonItem(_ item: UIBarButtonItem!, animated animated: Bool)

    Objective-C

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

    Parameters

    item

    The bar button item from which the action sheet originates.

    animated

    Specify YEStrue to animate the presentation of the action sheet or NOfalse 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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Displays an action sheet that originates from the specified view.

    Declaration

    Swift

    func showFromRect(_ rect: CGRect, inView view: UIView!, animated animated: Bool)

    Objective-C

    - (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 YEStrue to animate the presentation of the action sheet or NOfalse 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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Dismisses the action sheet immediately using an optional animation.

    Declaration

    Swift

    func dismissWithClickedButtonIndex(_ buttonIndex: Int, animated animated: Bool)

    Objective-C

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

    Parameters

    buttonIndex

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

    animated

    Specify YEStrue to animate the dismissal of the action sheet or NOfalse 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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

Data Types

  • Specifies the style of an action sheet.

    Declaration

    Swift

    enum UIActionSheetStyle : Int { case Automatic case Default case BlackTranslucent case BlackOpaque }

    Objective-C

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

    Constants

    • Automatic

      UIActionSheetStyleAutomatic

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

      Available in iOS 2.0 and later.

    • Default

      UIActionSheetStyleDefault

      The default style.

      Available in iOS 2.0 and later.

    • BlackTranslucent

      UIActionSheetStyleBlackTranslucent

      A black translucent style.

      Available in iOS 2.0 and later.

    • BlackOpaque

      UIActionSheetStyleBlackOpaque

      A black opaque style.

      Available in iOS 2.0 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.