UIPasteboard

Important

This is a preliminary document for an API or technology in development. Apple is supplying this information to help you plan for the adoption of the technologies and programming interfaces described herein for use on Apple-branded products. This information is subject to change, and software implemented according to this document should be tested with final operating system software and final documentation. Newer versions of this document may be provided with future betas of the API or technology.

The UIPasteboard class enables an app to share data within the app and with another app. To share data with any other app, you can use system-wide pasteboards; to share data with another app that has the same team ID as your app, you can use app-specific pasteboards.

Typically, an object in the app writes data to a pasteboard when the user requests a copy or cut operation on a selection in the user interface. Another object in the same or different app then reads that data from the pasteboard and presents it to the user at a new location; this usually happens when the user requests a paste operation.

A pasteboard is a named region of memory where data can be shared. There are two system pasteboards: the General pasteboard (UIPasteboardNameGeneral) and the Find pasteboard (UIPasteboardNameFind. You can use the General pasteboard for copy-paste operations involving any kind of data; the Find pasteboard, which is used in search operations, holds the most recent string value in the search bar. Apps can also create pasteboards for their own use or for use by other apps that have the same team ID. A pasteboard must be identified by a unique name. You may also mark an app-specific pasteboard as persistent, so that it continues to exist past the termination of the app and past system reboots. System pasteboards are persistent by default.

When you write an object to a pasteboard, it is stored as a pasteboard item. A pasteboard item is one or more key-value pairs where the key is a string that identifies the representation type of the value. Having multiple representation types per pasteboard item makes it more possible for one app to share data with another app without having to know specific capabilities of that app. For example, the source app could write the same image to the pasteboard in PNG, JPEG, and GIF data formats. If the receiving app can only handle GIF images, it can still obtain the pasteboard data.

A Uniform Type Identifier (UTI) is frequently used for a representation type (sometimes called a pasteboard type). For example, you could use kUTTypeJPEG (a constant for public.jpeg) as a representation type for JPEG data. Apps are free to use any string to name a representation type; however, for app-specific data types, it is recommended that you use reverse-DNS notation to ensure the uniqueness of the type (for example, com.myCompany.myApp.myType).

UIPasteboard provides methods for reading and writing single pasteboard items at a time as well as multiple pasteboard items. The data written and read can be in two general forms. If the data to be written can be represented by an object—such as NSString, NSArray, NSDictionary, NSDate, NSNumber, UIImage, or NSURL—use a method such as setValue:forPasteboardType: to write it to the pasteboard. If the data is binary, use the setData:forPasteboardType: method to write it to the pasteboard. The class also provides convenience methods for writing and reading strings, images, URLs, and colors to and from single or multiple pasteboard items.

Although UIPasteboard is central to copy-paste operations, several other UIKit classes and protocols are used in these operations as well:

UIMenuController — Displays a menu with Copy, Cut, Paste, Select, and Select All commands above or below the selection.

An app that implements copy-paste usually has to handle the management and presentation of selections in its user interface. It must also coordinate the addition and removal of items via paste and cut operations with its data model.

Declaration

Return Value

Discussion

You may use the general pasteboard for copying and pasting text, images, URLs, colors, and other data within an app or between apps. The general pasteboard is persistent across device restarts and app uninstalls.

Declaration

Parameters

A string or string constant that identifies (or should identify) the pasteboard. Specify nil if you want UIPasteboard to create a pasteboard with a unique name.

create

A Boolean value that indicates whether the pasteboard should be created if it doesn’t already exist. Specify NOfalse for system pasteboards or if you want an existing app pasteboard.

Return Value

A pasteboard object that can be used for transferring data within an app or between apps that have the same team ID.

Discussion

You call this method to obtain the UIPasteboardNameFind pasteboard and to create custom app pasteboards. (You may also use it to obtain the general pasteboard, but generalPasteboard exists for that purpose.) App pasteboards returned by this method are not persistent, existing only until the app quits. To make them persistent, set the persistent property to YEStrue.

Declaration

Return Value

An app pasteboard object with a unique name.

Discussion

Obtain the value of the name property to discover the name of the returned pasteboard. App pasteboards returned by this method are not persistent, existing only until the app quits. To make them persistent, set the persistent property to YEStrue. Calling this method is equivalent to calling pasteboardWithName:create: with the first parameter set to nil and the second set to YEStrue.

Declaration

Parameters

pasteboardName

The name of the pasteboard to be invalidated.

Discussion

Invalidation of an app pasteboard frees up all resources used by it. Once a pasteboard is invalidated, you cannot use the it; UIPasteboard ignores any calls to it. The method has no effect if called with the name of a system pasteboard.

Declaration

Discussion

When a pasteboard is persistent, it continues to exist past app terminations and across system reboots. App pasteboards that are not persistent only last until the owning (creating) app quits. System pasteboards are persistent. App pasteboards by default are not persistent. A persistent app pasteboard is removed when the app that created it is uninstalled.

Declaration

Discussion

Whenever the contents of a pasteboard changes—specifically, when pasteboard items are added, modified, or removed—UIPasteboard increments the value of this property. After it increments the change count, UIPasteboard posts the notifications named UIPasteboardChangedNotification (for additions and modifications) and UIPasteboardRemovedNotification (for removals). These notifications include (in the userInfo dictionary) the types of the pasteboard items added or removed. Because UIPasteboard waits until the end of the current event loop before incrementing the change count, notifications can be batched. The class also updates the change count when an app reactivates and another app has changed the pasteboard contents. When users restart a device, the change count is reset to zero.

Declaration

Return Value

An array of strings indicating the representation types of the first item on the pasteboard.

Discussion

A type is frequently, but not necessarily, a UTI (Uniform Type Identifier). It identifies a representation of the data on the pasteboard. For example, a pasteboard item could hold image data under public.png and public.tiff representations. Apps can define their own types for custom data such as com.mycompany.myapp.mytype; however, in this case, only those apps that know of the type could understand the data written to the pasteboard.

With this method, you can determine if the pasteboard holds data of a particular representation type by a line of code such as this:

Declaration

Parameters

pasteboardTypes

An array of strings. Each string should identify a representation of the pasteboard item that the pasteboard reader can handle. These string are frequently UTIs. See the class description for more information about pasteboard item types.

Parameters

Return Value

An object that is an instance of the appropriate class based on pasteboardType or an NSData object containing “raw” data.

Discussion

This method attempts to return an object that is of a class type appropriate to the representation type, which typically is a UTI. For example, if the representation type is kUTTypePlainText (public.plain-text), the method returns an NSString object. If the method can’t determine the class type from the representation type, it returns the object as a generic object, such as an NSString, NSArray, NSDictionary, NSDate, NSNumber, NSURL, UIImage, or NSData object. This method works on the first item in the pasteboard. If there are other items, it ignores them.

Declaration

Parameters

data

The data object to be written to the pasteboard.

pasteboardType

A string identifying the representation type of the pasteboard item. This is typically a UTI.

Discussion

Use this method to put raw data on the pasteboard. For example, you could archive a graph of model objects and pass the resulting NSData object to a related app via a pasteboard using a custom pasteboard type. (To put objects—such as NSString, NSArray, NSDictionary, NSDate, NSNumber, UIImage, or NSURL objects—on the pasteboard, use the setValue:forPasteboardType: method.) This method writes data for the first item in the pasteboard. Calling this method replaces any items currently in the pasteboard.

Declaration

Discussion

The value of the property is an array of dictionaries. Each dictionary represents a pasteboard item, with the key being the representation type and the value the object associated with that type. Setting this property replaces all of the current pasteboard items.

Declaration

Discussion

The value stored in this property is an NSString object. The associated array of representation types is UIPasteboardTypeListString, which includes type kUTTypeUTF8PlainText. Setting this property replaces all current items in the pasteboard with the new item. If the first item has no value of the indicated type, nil is returned.

Declaration

Discussion

The value stored in this property is an array of NSString objects. The associated array of representation types is UIPasteboardTypeListString, which includes type kUTTypeUTF8PlainText.Setting this property replaces all current items in the pasteboard with the new items. The returned array may have fewer objects than the number of pasteboard items; this happens if a pasteboard item does not have a value of the indicated type.

Availability

Declaration

Discussion

The value stored in this property is a UIImage object. The associated array of representation types is UIPasteboardTypeListImage, which includes types kUTTypePNG and kUTTypeJPEG. Setting this property replaces all current items in the pasteboard with the new item. If the first item has no value of the indicated type, nil is returned.

Declaration

Discussion

The value stored in this property is an array of UIImage objects. The associated array of representation types is UIPasteboardTypeListImage, which includes types kUTTypePNG and kUTTypeJPEG. Setting this property replaces all current items in the pasteboard with the new items. The returned array may have fewer objects than the number of pasteboard items; this happens if a pasteboard item does not have a value of the indicated type.

Availability

Declaration

Discussion

The value stored in this property is an NSURL object. The associated array of representation types is UIPasteboardTypeListURL, which includes type kUTTypeURL. Setting this property replaces all current items in the pasteboard with the new item. If the first item has no value of the indicated type, nil is returned.

Availability

Declaration

Discussion

The value stored in this property is an array of NSURL objects. The associated array of representation types is UIPasteboardTypeListURL, which includes type kUTTypeURL. Setting this property replaces all current items in the pasteboard with the new items. The returned array may have fewer objects than the number of pasteboard items; this happens if a pasteboard item does not have a value of the indicated type.

Availability

Declaration

Discussion

The value stored in this property is a UIColor object. The associated array of representation types is UIPasteboardTypeListColor. Setting this property replaces all current items in the pasteboard with the new item. If the first item has no value of the indicated type, nil is returned.

Declaration

Discussion

The value stored in this property is an array of UIColor objects. The associated array of representation types is UIPasteboardTypeListColor. Setting this property replaces all current items in the pasteboard with the new items. The returned array may have fewer objects than the number of pasteboard items; this happens if a pasteboard item does not have a value of the indicated type.

Constants

The name identifying the General pasteboard, which is used for general copy-cut-paste operations.

Available in iOS 3.0 and later.

UIPasteboardNameFind

UIPasteboardNameFind

The name identifying the Find pasteboard, which is used in search operations. In such operations, the most recent search string in the search bar is put in the Find pasteboard.

Available in iOS 3.0 and later.

Discussion

You can access both system pasteboards by calling the class method pasteboardWithName:create:, specifying one of these constants as the first argument. You may also access the general pasteboard by calling the generalPasteboard class method. Both system pasteboards are persistent across device restarts, app uninstalls, and restores.

Posted by a pasteboard object when its contents change. This happens at the same time the pasteboard’s change count (changeCount property) is incremented. Changes include the addition, removal, and modification of pasteboard items. The userInfo dictionary may contain the representation types of pasteboard items that have been added to or removed from the pasteboard. See UserInfo Dictionary Keys for the keys used to access these representation types. If pasteboard items have been modified but not added or removed, the userInfo dictionary is nil.