UIActivity Class Reference

Inherits from	NSObject
Conforms to	NSObject (NSObject)
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:

activityType
activityTitle
activityImage
canPerformWithActivityItems:
prepareWithActivityItems:

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.

Tasks

Getting the Activity Information

Performing the Activity

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.

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 should be no larger than 43 by 43 points (which equates to 86 by 86 pixels for devices with Retina displays.) For iPad, images should be no larger than 55 x 55 points (which equates to 110 by 110 pixels for iPads with Retina displays.)

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. Instead, call activityDidFinish: from your background thread after the actual work has been completed.

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;

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, AVAsset, and NSURL objects as data for the activity items. You may also specify NSURL objects whose contents use the assets-library scheme.