UIActivity Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 6.0 and later.
Declared in
UIActivity.h

Overview

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:

Tasks

Getting the Activity Information

Performing the Activity

Class Methods

activityCategory

Returns the category of the activity, which may be used to group activities in the UI.

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

Availability
  • Available in iOS 7.0 and later.
Declared In
UIActivity.h

Instance Methods

activityDidFinish:

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

- (void)activityDidFinish:(BOOL)completed;
Parameters
completed

Specify YES if the service executed to completion or NO 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.

Availability
  • Available in iOS 6.0 and later.
Declared In
UIActivity.h

activityImage

An image that identifies the service to the user.

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

Availability
  • Available in iOS 6.0 and later.
Declared In
UIActivity.h

activityTitle

A user-readable string describing the service.

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

Availability
  • Available in iOS 6.0 and later.
Declared In
UIActivity.h

activityType

An identifier for the type of service being provided.

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

Availability
  • Available in iOS 6.0 and later.
Declared In
UIActivity.h

activityViewController

Returns the view controller to present to the user.

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

Availability
  • Available in iOS 6.0 and later.
Declared In
UIActivity.h

canPerformWithActivityItems:

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

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

YES if your service can act on the specified data items or NO if it cannot.

Discussion

The default implementation of this method returns NO. Subclasses must override it and return YES 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.

Availability
  • Available in iOS 6.0 and later.
Declared In
UIActivity.h

performActivity

Performs the service when no custom view controller is provided.

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

Availability
  • Available in iOS 6.0 and later.
Declared In
UIActivity.h

prepareWithActivityItems:

Prepares your service to act on the specified data.

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

Availability
  • Available in iOS 6.0 and later.
Declared In
UIActivity.h

Constants

Built-in Activity Types

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

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

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.

Declared in UIActivity.h.

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.

Declared in UIActivity.h.

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.

Declared in UIActivity.h.

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.

Available in iOS 6.0 and later.

Declared in UIActivity.h.

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.

Available in iOS 6.0 and later.

Declared in UIActivity.h.

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.

Declared in UIActivity.h.

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.

Declared in UIActivity.h.

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.

Declared in UIActivity.h.

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.

Declared in UIActivity.h.

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.

Declared in UIActivity.h.

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.

Declared in UIActivity.h.

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.

Declared in UIActivity.h.

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.

Declared in UIActivity.h.

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.

Declared in UIActivity.h.

Discussion

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

Categories of Activity

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

typedef enum : NSInteger {
   UIActivityCategoryAction,
   UIActivityCategoryShare,
} UIActivityCategory;
Constants
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.

Declared in UIActivity.h.

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.

Declared in UIActivity.h.