iOS Developer Library — Pre-Release

Developer

UIKit Framework Reference UIActivity Class Reference

Options
Deployment Target:

On This Page
Language:

UIActivity

The UIActivity class is an abstract class that you subclass in order to implement application-specific services. A service takes data that is passed to it, does something to that data, and returns the results. For example, an social media service might take whatever text, images, or other content is provided to it and post them to the user’s account. Activity objects are used in conjunction with a UIActivityViewController object, which is responsible for presenting services to the user.

You should subclass UIActivity only if you want to provide custom services to the user. The system already provides support for many standard services and makes them available through the UIActivityViewController object. For example, the standard activity view controller supports emailing data, posting items to one of the user’s social media accounts, and several other options. You do not have to provide custom services for any of the built-in types.

Subclassing Notes

This class must be subclassed before it can be used. The job of an activity object is to act on the data provided to it and to provide some meta information that iOS can display to the user. For more complex services, an activity object can also display a custom user interface and use it to gather additional information from the user.

Methods to Override

When subclassing, you must always override the following methods and use them to provide information about your service:

If your canPerformWithActivityItems: method indicates that your subclass is able to operate on the specified data, the active UIActivityViewController object displays your service to the user. When the user selects your service, the activity view controller calls the prepareWithActivityItems: method followed by only one of these methods:

  • activityViewController—Returns a view controller to present to the user. If your service requires additional input from the user, override this method and use it to return the view controller object responsible for presenting your custom UI. (You do not need to present the view controller yourself.) After your view controller object gathers the needed input, it is responsible for initiating the task associated with the service.

  • performActivity—Performs the service without displaying any additional UI. If your service does not need additional input from the user, override this method and perform the task associated with the service.

Inheritance


Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 6.0 and later.
  • Returns the category of the activity, which may be used to group activities in the UI.

    Declaration

    Swift

    class func activityCategory() -> UIActivityCategory

    Objective-C

    + (UIActivityCategory)activityCategory

    Return Value

    The assigned category of the activity. The default implementation returns UIActivityCategoryAction.

    Discussion

    Override this method to define a different activity category for your custom activity.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • An identifier for the type of service being provided.

    Declaration

    Swift

    func activityType() -> String?

    Objective-C

    - (NSString *)activityType

    Return Value

    A string that identifies the provided service to your app.

    Discussion

    This method returns nil by default. Subclasses must override this method and return a valid string that identifies the application service. This string is not presented to the user.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • A user-readable string describing the service.

    Declaration

    Swift

    func activityTitle() -> String?

    Objective-C

    - (NSString *)activityTitle

    Return Value

    A string that describes the service.

    Discussion

    This method returns nil by default. Subclasses must override this method and return a user-readable string that describes the service. The string you return should be localized.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • An image that identifies the service to the user.

    Declaration

    Swift

    func activityImage() -> UIImage?

    Objective-C

    - (UIImage *)activityImage

    Return Value

    An image that can be presented to the user.

    Discussion

    This method returns nil by default. Subclasses must override this method and return a valid image object. The image is used to generate a button for your service in the UI displayed by the UIActivityViewController object.

    The alpha channel of the image is used as a mask to generate the final image that is presented to the user. Any color data in the image itself is ignored. Opaque pixels have a gradient applied to them and this gradient is then laid on top of a standard background. Thus, a completely opaque image would yield a gradient filled rectangle.

    For iPhone and iPod touch, images on iOS 7 should be 60 by 60 points; on earlier versions of iOS, you should use images no larger than 43 by 43 points. For iPad, images on iOS 7 should be 76 by 76 points; on earlier versions of iOS you should use images no larger than 60 by 60 points. On a device with Retina display, the number of pixels is doubled in each direction.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Returns a Boolean indicating whether the service can act on the specified data items.

    Declaration

    Swift

    func canPerformWithActivityItems(_ activityItems: [AnyObject]) -> Bool

    Objective-C

    - (BOOL)canPerformWithActivityItems:(NSArray *)activityItems

    Parameters

    activityItems

    An array of objects of varying types. These are the data objects on which the service would act.

    Return Value

    YEStrue if your service can act on the specified data items or NOfalse if it cannot.

    Discussion

    The default implementation of this method returns NOfalse. Subclasses must override it and return YEStrue if the data in the activityItems parameter can be operated on by your service. Your implementation should check the types of the objects in the array and use that information to determine if your service can act on the corresponding data.

    The UIActivityViewController object calls this method when determining which services to show to the user.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Prepares your service to act on the specified data.

    Declaration

    Swift

    func prepareWithActivityItems(_ activityItems: [AnyObject])

    Objective-C

    - (void)prepareWithActivityItems:(NSArray *)activityItems

    Parameters

    activityItems

    An array of objects of varying types. These are the data objects on which to act.

    Discussion

    The default implementation of this method does nothing. This method is called after the user has selected your service but before your service is asked to perform its action. Subclasses should override this method and use it to store a reference to the data items in the activityItems parameter. In addition, if the implementation of your service requires displaying additional UI to the user, you can use this method to prepare your view controller object and make it available from the activityViewController method.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Returns the view controller to present to the user.

    Declaration

    Swift

    func activityViewController() -> UIViewController?

    Objective-C

    - (UIViewController *)activityViewController

    Return Value

    The view controller to present to the user. The default implementation returns nil.

    Discussion

    Subclasses that provide additional UI using a view controller can override this method to return that view controller. If this method returns a valid object, the system presents the returned view controller modally instead of calling the performActivity method.

    Your custom view controller should provide a view with your custom UI and should handle any user interactions inside those views. Upon completing the activity, do not dismiss the view controller yourself. Instead, call the activityDidFinish: method and let the system dismiss it for you.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Performs the service when no custom view controller is provided.

    Declaration

    Swift

    func performActivity()

    Objective-C

    - (void)performActivity

    Discussion

    The default implementation of this method does nothing. If your service does not provide any custom UI using the activityViewController method, override this method and use it to perform the activity. Your activity must operate on the data items received in the prepareWithActivityItems: method.

    This method is called on your app’s main thread. If your app can complete the activity quickly on the main thread, do so and call the activityDidFinish: method when it is done. If performing the activity might take some time, use this method to start the work in the background and then exit without calling activityDidFinish: from this method. When your background work has completed, call activityDidFinish:. You must call activityDidFinish: on the main thread.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Notifies the system that your activity object has completed its work.

    Declaration

    Swift

    func activityDidFinish(_ completed: Bool)

    Objective-C

    - (void)activityDidFinish:(BOOL)completed

    Parameters

    completed

    Specify YEStrue if the service executed to completion or NOfalse if the service was canceled or did not finish because of an error.

    Discussion

    This method dismisses the sharing interface provided by the UIActivityViewController object. If you provided a view controller using the activityViewController method, this method dismisses that view controller too.

    You must call this method after completing the work associated with this object’s service. This is true regardless of whether you used the activityViewController or performActivity method to initiate the service. When calling the method, use the Boolean value to indicate whether the service completed successfully.

    This method must be called on the main thread.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Activity types for which the system has built-in support.

    Declaration

    Swift

    let UIActivityTypePostToFacebook: String let UIActivityTypePostToTwitter: String let UIActivityTypePostToWeibo: String let UIActivityTypeMessage: String let UIActivityTypeMail: String let UIActivityTypePrint: String let UIActivityTypeCopyToPasteboard: String let UIActivityTypeAssignToContact: String let UIActivityTypeSaveToCameraRoll: String let UIActivityTypeAddToReadingList: String let UIActivityTypePostToFlickr: String let UIActivityTypePostToVimeo: String let UIActivityTypePostToTencentWeibo: String let UIActivityTypeAirDrop: String

    Objective-C

    NSString *const UIActivityTypePostToFacebook; NSString *const UIActivityTypePostToTwitter; NSString *const UIActivityTypePostToWeibo; NSString *const UIActivityTypeMessage; NSString *const UIActivityTypeMail; NSString *const UIActivityTypePrint; NSString *const UIActivityTypeCopyToPasteboard; NSString *const UIActivityTypeAssignToContact; NSString *const UIActivityTypeSaveToCameraRoll; NSString *const UIActivityTypeAddToReadingList; NSString *const UIActivityTypePostToFlickr; NSString *const UIActivityTypePostToVimeo; NSString *const UIActivityTypePostToTencentWeibo; NSString *const UIActivityTypeAirDrop;

    Constants

    • UIActivityTypePostToFacebook

      UIActivityTypePostToFacebook

      The object posts the provided content to the user’s wall on Facebook.

      When using this service, you can provide NSString, NSAttributedString, UIImage, ALAsset, and NSURL objects as data for the activity items. You may also specify NSURL objects whose contents use the assets-library scheme.

      Available in iOS 6.0 and later.

    • UIActivityTypePostToTwitter

      UIActivityTypePostToTwitter

      The object posts the provided content to the user’s Twitter feed.

      When using this service, you can provide NSString, NSAttributedString, UIImage, ALAsset, and NSURL objects as data for the activity items. You may also specify NSURL objects whose contents use the assets-library scheme.

      Available in iOS 6.0 and later.

    • UIActivityTypePostToWeibo

      UIActivityTypePostToWeibo

      The object posts the provided content to the user’s Weibo feed.

      When using this service, you can provide NSString, NSAttributedString, UIImage, ALAsset, and NSURL objects as data for the activity items. You may also specify NSURL objects whose contents use the assets-library scheme.

      Available in iOS 6.0 and later.

    • UIActivityTypeMessage

      UIActivityTypeMessage

      The object posts the provided content to the Messages app.

      When using this service, you can provide NSString and NSAttributedString objects as data for the activity items. You may also specify NSURL objects whose contents use the sms scheme.

      If MMS or FaceTime are enabled, you can provide UIImage, ALAsset, and NSURL objects as data for the activity items. You may also specify NSURL objects whose contents use the assets-library scheme.

      To specify an NSData object, you must implement the UIActivityItemSource protocol, return the data object in activityViewController:itemForActivityType:, and return the data object’s UTI in activityViewController:dataTypeIdentifierForActivityType:.

      Available in iOS 6.0 and later.

    • UIActivityTypeMail

      UIActivityTypeMail

      The object posts the provided content to a new email message.

      When using this service, you can provide NSString and UIImage objects and NSURL objects pointing to local files as data for the activity items.

      To specify an NSData object, you must implement the UIActivityItemSource protocol, return the data object in activityViewController:itemForActivityType:, and return the data object’s UTI in activityViewController:dataTypeIdentifierForActivityType:. Also, you may need to register the appropriate mapping so that the MIME type can be determined.

      Available in iOS 6.0 and later.

    • UIActivityTypePrint

      UIActivityTypePrint

      The object prints the provided content.

      When using this service, you can provide UIImage and NSData objects and NSURL objects pointing to local files as data for the activity items. You can also provide UIPrintPageRenderer, UIPrintFormatter, and UIPrintInfo objects.

      Available in iOS 6.0 and later.

    • UIActivityTypeCopyToPasteboard

      UIActivityTypeCopyToPasteboard

      The object posts the provided content to the pasteboard.

      When using this service, you can provide NSString, UIImage, NSURL, UIColor, and NSDictionary objects as data for the activity items.

      Available in iOS 6.0 and later.

    • UIActivityTypeAssignToContact

      UIActivityTypeAssignToContact

      The object assigns the image to a contact.

      When using this service, you can provide a UIImage object as data for the activity items.

      Available in iOS 6.0 and later.

    • UIActivityTypeSaveToCameraRoll

      UIActivityTypeSaveToCameraRoll

      The object assigns the image or video to the user’s camera roll.

      When using this service, you can provide a UIImage object as data for image-based activity items. For image and video items, you can provide an NSURL object with a path to the video.

      Available in iOS 6.0 and later.

    • UIActivityTypeAddToReadingList

      UIActivityTypeAddToReadingList

      The object adds the URL to Safari’s reading list.

      When using this service, you can provide an NSURL object whose contents uses the http or https scheme that points to the page to add.

      Available in iOS 7.0 and later.

    • UIActivityTypePostToFlickr

      UIActivityTypePostToFlickr

      The object posts the provided image to the user’s Flickr account.

      When using this service, you can provide UIImage, ALAsset, NSURL objects whose contents use the file scheme and point to an image, and NSData objects whose contents are image data as data for the activity items. You may also specify NSURL objects whose contents use the assets-library scheme.

      Available in iOS 7.0 and later.

    • UIActivityTypePostToVimeo

      UIActivityTypePostToVimeo

      The object posts the provided video to the user’s Vimeo account.

      When using this service, you can provide ALAsset, NSURL objects whose contents use the file scheme and point to a video, and NSData objects whose contents are video data as data for the activity items. You may also specify NSURL objects whose contents use the assets-library scheme.

      Available in iOS 7.0 and later.

    • UIActivityTypePostToTencentWeibo

      UIActivityTypePostToTencentWeibo

      The object posts the provided content to the user’s Tencent Weibo feed.

      When using this service, you can provide NSString, NSAttributedString, UIImage, ALAsset, and NSURL objects as data for the activity items. You may also specify NSURL objects whose contents use the assets-library scheme.

      Available in iOS 7.0 and later.

    • UIActivityTypeAirDrop

      UIActivityTypeAirDrop

      The object makes the provided content available via AirDrop.

      When using this service, you can provide NSString, NSAttributedString, UIImage, ALAsset, and NSURL objects as data for the activity items. You may also specify NSURL objects whose contents use the assets-library scheme. You may also provide NSArray or NSDictionary objects that contain the listed data types.

      Available in iOS 7.0 and later.

    Discussion

    These constants represent the values that can be stored in the activityType property of system-defined activity objects.

  • Activities have a defined category, and the activity UI may show activities grouped by category.

    Declaration

    Swift

    enum UIActivityCategory : Int { case Action case Share }

    Objective-C

    typedef enum : NSInteger { UIActivityCategoryAction, UIActivityCategoryShare, } UIActivityCategory;

    Constants

    • Action

      UIActivityCategoryAction

      Activities whose primary purpose is to take an action on the selected item. For example, copying an image, or saving it to the camera roll.

      Available in iOS 7.0 and later.

    • Share

      UIActivityCategoryShare

      Activities whose primary purpose is to share the selected item. For example, sending an image by email.

      Available in iOS 7.0 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.